A query selects entities from one or more sources and keeps its results current as the data changes, so an app reads
data the same way whether it was written here or by another peer.
A filter is a predicate: it says which entities match, by type, field values, text or time. A query is the shape
around filters: which entities to start from, which references or relations to follow, and how to order, limit and
group the results. Learn to query builds queries for the contacts app.
Order the query results.
Orders are specified in priority order. The first order will be applied first, etc.
Order.property orders by the current result shape's fields, so it works both before and after
an
aggregate
: before, by member (row) properties; after, by the flat record's fields
(any group or aggregate field — e.g. Order.property('lastMessageAt') reorders the groups by
that aggregate).
@param ― order - Order to sort the results.
@returns ― Query for the ordered results.
@performance ― O(k) in the number of orders; builds the AST without executing anything.
@param ― limit - Maximum number of results to return.
@returns ― Query for the limited results.
@performance ― O(1); wraps the current AST in a new immutable node without executing anything.
limit(20);
13
A query can follow references forwards with reference and backwards with referencedBy, and relations with
sourceOf and targetOf. One query answers “the people who work at Acme” without loading each person to check.
A query can also aggregate: count, sum, find the minimum or maximum, or group the results by a field.
entries partition the
results into contiguous groups (one record each), keyed by the record field the group is named
after; with no group entries the entire input aggregates into a single record. Each declared
aggregate becomes a top-level field and can be ordered by with a following
orderBy
using
Order.property
.
Groups are ordered by the first occurrence of their key in the incoming stream, so a preceding
orderBy controls group order in the absence of a following one.
Aggregate.items
's own
order option is a separate, explicit per-group member ordering — pass it there rather than
relying on a preceding orderBy, whose only well-defined job once aggregate follows is
establishing initial group order. For example, message threads ordered by their most recent
message, each retaining up to 20 members newest-first:
@performance ― Async; executes the full query (index plus working set) on every call, not cached; O(n) in the data
the executor examines, not in the result count.
run();
7
A query reads from sources, chosen with Scope: this space, the code-shipped registry of types, or a
feed. Without from, a query reads the database it runs on.
1
import {
import Filter
Filter,
import Query
Query,
import Scope
Scope,
import Type
Type } from'@dxos/echo';
2
3
// Every type this space stores, and every type registered in code.
@performance ― O(k) in the number of scopes; builds the AST without executing anything.
from(
import Scope
Scope.
constspace: (options?: {
id?: string;
includeAllFeeds?: boolean;
}) =>SpaceScope
Scope targeting a space's automerge documents.
With no spaceId, targets the owning space — i.e. the space of whichever database
executes the query — so callers can reference "this space" without looking up its id.
@example
db.query(Filter.type(Person).from(Scope.space())); // owning space
db.query(Filter.type(Person).from(Scope.space({ id: otherSpaceId }))); // a specific space
@performance ― Async; executes the full query (index plus working set) on every call, not cached; O(n) in the data
the executor examines, not in the result count.
A query is live. Its results change when matching data changes, here or on another peer, and subscribers are notified
only when the results change. org.dxos.echo.query#F-2.3
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.
Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(newError('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
Results combine what this tab holds with answers from the index and from EDGE. Each source has its own state, pending
until it first answers, and the results grow as sources answer. A live query never ends: there is no point after which
its results stop changing. org.dxos.echo.query#F-3.3
An entry from the index or EDGE is checked against the object only if this tab holds the object. Otherwise it is shown
on the source’s word until the object loads. org.dxos.echo.query#F-5.2
A page read with skip is cut by the source that answers it. Local writes can drop entries from the page, but they do
not re-page it. A window with a property order and only a limit also admits local matches that sort inside it.
org.dxos.echo.query#F-9.2org.dxos.echo.query#F-9.3
An aggregate from a remote source is adjusted for local changes, but a minimum or maximum that a local removal would
change is marked unverified until the source answers again. org.dxos.echo.query#F-8.3
