title: Querying data
type: guide
order: 6
version: 0.15

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.

Queries

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 a query expression.

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.

Querying a store's cache

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

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

By querying the cache instead of the store, 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 store.