Skip to content

SelectQueryBuilder

Defined in: src/query/queryBuilder.ts:92

Builds and runs a query.

The selection is fixed when the builder is created and the filter is added by chaining, so the result type is known before a single predicate is written. Create one with client.select(...) rather than constructing it directly — that is what infers the result shape from the selection.

The query returns flat rows: the selected entity fields and attributes side by side. Naming a schema with from changes what the selection means for nothing but the selected attributes — they come back typed and checked as the schema declares — and has where checked against it, so that filtering on a column the schema does not index, or comparing one against the wrong type, is a compile error. A named schema also restricts the query to entities tagged with its name, and leaves that tag out of the rows’ $attributes and $attributeSchema.

Every filter added with where, ownedBy and createdBy must hold; use or for alternatives inside one call. orderBy sorts what they match.

import { createPublicClient } from "@arkiv-network/sdk"
import { dec } from "@arkiv-network/sdk/schema"
import { rabdi } from "@arkiv-network/sdk/chains"
import { and, desc, eq, gt } from "@arkiv-network/sdk/query"
import { http } from "viem"
const client = createPublicClient({ chain: rabdi({ accessKey: "..." }), transport: http() })
const page = await client
.select({ $key: true, author: true, title: true })
.from(Posts)
.where(and(eq("category", "docs"), gt("score", dec("4.0"))))
.orderBy(desc("score"))
.limit(20)
.fetch()
for (const row of page.entities) console.log(row.$key, row.title.value)

TSelection = "*"

The selection, inferred by client.select().

TSchema extends Schema | undefined = undefined

The schema named with from, if any.

TCount extends bigint | undefined = undefined

new SelectQueryBuilder<TSelection, TSchema, TCount>(client, selection?): SelectQueryBuilder<TSelection, TSchema, TCount>

Defined in: src/query/queryBuilder.ts:109

ArkivClient

SelectArg

SelectQueryBuilder<TSelection, TSchema, TCount>

If the selection is not "*" or an object, asks for nothing, or names an attribute outside the name grammar.

QueryBuilderBase<TSchema>.constructor

createdBy(creator): this

Defined in: src/query/builderBase.ts:123

Restricts the query to entities this account created — shorthand for where(eq("$creator", addr(creator))). Calling it again replaces the filter.

The creator never changes; the owner does, so these differ after a transfer.

`0x${string}`

this

QueryBuilderBase.createdBy


fetch(): Promise<QueryResult<ResultOf<TSelection, TSchema>, TCount>>

Defined in: src/query/queryBuilder.ts:286

Runs the query and returns one page: up to limit matches, past the first offset.

Promise<QueryResult<ResultOf<TSelection, TSchema>, TCount>>

If no filter has been added, or a filter or sort key does not fit the schema.

If the limit is not an integer from 1 to 100, or the offset is not a non-negative integer.

If, through a schema, a matching entity does not fit the selected columns or a named schema’s tag, and from() was given { onMismatch: "throw" }.

If the node rejects the query.

const page = await client.select({ $key: true }).where(eq("category", "docs")).fetch()
page.entities

from<S>(schema, options): SelectQueryBuilder<TSelection, S, TCount>

Defined in: src/query/queryBuilder.ts:144

Runs the query through a schema. The selection keeps its meaning and the rows their shape; each selected attribute becomes a column — typed as the schema declares, and checked against it — and where is checked against the schema’s indexed columns.

A named schema also filters: only entities tagged with its name match, so a query through it sees only entities written through it, and needs no other filter. The tag is how the query finds them rather than one of their attributes, so rows leave it out of $attributes and $attributeSchema. An unnamed schema types the query without filtering it — where alone decides which entities match.

A matching entity that does not fit — a selected required column missing or of another type, or, for a named schema, a tag that does not match — is left out of the page, or fails the fetch with a SchemaMismatchError with { onMismatch: "throw" }. Columns the selection leaves out are not checked.

Returns a new builder, carrying whatever this one already holds; this one is left as it was.

S extends Schema<Columns>

S & SelectionCheck<TSelection, S>

The schema, built with defineSchema.

FromOptions = {}

How to treat entities that do not fit. FromOptions

SelectQueryBuilder<TSelection, S, TCount>

If schema was not built with defineSchema.

If the selection names something that is neither an entity field nor a column.

