Liking cljdoc? Tell your friends :D

(ns crux.api)

crux.api exposes a union of methods from ICruxNode and ICruxDatasource, with few lifecycle members added.

ICruxNode

db

  (db
    [node]
    [node ^Date valid-time]
    [node ^Date valid-time ^Date transaction-time]
    "Will return the latest value of the db currently known. Non-blocking.

     When a valid time is specified then returned db value contains only those
     documents whose valid time is not after the specified. Non-blocking.

     When both valid and transaction time are specified returns a db value
     as of the valid and transaction time. Will block until the transaction
     time is present in the index.")

document

  (document [node content-hash]
    "Reads a document from the document store based on its
    content hash.")

history

  (history [node eid]
    "Returns the transaction history of an entity, in reverse
    chronological order. Includes corrections, but does not include
    the actual documents.")

history-range

  (history-range [node eid
                  ^Date valid-time-start
                  ^Date transaction-time-start
                  ^Date valid-time-end
                  ^Date transaction-time-end]
    "Returns the transaction history of an entity, ordered by valid
    time / transaction time in chronological order, earliest
    first. Includes corrections, but does not include the actual
    documents.

    Giving null as any of the date arguments makes the range open
    ended for that value.")

status

  (status [node]
    "Returns the status of this node as a map.")

submit-tx

  (submit-tx [node tx-ops]
    "Writes transactions to the log for processing
     tx-ops datalog style transactions.
     Returns a map with details about the submitted transaction,
     including tx-time and tx-id.")

tx-committed?

  (tx-committed? [node submitted-tx]
    "Checks if a submitted tx was successfully committed.
     submitted-tx must be a map returned from `submit-tx`.
     Returns true if the submitted transaction was committed,
     false if the transaction was not committed, and throws `NodeOutOfSyncException`
     if the node has not yet indexed the transaction.")

await-tx

  (await-tx
    [node tx]
    [node tx ^Duration timeout]
    "Blocks until the node has indexed a transaction that is at or past the
  supplied tx. Will throw on timeout. Returns the most recent tx indexed by the
  node.")

await-tx-time

  (await-tx-time
    [node ^Date tx-time]
    [node ^Date tx-time ^Duration timeout]
    "Blocks until the node has indexed a transaction that is past the supplied
  txTime. Will throw on timeout. The returned date is the latest index time when
  this node has caught up as of this call.")

sync

 (sync
    [node]
    [node ^Duration timeout]
    "Blocks until the node has caught up indexing to the latest tx available at
  the time this method is called. Will throw an exception on timeout. The
  returned date is the latest transaction time indexed by this node. This can be
  used as the second parameter in (db valid-time, transaction-time) for
  consistent reads.

  timeout – max time to wait, can be nil for the default.
  Returns the latest known transaction time.")

tx-log

(open-tx-log ^ITxLog [this after-tx-id with-ops?]
  "Reads the transaction log. Optionally includes
  operations, which allow the contents under the :crux.api/tx-ops
  key to be piped into (submit-tx tx-ops) of another
  Crux instance.
  after-tx-id      optional transaction id to start after.
  with-ops?       should the operations with documents be included?
  Returns an iterator of the TxLog.")
  (attribute-stats [node]
    "Returns frequencies of indexed attributes")

attribute-stats

  (attribute-stats [node]
    "Returns frequencies of indexed attributes")

ICruxDatasource

Represents the database as of a specific valid and transaction time.

entity

  (entity [db eid]
    "queries a document map for an entity.
    eid is an object which can be coerced into an entity id.
    returns the entity document map.")

entity-tx

  (entity-tx [db eid]
    "returns the transaction details for an entity. Details
    include tx-id and tx-time.
    eid is an object that can be coerced into an entity id.")

new-snapshot

  (new-snapshot ^java.io.Closeable [db]
     "Returns a new implementation specific snapshot allowing for lazy query
     results in a try-with-resources block using (q db  snapshot  query)}.
     Can also be used for
     (history-ascending db snapshot  eid) and
     (history-descending db snapshot  eid)
     returns an implementation specific snapshot")

q

  (q
    [db query]
    [db snapshot query]
    "q[uery] a Crux db.
    query param is a datalog query in map, vector or string form.
    First signature will evaluate eagerly and will return a set or vector
    of result tuples.
    Second signature accepts a db snapshot, see `new-snapshot`.
    Evaluates *lazily* consequently returns lazy sequence of result tuples.")

history-ascending

  (history-ascending
    [db snapshot eid]
    "Retrieves entity history lazily in chronological order
    from and including the valid time of the db while respecting
    transaction time. Includes the documents.")

history-descending

  (history-descending
    [db snapshot eid]
    "Retrieves entity history lazily in reverse chronological order
    from and including the valid time of the db while respecting
    transaction time. Includes the documents.")

valid-time

  (valid-time [db]
    "returns the valid time of the db.
    If valid time wasn't specified at the moment of the db value retrieval
    then valid time will be time of the latest transaction.")

transaction-time

  (transaction-time [db]
    "returns the time of the latest transaction applied to this db value.
    If a tx time was specified when db value was acquired then returns
    the specified time."))

Lifecycle members

start-node

(defn start-node ^ICruxAPI [options])
requires any dependendies on the classpath that the Crux modules may need.

Options:

{:crux.node/topology ['crux.standalone/topology]}

Options are specified as keywords using their long format name, like :crux.kafka/bootstrap-servers etc. See the individual modules used in the specified topology for option descriptions.

returns a node which implements ICruxAPI and java.io.Closeable. Latter allows the node to be stopped by calling (.close node).

throws IndexVersionOutOfSyncException if the index needs rebuilding. throws NonMonotonicTimeException if the clock has moved backwards since last run. Only applicable when using the event log.

new-api-client

(defn new-api-client ^ICruxAPI [url])

Creates a new remote API client ICruxAPI. The remote client requires valid and transaction time to be specified for all calls to db.

requires either clj-http or http-kit on the classpath, see crux.remote-api-client/internal-http-request-fn for more information.

Param url the URL to a Crux HTTP end-point.

Returns a remote API client.

new-ingest-client

(defn new-ingest-client ^ICruxAsyncIngestAPI [options])

Starts an ingest client for transacting into Kafka without running a full local node with index.

For valid options, see crux.kafka/default-options. Options are specified as keywords using their long format name, like :crux.kafka/bootstrap-servers etc.

Options:

{:crux.kafka/bootstrap-servers "kafka-cluster-kafka-brokers.crux.svc.cluster.local:9092"
:crux.kafka/group-id           "group-id"
:crux.kafka/tx-topic           "crux-transaction-log"
:crux.kafka/doc-topic          "crux-docs"
:crux.kafka/create-topics      true
:crux.kafka/doc-partitions     1
:crux.kafka/replication-factor 1}

Returns a crux.api.ICruxIngestAPI component that implements java.io.Closeable, which allows the client to be stopped by calling close.

Can you improve this documentation? These fine people already did:
Daniel Mason, Jon Pither, James Henderson, Jeremy Taylor, Ivan Fedorov & Antonelli712
Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close