Querying key-value pairs

You can use the storage.query method to query data stored through the Key-Value Store's basic methods:

1
2
import { storage, startsWith } from '@forge/api';

await storage.query()
  // Filter the response to only keys that start with the string 'value'
  .where('key', startsWith('value'))

  // Limit the result size to 10 values, up to a maximum of 20
  .limit(10)

  // Use the cursor provided (returned from a previous invocation)
  // Cursors shouldn't be persisted
  .cursor('...')

  // Get a list of results
  .getMany();

Each installation of your app is subject to the Storage API's quotas and limits. See Storage quotas and Storage limits for more details.

query.where

Returns a new query with an additional predicate that returned values must match. Filters are applied server side and have the following restrictions:

• Queries can only target the key field.
• There may only be a single where condition for a query.
• The only condition supported by the Key-value store is startsWith.

If no conditions are supplied, the query iterates over all values.

Method signature

1
2
query.where(field: 'key', condition: Predicate): Query

startsWith condition

You can use the startsWith condition to filter results from the Key-value store. This condition lets you construct a predicate filter only fields that start with the specified string:

1
2
startsWith(value: string): Predicate

query.limit

Returns a new Query with a limit on how many matching values get returned. The query API returns up to 10 values by default, this can be increased to a maximum of 100.

Method signature

1
2
query.limit(limit: number): Query

query.cursor

Returns a new Query that will start after the provided cursor. Cursors enable your app to fetch subsequent pages of results after completing an initial query.

Cursors are returned from the getMany query API.

Method signature

1
2
query.cursor(after: string): Query;

query.getMany

Execute the query and return a list of results up to the provided limit in length. This method returns both the array of results and a cursor that's used to fetch subsequent pages of results.

Method signature

1
2
query.getMany(): Promise<ListResult>;

interface ListResult {
  results: Result[];
  nextCursor?: string;
}

export interface Result {
  key: string;
  value: object;
}

query.getOne

Execute the query and get the first matching result, if any matches exist. If there is no match, the result resolves to undefined.

Method signature

1
2
query.getOne(): Promise<Result | undefined>;

export interface Result {
  key: string;
  value: object;
}