Last updated Mar 3, 2025

KVS Transactions

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
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 discusses KVS transactions. For Custom Entity Store transactions, see here.

KVS and Custom Entity Store transactions are not available through the legacy storage module of @forge/api.

Limitations

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

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