@coasys/ad4m / Exports / ModelQueryBuilder
Class: ModelQueryBuilder<T>
Query builder for Ad4mModel queries. Allows building queries with a fluent interface and either running them once or subscribing to updates.
Example
const builder = Recipe.query(perspective)
.where({ category: "Dessert" })
.order({ rating: "DESC" })
.limit(10);
// Run once
const recipes = await builder.run();
// Or subscribe to updates
await builder.subscribe(recipes => {
console.log("Updated recipes:", recipes);
});Type parameters
| Name | Type |
|---|---|
T | extends Ad4mModel |
Table of contents
Constructors
Properties
Methods
- collections
- count
- countSubscribe
- dispose
- get
- limit
- offset
- order
- overrideModelClassName
- paginate
- paginateSubscribe
- properties
- source
- subscribe
- useSurrealDB
- where
Constructors
constructor
• new ModelQueryBuilder<T>(perspective, ctor, query?)
Type parameters
| Name | Type |
|---|---|
T | extends Ad4mModel<T> |
Parameters
| Name | Type |
|---|---|
perspective | PerspectiveProxy |
ctor | typeof Ad4mModel |
query? | Query |
Defined in
model/Ad4mModel.ts:2503 (opens in a new tab)
Properties
ctor
• Private ctor: typeof Ad4mModel
Defined in
model/Ad4mModel.ts:2499 (opens in a new tab)
currentSubscription
• Private Optional currentSubscription: any
Defined in
model/Ad4mModel.ts:2500 (opens in a new tab)
modelClassName
• Private modelClassName: string = null
Defined in
model/Ad4mModel.ts:2498 (opens in a new tab)
perspective
• Private perspective: PerspectiveProxy
Defined in
model/Ad4mModel.ts:2496 (opens in a new tab)
queryParams
• Private queryParams: Query = {}
Defined in
model/Ad4mModel.ts:2497 (opens in a new tab)
useSurrealDBFlag
• Private useSurrealDBFlag: boolean = true
Defined in
model/Ad4mModel.ts:2501 (opens in a new tab)
Methods
collections
▸ collections(collections): ModelQueryBuilder<T>
Specifies which collections to include in the results.
Parameters
| Name | Type | Description |
|---|---|---|
collections | string[] | Array of collection names to include |
Returns
The query builder for chaining
Example
.collections(["ingredients", "steps"])Defined in
model/Ad4mModel.ts:2640 (opens in a new tab)
count
▸ count(): Promise<number>
Gets the total count of matching entities.
Returns
Promise<number>
Total count
Example
const totalDesserts = await Recipe.query(perspective)
.where({ category: "Dessert" })
.count();Defined in
model/Ad4mModel.ts:2794 (opens in a new tab)
countSubscribe
▸ countSubscribe(callback): Promise<number>
Subscribes to count updates for matching entities.
This method:
- Creates and initializes a SurrealDB live query subscription for the count (default)
- Sets up the callback to process future count updates
- Returns the initial count immediately
Remember to call dispose() when you're done with the subscription to clean up resources.
Parameters
| Name | Type | Description |
|---|---|---|
callback | (count: number) => void | Function to call with updated count |
Returns
Promise<number>
Initial count
Example
const builder = Recipe.query(perspective)
.where({ status: "active" });
const initialCount = await builder.countSubscribe(count => {
console.log("Active items:", count);
});
// When done with subscription:
builder.dispose();Remarks
By default, this uses SurrealDB live queries for real-time updates.
Prolog subscriptions remain available via .useSurrealDB(false).
Defined in
model/Ad4mModel.ts:2841 (opens in a new tab)
dispose
▸ dispose(): void
Disposes of the current subscription if one exists.
This method:
- Stops the keepalive signals to the subscription
- Unsubscribes from GraphQL subscription updates
- Notifies the backend to clean up subscription resources
- Clears the subscription reference
You should call this method when you're done with a subscription to prevent memory leaks and ensure proper cleanup.
Returns
void
Defined in
model/Ad4mModel.ts:2521 (opens in a new tab)
get
▸ get(): Promise<T[]>
Executes the query once and returns the results.
Returns
Promise<T[]>
Array of matching entities
Example
const recipes = await Recipe.query(perspective)
.where({ category: "Dessert" })
.get();Defined in
model/Ad4mModel.ts:2692 (opens in a new tab)
limit
▸ limit(limit): ModelQueryBuilder<T>
Sets the maximum number of results to return.
Parameters
| Name | Type | Description |
|---|---|---|
limit | number | Maximum number of results |
Returns
The query builder for chaining
Example
.limit(10)Defined in
model/Ad4mModel.ts:2576 (opens in a new tab)
offset
▸ offset(offset): ModelQueryBuilder<T>
Sets the number of results to skip.
Parameters
| Name | Type | Description |
|---|---|---|
offset | number | Number of results to skip |
Returns
The query builder for chaining
Example
.offset(20) // Skip first 20 resultsDefined in
model/Ad4mModel.ts:2592 (opens in a new tab)
order
▸ order(orderBy): ModelQueryBuilder<T>
Sets the order for the query results.
Parameters
| Name | Type | Description |
|---|---|---|
orderBy | Order | The ordering criteria |
Returns
The query builder for chaining
Example
.order({ createdAt: "DESC" })Defined in
model/Ad4mModel.ts:2560 (opens in a new tab)
overrideModelClassName
▸ overrideModelClassName(className): ModelQueryBuilder<T>
Parameters
| Name | Type |
|---|---|
className | string |
Returns
Defined in
model/Ad4mModel.ts:2645 (opens in a new tab)
paginate
▸ paginate(pageSize, pageNumber): Promise<PaginationResult<T>>
Gets a page of results with pagination metadata.
Parameters
| Name | Type | Description |
|---|---|---|
pageSize | number | Number of items per page |
pageNumber | number | Which page to retrieve (1-based) |
Returns
Promise<PaginationResult<T>>
Paginated results with metadata
Example
const page = await Recipe.query(perspective)
.where({ category: "Main" })
.paginate(10, 1);
console.log(`Page ${page.pageNumber}, ${page.results.length} of ${page.totalCount}`);Defined in
model/Ad4mModel.ts:2890 (opens in a new tab)
paginateSubscribe
▸ paginateSubscribe(pageSize, pageNumber, callback): Promise<PaginationResult<T>>
Subscribes to paginated results updates.
This method:
- Creates and initializes a SurrealDB live query subscription for the paginated results (default)
- Sets up the callback to process future page updates
- Returns the initial page immediately
Remember to call dispose() when you're done with the subscription to clean up resources.
Parameters
| Name | Type | Description |
|---|---|---|
pageSize | number | Number of items per page |
pageNumber | number | Which page to retrieve (1-based) |
callback | (results: PaginationResult<T>) => void | Function to call with updated pagination results |
Returns
Promise<PaginationResult<T>>
Initial pagination results
Example
const builder = Recipe.query(perspective)
.where({ category: "Main" });
const initialPage = await builder.paginateSubscribe(10, 1, page => {
console.log("Updated page:", page.results);
});
// When done with subscription:
builder.dispose();Remarks
By default, this uses SurrealDB live queries for real-time updates.
Prolog subscriptions remain available via .useSurrealDB(false).
Defined in
model/Ad4mModel.ts:2938 (opens in a new tab)
properties
▸ properties(properties): ModelQueryBuilder<T>
Specifies which properties to include in the results.
Parameters
| Name | Type | Description |
|---|---|---|
properties | string[] | Array of property names to include |
Returns
The query builder for chaining
Example
.properties(["name", "description", "rating"])Defined in
model/Ad4mModel.ts:2624 (opens in a new tab)
source
▸ source(source): ModelQueryBuilder<T>
Sets the source filter for the query.
Parameters
| Name | Type | Description |
|---|---|---|
source | string | The source to filter by |
Returns
The query builder for chaining
Example
.source("ad4m://self")Defined in
model/Ad4mModel.ts:2608 (opens in a new tab)
subscribe
▸ subscribe(callback): Promise<T[]>
Subscribes to the query and receives updates when results change.
This method:
- Creates and initializes a SurrealDB live query subscription (default)
- Sets up the callback to process future updates
- Returns the initial results immediately
Remember to call dispose() when you're done with the subscription to clean up resources.
Parameters
| Name | Type | Description |
|---|---|---|
callback | (results: T[]) => void | Function to call with updated results |
Returns
Promise<T[]>
Initial results array
Example
const builder = Recipe.query(perspective)
.where({ status: "cooking" });
const initialRecipes = await builder.subscribe(recipes => {
console.log("Updated recipes:", recipes);
});
// When done with subscription:
builder.dispose();Remarks
By default, this uses SurrealDB live queries for real-time updates.
Prolog subscriptions remain available via .useSurrealDB(false).
Defined in
model/Ad4mModel.ts:2737 (opens in a new tab)
useSurrealDB
▸ useSurrealDB(enabled?): ModelQueryBuilder<T>
Enables or disables SurrealDB query path.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
enabled | boolean | true | Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy) |
Returns
The query builder for chaining
Example
// Use SurrealDB (default)
const recipes = await Recipe.query(perspective)
.where({ category: "Dessert" })
.useSurrealDB(true)
.get();
// Use Prolog (legacy)
const recipesProlog = await Recipe.query(perspective)
.where({ category: "Dessert" })
.useSurrealDB(false)
.get();Remarks
Note: Subscriptions (subscribe(), countSubscribe(), paginateSubscribe()) default to SurrealDB live queries if useSurrealDB(true) is set (default).
Defined in
model/Ad4mModel.ts:2675 (opens in a new tab)
where
▸ where(conditions): ModelQueryBuilder<T>
Adds where conditions to the query.
Parameters
| Name | Type | Description |
|---|---|---|
conditions | Where | The conditions to filter by |
Returns
The query builder for chaining
Example
.where({
category: "Dessert",
rating: { gt: 4 },
tags: ["vegan", "quick"],
published: true
})