SelectQueryBuilder

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

SelectQueryBuilder is the recommended query builder. It requires the selection to be declared up front, so results always contain exactly the data you asked for — and the type of each returned entity is narrowed to exactly the selected fields.

The selection is fixed at construction time and is flat — each field maps to an entity field. Create one via client.select(...) rather than constructing it directly, so the result type is inferred from the selection.

Example

// everything
await client.select().where(eq("name", "John")).fetch()
await client.select("*").where(eq("name", "John")).fetch()
// specific fields
await client.select({ owner: true, attributes: true }).fetch()
// a single field — result is typed (flat) { owner: Hex }
await client.select({ owner: true }).fetch()

Extends

• BaseQueryBuilder<TEntity>

Type Parameters

TEntity

TEntity

The projected entity shape, inferred from the selection by client.select().

Constructors

Constructor

new SelectQueryBuilder<TEntity>(client, selection?): SelectQueryBuilder<TEntity>

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

Parameters

client

ArkivClient

selection?

"*" | Required<Pick<SelectionFields, "key">> & Partial<Omit<SelectionFields, "key">> | Required<Pick<SelectionFields, "contentType">> & Partial<Omit<SelectionFields, "contentType">> | Required<Pick<SelectionFields, "owner">> & Partial<Omit<SelectionFields, "owner">> | Required<Pick<SelectionFields, "creator">> & Partial<Omit<SelectionFields, "creator">> | Required<Pick<SelectionFields, "expiresAtBlock">> & Partial<Omit<SelectionFields, "expiresAtBlock">> | Required<Pick<SelectionFields, "createdAtBlock">> & Partial<Omit<SelectionFields, "createdAtBlock">> | Required<Pick<SelectionFields, "lastModifiedAtBlock">> & Partial<Omit<SelectionFields, "lastModifiedAtBlock">> | Required<Pick<SelectionFields, "transactionIndexInBlock">> & Partial<Omit<SelectionFields, "transactionIndexInBlock">> | Required<Pick<SelectionFields, "operationIndexInTransaction">> & Partial<Omit<SelectionFields, "operationIndexInTransaction">> | Required<Pick<SelectionFields, "attributes">> & Partial<Omit<SelectionFields, "attributes">> | Required<Pick<SelectionFields, "payload">> & Partial<Omit<SelectionFields, "payload">>

Returns

SelectQueryBuilder<TEntity>

Overrides

BaseQueryBuilder.constructor

Methods

count()

count(): Promise<number>

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

Counts the entities from the query.

Returns

Promise<number>

The number of entities

Example

const builder = client.select()
const result = await builder.where(eq("name", "John")).count()
// result = 10

Inherited from

BaseQueryBuilder.count

---

createdBy()

createdBy(createdBy): this

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

Sets the createdBy filter

Parameters

createdBy

`0x${string}`

The address of the creator

Returns

this

The query builder instance

Example

const builder = client.select()
builder.createdBy("0x1234567890123456789012345678901234567890")

Inherited from

BaseQueryBuilder.createdBy

---

cursor()

cursor(cursor): this

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

Sets the cursor for the query - it is advances setting which rather shouldn’t be used manually but it is provided from query result if limit is used (pagination).

Parameters

cursor

string

The cursor to set which tells to RPC Query server where to start or continue the query.

Returns

this

The query builder instance

Example

const builder = client.select()
builder.cursor("0xABC123")

Inherited from

BaseQueryBuilder.cursor

---

fetch()

fetch(): Promise<QueryResult<TEntity>>

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

Fetches the entities from the query. It will return a QueryResult instance which can be used to fetch the next and previous pages.

Returns

Promise<QueryResult<TEntity>>

The QueryResult instance QueryResult

Example

const builder = client.select()
const result = await builder.where(eq("name", "John")).fetch()
// result = { entities: [Entity, Entity, Entity], next: async () => QueryResult, previous: async () => QueryResult }

Inherited from

BaseQueryBuilder.fetch

---

limit()

limit(limit): this

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

Sets the limit for the query

Parameters

limit

number

The number of entities to return

Returns

this

The query builder instance

Example

const builder = client.select()
builder.limit(10)

Inherited from

BaseQueryBuilder.limit

---

orderBy()

Call Signature

orderBy(attributeName, attributeType, order?): this

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

