Liking cljdoc? Tell your friends :D

Transactions

Transactions are how you modify data within Crux.

They are comprised of a series of Transaction Operations to be performed.

If the transaction contains pre-conditions, all pre-conditions must pass, or the entire transaction is aborted. This happens at the query node during indexing, and not when submitting the transaction.

Java

A transaction is performed by calling .submitTx on an ICruxIngestAPI with a Transaction object.

The Transaction object can be created by either using Transaction.Builder directly or using a Consumer.

If using the Consumer approach, we recommend importing crux.api.tx.Transaction.buildTx statically for brevity.

link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]

link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]

link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]

// To run the transaction:
link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]

// To run a transaction directly:
link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
Clojure

A transaction is performed by calling crux.db/submit-tx on a node with a list of transaction operations.

(crux/submit-tx node
                [
                ;; Operations
                ])

Operations

There are five transaction (write) operations:

Table 1. Write Operations
OperationPurposePre-condition?

Put

Write a version of a document

Delete

Deletes a specific document

Match

Check the document state against the given document

Evict

Evicts a document entirely, including all historical versions

Function

Runs a transaction function

Java

You can add individual operations to the Transaction.Builder instance with their respective methods.

Clojure

Transaction Operations are vectors which have their associated keyword as their first value.

Put

Puts a Document into Crux. If a document already exists with the same id, a new version of this document will be created at the supplied valid time. See Valid Time for more details.

Java
link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
1Putting a document as of now.
2Putting a document with a specific valid time
3Putting a document with a valid time and end valid time
Clojure
link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]
1Document to add
2(optional) valid time
3(optional) end valid time

Delete

Deletes a Document . See Valid Time for details on how this interacts with multiple versions of the document.

Java
link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
1Deletes as of now
2Deleting with a specific valid time
3Deleting with a valid time and end valid time
Clojure
link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]
1Document ID to be deleted
2(optional) valid time
3(optional) end valid time

Match

Match checks the state of an entity - if the entity doesn’t match the provided document, the transaction will not continue.

Java
link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
1Passes if document1 is exactly present now
2Passes if document2 is exactly present at validTime1
3Passes if there is no document with the id documentId1 present now
4Passes if there is no document with the id documentId2 present at validTime2
5Operation(s) to apply if all preconditions are met
Clojure
link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]
1ID to be matched (for an entity which may or may not exist)
2A specific document revision (or nil)
3(optional) valid time
4Operation(s) to perform if the document is matched

If the document supplied is nil, the match only passes if there does not exist a Document with the given ID.

Evict

Evicts a document from Crux. Historical versions of the document will no longer be available.

Java
link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
Clojure
link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]

Evict is primarily used for GDPR Right to Erasure compliance.

It is important to note that Evict is the only operation which will have effects on the results returned when querying against an earlier Transaction Time.

Transaction Functions

Transaction functions are user-supplied functions that run on the individual Crux nodes when a transaction is being ingested.

Transaction functions can be used, for example, to safely check the current database state before applying a transaction, for integrity checks, or to patch an entity.

Anatomy

link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]
1Transaction functions are passed a context parameter and any number of other parameters.
2The context parameter can be used to obtain a database value using db or open-db.
3Transaction functions should return a list of transaction operations or false

If a list of transaction operations is returned, these are indexed as part of the transaction.

If false is returned, or an exception is thrown, the whole transaction will roll back.

Creating / Updating

Transaction functions are created/updated by submitting a document to Crux with the desired function.

Java

You create a function document with CruxDocument.createFunction.

It takes the ID for the function as well as a string consisting of the Clojure function to run.

link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
Clojure

The document should use the :crux.db/fn key.

link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]
1Note that the function itself is quoted

Usage

When invoking a transaction function, you specify its ID and (optionally) other arguments

Java
link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
Clojure
link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]
1Function ID
2Parameter(s)

Documents

Java

