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.

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