datomic.client.api.async
Async client API for Datomic. See also datomic.client.api
for the corresponding synchronous API.
Functions in this namespace that communicate with a separate process
take an arg-map with the following optional keys:
:timeout timeout in msec
Asynchronous functions return a core.async channel. In the case of an
error, the channel will get an error map with contents specified by
cognitect.anomalies. See https://github.com/cognitect-labs/anomalies.
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. Chunked functions support the following optional
keys:
:chunk Optional. Maximum number of results that will be returned
for each chunk. Defaults to 1000.
:offset Number of results to omit from the beginning
of the returned data.
:limit Maximum total number of results to return.
Specify -1 for no limit. Defaults to 1000.
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.administer-system
(administer-system client arg-map)
Run :action on system.
Currently the only supported action is:
:upgrade-schema upgrade an existing database to use the latest base schema
:upgrade-schema takes the following map
:db-name database name
Returns a diganostic value on success, throws on failure.
client
(client arg-map)
Create a client for a Datomic system. This function does not
communicate with a server and returns immediately.
For a cloud system, arg-map requires:
:server-type - :cloud
:region - AWS region, e.g. "us-east-1"
:system - your system name
:endpoint - IP address of your system or query group
Optionally, a cloud system arg-map accepts:
:creds-provider - instance of com.amazonaws.auth.AWSCredentialsProvider. Defaults to DefaultAWSCredentialsProviderChain
:creds-profile - name of an AWS Named Profile. See http://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html
:proxy-port - local port for SSH tunnel to bastion
Note: :creds-provider and :creds-profile are mutually exclusive, providing both will result in an error.
For a dev-local system, arg-map comprises:
:server-type - :datomic-local (required)
:system - a system name (required)
:storage-dir - optional, overrides :storage-dir in ~/.datomic/dev-local.edn
dev-local stores databases under ${storage-dir}/${system}/${db-name}.
For a peer-server system, arg-map requires:
:server-type - :peer-server
:access-key - access-key from peer server launch
:secret - secret from peer server launch
:endpoint - peer server host:port
:validate-hostnames - false
Returns a client object.connect
(connect client db-name)
Connects to a database. Takes a client object and an arg-map with keys:
:db-name database name
Returns a channel of a connection.
See namespace doc for error and timeout handling.
Returned connection supports ILookup for key-based access. Supported
keys are:
:db-name database name
create-database
(create-database client arg-map)
Creates a database specified by arg-map with key:
:db-name The database name.
Returns a channel of true.
See namespace doc for error and timeout handling.
datoms
(datoms db arg-map)
Returns datoms from an index as specified by arg-map:
:index One of :eavt, :aevt, :avet, or :vaet.
:components Optional vector in the same order as the index
containing one or more values to further narrow the
result
Returns a channel of collections of datoms that will close after all
requested datoms are returned.
Datoms are associative and indexed:
Key Index Value
--------------------------
:e 0 entity id
:a 1 attribute id
:v 2 value
:tx 3 transaction id
:added 4 boolean add/retract
For a description of Datomic indexes, see
https://docs.datomic.com/cloud/query/raw-index-access.html.
See namespace doc for timeout, offset/limit, and error handling.db
(db conn)
Returns the current database value for a connection.
Supports ILookup interface for key-based access. Supported keys are:
:db-name database name
:t basis t for the database
:as-of a point in time
:since a point in time
:history true for history databases
db-stats
(db-stats db)
Queries for database stats.
Returns a channel of a map including at least:
:datoms total count of datoms in the (history) database
See namespace doc for timeout and error handling.
delete-database
(delete-database client arg-map)
Deletes a database specified by arg-map with keys:
:db-name The database name.
Returns a channel of true.
See namespace doc for error and timeout handling.
history
(history db)
Returns a database value containing all assertions and
retractions across time. A history database can be passed to 'datoms',
'index-range', and 'q', but not to 'with' or 'pull'. Note
that queries against a history database will include retractions
as well as assertions. Retractions can be identified by the fifth
datom field ':added', which is true for asserts and false for
retracts.
See https://docs.datomic.com/cloud/time/filters.html.
index-pull
(index-pull db arg-map)
Walks an index, pulling entities via :e if :avet or :v if :aevt,
using the selector.
:index :avet or :aevt
:selector a pull selector (see 'pull')
:start A vector in the same order as the index indicating
the initial position. At least :a must be specified.
Iteration is limited to datoms matching :a.
:reverse optional, when true iterate the index in reverse
order
See namespace doc for timeout, offset/limit, and error handling.
Returns a channel of a mapindex-range
(index-range db arg-map)
Returns datoms from the AVET index as specified by arg-map:
:attrid An attribute entity identifier.
:start Optional. The start value, inclusive, of the requested
range, defaulting to the beginning of the index.
:end Optional. The end value, exclusive, of the requested
range, defaultin to the end of the index.
For a description of Datomic indexes, see
https://docs.datomic.com/cloud/query/raw-index-access.html.
Returns a channel of collections of datoms.
See namespace doc for chunk, offset/limit, timeout, and error handling.list-databases
(list-databases client arg-map)
Lists all databases. arg-map requires no keys but can contain any of
the optional keys listed in the namespace doc.
Returns a channel of a collection of database names.
pull
(pull db arg-map)
Returns a hierarchical selection described by the keys in arg-map:
:selector the selector expression
:eid entity id
For a complete description of the selector syntax, see
https://docs.datomic.com/cloud/query/query-pull.html.
Returns a channel of a map.
You can get information about the I/O reads performed by a
pull with io-stats. To request io-stats, add :io-context
(a qualified keyword) to the arg-map you use to call pull. The return
value will be a map with
:ret the result of the pull
:io-stats io-stats for the pull
The io-stats map includes:
:io-context the io-context passed in
:api :tx-with
:api-ms msec to peform the API call
:reads breakout of reads by cache tier and index sort
:nested breakout iff nested queries set :io-context
See https://docs.datomic.com/cloud/api/io-stats.html.
q
(q arg-map)
Performs the query described by arg-map's :query and :args:
:query The query to perform: a map, list, or string (see below).
:args Data sources for the query, e.g. database values
retrieved from a call to db, and/or rules.
The query list form is [:find ?var1 ?var2 ...
:with ?var3 ...
:in $src1 $src2 ...
:where clause1 clause2 ...]
:find specifies the tuples to be returned
:with is optional, and names vars to be kept in the aggrgation set
but not returned
:in is optional. Omitting ':in ...' is the same as specifying
':in $'
:where limits the result returned
For a complete description of the query syntax, see
https://docs.datomic.com/cloud/query/query-data-reference.html.
Returns a channel of collections of tuples that closes when all results
are returned.
You can get information about the I/O reads performed by a query
with io-stats. To request io-stats, add :io-context (a qualified
keyword) to the arg-map you use to call query. Query will return a map
with
:ret the result of the query
:io-stats io-stats for the query
The io-stats map includes:
:io-context the io-context passed in
:api :tx-with
:api-ms msec to peform the API call
:reads breakout of reads by cache tier and index sort
:nested breakout iff nested queries set :io-context
See https://docs.datomic.com/cloud/api/io-stats.html.
See namespace doc for chunk, offset/limit, timeout, and error handling.qseq
(qseq arg-map)
Performs the query described by query and args (as per 'q'),
returning a channel of collections of tuples that closes when all results
are returned. Item transformations such as
'pull' are deferred until the seq is consumed. For queries with
pull(s), this results in:
* reduced memory use and the ability to execute larger queries
* lower latency before the first results are returned
sync
(sync conn t)
Used to coordinate with other clients.
Returns channel of a database value with basis :t >= t.
Does *not* make a remote call.
transact
(transact conn arg-map)
Submits a transaction specified by arg-map:
:tx-data a collection of list forms or map forms
For a complete specification of the tx-data format, see
https://docs.datomic.com/cloud/transactions/transaction-data-reference.html.
Returns a channel of 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.
You can get information about the I/O reads performed by a
transaction with io-stats. To request io-stats, add :io-context
(a qualified keyword) to the arg-map you use to call transact. The map returned
by transact will include an additional :io-stats keyword whose
value is a map with
:io-context the io-context passed in
:api :tx-with
:api-ms msec to peform the API call
:reads breakout of reads by cache tier and index sort
:nested breakout iff nested queries set :io-context
Note that :api-ms is just the time spent processing the
transaction and does not include queue, storage, or network
latency.
Datomic logs the io-stats for every transaction. If you
pass an :io-context to transact, you can use this context to
correlate transactions with I/O costs after the fact.
See https://docs.datomic.com/cloud/api/io-stats.html.
See namespace doc for timeout and error handling.
tx-range
(tx-range conn arg-map)
Retrieve transactions from the log as specified by arg-map:
:start Optional. The start time-point or nil to start from the
beginning of the transaction log.
:end Optional. The end time-point, exclusive, or nil to
run to the end of the transaction log.
Returns a channel of transactions that will close after all requested
transations are returned.
Transactions have keys:
:t the basis t of the transaction
:data a collection of the datom in the transaction
See datoms for a description of :data value.
See namespace doc for chunk, offset/limit, timeout, and error handling.with
(with db m)
Applies tx-data to a database returned from 'with-db' or a
prior call to 'with'. The result of calling 'with' is a
database value as-if the data was applied in a transaction, but
the durable database is unaffected.
Takes and returns data in the same format expected by transact.
See namespace doc for timeout and error handling.
with-db
(with-db conn)
Returns a channel of a with-db value suitable for passing to 'with'.