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.
Example
Section titled “Example”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)Extends
Section titled “Extends”QueryBuilderBase<TSchema>
Type Parameters
Section titled “Type Parameters”TSelection
Section titled “TSelection”TSelection = "*"
The selection, inferred by client.select().
TSchema
Section titled “TSchema”TSchema extends Schema | undefined = undefined
The schema named with from, if any.
TCount
Section titled “TCount”TCount extends bigint | undefined = undefined
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new SelectQueryBuilder<
TSelection,TSchema,TCount>(client,selection?):SelectQueryBuilder<TSelection,TSchema,TCount>
Defined in: src/query/queryBuilder.ts:109
Parameters
Section titled “Parameters”client
Section titled “client”selection?
Section titled “selection?”Returns
Section titled “Returns”SelectQueryBuilder<TSelection, TSchema, TCount>
Throws
Section titled “Throws”If the selection is not "*" or an object, asks for nothing, or names an attribute
outside the name grammar.
Overrides
Section titled “Overrides”QueryBuilderBase<TSchema>.constructor
Methods
Section titled “Methods”createdBy()
Section titled “createdBy()”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.
Parameters
Section titled “Parameters”creator
Section titled “creator”`0x${string}`
Returns
Section titled “Returns”this
Inherited from
Section titled “Inherited from”fetch()
Section titled “fetch()”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.
Returns
Section titled “Returns”Promise<QueryResult<ResultOf<TSelection, TSchema>, TCount>>
Throws
Section titled “Throws”If no filter has been added, or a filter or sort key does not fit the schema.
Throws
Section titled “Throws”If the limit is not an integer from 1 to 100, or the offset is not a non-negative integer.
Throws
Section titled “Throws”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" }.
Throws
Section titled “Throws”If the node rejects the query.
Example
Section titled “Example”const page = await client.select({ $key: true }).where(eq("category", "docs")).fetch()page.entitiesfrom()
Section titled “from()”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.
Type Parameters
Section titled “Type Parameters”Parameters
Section titled “Parameters”schema
Section titled “schema”S & SelectionCheck<TSelection, S>
The schema, built with defineSchema.
options
Section titled “options”FromOptions = {}
How to treat entities that do not fit. FromOptions
Returns
Section titled “Returns”SelectQueryBuilder<TSelection, S, TCount>
Throws
Section titled “Throws”If schema was not built with defineSchema.
Throws
Section titled “Throws”If the selection names something that is neither an entity field nor a column.
Example
Section titled “Example”client.select({ $key: true, title: true }).from(Posts) // rows typed { $key; title }client.select().from(Posts) // every field and every columnclient.select().from(Posts, { onMismatch: "throw" }) // fail on entities that do not fitlimit()
Section titled “limit()”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.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”this
Example
Section titled “Example”builder.limit(100)offset()
Section titled “offset()”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.
Parameters
Section titled “Parameters”offset
Section titled “offset”number
Returns
Section titled “Returns”this
Example
Section titled “Example”builder.orderBy(asc("$key")).limit(20).offset(40) // the third page of 20orderBy()
Section titled “orderBy()”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.
Type Parameters
Section titled “Type Parameters”K extends OrderTerm<AttributeRef>
Parameters
Section titled “Parameters”K & OrderCheck<K, TSchema>
The sort, an asc(...) or a desc(...).
Returns
Section titled “Returns”this
Throws
Section titled “Throws”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.
Example
Section titled “Example”builder.orderBy(desc("score")) // through a schemabuilder.orderBy(desc("score", "u256")) // without onebuilder.orderBy(asc("$expiresAt"))ownedBy()
Section titled “ownedBy()”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.
Parameters
Section titled “Parameters”`0x${string}`
Returns
Section titled “Returns”this
Example
Section titled “Example”builder.ownedBy("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")Inherited from
Section titled “Inherited from”toString()
Section titled “toString()”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.
Returns
Section titled “Returns”string
Throws
Section titled “Throws”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.
Overrides
Section titled “Overrides”where()
Section titled “where()”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.
Type Parameters
Section titled “Type Parameters”E extends readonly (Expression | readonly Expression[])[]
Parameters
Section titled “Parameters”expressions
Section titled “expressions”…E & FilterCheck<E, TSchema>
The expressions, as separate arguments or one array.
Returns
Section titled “Returns”this
Example
Section titled “Example”builder.where(eq("category", "docs"))builder.where(gte("level", i32(10)), lt("level", i32(20)))builder.where(or(eq("status", "open"), exists("reviewedBy")))Inherited from
Section titled “Inherited from”withCount()
Section titled “withCount()”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.
Returns
Section titled “Returns”SelectQueryBuilder<TSelection, TSchema, bigint>
Throws
Section titled “Throws”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.
Example
Section titled “Example”const page = await builder.withCount().limit(20).fetch()page.count // every match, not just these 20