This library handles storage and retrieval of terms on files. By using indexing, the store/retrieve operations are efficient also for large data sets.
The package is loaded by the query
| ?- use_module(library(db)).
The idea is to get a behavior similar to
clause/2 but the terms are stored on files
instead of in primary memory.
The differences compared with the internal database are:
Some commercial databases can't store non-ground terms or more than one instance of a term. The SICStus database can however store terms of either kind.
The database is kept in a secure state and the last stored term is safe
even if the SICStus process dies (machine rebooted, process killed,
halt/0, power failure...) (but see section Current Limitations).
db_storethe database could be inconsistent.
The db-spec defines which parts of a term that is used for
indexing in a database. It is a structure with the functor
off. The arguments are
off or the same kind of
The db-spec is compared with the indexed term and every argument
where there is an
on in the db-spec is indexed.
If the db-spec is of lower arity than the indexed term, the last part of the indexed term is skipped or vice versa.
The idea of a db-spec are illustrated with a few examples. (A section further down explains the db-spec in a more formal way).
DB-Spec Term (the parts with indexing are underlined) on(on) a(b) a(b,c) a [a,b(c),d] /* as Prolog */ - - - - - -- on(on,on) a(b) a(b,c) a(b,c,d) a(b,c(d)) [a,b(c),d] - - - - - - - - - - - --- on(off,on(on)) a(b) a(b,c) a(b,c,d) a(b,c(d)) [a,b(c),d] - - - - - - - - - --
The following conventions are used in the predicate descriptions below.
db_canonical/(2,3)can be used to check whether two TermRefs refer to the same term.
db_open(+Name, +Mode, -DBref)
db_open(+Name, +Mode, ?Spec, -DBref)
on(on), the same kind of indexing as in the internal database. When opening an existing database, any db-spec from the database is accepted.
db_close/0closes the default database. Note that after
db_close/0there is no default database.
abort/0does not close databases.
current_db(?Name, ?Mode, ?Spec, ?DBref)
db_store(+DBref, +Term, -TermRef)
db_fetch(+DBref, ?Term, ?TermRef)
db_findall/(2-3). If TermRef and DBref are instantiated (and the referenced term is not erased), the referenced term is read and unified with Term.
db_findall(+DBref, ?Term, ?TermList)
db_canonical(+DBref, +TermRef, -TermID)
db_buffering(+DBref, ?Old, ?New)
off. Buffering is initially
off. When it is
on, modified pages are not immediately flushed to disk, enabling faster execution but with a higher risk of inconsistencies if a crash occurs.
db_closealways flushes any modified pages.
| ?- db_open(my_db,update,on(on),R), set_default_db(R). R = '$db'(1411928) ? yes | ?- db_store(a(b),_). yes | ?- db_store(a(c),_). yes | ?- db_fetch(X,_). X = a(b) ? ; X = a(c) ? ; no | ?- current_db(A,B,C,D). A = my_db, B = update, C = on(on), D = '$db'(1411928) ? ; no | ?- db_close. yes
A db-spec is on of the following terms:
offand every argument being a db-spec.
The following table defines the way indices are calculated a bit more formally. The table defines the index as a function INDEX of the db-spec and the indexed term.
The column Index Calculation describes the procedure: a "yes"
means that some primitive function is used, such as a hash function;
"INDEX(s,t)" means simply that the function definition (the
table) is applied again, but with a new db-spec s and a new term
t; I means
DB-Spec Indexed Term Index Calculation
onany yes (on principal functor)
I(S1,S2...Sn)F(A1,A2...Am) yes (on principal functor) INDEX(Si,Ai) for 1 =< i =< min(n,m)
Every term is stored together with a set of "keywords" for indexing purposes. The space overhead is approximately 16 bytes per keyword per term. The number of keywords stored depends on the db-spec and on the term being indexed. The following table defines the number of keywords as a function K of the db-spec and the indexed term.
DB-Spec Indexed Term Number of keywords
I(S1,...,Sn)F(A1,...,Am) 1+K(S1,A1)*...*K(Sj,Aj), j=min(n,m)
Go to the first, previous, next, last section, table of contents.