client.select({ $key: true, title: true }).from(Posts) // rows typed { $key; title }
client.select().from(Posts) // every field and every column
client.select().from(Posts, { onMismatch: "throw" }) // fail on entities that do not fit

limit(limit): this

Defined in: src/query/queryBuilder.ts:217

Sets the page size, up to the node maximum of 100. Without it the node picks the page size.

number

this

builder.limit(100)

offset(offset): this

Defined in: src/query/queryBuilder.ts:240

Skips the first offset matches. With limit, this takes one page: page n of size size is .limit(size).offset(n * size).

Every request reads the latest block, so an entity created or deleted between two requests shifts the matches after it, and a row can repeat or be missed. Sort by a key that does not change, such as asc("$key"), so that pages line up at least while nothing is written; without orderBy, the order is the node’s own. Through a schema, the offset counts the entities a page skips as well as its rows.

To read every match exactly once while others write, page by key instead: sort by asc("$key") and filter on gt("$key", key(lastKey)), with lastKey the last $key of the previous page. Through a schema, use { onMismatch: "throw" } for that: a page of skipped entities returns no rows, so no key to continue from.

number

this

builder.orderBy(asc("$key")).limit(20).offset(40) // the third page of 20

orderBy<K>(key): this

Defined in: src/query/queryBuilder.ts:187

Sorts the results by one attribute, with an asc or desc key. All the matches are sorted, not each page on its own, and ties come in the node’s own order. Calling it again replaces the order. To page with offset, sort by a key that does not change, such as asc("$key").

Any attribute but a bytes one can be sorted on, indexed or not. After from(), the key takes its type from the column, and naming anything but a non-bytes column or a queryable system attribute is a compile error. Without a schema, a key on a user attribute names its type. Call it after from(): a key given before it is checked against the schema only when the query is sent.

K extends OrderTerm<AttributeRef>

K & OrderCheck<K, TSchema>

The sort, an asc(...) or a desc(...).

this

If not given exactly one key, or the key is not one asc(...) or desc(...) would build. A key that does not fit the schema, or has no type without one, throws when the query is sent.

builder.orderBy(desc("score")) // through a schema
builder.orderBy(desc("score", "u256")) // without one
builder.orderBy(asc("$expiresAt"))

ownedBy(owner): this

Defined in: src/query/builderBase.ts:112

Restricts the query to entities this account owns — shorthand for where(eq("$owner", addr(owner))). Calling it again replaces the filter.

`0x${string}`

this

builder.ownedBy("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")

QueryBuilderBase.ownedBy


toString(): string

Defined in: src/query/queryBuilder.ts:205

The query string this builder will send: the filters, as QueryBuilderBase.toString renders them, followed by the orderBy clause, if any.

string

If no filter has been added, a filter or sort key does not fit the schema, or — without a schema — a sort key on a user attribute has no type.

QueryBuilderBase.toString


where<E>(…expressions): this

Defined in: src/query/builderBase.ts:98

Adds filters. Everything passed here, and across repeated calls, must hold.

After from(), every attribute a filter names must be an indexed column of the schema, compared against a value of its type — anything else is a compile error.

E extends readonly (Expression | readonly Expression[])[]

…E & FilterCheck<E, TSchema>

The expressions, as separate arguments or one array.

this

builder.where(eq("category", "docs"))
builder.where(gte("level", i32(10)), lt("level", i32(20)))
builder.where(or(eq("status", "open"), exists("reviewedBy")))

QueryBuilderBase.where


withCount(): SelectQueryBuilder<TSelection, TSchema, bigint>

Defined in: src/query/queryBuilder.ts:262

Also counts every entity the query matches, regardless of the limit and offset. The page then carries the total as QueryResult.count, typed bigint, so a paginated list can show it without a second query. To count without fetching rows, use client.count() instead.

The node counts what the filters match, at the block the page was read at. Through a schema, that includes entities the page leaves out for not fitting it. Later pages read later blocks, so the count can be out of date by the time they arrive.

SelectQueryBuilder<TSelection, TSchema, bigint>

If, when fetched, the node returns no count — it predates the count projection.

Returns a new builder, carrying whatever this one already holds; this one is left as it was.

const page = await builder.withCount().limit(20).fetch()
page.count // every match, not just these 20