Skip to content
DXOS LogotypeDXOS LogotypeDXOS Documentation

Filter

import { Filter } from '@dxos/echo';

Build a predicate, then pass it to db.query directly or through Query.select. Every builder is O(1): it creates an AST node and matches nothing until the query runs.

Member Signature Summary
type (type, props?) => Filter<T> Objects of a type, optionally by props
props (props) => Filter<T> Objects whose fields match
eq neq (value) => Filter<T> Equal, not equal
gt gte lt lte (value) => Filter<T> Ordered comparison
between (from, to) => Filter<T> From inclusive, to exclusive
contains (value) => Filter<readonly T[]> Array field holds the value
and or not (...filters) => Filter<T> Boolean combinators
text (text, options?) => Filter Full-text or vector search
created updated ({ after?, before? }) => Filter Timestamp range

Match by type

Section titled “Match by type”

type takes an ECHO type and an optional props shape, so field names and value types are checked. props matches on shape alone.

const 
const urgent: Filter.Filter<unknown>
urgent = 
import Filter
Filter.
const type: (input: Type.AnyEntity | URI, props?: Filter.Props<unknown>) => Filter.Filter<unknown> (+4 overloads)
type(
class Task
Task, { 
priority: Filter.Filter<number | undefined>
priority: 
import Filter
Filter.
const gte: <number>(value: number) => Filter.Filter<number | undefined>
Predicate for property to be greater than or equal to the provided value.
@performance ― O(1); builds a filter AST node without matching anything.
gte(8) });
const 
const untyped: Filter.Filter<{
    priority: number;
}>
untyped = 
import Filter
Filter.
const props: <{
    priority: number;
}>(props: Filter.Props<{
    priority: number;
}>) => Filter.Filter<{
    priority: number;
}>
Filter by properties.
@performance ― O(p) in the number of predicates; builds the AST without matching anything.
props<{ 
priority: number
priority: number }>({ 
priority?: number | Filter.Filter<number> | undefined
priority: 8 });

Compare a field

Section titled “Compare a field”

Comparators go in the props shape, on the field they test.

const 
const midrange: Filter.Filter<Task & OfKind<EntityKind.Object>>
midrange = 
import Filter
Filter.
const type: <typeof Task>(type: typeof Task, props?: Filter.Props<Task & OfKind<EntityKind.Object>> | undefined) => Filter.Filter<Task & OfKind<EntityKind.Object>> (+4 overloads)
type(
class Task
Task, { 
priority?: number | Filter.Filter<number> | undefined
priority: 
import Filter
Filter.
const between: <number>(from: number, to: number) => Filter.Filter<number>
Predicate for property to be in the provided range.
@param ― from - Start of the range (inclusive).
@param ― to - End of the range (exclusive).
@performance ― O(1); builds a filter AST node without matching anything.
between(3, 7) });
const 
const tagged: Filter.Filter<unknown>
tagged = 
import Filter
Filter.
const type: (input: Type.AnyEntity | URI, props?: Filter.Props<unknown>) => Filter.Filter<unknown> (+4 overloads)
type(
class Task
Task, { 
tags: Filter.Filter<readonly string[] | undefined>
tags: 
import Filter
Filter.
const contains: <string>(value: string) => Filter.Filter<readonly string[] | undefined>
Predicate for an array property to contain the provided value.
@param ― value - Value to check against.
@performance ― O(1); builds a filter AST node without matching anything.
contains('docs') });

Combine filters

Section titled “Combine filters”
const 
const triage: Filter.Filter<unknown>
triage = 
import Filter
Filter.
const and: <[Filter.Filter<Task & OfKind<EntityKind.Object>>, Filter.Filter<unknown>, Filter.Filter<Task & OfKind<EntityKind.Object>>]>(filters_0: Filter.Filter<Task & OfKind<EntityKind.Object>>, filters_1: Filter.Filter<unknown>, filters_2: Filter.Filter<Task & OfKind<EntityKind.Object>>) => Filter.Filter<unknown>
Combine filters with a logical AND.
@performance ― O(k) in the number of filters; builds the AST without matching anything.
and(
import Filter
Filter.
const type: <typeof Task>(type: typeof Task, props?: Filter.Props<Task & OfKind<EntityKind.Object>> | undefined) => Filter.Filter<Task & OfKind<EntityKind.Object>> (+4 overloads)
type(
class Task
Task), 
import Filter
Filter.
const or: <[Filter.Filter<unknown>, Filter.Filter<unknown>]>(filters_0: Filter.Filter<unknown>, filters_1: Filter.Filter<unknown>) => Filter.Filter<unknown>
Combine filters with a logical OR.
@performance ― O(k) in the number of filters; builds the AST without matching anything.
or(
const urgent: Filter.Filter<unknown>
urgent, 
const tagged: Filter.Filter<unknown>
tagged), 
import Filter
Filter.
const not: <Filter.Filter<Task & OfKind<EntityKind.Object>>>(filter: Filter.Filter<Task & OfKind<EntityKind.Object>>) => Filter.Filter<Task & OfKind<EntityKind.Object>>
Negate the filter.
@performance ― O(1); builds a filter AST node without matching anything.
not(
const midrange: Filter.Filter<Task & OfKind<EntityKind.Object>>
midrange));
const 
const results: unknown[]
results = await 
const db: Database.Database
db.
Database.query: Database.QueryFn
<Query.Query<unknown>>(query: Query.Query<unknown>) => QueryResult<unknown> (+1 overload)
query(
import Query
Query.
const select: <Filter.Filter<unknown>>(filter: Filter.Filter<unknown>) => Query.Query<unknown>
Select objects based on a filter.
@param ― filter - Filter to select the objects.
@returns ― Query for the selected objects.
@performance ― O(1); wraps the current AST in a new immutable node without executing anything.
select(
const triage: Filter.Filter<unknown>
triage)).
QueryResult<unknown>.run(opts?: RunOptions): Promise<unknown[]>
Returns all known results.
@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();

Search text

Section titled “Search text”

options.type selects full-text or vector.

const 
const matches: Filter.Any
matches = 
import Filter
Filter.
const text: (text: string, options?: Filter.TextSearchOptions) => Filter.Any
Full-text or vector search.
@performance ― O(1); builds a filter AST node without matching anything.
text('conflict resolution', { 
type?: "full-text" | "vector" | undefined
type: 'full-text' });

Filter by time

Section titled “Filter by time”

Both bounds accept a number of milliseconds or a Date. With both set, the filter is the AND of the two.

const 
const recent: Filter.Any
recent = 
import Filter
Filter.
const updated: (range: TimeRange) => Filter.Any
Filter objects by updatedAt timestamp.
@performance ― O(1); builds a filter AST node without matching anything.
updated({ 
after?: number | Date | undefined
after: new 
var Date: DateConstructor
new (value: number | string | Date) => Date (+3 overloads)
Date('2026-11-01') });