Package xtdb.api

Interface IXtdb

All Superinterfaces:
AutoCloseable, Closeable, IXtdbSubmitClient
public interface IXtdb extends IXtdbSubmitClient, Closeable
Provides API access to XTDB.

  • Field Details

    • TX_INDEXED_EVENT_OPTS

      static final Map<clojure.lang.Keyword,?> TX_INDEXED_EVENT_OPTS
      Temporary helper value to pass to `listen`, to subscribe to tx-indexed events.

  • Method Details

    • startNode

      static IXtdb startNode()
      Starts an in-memory query node.

      When you're done, close the node with Closeable.close()

      Returns:
      the started node
      See Also:

    • startNode

      static IXtdb startNode(Map<?,?> options) throws IndexVersionOutOfSyncException
      Starts an XTDB node using the provided configuration.

      When you're done, close the node with Closeable.close()

      Parameters:
      options - a Map of XTDB configuration
      Returns:
      the started node.
      Throws:
      IndexVersionOutOfSyncException - if the index needs rebuilding.
      See Also:

    • startNode

      static IXtdb startNode(File file) throws IndexVersionOutOfSyncException
      Starts an XTDB node using the provided configuration.

      When you're done, close the node with Closeable.close()

      Parameters:
      file - a JSON or EDN file containing XTDB configuration
      Returns:
      the started node.
      Throws:
      IndexVersionOutOfSyncException - if the index needs rebuilding.
      See Also:

    • startNode

      static IXtdb startNode(URL url) throws IndexVersionOutOfSyncException
      Starts an XTDB node using the provided configuration.

      When you're done, close the node with Closeable.close()

      Parameters:
      url - a URL of a JSON or EDN file containing XTDB configuration
      Returns:
      the started node.
      Throws:
      IndexVersionOutOfSyncException - if the index needs rebuilding.
      See Also:

    • startNode

      static IXtdb startNode(Consumer<NodeConfiguration.Builder> f) throws IndexVersionOutOfSyncException
      Starts an XTDB node using the provided configuration. 

       IXtdb xtdbNode = IXtdb.startNode(n -> {
   // ...
 });

      When you're done, close the node with Closeable.close()

      Parameters:
      f - a callback, provided with an object to configure the node before it starts.
      Returns:
      the started node.
      Throws:
      IndexVersionOutOfSyncException - if the index needs rebuilding.
      See Also:

    • startNode

      static IXtdb startNode(NodeConfiguration configuration) throws IndexVersionOutOfSyncException
      Throws:
      IndexVersionOutOfSyncException

    • newApiClient

      static IXtdb newApiClient(String url)
      Creates a new remote API client.

      NOTE: requires xtdb-http-client on the classpath.

      When you're done, close the node with Closeable.close()

      Parameters:
      url - the URL to an XTDB HTTP end-point.
      Returns:
      a remote API client.

    • newApiClient

      static IXtdb newApiClient(String url, RemoteClientOptions options)
      Creates a new remote API client.

      NOTE: requires xtdb-http-client on the classpath.

      When you're done, close the node with Closeable.close()

      Parameters:
      url - the URL to an XTDB HTTP end-point.
      options - options for the remote client.
      Returns:
      a remote API client.

    • db

      IXtdbDatasource db()
      Returns a db as of now. Will return the latest consistent snapshot of the db currently known. Does not block.

    • openDB

      IXtdbDatasource openDB()
      Returns a db as of now. Will return the latest consistent snapshot of the db currently known. Does not block. This method returns a DB that opens resources shared between method calls - it must be `.close`d when you've finished using it.

    • db

      IXtdbDatasource db(Date validTime)
      Returns a db as of the provided valid time. Will return the latest consistent snapshot of the db currently known, but does not wait for valid time to be current. Does not block.

    • openDB

      IXtdbDatasource openDB(Date validTime)
      Returns a db as of the provided valid time. Will return the latest consistent snapshot of the db currently known, but does not wait for valid time to be current. Does not block. This method returns a DB that opens resources shared between method calls - it must be `.close`d when you've finished using it.

    • db

      IXtdbDatasource db(Date validTime, Date transactionTime) throws NodeOutOfSyncException
      Returns a db as of valid time and transaction time.
      Throws:
      NodeOutOfSyncException - if the node hasn't indexed up to the given `transactionTime`

    • openDB

      IXtdbDatasource openDB(Date validTime, Date transactionTime) throws NodeOutOfSyncException
      Returns a db as of valid time and transaction time. This method returns a DB that opens resources shared between method calls - it must be `.close`d when you've finished using it.
      Throws:
      NodeOutOfSyncException - if the node hasn't indexed up to the given `transactionTime`

    • db

      IXtdbDatasource db(DBBasis dbBasis) throws NodeOutOfSyncException
      Returns a db as of the given basis.
      Throws:
      NodeOutOfSyncException - if the node hasn't indexed up to the given transaction

    • db

      @Deprecated IXtdbDatasource db(Map<clojure.lang.Keyword,?> dbBasis) throws NodeOutOfSyncException
      Deprecated.
      in favour of db(DBBasis)
      Returns a db as of the given basis.
      Throws:
      NodeOutOfSyncException - if the node hasn't indexed up to the given transaction

    • db

      IXtdbDatasource db(TransactionInstant txInstant) throws NodeOutOfSyncException
      Returns a db as of the TransactionInstant, with valid-time set to the invocation time of this method.
      Throws:
      NodeOutOfSyncException - if the node hasn't indexed up to the given transaction

    • openDB

      IXtdbDatasource openDB(DBBasis dbBasis) throws NodeOutOfSyncException
      Returns a db as of the given basis. This method returns a DB that opens resources shared between method calls - it must be `.close`d when you've finished using it.
      Throws:
      NodeOutOfSyncException - if the node hasn't indexed up to the given transaction

    • openDB

      @Deprecated IXtdbDatasource openDB(Map<clojure.lang.Keyword,?> dbBasis) throws NodeOutOfSyncException
      Deprecated.
      in favour of openDB(DBBasis) or openDB(TransactionInstant)
      Returns a db as of the given basis. This method returns a DB that opens resources shared between method calls - it must be `.close`d when you've finished using it.
      Throws:
      NodeOutOfSyncException - if the node hasn't indexed up to the given transaction

    • openDB

      IXtdbDatasource openDB(TransactionInstant txInstant) throws NodeOutOfSyncException
      Returns a db as of the TransactionInstant, with valid-time set to the invocation time of this method. This method returns a DB that opens resources shared between method calls - it must be `.close`d when you've finished using it.
      Throws:
      NodeOutOfSyncException - if the node hasn't indexed up to the given transaction

    • status

      Map<clojure.lang.Keyword,?> status()
      Returns the status of this node as a map.
      Returns:
      the status map.

    • hasTxCommitted

      boolean hasTxCommitted(TransactionInstant submittedTx) throws NodeOutOfSyncException
      Checks if a submitted tx was successfully committed.
      Parameters:
      submittedTx - must be a transaction instant returned from IXtdbSubmitClient.submitTx(Transaction txOps).
      Returns:
      true if the submitted transaction was committed, false if it was not committed.
      Throws:
      NodeOutOfSyncException - if the node has not yet indexed the transaction.

    • hasTxCommitted

      @Deprecated boolean hasTxCommitted(Map<clojure.lang.Keyword,?> submittedTx) throws NodeOutOfSyncException
      Deprecated.
      in favour of hasTxCommitted(TransactionInstant)
      Checks if a submitted tx was successfully committed.
      Parameters:
      submittedTx - must be a transaction instant returned from IXtdbSubmitClient.submitTx(List))}.
      Returns:
      true if the submitted transaction was committed, false if it was not committed.
      Throws:
      NodeOutOfSyncException - if the node has not yet indexed the transaction.

    • sync

      Date sync(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.
      Parameters:
      timeout - max time to wait, can be null for the default.
      Returns:
      the latest known transaction time.

    • awaitTxTime

      Date awaitTxTime(Date txTime, 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.
      Parameters:
      txTime - transaction time to await.
      timeout - max time to wait, can be null for the default.
      Returns:
      the latest known transaction time.

    • awaitTx

      TransactionInstant awaitTx(TransactionInstant 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.
      Parameters:
      tx - Transaction to await, as returned from submitTx.
      timeout - max time to wait, can be null for the default.
      Returns:
      the latest known transaction.

    • awaitTx

      @Deprecated Map<clojure.lang.Keyword,?> awaitTx(Map<clojure.lang.Keyword,?> tx, Duration timeout)
      Deprecated.
      in favour of awaitTx(TransactionInstant, Duration)
      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.
      Parameters:
      tx - Transaction to await, as returned from submitTx.
      timeout - max time to wait, can be null for the default.
      Returns:
      the latest known transaction.

    • listen

      AutoCloseable listen(Map<clojure.lang.Keyword,?> eventOpts, Consumer<Map<clojure.lang.Keyword,?>> listener)
      Attaches a listener to XTDB's event bus. We currently only support one public event-type: `::xt/indexed-tx`. Supplying `:with-tx-ops? true` will include the transaction's operations in the event passed to `f`. See/use TX_INDEXED_EVENT_OPTS This is an experimental API, subject to change.
      Parameters:
      eventOpts - should contain `::xt/event-type`, along with any other options the event-type requires.
      Returns:
      an AutoCloseable - closing the return value detaches the listener.

    • latestCompletedTx

      TransactionInstant latestCompletedTx()
      Returns:
      the latest transaction to have been indexed by this node.

    • latestSubmittedTx

      TransactionInstant latestSubmittedTx()
      Returns:
      the latest transaction to have been submitted to this cluster

    • attributeStats

      Map<clojure.lang.Keyword,Long> attributeStats()
      Return frequencies of indexed attributes.
      Returns:
      Map containing attribute freqencies.

    • activeQueries

      List<IQueryState> activeQueries()
      Returns a list of currently running queries.
      Returns:
      List containing maps with query information.

    • recentQueries

      List<IQueryState> recentQueries()
      Returns a list of recently completed/failed queries
      Returns:
      List containing maps with query information.

    • slowestQueries

      List<IQueryState> slowestQueries()
      Returns a list of slowest completed/failed queries ran on the node
      Returns:
      List containing maps with query information.