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.
This is distinct from the syncState parameter on a query, which indicates how you wish to query your local database.
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 atimeout
parameter, which informs Triplit to waittimeout
milliseconds for the remote result to update the local database.