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 2import { 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.
Data stored through transactions is still subject to Custom entities limits. Transactions are also subject to additional limits, namely:
Category | Limit |
---|---|
Rate limit | Transactions 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.
|
Quota | The transaction.set operation is subject to the quota limits defined in KVS and Custom Entity Store quotas. |
Payload | Each transaction is limited to a payload size of 4MB. |
Transaction operations | Each transaction can contain a maximum of 25 operations. |
Unique keys | Each key can only be used once in a transaction. |
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.
To use either method:
1 2import { 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>"))
Adds an operation to the transaction to set a JSON value with a specified key for a custom entity. Conditions are optional.
1 2transact().set(key: string, value: object, options: { entityName: string, conditions?: Filter }): TransactionBuilder;
1 2await 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')) })
Deletes a value by key for a custom entity, this succeeds whether the key exists or not. Conditions are optional.
1 2transact().delete(key: string, options: { entityName: string, conditions?: Filter }): TransactionBuilder;
1 2await 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')) })
Checks a key meets the specified conditions for a custom entity. Conditions are mandatory.
1 2transact().check(key: string, options: { entityName: string, conditions: Filter }): TransactionBuilder;
1 2await 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: