Project

Namespaces

Public Vars

xtdb.api

This namespace is the main public Clojure API to XTDB.

It lives in the `com.xtdb/xtdb-api` artifact - include this in your dependency manager of choice.

To start a node, you will additionally need:

* `xtdb.node`, for an in-process node.
* `xtdb.client`, for a remote client.

execute-tx

(execute-tx node tx-ops)(execute-tx node tx-ops tx-opts)
Executes a transaction; blocks waiting for the receiving node to index it.

tx-ops: XTQL/SQL style transactions.
  [[:put-docs :table {:xt/id "my-id", ...}]
   [:delete-docs :table "my-id"]

   [:sql "INSERT INTO foo (xt$id, a, b) VALUES ('foo', ?, ?)"
    [0 1]]

   [:sql "INSERT INTO foo (xt$id, a, b) VALUES ('foo', ?, ?)"
    [2 3] [4 5] [6 7]]

   [:sql "UPDATE foo SET b = 1"]]

Returns a map with details about the submitted transaction, including system-time and tx-id.

opts (map):
 - :system-time
   overrides system-time for the transaction,
   mustn't be earlier than any previous system-time

 - :default-tz
   overrides the default time zone for the transaction,
   should be an instance of java.time.ZoneId

q

(q node query)(q node query opts)
query an XTDB node.

- query: either an XTQL or SQL query.
- opts:
  - `:basis`: see 'Transaction Basis'
  - `:args`: arguments to pass to the query.

For example:

(q node '(from ...))

(q node '(from :foo [{:a $a, :b $b}])
    {:a a-value, :b b-value})

(q node "SELECT foo.id, foo.v FROM foo WHERE foo.id = 'my-foo'")
(q node "SELECT foo.id, foo.v FROM foo WHERE foo.id = ?" {:args [foo-id]})

Please see XTQL/SQL query language docs for more details.

This function returns the results of its query as a vector of maps

Transaction Basis:

In XTDB there are a number of ways to control at what point in time a query is run -
this is done via a basis map optionally supplied as part of the query map.

In the case a basis is not provided the query is guaranteed to run sometime after
the latest transaction submitted by this connection/node.

Alternatively a basis map containing reference to a specific transaction can be supplied,
in this case the query will be run exactly at that transaction, ensuring the repeatability of queries.

This tx reference (known as a TransactionKey) is the same map returned by submit-tx

(q node '(from ...)
   {:basis {:at-tx tx}})

Additionally a Basis Timeout can be supplied to the query map, which if after the specified duration
the query's requested basis is not complete the query will be cancelled.

(q node '(from ...)
   {:tx-timeout (Duration/ofSeconds 1)})

status

(status node)
Returns the status of this node as a map,
including details of both the latest submitted and completed tx

submit-tx

(submit-tx node tx-ops)(submit-tx node tx-ops tx-opts)
Writes transactions to the log for processing

tx-ops: XTQL/SQL style transactions.
  [[:put-docs :table {:xt/id "my-id", ...}]
   [:delete-docs :table "my-id"]

   [:sql "INSERT INTO foo (xt$id, a, b) VALUES ('foo', ?, ?)"
    [0 1]]

   [:sql "INSERT INTO foo (xt$id, a, b) VALUES ('foo', ?, ?)"
    [2 3] [4 5] [6 7]]

   [:sql "UPDATE foo SET b = 1"]]

Returns a map with details about the submitted transaction, including system-time and tx-id.

opts (map):
 - :system-time
   overrides system-time for the transaction,
   mustn't be earlier than any previous system-time

 - :default-tz
   overrides the default time zone for the transaction,
   should be an instance of java.time.ZoneId

template

macro

(template query)
This macro quotes the given query, but additionally allows you to use Clojure's unquote (`~`) and unquote-splicing (`~@`) forms within the quoted form.

Usage:

(defn build-posts-query [{:keys [with-author?]}]
  (xt/template (from :posts [{:xt/id id} text
                             ~@(when with-author?
                                 '[author])])))