Skip to main content
Version: Next

Querying data

The contents of a source can be interrogated using a Query. Orbit comes with a standard set of query expressions for finding records and related records. These expressions can be paired with refinements (e.g. filters, sort order, etc.).

Custom query expressions can also be developed, as long as all the sources participating can understand them.

Query expressions#

The base QueryExpression interface consists of:

  • op - a string identifying the type of query operation
  • options - (Optional) a RequestOptions object

The other members of a QueryExpression are specific to the op. The following standard record-specific query expressions are defined in @orbit/records:

interface FindRecord extends QueryExpression {  op: 'findRecord';  record: RecordIdentity;}
interface FindRelatedRecord extends QueryExpression {  op: 'findRelatedRecord';  record: RecordIdentity;  relationship: string;}
interface FindRelatedRecords extends QueryExpression {  op: 'findRelatedRecords';  record: RecordIdentity;  relationship: string;  sort?: SortSpecifier[];  filter?: FilterSpecifier[];  page?: PageSpecifier;}
interface FindRecords extends QueryExpression {  op: 'findRecords';  type?: string;  sort?: SortSpecifier[];  filter?: FilterSpecifier[];  page?: PageSpecifier;}

Supporting interfaces include:

export type SortOrder = 'ascending' | 'descending';
export interface SortSpecifier {  kind: string;  order: SortOrder;}
export interface AttributeSortSpecifier extends SortSpecifier {  kind: 'attribute';  attribute: string;}
export type ComparisonOperator =  | 'equal'  | 'gt'  | 'lt'  | 'gte'  | 'lte'  | 'some'  | 'all'  | 'none';
export interface FilterSpecifier {  op: ComparisonOperator;  kind: string;}
export interface AttributeFilterSpecifier extends FilterSpecifier {  kind: 'attribute';  attribute: string;  value: any;}
export interface PageSpecifier {  kind: string;}
export interface OffsetLimitPageSpecifier extends PageSpecifier {  kind: 'offsetLimit';  offset?: number;  limit?: number;}

Queries#

The Query interface has the following members:

  • id - a string that uniquely identifies the query
  • expressions - an instance or array of QueryExpression objects
  • options - an optional object that represents options that can influence how a query is processed

Although queries can be created "manually", you'll probably find it easier to use a builder function that returns a query.

To use a query builder, pass a function into a source's method that expects a query, such as query or pull. A QueryBuilder that's compatible with the source should be applied as an argument. You can then use this builder to create query expressions.

Standard queries#

You can use the standard @orbit/data query builder as follows:

// Find a single record by identitymemory.query((q) => q.findRecord({ type: 'planet', id: 'earth' }));
// Find all records by typememory.query((q) => q.findRecords('planet'));
// Find a related record in a to-one relationshipmemory.query((q) => q.findRelatedRecord({ type: 'moon', id: 'io' }, 'planet'));
// Find related records in a to-many relationshipmemory.query((q) =>  q.findRelatedRecords({ type: 'planet', id: 'earth' }, 'moons'));

The base findRecords query can be enhanced significantly:

// Sort by namememory.query((q) => q.findRecords('planet')                     .sort('name'));
// Sort by classification, then name (descending)memory.query((q) => q.findRecords('planet')                     .sort('classification', '-name'));
// Filter by a single attributememory.query((q) => q.findRecords('planet')                     .filter({ attribute: 'classification', value: 'terrestrial' });
// Filter by multiple attributesmemory.query((q) => q.findRecords('planet')                     .filter({ attribute: 'classification', value: 'terrestrial' },                             { attribute: 'mass', op: 'gt', value: 987654321 });
// Filter by related recordsmemory.query((q) => q.findRecords('moons')                     .filter({ relation: 'planet', record: { type: 'planet', id: 'earth' }});
// Filter by multiple related recordsmemory.query((q) => q.findRecords('moons')                     .filter({ relation: 'planet', records: [{ type: 'planet', id: 'earth' }, { type: 'planet', id: 'jupiter'}]});
// Paginate by offset and limitmemory.query((q) => q.findRecords('planet')                     .page({ offset: 0, limit: 10 }));
// Combine filtering, sorting, and paginatingmemory.query((q) => q.findRecords('planet')                     .filter({ attribute: 'classification', value: 'terrestrial' })                     .sort('name')                     .page({ offset: 0, limit: 10 }));

The same parameters can be applied to findRelatedRecords:

// Sort by namememory.query((q) => q.findRelatedRecords({ id: 'solar', type: 'planetarySystem' }, 'planets')                     .sort('name'));
// Sort by classification, then name (descending)memory.query((q) => q.findRelatedRecords({ id: 'solar', type: 'planetarySystem' }, 'planets')                     .sort('classification', '-name'));
// Filter by a single attributememory.query((q) => q.findRelatedRecords({ id: 'solar', type: 'planetarySystem' }, 'planets')                     .filter({ attribute: 'classification', value: 'terrestrial' });
// Filter by multiple attributesmemory.query((q) => q.findRelatedRecords({ id: 'solar', type: 'planetarySystem' }, 'planets')                     .filter({ attribute: 'classification', value: 'terrestrial' },                             { attribute: 'mass', op: 'gt', value: 987654321 });
// Filter by related recordsmemory.query((q) => q.findRelatedRecords({ id: 'solar', type: 'planetarySystem' }, 'moons')                     .filter({ relation: 'planet', record: { type: 'planet', id: 'earth' }});
// Filter by multiple related recordsmemory.query((q) => q.findRelatedRecords({ id: 'solar', type: 'planetarySystem' }, 'moons')                     .filter({ relation: 'planet', records: [{ type: 'planet', id: 'earth' }, { type: 'planet', id: 'jupiter'}]});
// Paginate by offset and limitmemory.query((q) => q.findRelatedRecords({ id: 'solar', type: 'planetarySystem' }, 'planets')                     .page({ offset: 0, limit: 10 }));
// Combine filtering, sorting, and paginatingmemory.query((q) => q.findRelatedRecords({ id: 'solar', type: 'planetarySystem' }, 'planets')                     .filter({ attribute: 'classification', value: 'terrestrial' })                     .sort('name')                     .page({ offset: 0, limit: 10 }));

Filtering#

As shown in some of the previous examples, you can filter over the records that are found by a findRecords or findRelatedRecords query. Filtering is done building a boolean expression and only retrieving the records for which this expression returns true. This boolean expression, just like it is with regular javascript, is built out of three parts.

Javascript:

 const denserThanEarth = planets.filter((planet) => {    return planet.density    >     earth.density }) //    |      1       |   2    |      3      |

Filter expression:

const denserThanEarth = orbit.cache.query((q) => {  return q.findRecords('planets')          .filter({ attribute: 'radius', op: 'lt', value: earth.density })}) //             |         1          |    2    |          3           |
  1. the left hand value: This is a reference to the property of the records that you want to compare. This can either be a relationship or an attribute. During evaluation, the reference will be replaced by the actual values of the records.

  2. the comparison operation The operation determines the way the two values will be compared.

  3. the right hand value: This is a value that will remain constant for the entirety of the filter. This value determines, given the operation, which records will be returned and which will not.

Comparison operators for filtering#

There are two different kinds of filtering. Filtering on attribute values and filtering on relationship values. Both have their own comparison operators.

Attribute filtering#

Attribute filtering looks like the following:

const denserThanEarth = orbit.cache.query((q) => {  return q.findRecords('planets')    .filter({ attribute: 'radius', op: 'lt', value: earth.density })})

For attribute filtering, the following comparison operators are available.

  • equal: alias for the === operator.
  • gt: alias for the > operator.
  • lt: alias for the < operator.
  • gte: alias for the >= operator.
  • lte: alias for the <= operator.

