API for datomic.client - Datomic Clojure Client


Full namespace name: datomic.client

Overview

Client library for interacting with Datomic.
Alpha, subject to change.

Functions that interact with the cluster are asynchronous and return
a core.async channel. In the case of an error, an error map is
returned which will return true from 'error?'

All async, channel-returning functions in this namespace
allow an optional :timeout argument in their arg-map.

A database is a descriptor map with possible keys:
:database-id, :t, :next-t, :as-of, :since, :history
Please use the various functions that produce database values
and do not construct these maps directly.

Functions that return chunked results will return a succession of
vectors of values in a channel. The channel will be closed when the
results are exhausted.  If there is an error it will be in the
channel instead of the chunk.

Functions that return datoms return values of a type that supports
indexed (count/nth) access of [e a v t added] as well as
lookup (keyword) access via :e :a :v :t :added.

Public Variables and Functions



as-of

function
Usage: (as-of db t)
Returns the value of the database as of some point t, inclusive. t
can be a transaction number, transaction ID, or Date.

Alpha, subject to change.


connect

function
Usage: (connect arg-map)
Async, see also namespace doc.
Connects to a database described by the argument map, which
has the following keys:

:db-name - a string which names a database.
:timeout - optional, timeout value to use for all remote requests

There are six additional optional keys:

:account-id - must be set to datomic.client/PRO_ACCOUNT
:access-key - access key associated with this account
:secret - secret associated with this account
:endpoint - host and port number for peer-server
:region - must be "none"
:service - must be "peer-server"

The access-key/secret pair must match with one used to launch peer-server.

If the optional keys are not specified, they are read from environment
variables DATOMIC_ACCOUNT_ID, DATOMIC_SECRET, DATOMIC_ENDPOINT, DATOMIC_REGION,
and DATOMIC_SERVICE, respectively, then from the ~/.datomic/config file.

Returns a promise channel that will yield a connection object.

Datomic connections do not adhere to an acquire/use/release
pattern. They are thread-safe and long lived. Connections are cached
such that calling connect multiple times with the same database
value will return the same connection object.

Alpha, subject to change.


datoms

function
Usage: (datoms db {:keys [index components], :as arg-map})
Async and chunked, see also namespace doc.
 Returns datoms from an index as specified by arg-map:

:index - One of :eavt, :aevt, :avet, or :vaet, indicating the
  desired index. EAVT, AEVT, and AVET indexes contain all datoms.
  VAET contains only datoms for attributes of :db.type/ref.
:components - Optional. A vector in the same order as the index
  containing one or more values to further narrow the result
:offset - Optional. Number of results to omit from the beginning of
  the returned data.
:limit - Optional. Maximum total number of results that will be
  returned. Specify -1 to indicate no limit. Defaults to 1000.
:chunk - Optional. Maximum number of results that will be returned
  for each chunk, up to 10000. Defaults to 1000.

Returns a channel which yields chunks of datoms.

Alpha, subject to change.


db

function
Usage: (db conn)
Returns the current value of the database.

Alpha, subject to change.


db-stats

function
Usage: (db-stats db)
Async, see also namespace doc.

Queries for database stats. Returns a promise channel with a map
including at least:

:datoms - total count of datoms in the database, including history.

Alpha, subject to change.


error?

function
Usage: (error? resp)
Returns true if resp is an error map. Use
:cognitect.anomalies/category key to get more info.

  Alpha, subject to change.


history

function
Usage: (history db)
Returns a database value containing all assertions and
retractions across time. A history database can be used for
datoms and index-range calls and queries, but not for with calls.
Note that queries against a history database will include
retractions as well as assertions. These can be distinguished
by the fifth datom field ':added', which is true for asserts
and false for retracts.

Alpha, subject to change.


index-range

function
Usage: (index-range db arg-map)
Async and chunked, see also namespace doc.
Returns datoms from the AVET index as specified by arg-map:

:attrid - An attribute keyword or ID.
:start - Optional. The start point, inclusive, of the requested
  range (as a transaction number, transaction ID, or Date) or
  nil/absent to start from the beginning.
:end - Optional. The end point, exclusive, of the requested range (as a
  transaction number, transaction ID, or Date) or nil/absent to return
  results through the end of the attribute index.
:offset - Optional. Number of results to omit from the beginning of
  the returned data.
:limit - Optional. Maximum total number of results that will be
  returned. Specify -1 to indicate no limit. Defaults to 1000.
:chunk - Maximum number of results that will be returned for each
  chunk, up to 10000. Defaults to 1000.

Returns a channel which yields chunks of datoms.

Alpha, subject to change.


log

function
Usage: (log conn)
Given a connection, returns a log descriptor usable in query.

Alpha, subject to change.


pull

function
Usage: (pull db arg-map)
Async, see also namespace doc.

Returns a promise channel with a hierarchical selection
described by arg-map:

:selector - the selector expression
:eid - an entity id

Alpha, subject to change.


q

function
Usage: (q conn arg-map)
Async and chunked, see also namespace doc.

Performs the query described by arg-map:

:query - The query to perform. A map, list, or string (see below).
:args - data sources for the query, e.g. a database value
  retrieved from a call to db, a list of lists, and/or rules.
:offset - Optional. Number of results to omit from the beginning of
  the returned data.
:limit - Optional. Maximum total number of results that will be
  returned. Specify -1 to indicate no limit. Defaults to 1000.
:chunk - Optional. Maximum number of results that will be returned
  for each chunk, up to 10000. Defaults to 1000.
:timeout - Optional. Amount of time in milliseconds after which
  the query may be cancelled. Defaults to 60000.

:args are data sources i.e. a database value retrieved from
a call to db, a list of lists, and/or rules. If only one data
source is provided, no :in section is required, else the :in section
describes the inputs.

:query can be a map, list, or string:

The query map form is {:find vars-and-aggregates
                       :with vars-included-but-not-returned
                       :in sources
                       :where clauses}
where vars, sources and clauses are lists.

:with is optional, and names vars to be kept in the aggregation set but
not returned.

The query list form is [:find ?var1 ?var2 ...
                        :with ?var3 ...
                        :in $src1 $src2 ...
                        :where clause1 clause2 ...]
The query list form is converted into the map form internally.

The query string form is a string which, when read, results in a
query list form or query map form.

Query parse results are cached.

Returns a channel that yields chunked query result tuples.

Alpha, subject to change.


shutdown

function
Usage: (shutdown conn)
Shuts down this connection, releasing any resources that might be
held open. This is an optional method, and callers are not expected
to call it, but can if they want to explicitly release any open
resources. Once a client has been shutdown, it should not be used to
make any more requests.

Alpha, subject to change.


since

function
Usage: (since db t)
Returns the value of the database since some point t, exclusive.
t is a transaction number, transaction ID, or Date.

Alpha, subject to change.


transact

function
Usage: (transact conn arg-map)
Async, see also namespace doc.

Submits a transaction specified by arg-map:

:tx-data - A list of write operations, each of which is either an
  assertion, a retraction or the invocation of a data function. Each
  nested list starts with a keyword identifying the operation followed
  by the arguments for the operation. Write operations may also be
  maps from attribute identifiers to values to be asserted.

Returns a promise channel that can be used to monitor the
completion of the transaction. See (doc datomic.client). If the
transaction commits, the channel's value is a map with the following
keys:

:db-before - Database value before the transaction
:db-after - Database value after the transaction
:tx-data - Collection of Datoms produced by the transaction
:tempids - A map from tempids to their resolved entity IDs.

Alpha, subject to change.


tx-range

function
Usage: (tx-range conn arg-map)
Async and chunked, see also namespace doc.

Retrieve a range of transactions in the log as specified by arg-map:

:start - Optional. The start point, inclusive, of the requested
  range (as a transaction number, transaction ID, or Date) or nil to
  start from the beginning of the transaction log.
:end - Optional. The end point, exclusive, of the requested
  range (as a transaction number, transaction ID, or Date) or nil to
  return results through the end of the transaction log.
:offset - Optional. Number of results to omit from the beginning of
  the returned data.
:limit - Optional. Maximum total number of results that will be
  returned. Specify -1 to indicate no limit. Defaults to 1000.
:chunk - Optional. Maximum number of results that will be returned
  for each chunk, up to 10000. Defaults to 1000.

Returns a channel which yields chunked transactions.
Transactions are maps with keys:

:t - the T point of the transaction
:tx-data - a collection of the datoms asserted/retracted by the
  transaction

Alpha, subject to change.


with

function
Usage: (with db arg-map)
Async, see also namespace doc.

Applies tx-data to a database that must have been returned from
'with-db' or a prior call to 'with'.  The result of calling 'with'
is as if the data was applied in a transaction, but the source of
the database is unaffected.

Takes data in the same format expected by transact, and returns a
promise channel similar to the return of transact.

Alpha, subject to change.


with-db

function
Usage: (with-db conn)
Async, see also namespace doc.

  Returns a promise channel that yields a database value suitable
for passing to 'with'.

  Alpha, subject to change.

datomic.client.admin

Client library for admin interactions with Datomic.
Alpha, subject to change.


create-database

function
Usage: (create-database arg-map)
Async, see also datomic.client namespace doc.

Creates a database described by the arg-map:

:db-name - a string which names a database.

The arg-map can also contain any of the optional keys listed
for datomic.client/connect.

Returns a promise channel that will yield true.

Alpha, subject to change.

delete-database

function
Usage: (delete-database arg-map)
Async, see also datomic.client namespace doc.

:db-name - a string which names a database.

The arg-map can also contain any of the optional keys listed
for datomic.client/connect.

Returns a promise channel that will yield true.

Alpha, subject to change.

list-databases

function
Usage: (list-databases arg-map)
Async, sell alos datomic.client namespace doc.
Lists all databases for the account specified by the arg-map, which
requires no keys but can contain any of the optional keys listed for
datomic.client/connect

Returns a promise-channel that will yield a collection of database
names.

Alpha, subject to change.
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.