Query

The query builder API enables you to query the app storage API and returns filtered 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
  .limit(10)

  // Use the cursor provided (returned from a previous invocation)
  .cursor('...')

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

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 supported condition is startsWith. Other more advanced conditions are only enabled by custom entities (see Conditions for complex queries for information).

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

Method signature

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

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 matching result the result resolves to undefined.

Method signature

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

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

startsWith

Constructs a predicate used in the query.where method to filter results. startsWith enforces that the specified field must start with the specified string.

Method signature

1
2
startsWith(value: string): Predicate