Package xtdb.api

Interface IXtdbDatasource

All Superinterfaces:
AutoCloseable, Closeable
public interface IXtdbDatasource extends Closeable
Represents the database as of a specific valid and transaction time.

  • Method Details

    • entity

      XtdbDocument entity(Object eid)
      Returns the document map for an entity.
      Parameters:
      eid - an object that can be coerced into an entity id.
      Returns:
      the entity document map.

    • entityTx

      Map<clojure.lang.Keyword,?> entityTx(Object eid)
      Returns the transaction details for an entity. Details include tx-id and tx-time.
      Parameters:
      eid - an object that can be coerced into an entity id.
      Returns:
      the entity transaction details.

    • query

      Collection<List<?>> query(Object query, Object... args)
      Queries the db. This function will return a set of result tuples if you do not specify `:order-by`, `:limit` or `:offset`; otherwise, it will return a vector of result tuples.
      Parameters:
      query - the query in map, vector or string form.
      args - bindings for in.
      Returns:
      a set or vector of result tuples.

    • openQuery

      ICursor<List<?>> openQuery(Object query, Object... args)
      Queries the db lazily.
      Parameters:
      query - the query in map, vector or string form.
      args - bindings for in.
      Returns:
      a cursor of result tuples.

    • pull

      Map<clojure.lang.Keyword,?> pull(Object projection, Object eid)
      Returns the requested data for the given entity ID, based on the projection spec e.g. `db.pull("[:film/name :film/year]", "spectre")` => `{:film/name "Spectre", :film/year 2015}`
      Parameters:
      projection - An EQL projection spec as a String or Clojure data structure - see https://xtdb.com/reference/queries.html#pull
      eid - entity ID
      Returns:
      the requested projection starting at the given entity

    • pullMany

      List<Map<clojure.lang.Keyword,?>> pullMany(Object projection, Iterable<?> eids)
      Returns the requested data for the given entity IDs, based on the projection spec e.g. `db.pullMany("[:film/name :film/year]", Arrays.asList("spectre", "skyfall"))` => `[{:film/name "Spectre", :film/year 2015}, {:film/name "Skyfall", :film/year 2012}]`
      Parameters:
      projection - An EQL projection spec as a String or Clojure data structure - see https://xtdb.com/reference/queries.html#pull
      eids - entity IDs
      Returns:
      the requested projections starting at the given entities

    • pullMany

      List<Map<clojure.lang.Keyword,?>> pullMany(Object projection, Object... eids)
      Returns the requested data for the given entity IDs, based on the projection spec e.g. `db.pullMany("[:film/name :film/year]", "spectre", "skyfall")` => `[{:film/name "Spectre", :film/year 2015}, {:film/name "Skyfall", :film/year 2012}]`
      Parameters:
      projection - An EQL projection spec - see https://xtdb.com/reference/queries.html#pull
      eids - entity IDs
      Returns:
      the requested projections starting at the given entities

    • entityHistory

      List<Map<clojure.lang.Keyword,?>> entityHistory(Object eid, HistoryOptions options)
      Eagerly retrieves entity history for the given entity. Each entry in the result contains the following keys: * `::xt/valid-time`, * `::xt/tx-time`, * `::xt/tx-id`, * `::xt/content-hash` * `::xt/doc` (if withDocs is set on the options). If withCorrections is set on the options, bitemporal corrections are also included in the sequence, sorted first by valid-time, then tx-id. No matter what `start` and `end` parameters you specify, you won't receive results later than the valid-time and transact-time of this DB value.
      Parameters:
      eid - The entity id to return history for
      Returns:
      an eagerly-evaluated sequence of changes to the given entity.

    • entityHistory

      default List<Map<clojure.lang.Keyword,?>> entityHistory(Object eid, HistoryOptions.SortOrder sortOrder)
      Eagerly retrieves entity history for the given entity.
      Returns:
      an eagerly-evaluated sequence of changes to the given entity.
      See Also:

    • openEntityHistory

      ICursor<Map<clojure.lang.Keyword,?>> openEntityHistory(Object eid, HistoryOptions options)
      Lazily retrieves entity history for the given entity. Don't forget to close the cursor when you've consumed enough history!
      Returns:
      a cursor of changes to the given entity.
      See Also:

    • openEntityHistory

      default ICursor<Map<clojure.lang.Keyword,?>> openEntityHistory(Object eid, HistoryOptions.SortOrder sortOrder)
      Lazily retrieves entity history for the given entity. Don't forget to close the cursor when you've consumed enough history!
      Returns:
      a cursor of changes to the given entity.
      See Also:

    • validTime

      Date validTime()
      The valid time of this db. If valid time wasn't specified at the moment of the db value retrieval then valid time will be time the db value was retrieved.
      Returns:
      the valid time of this db.

    • transactionTime

      Date transactionTime()
      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.

    • dbBasis

      DBBasis dbBasis()
      Returns:
      the basis of this database snapshot.

    • withTx

      IXtdbDatasource withTx(Transaction transaction)
      Returns a new db value with the txOps speculatively applied. The txOps will only be visible in the value returned from this method - they're not submitted to the cluster, nor are they visible to any other database value in your application. If the transaction doesn't commit (eg because of a failed 'match'), this function returns null.
      Parameters:
      transaction - the transaction to be applied.
      Returns:
      a new db value with the transaction speculatively applied.

    • withTx

      @Deprecated IXtdbDatasource withTx(List<List<?>> transaction)
      Deprecated.
      in favour of withTx(Transaction)
      Returns a new db value with the txOps speculatively applied. The txOps will only be visible in the value returned from this method - they're not submitted to the cluster, nor are they visible to any other database value in your application. If the transaction doesn't commit (eg because of a failed 'match'), this function returns null.
      Parameters:
      transaction - the transaction to be applied.
      Returns:
      a new db value with the transaction speculatively applied.