Relationship filtering#

Relationship filtering has two types:

Filtering on a hasOne relationship:

const moonsOfJupiter = orbit.cache.query((q) => {  return q.findRecords('moon')          .filter({ relationship: 'planet', op: 'equal', record: { type: 'planet', id: 'jupiter' } })})

Filtering on a hasMany relationship:

const theSolarSystem = orbit.cache.query((q) => {  return q.findRecords('planetarySystem')          .filter({            relationship: 'planets',            op: 'some',            records: [{ type: 'planet', id: 'earth' }]          })})

Filtering on a hasOne relationship has different comparison operations available than filtering on a hasMany relationship.

hasOne operations:

  • equal: returns a record if the left hand relationship is equal to the right hand relationship.

hasMany operations:

  • equal: returns a record if the left hand relationsips are identical to the right hand relationships.
  • all: returns a record if the left hand relationships contain all the right hand relationships.
  • some: returns a record if the left hand relationships contain one or more of the right hand relationships.
  • none: returns a record if none of the left hand relationships are present in the right hand relationships.

findRelatedRecords vs findRecords.filter({ relation: ..., record: ... })#

If you're using the default settings for JSONAPISource, findRelatedRecords and findRecords.filter(...) produce very different URLs.

const relatedRecordId = { type: 'planet', id: 'earth' };
// This fetches from: /planets/earth/moonsmemory.query((q) => q.findRelatedRecords(relatedRecordId, 'moons'));
// This fetches from: /moons?filter[planet]=earthmemory.query((q) => q.findRecords('moon')).filter({ relation: 'planet', record: relatedRecordId });

Query options#

Options can be added to queries to provide processing instructions to particular sources and to include metadata about queries.

For example, the following query is given a label and contains instructions for the source named remote:

memory.query((q) => q.findRecords('contact').sort('lastName', 'firstName'), {  label: 'Find all contacts',  sources: {    remote: {      include: ['phone-numbers']    }  }});

A label can be useful for providing an understanding of actions that have been queued for processing.

The sources: { ${sourceName}: sourceSpecificOptions } pattern is used to pass options that only a particular source will understand when processing a query. In this instance, we're telling a source named remote (let's say it's a JSONAPISource) to include include=phone-numbers as a query param. This will result in a server response that includes contacts together with their related phone numbers.

It is possible to pass different options to each expression in the query.

memory.query((q) => [  q.findRecords('contact').options({ include: ['phone-numbers'] }),  q.findRecords('meeting').options({ include: ['location'] })]);

Querying a memory source's cache#

Note that memory.query is asynchronous and thus returns results wrapped in a promise. This may seem strange at first because the memory source's data is "in memory". In fact, if you want to just "peek" into the contents of the memory source, you can issue the same queries synchronously against the memory source's Cache. For example:

// Results will be returned synchronously by querying the cacheconst planets = memory.cache.query((q) => q.findRecords('planet').sort('name'));

By querying the cache instead of the memory source, you're not allowing other sources to participate in the fulfillment of the query. If you want to coordinate queries across multiple sources, it's critical to make requests directly on the memory source.

Live queries#

On a memory source's cach, you can subscribe to a SyncLiveQuery. For that you need to request a SyncLiveQuery instance and then subscribe to changes. By default the SyncLiveQuery will observe cache patch events with a debounce. The subscription callback will be called on every operation which is relevant to the query.

// Create a new LiveQuery instanceconst planetsLiveQuery = memory.cache.liveQuery((q) => q.findRecords('planet'));// Subscribe to LiveQuery changesconst unsubscribe = planetsLiveQuery.subscribe((update) => {  // Query for results when a change occure  update.query();});// Unsubscribe from the LiveQueryunsubscribe();
tip

If you use a pull based reactive system (for example Glimmer tracking) you can set debounceLiveQueries option to false on memory cache.