All functions are located in the com.biffweb namespace.


View source
 {:keys [topology dir opts jdbc-spec pool-opts kv-store tx-fns],
  :or {kv-store :rocksdb},
  :as options})
A higher-level version of xtdb.api/start-node.

Calls xtdb.api/sync before returning the node.

topology:   One of #{:standalone :jdbc}.
kv-store:   One of #{:rocksdb :lmdb}. Default :rocksdb
dir:        A path to store RocksDB instances in.
pool-opts:  Used only when topology is :jdbc. Passed in as
             {:db-spec jdbc-spec :pool-opts pool-opts ...}}.
opts:       Additional options to pass to xtdb.api/start-node.
tx-fns:     A map of transaction functions to be saved after indexing
            finishes. See save-tx-fns!
 {:keys [biff/secret],
  :biff.xtdb/keys [topology kv-store dir opts tx-fns],
  :as ctx})
A Biff component that starts an XTDB node.

Sets :biff.xtdb/node on the system map. topology, kv-store, dir, opts and
tx-fns are passed to start-node. Any keys matching :biff.xtdb.jdbc/* or
:biff.xtdb.jdbc-pool/* are passed in as jdbc-spec and pool-opts,

If :biff/secret is set, the value of :biff.xtdb.jdbc/password will be replaced
with (secret :biff.xtdb.jdbc/password).


View source
 {:keys [biff/plugins biff/features biff.xtdb/on-tx biff.xtdb/node],
  :as ctx})
If on-tx or plugins is provided, starts an XTDB transaction listener.

plugins:  A var containing a collection of plugin maps. Each plugin map may
          contain an :on-tx key.
features: Deprecated. Alias for plugins. plugins takes precedence.
on-tx:    Deprecated. Use plugins instead. If set, takes precedence over

Calls each on-tx function in plugins whenever a new transaction is
successfully indexed. on-tx receives the system map and the transaction, i.e.
(on-tx ctx tx). tx is the transaction as returned by (xtdb.api/open-tx-log
node tx-id true). on-tx will not be called concurrently: if a second
transaction is indexed while on-tx is still running, use-tx-listener will
wait until it finishes before passing the second transaction.


View source
(assoc-db {:keys [biff.xtdb/node], :as ctx})
Sets :biff/db on the context map to (xt/db node)
(q db query & args)
Convenience wrapper for xtdb.api/q.

If the :find value is not a vector, results will be passed through
(map first ...). Also throws an exception if (count args) doesn't match
(count (:in query)).
(lazy-q db query & args)
Calls xtdb.api/open-q and passes a lazy seq of the results to a function.

Accepts the same arguments as xtdb.api/open-q, except the last argument is a
function which must process the results eagerly. Also includes the same
functionality as biff/q.
(lookup db & args)
Returns the first document found with the given key(s) and value(s).

For example:
(lookup db :user/email "hello@example.com")
=> {:xt/id #uuid "...", :user/email "hello@example.com"}

You can pass in a custom pull expression if needed (default is '[*]):
(lookup db '[:xt/id {:msg/_user [:msg/text]}] :user/email "hello@example.com")
=> {:xt/id #uuid "..."
    :msg/_user ({:msg/text "hello"}
                {:msg/text "how do you do"})}


View source
(lookup-all db & args)
Like lookup, but returns multiple documents.


View source
(lookup-id db & kvs)
Returns the ID of the first document found with the given key(s) and value(s).

For example:
(lookup-id db :user/email "hello@example.com")
=> #uuid "..."


View source
(lookup-id-all db & kvs)
Like lookup-id, but returns multiple documents.


View source
 {:keys [biff/now biff/db biff/malli-opts], :as ctx}
Converts the given Biff transaction into an XT transaction.

The elements of biff-tx may be maps (in which case they are treated as Biff
operations) or vectors (in which case they are treated as XT operations). For

[{:db/doc-type :user
  :xt/id #uuid "..."
  :user/name "example"}
 [:xtdb.api/put {:xt/id #uuid "..."}]]

biff-tx may optionally be a function which takes ctx and returns a Biff

See https://biffweb.com/docs/reference/transactions.


View source
(submit-with-retries ctx make-tx)
Submits an XT transaction, retrying up to three times if there is contention.
Blocks until the transaction is indexed or aborted.

make-tx is a one-argument function that takes the context map and returns an
XT transaction. The :biff/db and :biff/now keys in ctx will be updated before
each time make-tx is called.


View source
 {:keys [biff.xtdb/retry biff.xtdb/node], :or {retry true}, :as ctx}
High-level wrapper over xtdb.api/submit-tx. See biff-tx->xt.

If retry is true, the transaction will be passed to submit-with-retries.


View source
(save-tx-fns! node tx-fns)
Saves (or updates) the given transaction functions.

For example, given the map {:foo '(fn ...)}, a transaction of the form
[:xtdb.api/put {:xt/id :foo :xt/fn '(fn ...)}] will be submitted.

If all the given functions are already in the database and haven't been
changed, then no transaction will be submitted.
A map of Biff-provided transaction functions. See use-xt and save-tx-fns!

Includes the following tx fns:

:biff/ensure-unique - Aborts the transaction if more than one document
contains the given key-value pairs. For example:

(biff/submit-tx ctx
  [{:db/doc-type :user
    :db/op :update
    :xt/id user-id
    :user/name "example"}
   [:xtdb.api/fn :biff/ensure-unique {:user/name "example"}]])
Have a question? Join the forum or the #biff channel on Clojurians Slack.

Sign up for Biff: The Newsletter
Announcements, blog posts, et cetera et cetera.
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.