Product REST APIs
Async events API
Fetch API
Storage API

In 2024, Forge hosted storage will automatically include data residency. This means that all app data in Forge hosted storage will inherit data residency, in all current and future Atlassian-supported regions.

This implementation will provide your customers with greater control over their app data’s location. For more information, read this announcement.

Query

The Storage API lets you query data stored in the Key-value store and filter the results.

Use the storage.query method to start building a query:

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

When building a query, do not persist cursors, as they may not always be stable. See Cursors for related information.

The Query object is immutable.

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.
  • The Custom entity store supports additional conditions for more complex queries. See Complex queries for details.

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 20.

Method signature

1
2
query.set(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;
}

Rate this page: