Transactions - Custom Entity (EAP)

 

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 data stored in 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();

Related information

Data stored through transactions must still follow limits defined in Custom entities limits.

Limitations

• Rate limits: Maximum is 25 transactions per minute for an installation.
• Payload limit: The payload size is limited to 4MB of data in a single transaction.
• Transaction size: A transaction can contain up to 25 operations.
• Unique keys: Each key can only be used once in a transaction.

Conditions

As part of each operation of a transaction conditions can be specified. These conditions are checked and must be true before processing the operation. Failure of any condition for any operation within a transaction will fail the entire transaction.

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'))