datomic.client.api

Synchronous client library for interacting with Datomic.

This namespace is a wrapper for datomic.client.api.async.

Functions in this namespace that communicate with a separate
process take an arg-map with the following optional keys:

  :timeout   Timeout in msec.

Functions that support offset and limit take the following
additional optional keys:

  :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 -1 for q
             and to 1000 for all other APIs.

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.

All errors are reported via ex-info exceptions, with map contents
as specified by cognitect.anomalies.
See https://github.com/cognitect-labs/anomalies.

Client

protocol

members

connect

(connect client arg-map)
Connects to a database. Takes a client object and an arg-map with keys:

:db-name               database name

Returns 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 true. See namespace doc for error and timeout handling.
NOTE: create-database is not available with peer-server. 
Use a Datomic Peer to create databases with Datomic On-Prem.

delete-database

(delete-database client arg-map)
Deletes a database specified by arg-map with keys:

  :db-name    The database name.

Returns true. See namespace doc for error and timeout handling.
NOTE: delete-database is not available with peer-server. 
Use a Datomic Peer to delete databases with Datomic On-Prem.

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 collection of database names.

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
  :query-group   - your query group name
  :endpoint      - IP address of your system

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 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

Returns a client object.

Connection

protocol

members

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

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 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.

See namespace doc for timeout and error handling.

tx-range

(tx-range conn arg-map)
Retrieve a range of transactions in 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 an Iterable of transactions.
  Transactions have keys:

  :t       the basis t of the transaction
  :data    a collection of the datom in the transaction

See namespace doc for offset/limit, timeout, and error handling.

with-db

(with-db conn)
Returns a with-db value suitable for passing to 'with'.

Db

protocol

members

as-of

(as-of db time-point)
Returns the value of the database as of some time-point.

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

For a description of Datomic indexes, see
https://docs.datomic.com/cloud/query/raw-index-access.html.

Returns an Iterable of datoms. See namespace doc for timeout,
offset/limit, and error handling.

db-stats

(db-stats db)
Queries for database stats. Returns a map including at least:

  :datoms      total count of datoms in the (history) database

See namespace doc for timeout and error 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.

index-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 an Iterable of datoms. See namespace doc for
offset/limit, timeout, and error handling.

pull

(pull db arg-map)(pull db selector eid)
Returns a hierarchical selection described by selector and eid.

  :selector   the selector expression
  :eid        entity id

For a complete decription of the selector syntax, see
https://docs.datomic.com/cloud/query/query-pull.html.

Returns a map.

The arity-2 version takes :selector and :eid in arg-map, which
also supports :timeout. See namespace doc.

since

(since db t)
Returns the value of the database since some time-point.

with

(with db arg-map)
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.

q

(q arg-map)(q query & args)
Performs the query described by 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 collection of tuples.

The arity-1 version takes :query and :args in arg-map, which
allows additional options for :offset, :limit, and :timeout. See
namespace doc.