Key-Value Store
Custom Entity Store
SQL
Cache (EAP)
Last updated Mar 3, 2025

Custom Entity Store Transactions

Transactions allow you to perform multiple conditional operations in a single transaction, ensuring that all operations are either committed if all conditions are met or rolled back together. This works with data stored through the Custom Entity Store.

1
2
import { kvs, Filter, Conditions } from '@forge/kvs';

// Pre define conditions for performing a transaction operation 
const conditions = new Filter().and('surname', FilterConditions.beginsWith('S'))

await kvs
   .transact()
   
   // set key with a value for employee entity
   .set('employee1', {
    surname:"Davis",
    age: 30,
    employmentyear: 2022,
    gender: "male",
    nationality: "Australian"
    }, { entityName: 'employee' })
   
   // conditionally set key with value with inline conditions
   .set('employee2', {
    surname:"Scott",
    age: 30,
    employmentyear: 2022,
    gender: "male",
    nationality: "Australian"
    }, {
     entityName: 'employee',
     conditions: new Filter().and('surname', FilterConditions.beginsWith('S'))
       .and('nationality', FilterConditions.beginsWith('A'))
   })
   
   // delete value for key
   .delete('employee3', { entityName: 'employee' })
   
    // delete value with premade conditions
   .delete('employee4', { entityName: 'employee', conditions }) 
   
   // check if key exists and meets conditions
   .check('employee5', filter, { entityName: 'author', conditions })
   
   // Commit the transaction
   .execute();

This page discusses Custom Entity Store transactions. For Key-Value Store transactions, see here.

Limitations

Data stored through transactions is still subject to Custom entities limits. Transactions are also subject to additional limits, namely:

CategoryLimit
Rate limitTransactions are treated as a single Write operation, subject to the rate limits defined in KVS and Custom Entity Store limits - Future Limits. The transaction will fail if it exceeds these limits, returning a TOO_MANY_REQUESTS error.
QuotaThe transaction.set operation is subject to the quota limits defined in KVS and Custom Entity Store quotas.
PayloadEach transaction is limited to a payload size of 4MB.
Transaction operationsEach transaction can contain a maximum of 25 operations.
Unique keysEach key can only be used once in a transaction.

Conditions

You can specify conditions for each operation of a transaction. Each condition is checked and must be true; if any condition is not met, the entire transaction will fail.

You can specify conditions using the Filter class. This class provides an and() or or() method for adding conditions to the transaction. The conditions that are supported are the same as filters for custom entity querying.

Method signature

To use either method:

1
2
import { Filter, FilterConditions } from '@forge/kvs';

Each filtering method use the following signatures:

  • and: all conditions must be matched.
1
2
.and("<attribute>", FilterConditions.<condition>("<value>"))
  • or: any condition must be matched.
1
2
.or("<attribute>", FilterConditions.<condition>("<value>"))

transact.set

Adds an operation to the transaction to set a JSON value with a specified key for a custom entity. Conditions are optional.

Method signature

1
2
  transact().set(key: string, value: object, options: { entityName: string, conditions?: Filter }): TransactionBuilder;

Example

1
2
await kvs
   .transact()
   
   // set key with a value for employee entity
   .set('employee1', {
    surname:"Davis",
    age: 30,
    employmentyear: 2022,
    gender: "male",
    nationality: "Australian"
    }, { entityName: 'employee' })
   
   // conditionally update key with value for employee entity
   .set('employee2', {
    surname:"Scott",
    age: 30,
    employmentyear: 2022,
    gender: "male",
    nationality: "Australian"
    }, {
     entityName: 'employee',
     conditions: new Filter().and('lastName', FilterConditions.beginsWith('S'))
       .and('nationality', FilterConditions.beginsWith('A'))
   })

transact.delete

Deletes a value by key for a custom entity, this succeeds whether the key exists or not. Conditions are optional.

Method signature

1
2
  transact().delete(key: string, options: { entityName: string, conditions?: Filter }): TransactionBuilder;

Example

1
2
await kvs.transact()
   // delete value for key in employee entity
   .delete('employee1', { entityName: 'employee' })
   
    // delete value for key in employee entity with condition
   .delete('employee2', { entityName: 'employee', conditions: new Filter().or('lastName', FilterConditions.beginsWith('S'))
       .or('lastName', FilterConditions.beginsWith('A')) }) 

transact.check

Checks a key meets the specified conditions for a custom entity. Conditions are mandatory.

Method signature

1
2
  transact().check(key: string, options: { entityName: string, conditions: Filter }): TransactionBuilder;

Example

1
2
await kvs.transact()
    // Check value in key for employee entitiy meets conditions
    .check('employee1', { entityName: 'employee', conditions: new Filter().and('lastName', FilterConditions.beginsWith('S'))

Rate this page: