Skip to main content

Creating a Query Builder

const builder = client.queryBuilder();

Methods

collection

Set the collection to query.
builder.collection(name: string)

find

Add complex find conditions using LogicalOperator.
builder.find(callback: (builder: FindBuilder) => LogicalExpression)

whereField

Quick field condition.
builder.whereField(field: string)
Returns a FieldConditionBuilder with operators.

select

Select specific fields.
builder.select(callback: (selection: SelectionBuilder) => SelectionBuilder)

selectFields

Quick field selection.
builder.selectFields(fields: string[])

selectAll

Select all fields.
builder.selectAll()

limit

Set result limit.
builder.limit(count: number)

offset

Set result offset.
builder.offset(count: number)

orderBy

Set sort order.
builder.orderBy(field: string, direction?: 'asc' | 'desc')

groupBy

Group results by field.
builder.groupBy(field: string)

joinOne

One-to-one join.
builder.joinOne(alias: string, collection: string)
Returns a JoinBuilder.

joinMany

One-to-many join.
builder.joinMany(alias: string, collection: string)
Returns a JoinBuilder.

Execution Methods

execute

Execute query and return results.
const result = await builder.execute<T>();

executeUnique

Execute and return single latest record.
const record = await builder.executeUnique<T>();

getQueryRequest

Get the query request object without executing.
const request = builder.getQueryRequest();

Aggregation Methods

count

Count matching records.
const count = await builder.count();

sumBy

Sum a numeric field.
const sum = await builder.sumBy(field: string);

avgBy

Average a numeric field.
const avg = await builder.avgBy(field: string);

minBy

Get minimum value.
const min = await builder.minBy<T>(field: string);

maxBy

Get maximum value.
const max = await builder.maxBy<T>(field: string);

distinctBy

Get distinct values.
const values = await builder.distinctBy(field: string);

countDistinct

Count distinct values.
const count = await builder.countDistinct(field: string);

FieldConditionBuilder Operators

Comparison

.equals(value)
.notEquals(value)
.greaterThan(value)
.lessThan(value)
.greaterThanOrEqual(value)
.lessThanOrEqual(value)
.between(min, max)
.notBetween(min, max)

String

.contains(value)
.startsWith(value)
.endsWith(value)
.regExpMatches(pattern)
.includesCaseInsensitive(value)
.startsWithCaseInsensitive(value)
.endsWithCaseInsensitive(value)
.wildcard(pattern)
.glob(pattern)

Date/Time

.dateEquals(date)
.dateBefore(date)
.dateAfter(date)
.dateBetween(start, end)
.dateToday()
.dateThisWeek()
.dateThisMonth()
.dateThisYear()

Array

.in(values)
.notIn(values)
.arrayLength(length)
.arrayContains(value)
.arrayNotContains(value)

Boolean

.isTrue()
.isFalse()

Existence

.isNull()
.isNotNull()
.exists()
.notExists()
.isEmpty()
.isNotEmpty()

Type Checking

.isString()
.isNumber()
.isBoolean()
.isArray()
.isObject()

Geographical

.geoWithinRadius(lat, lng, radius)
.geoWithinBounds(ne, sw)
.inCountry(code)

JoinBuilder

onField

Set join condition field.
joinBuilder.onField(field: string)
Returns a JoinConditionBuilder.

selectFields

Select fields from joined collection.
joinBuilder.selectFields(fields: string[])

selectAll

Select all fields from joined collection.
joinBuilder.selectAll()

build

Finalize the join.
joinBuilder.build()

JoinConditionBuilder Operators

.equals(value)       // Use '$data.fieldname' to reference parent
.in(values)
.greaterThan(value)
.lessThan(value)
.isNull()
.isNotNull()

LogicalOperator

import { LogicalOperator } from '@onchaindb/sdk';

LogicalOperator.And([...conditions])
LogicalOperator.Or([...conditions])
LogicalOperator.Not(condition)
LogicalOperator.Condition(fieldCondition)

SelectionBuilder

import { SelectionBuilder } from '@onchaindb/sdk';

new SelectionBuilder()
  .field('name')
  .fields(['id', 'email'])
  .nested('profile', nested => nested.field('bio'))
  .excludeFields(['password'])
  .build();

SelectionBuilder.all();  // Select all