Log API

Datomic's database log is a recording of all transaction data in historic order, organized for efficient access by transaction. You can access the log:

  • Programmatically from methods on Connection
  • Via helper functions inside query

Connection.log and Log.txRange

You can access the log via Connection.log:

datomic.Log log = conn.log();

Given a log, you can retrieve an Iterable over a range in the log with Log.txRange:

Iterable<Map> range = log.txRange(1000, 1020);

The arguments are startT (inclusive), and endT (exclusive). Legal values for these arguments are:

  • txes (transaction entity ids)
  • ts (as e.g. returned from Database.nextT)
  • transaction instants (java.util.Dates)
  • null (to represent the beginning/end of the log)

Each map represents a single transaction, and contains two key/value pairs.

KeywordJava ConstantValue
:tLog.Tthe transaction t
:dataLog.DATAa collection of datoms

The datoms implement the datomic.Datom interface. In Clojure, they act as both sequential and associative collections, and can be destructured accordingly.

Log in Query: tx-ids and tx-data

The log API includes two convenience functions that are available within query. The tx-ids function takes arguments similar to txRange above, but returns a collection of transaction entity ids. You will typically use the collection binding form [?tx …] to capture the results.

[(tx-ids ?log ?t1 ?tx) [?tx ...]]

The following example query returns the count of transactions within the range [t1, t2):

(d/q '[:find (count ?tx)
       :in ?log ?t1 ?t2
       :where [(tx-ids ?log ?t1 ?t2) [?tx ...]]]
     (d/log conn) t1 t2)  

The tx-data function returns the datoms associated with a particular t or tx. You will typically use the relation binding form [ [?e ?a ?v _ ?op ] ] to capture the results.

[(tx-data ?log ?tx) [[?e ?a ?v _ ?op]]]

Note the underscore binding. You should not bind the ?tx position, as ?tx is already bound on input to the function.

tx-data is the efficient way to get transaction data given t or tx. A common scenario is to use tx-data in combination with tx-ids, to return the datoms associated with a range in time. The following example query returns all the entities that were modified on August 1, 2013:

(d/q '[:find ?e
       :in ?log ?t1 ?t2
       :where [(tx-ids ?log ?t1 ?t2) [?tx ...]]
              [(tx-data ?log ?tx) [[?e]]]]
     (d/log conn) #inst "2013-08-01" #inst "2013-08-02")