TypeDB 3.0 is live! Get started for free.

Transactions

Transactionality

TypeDB transactions come in 3 flavors: read, write, and schema transactions. All transactions operate over snapshots of the database, providing a consistent view regardless of the operations performed in concurrent transactions.

TypeDB transactions provide ACID guarantees up to snapshot isolation.

Read transactions

Read transactions can execute only read queries, and will error when provided data update queries or schema mutation queries.

  • They are the most lightweight and should be used whenever possible.

  • Any number of read transactions can be opened concurrently, and they will never fail to open even when write or schema transactions are open.

Write transactions

Write transactions can execute read queries and data update queries, and will error when provided schema mutation queries.

  • Write transactions can be opened concurrently to other write transactions and read transactions.

  • Write transactions may fail on commit, as required to enforce data consistency and isolation, such as when two write transactions concurrently update same piece of data and commit.

Example of conflicting writes

  1. We open transaction 1 and modify the owned attribute of an entity.

  2. We then open transaction 2 before transaction 1 has been committed, and modify the same ownership.

  3. If we commit first transaction 1, then transaction 2, the commit of transaction 2 will fail.

Schema transactions

Schema transactions can execute any type of query: read, data update, and schema mutation queries. They thus subsume the previous two transaction types.

  • Schema transactions are exclusive both against other schema transactions and write transactions. Existing open write transactions will block schema transactions from opening. Similarly, a schema transaction will block write transactions from opening. This prevents the data from mutating while the schema is being updated.

  • Schema transactions can mutate both data and schema at the same time, allowing atomic migrations from one database state to another.

Executing queries in transaction

All transactions types have an identical API to submit queries.

  • Studio

  • Console

  • Python

  • Rust

  • Java

Select your database using the database selector (database none), then select your transaction type in the top menu.

Open your query file. Run the query by clicking the studio run Run Query button. Finally, use the commit button (studio check) to persist any changes made.

Open the transaction with

transaction my-db <TYPE>

where <TYPE> can be one of schema, write, or read.

Then run your queries in the newly opened prompt, using enters for newlines and double enters for query submissions. Use

commit

if you want to commit changes, or press Ctrl+C (interrupt) or Ctrl+D (end of input) to terminate the transaction without committing.

Open a transaction and send a query with

with driver.transaction(<DATABASE NAME>, TransactionType.<TYPE>) as transaction:
    answer = transaction.query(<QUERY>).resolve()

where:

  • <QUERY> and <DATABASE NAME> are str s.

  • <TYPE> can be one of SCHEMA, WRITE, or READ.

Use

transaction.commit()

if you want to commit changes.

Open a transaction and send a query with

let transaction = driver.transaction(<DATABASE NAME>, TransactionType::<TYPE>).await.unwrap();
{
    let answer = transaction.query(<QUERY>).await.unwrap();
}

where:

  • <QUERY> and <DATABASE NAME> are &str s.

  • <TYPE> can be one of Schema, Write, or Read.

Use

transaction.commit().await.unwrap();

if you want to commit changes.

Open a transaction and send a query with

try (TypeDBTransaction transaction = session.transaction(<DATABASE NAME>, Transaction.Type.<TYPE>)) {
    transaction.query(<QUERY>).resolve();
}

where:

  • <QUERY> and <DATABASE NAME> are String s.

  • <TYPE> can be one of SCHEMA, WRITE, or READ.

Use

transaction.commit();

if you want to commit changes.