Filter by keyword
Key-Value Store
Custom Entity Store
SQL (Preview)
Cache (EAP)

Transactions - Key-Value Store (EAP)

On This Page

    Transactions is now available as part of our Early Access Program (EAP). To start testing this feature, sign up using this form.

    Transactions is an experimental feature offered for testing and feedback purposes. This feature is unsupported and subject to change without notice. Do not use transactions in apps that handle sensitive information, including personal data and customer data.

    For more details, see Forge EAP, Preview, and GA.

     

    Transactions allow you to perform multiple operations in a single transaction, ensuring that all operations are either committed or rolled back together. This works with data stored through the Key-Value Store's basic methods:

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { kvs } from '@forge/kvs';

await kvs.transact()
    // set first key with value
    .set('key1', 'value1')
    
    // delete second key
    .delete('key2')
    
    //set third key with value
    .set('key3', 'value3')
    
    //commit the transaction
    .execute();

    This page covers transaction usage for Key-Value Store. For transactions with the Custom Entity Store, see here.

    Data stored through transactions must still follow limits defined in Forge hosted storage key and object size 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.

    transact.set

    Adds an operation to the transaction to set a JSON value with a specified key.

    Method signature

    1
2
      transact.set(key: string, value: array | boolean | number | object | string): TransactionBuilder;

    Example

    1
2
    // array
kvs.transact().set('example-key', [ 'Hello', 'World' ])

// boolean
kvs.transact().set('example-key', true);

// number
kvs.transact().set('example-key', 123);

// object
kvs.transact().set('example-key', { hello: 'world' });

// string
kvs.transact().set('example-key', 'Hello world');

    transact.delete

    Deletes a value by key, this succeeds whether the key exists or not.

    Method signature

    1
2
      transact.delete(key: string): TransactionBuilder;

    Example

    1
2
    kvs.transact().delete('example-key');

    Rate this page: