Fetching

Data for a query can be requested at a single moment in time. The Triplit Client provides the methods fetch, fetchOne, and fetchById which will make a single request to your database.

Fetch

fetch() executes the specified query and returns a Map with entity ids as keys and the associated entities as values. For example:

await client.insert('employees', { id: 'Fry', name: 'Philip J. Fry' });
await client.insert('employees', { id: 'Leela', name: 'Turanga Leela' });
 
const query = client.query('employees').build();
const result = await client.fetch(query, options); // Map<string, { name: string }>

FetchOne

fetchOne is similar to fetch() but will return a tuple [id, entity] of the first entity in the result set or null if the result set is empty. For example:

await client.insert('employees', { id: 'Fry', name: 'Philip J. Fry' });
await client.insert('employees', { id: 'Leela', name: 'Turanga Leela' });
 
const query = client.query('employees').build();
const result = await client.fetchOne(query, options); // ['Fry', { name: 'Philip J. Fry' }]
 
const queryEmpty = client
  .query('employees')
  .where('name', '=', 'Bender')
  .build();
const resultEmpty = await client.fetchOne(queryEmpty); // null

This is a convenient shorthand for using the limit parameter .limit(1) and extracting the result from the result set.

FetchById

fetchById() queries for a single entity by its id and returns the entity if it is found or null if it is not. For example:

await client.insert('employees', { id: 'Fry', name: 'Philip J. Fry' });
await client.insert('employees', { id: 'Leela', name: 'Turanga Leela' });
 
const fry = await client.fetchById('employees', 'Fry', options); // { name: 'Philip J. Fry' }
const leela = await client.fetchById('employees', 'Leela', options); // { name: 'Turanga Leela' }
const bender = await client.fetchById('employees', 'Bender', options); // null

This is a convenient shorthand for using the entityId parameter .entityId(id) and extracting the result from the result set.

Fetch options

Because a Triplit Client may be dealing with two databases (your local database and remote database), the exact nature of how you would like to query those is customizable.

If no options are provided, queries will be fulfilled with the options { policy: 'local-first' }.

Policy

The policy option determines how you interact with your local and remote databases.

The following policy types are valid:

• local-first: (default) This policy will fetch data directly from the local database, however if is determined that the query cannot be fulfilled it will fetch data from the remote database. If the remote database fails to fulfill the query, the cached data is used.
• local-only: This policy will fetch data directly from the local database and will never go to the network.
• remote-first: This policy will fetch data from the remote database and update the local database with those results before querying the local database.
• remote-only: This policy will fetch data directly from the remote database and will not update the local database with results. Results using this policy will also not include any data from the local database - notably any data that has been updated locally but not yet synced. This policy is not available on subscriptions.
• local-and-remote: This policy will fetch data from the local database and will fetch results from the remote database in the background and update the local database with those results. Optionally you may provide a timeout parameter, which informs Triplit to wait timeout milliseconds for the remote result to update the local database.