QueryBuilder

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

QueryBuilder is a helper class to build queries to the Arkiv DBChains. It can be used to fetch entities from the Arkiv DBChains. It follows the Builder pattern allowing chaining of methods.

By default the result includes only the entity key. Additional data is opt-in through withAttributes(), withMetadata() and withPayload().

Param

The Arkiv client

Deprecated

Use SelectQueryBuilder via client.select() instead. Declaring the selection up front avoids the common mistake of forgetting to opt in to data and getting back entities with only their key populated. This class remains for backwards compatibility and will be removed in a future release.

Extends

• BaseQueryBuilder<Entity>

Constructors

Constructor

new QueryBuilder(client): QueryBuilder

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

Parameters

client

ArkivClient

Returns

QueryBuilder

Inherited from

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<Entity>>

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<Entity>>

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

---

withAttributes()

withAttributes(withAttributes): this

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

Sets the withAttributes flag which will return the attributes for the entities if true

Parameters

withAttributes

boolean = true

The boolean value to set

Returns

this

The QueryBuilder instance

Example

const builder = client.buildQuery()
builder.withAttributes(true)

---

withMetadata()

withMetadata(withMetadata): this

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

Sets the withMetadata flag which will return the metadata (like owner, expiredAt, etc.) for the entities if true

Parameters

withMetadata

boolean = true

The boolean value to set

Returns

this

The QueryBuilder instance

Example

const builder = client.buildQuery()
builder.withMetadata(true)

---

withPayload()

withPayload(withPayload): this

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

Sets the withPayload flag which will return the payload for the entities if true

Parameters

withPayload

boolean = true

The boolean value to set

Returns

this

The QueryBuilder instance

Example

const builder = client.buildQuery()
builder.withPayload(true)