Sets the orderBy for the query. It can be called multiple times to order by multiple attributes. The order of the attributes is important. The first attribute is the primary order by attribute. You can use the helper functions asc() and desc() as input for this method.

Deprecated

Server-side ordering is not supported by the network, so this method has no effect on the returned order. Sort the fetched entities in JavaScript instead, e.g. result.entities.sort((a, b) => ...). This method will be removed in a future release.

Parameters

attributeName

string

The name of the attribute to order by

attributeType

The type of the attribute to order by (string or number)

"string" | "number"

order?

The order to set the order by (asc or desc)

"asc" | "desc"

Returns

this

The query builder instance

Example

const builder = client.select()
builder.orderBy("name", "string", "desc")
builder.orderBy(asc("name", "string"))
builder.orderBy(desc("name", "string"))

Inherited from

BaseQueryBuilder.orderBy

Call Signature

orderBy(orderByAttribute): this

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

Sets the orderBy for the query. This method takes the OrderByAttribute object as an argument and is mainly used to use the helper functions asc() and desc() to create the OrderByAttribute instances.

Deprecated

Server-side ordering is not supported by the network, so this method has no effect on the returned order. Sort the fetched entities in JavaScript instead, e.g. result.entities.sort((a, b) => ...). This method will be removed in a future release.

Parameters

orderByAttribute

OrderByAttribute

The OrderByAttribute instance to set

Returns

this

The query builder instance

Example

const builder = client.select()
builder.orderBy(asc("name", "string"))
builder.orderBy(desc("name", "string"))

Inherited from

BaseQueryBuilder.orderBy

---

ownedBy()

ownedBy(ownedBy): this

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

Sets the ownedBy filter

Parameters

ownedBy

`0x${string}`

The address of the owner

Returns

this

The query builder instance

Example

const builder = client.select()
builder.ownedBy("0x1234567890123456789012345678901234567890")

Inherited from

BaseQueryBuilder.ownedBy

---

validAtBlock()

validAtBlock(validAtBlock): this

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

Sets the validAtBlock for the query which tells at which block height the state we are intested. If not set, the latest block is used.

Parameters

validAtBlock

bigint

The block number to set

Returns

this

The query builder instance

Example

const builder = client.select()
builder.validAtBlock(10000)

Inherited from

BaseQueryBuilder.validAtBlock

---

where()

Call Signature

where(predicates): this

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

Sets the predicates for the query limiting the results. It can be a single predicate, multiple predicates passed as separate arguments, or an array of predicates - all combined with ‘and’. Predicates can be nested using ‘or’ and ‘and’ predicates.

Parameters

predicates

Predicate[]

The predicates to set, either as a single array or as separate arguments

Returns

this

The query builder instance

Example

const builder = client.select()
builder.where(eq("name", "John"))
builder.where(eq("name", "John"), eq("age", 30))
builder.where([eq("name", "John"), eq("age", 30)])
builder.where(eq("name", "John"), or(eq("age", 30), eq("age", 31)))
builder.where(eq("name", "John"), and(eq("age", 30), eq("age", 31)))
builder.where(eq("name", "John"), or(eq("age", 30), and(eq("age", 31), eq("age", 32))))
builder.where(eq("name", "John"), and(eq("age", 30), or(eq("age", 31), eq("age", 32))))

Inherited from

BaseQueryBuilder.where

Call Signature

where(…predicates): this

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

Sets the predicates for the query limiting the results. It can be a single predicate, multiple predicates passed as separate arguments, or an array of predicates - all combined with ‘and’. Predicates can be nested using ‘or’ and ‘and’ predicates.

Parameters

predicates

…Predicate[]

The predicates to set, either as a single array or as separate arguments

Returns

this

The query builder instance

Example

const builder = client.select()
builder.where(eq("name", "John"))
builder.where(eq("name", "John"), eq("age", 30))
builder.where([eq("name", "John"), eq("age", 30)])
builder.where(eq("name", "John"), or(eq("age", 30), eq("age", 31)))
builder.where(eq("name", "John"), and(eq("age", 30), eq("age", 31)))
builder.where(eq("name", "John"), or(eq("age", 30), and(eq("age", 31), eq("age", 32))))
builder.where(eq("name", "John"), and(eq("age", 30), or(eq("age", 31), eq("age", 32))))

Inherited from

BaseQueryBuilder.where