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 assert/1
,
retract/1
and clause/2
but the terms are stored on files
instead of in primary memory.
The differences compared with the internal database are:
db_open
and
db_close
.)
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_store
the database
could be inconsistent.
db_buffering/(2-3)
.
The db-spec defines which parts of a term that is used for
indexing in a database. It is a structure with the functor on
or
off
. The arguments are on
, off
or the same kind of
structure.
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.
update
or read
db_open(+Name, +Mode, -DBref)
db_open(+Name, +Mode, ?Spec, -DBref)
update
.
db_open/4:
db_open/3:
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
db_close(+DBref)
db_close/0
closes the default database.
Note that after db_close/0
there is no default database.
abort/0
does not close databases.
set_default_db(+DBref)
set_default_db(+Name)
get_default_db(?DBref)
current_db(?Name, ?Mode, ?Spec, ?DBref)
db_store(+Term, -TermRef)
db_store(+DBref, +Term, -TermRef)
db_store/2
uses the default
database.
db_fetch(?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_fetch/2
uses the default database.
db_findall(?Term, ?TermList)
db_findall(+DBref, ?Term, ?TermList)
db_findall/2
uses the default database.
db_erase(+TermRef)
db_erase(+DBref, +TermRef)
db_erase/1
uses the default database.
db_buffering(?Old, ?New)
db_buffering(+DBref, ?Old, ?New)
on
or 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_close
always flushes any modified pages. db_buffering/2
uses the default
database.
| ?- 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:
on
, or
off
, or
on
or off
and 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 on
or off
.
DB-Spec Indexed Term Index Calculationoff
any noon
any yes (on principal functor)I(...)
atomic yesI(...)
variable yesI(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 keywordsoff
any 0on
any 2I(...)
atomic 2I(...)
variable 2I(S1,...,Sn)
F(A1,...,Am) 1+K(S1,A1)*...*K(Sj,Aj), j=min(n,m)