A CruxDocument is created with an ID that must be of a valid type.

The instance itself is immutable and plusing/minusing data yields a new instance of CruxDocument.

Similarly to Transactions, you can use CruxDocument.Builder directly or use the Consumer approach.

link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]

link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]

// You can also chain creating new instances of the document,
// but this will be slow for larger documents.
link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
Clojure

A document is a map from keywords to values.

{:crux.db/id :dbpedia.resource/Pablo-Picasso
 :name "Pablo"
 :last-name "Picasso"}

All documents must contain the :crux.db/id key.

For operations containing documents, the id and the document are hashed, and the operation and hash is submitted to the tx-topic in the event log. The document itself is submitted to the doc-topic, using its content hash as key. In Kafka, the doc-topic is compacted, which enables later deletion of documents.

Valid IDs

Java

The following types of document IDs are allowed:

Table 2. Valid ID types (Java)
TypeExample

Keyword

Keyword.intern("my-id")

String

"my-id"

Long

42L

UUID

UUID.randomUUID()

URI

URI.create("mailto:crux@juxt.pro")

URL

new URL("https://github.com/juxt/crux")

IPersistentMap

PersistentArrayMap.EMPTY.assoc("foo", "bar")

Clojure

The following types of :crux.db/id are allowed:

Table 3. Valid ID types (Clojure)
TypeExample

Keyword

:my-id or :dbpedia.resource/Pablo-Picasso

String

"my-id"

Integers/Longs

42

UUID

#uuid "6f0232d0-f3f9-4020-a75f-17b067f41203"

URI

#crux/id "mailto:crux@juxt.pro"

URL

#crux/id "https://github.com/juxt/crux"

Maps

{:this :id-field}

The #crux/id reader literal will take URI/URL strings and attempt to coerce them into valid IDs.

URIs and URLs are interpreted using Java classes (java.net.URI and java.net.URL respectively) and therefore you can also use these directly.

Transaction Time

When you submit a transaction, the current time will be the Transaction Time.

Valid Times

When an optional valid time is omitted from a transaction operation, the Transaction Time will be used as valid time.

Only Valid Time Provided

When valid time is used as a parameter for Put or Delete, it specifies the time from which the change is valid.

If there is a document, A, already present at the given valid time, the operation’s effect is valid from valid time to the end of the current validity of A.

End Valid Time

When both valid time and end valid time are provided for Put or Delete, the operation’s effect is valid from valid time (inclusive) to end valid time (exclusive).

Awaiting Transactions

After a transaction is submitted, it needs to be indexed before it is visible in Crux DB snapshots.

The return value from submitting the transaction can be used to wait for the transaction to be indexed.

This return value holds both the ID of the transaction, and the Transaction Time

Java

In Java, you receive a TransactionInstant from the submitTx call.

link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
Clojure

In Clojure, you receive a map from submit-tx containing :crux.tx/tx-id and :crux.tx/tx-time

link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]

Speculative transactions

You can submit speculative transactions to Crux, to see what the results of your queries would be if a new transaction were to be applied. This is particularly useful for forecasting/projections or further integrity checks, without persisting the changes or affecting other users of the database.

You’ll receive a new database value, against which you can make queries and entity requests as you would any normal database value. Only you will see the effect of these transactions - they’re not submitted to the cluster, and they’re not visible to any other database value in your application.

Java

You submit these transactions to an instance of ICruxDatasource using withTx:

link:example$test/crux/docs/examples/transactions/TransactionsTest.java[role=include]
Clojure

You submit these transactions to a database value using with-tx:

link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]
link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]
link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]
link:example$test/crux/docs/examples/transactions/transactions_test.clj[role=include]

The entities submitted by the speculative Put take their valid time (if not explicitly specified) from the valid time of the db from which they were forked.

Can you improve this documentation? These fine people already did:
Alistair, Daniel Mason & James Henderson
Edit on GitHub

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

× close