Class: VectorQueryBuilder

Defined in: src/batteries/vector/builder.ts:277

The where-clause surface of the query builder, factored out so a grouping callback can be handed a builder that only exposes filter methods (not near*/select/limit or the terminals).

Chained .where() ANDs; the first .orWhere() snapshots the accumulated AND-list into the first branch of an OR (knex semantics). Any of the where-methods also accepts a FilterCallback to open a nested group, letting AND and OR mix to any depth.

Extends

• FilterBuilder

Implements

• PromiseLike<VectorMatch[]>

Constructors

Constructor

new VectorQueryBuilder(
   sink: PlanSink,
   collection: string,
   defaultTopK: number): VectorQueryBuilder;

Defined in: src/batteries/vector/builder.ts:287

Parameters

Parameter	Type
sink	PlanSink
collection	string
defaultTopK	number

Returns

VectorQueryBuilder

Overrides

FilterBuilder.constructor

Methods

andWhere()

Call Signature

andWhere(cb: FilterCallback): this;

Defined in: src/batteries/vector/builder.ts:129

Alias of FilterBuilder.where (callback group form) for readability in a chain.

Parameters

Parameter	Type
cb	FilterCallback

Returns

this

Inherited from

FilterBuilder.andWhere

Call Signature

andWhere(
   a: string,
   b?: unknown,
   c?: unknown): this;

Defined in: src/batteries/vector/builder.ts:131

Alias of FilterBuilder.where (field op value form) for readability in a chain.

Parameters

Parameter	Type
a	string
b?	unknown
c?	unknown

Returns

this

Inherited from

FilterBuilder.andWhere

Call Signature

andWhere(obj: Record<string, unknown>): this;

Defined in: src/batteries/vector/builder.ts:133

Alias of FilterBuilder.where (object form) for readability in a chain.

Parameters

Parameter	Type
obj	Record<string, unknown>

Returns

this

Inherited from

FilterBuilder.andWhere

---

consistency()

consistency(mode: VectorConsistency): this;

Defined in: src/batteries/vector/builder.ts:405

Per-operation read-after-write override for the terminal .upsert() / .delete(). Universal across adapters: strongly-consistent backends ignore it (no-op), so a chain written for an eventually-consistent backend keeps working verbatim when the adapter is swapped. Precedence: this > the store's consistency option > the adapter's declared capabilities.consistency.default. See VectorConsistency.

Parameters

Parameter	Type
mode	VectorConsistency

Returns

this

---

delete()

delete(): Promise<void>;

Defined in: src/batteries/vector/builder.ts:449

Terminal: delete records matching the accumulated filter (or the id IN [...] fast path).

Returns

Promise<void>

---

limit()

limit(n: number): this;

Defined in: src/batteries/vector/builder.ts:387

Cap the number of matches returned (the search topK).

Parameters

Parameter	Type
n	number

Returns

this

---

nearId()

nearId(id: string): this;

Defined in: src/batteries/vector/builder.ts:328

Search by nearest neighbours to the stored vector of the record with the given id. Mutually exclusive with the other near* clauses.

Parameters

Parameter	Type
id	string

Returns

this

Throws

@nhtio/adk/batteries!E_VECTOR_STORE_QUERY_CONFLICT when a near* clause is already set.

---

nearText()

nearText(text: string): this;

Defined in: src/batteries/vector/builder.ts:314

Search by nearest neighbours to text, embedded server-side by the backend. Mutually exclusive with the other near* clauses.

Parameters

Parameter	Type
text	string

Returns

this

Throws

@nhtio/adk/batteries!E_VECTOR_STORE_QUERY_CONFLICT when a near* clause is already set.

---

nearVector()

nearVector(vector: number[]): this;

Defined in: src/batteries/vector/builder.ts:300

Search by nearest neighbours to a client-supplied query vector. Mutually exclusive with the other near* clauses.

Parameters

Parameter	Type
vector	number[]

Returns

this

Throws

@nhtio/adk/batteries!E_VECTOR_STORE_QUERY_CONFLICT when a near* clause is already set.

---

offset()

offset(n: number): this;

Defined in: src/batteries/vector/builder.ts:393

Skip the first n matches before returning results.

Parameters

Parameter	Type
n	number

Returns

this

---

orWhere()

Call Signature

orWhere(cb: FilterCallback): this;

Defined in: src/batteries/vector/builder.ts:148

Open a new OR branch holding a parenthesized condition group via a FilterCallback.

Parameters

Parameter	Type
cb	FilterCallback

Returns

this

Inherited from

FilterBuilder.orWhere

Call Signature

orWhere(field: string, value: unknown): this;

Defined in: src/batteries/vector/builder.ts:150

Open a new OR branch holding the equality condition field = value.

Parameters

Parameter	Type
field	string
value	unknown

Returns

this

Inherited from

FilterBuilder.orWhere

Call Signature

orWhere(
   field: string,
   op: FilterOperator,
   value: unknown): this;

Defined in: src/batteries/vector/builder.ts:152

Open a new OR branch holding the condition field op value.

Parameters

Parameter	Type
field	string
op	FilterOperator
value	unknown

Returns

this

Inherited from

FilterBuilder.orWhere

---

orWhereNot()

Call Signature

orWhereNot(cb: FilterCallback): this;

Defined in: src/batteries/vector/builder.ts:183

Open a new OR branch holding a negated parenthesized condition group via a FilterCallback.

Parameters

Parameter	Type
cb	FilterCallback

Returns

this

Inherited from

FilterBuilder.orWhereNot

Call Signature

orWhereNot(field: string, value: unknown): this;

Defined in: src/batteries/vector/builder.ts:185

Open a new OR branch holding the negated equality condition field != value.

Parameters

Parameter	Type
field	string
value	unknown

Returns

this

Inherited from

FilterBuilder.orWhereNot

---

select()

select(...args: SelectArg[]): this;

Defined in: src/batteries/vector/builder.ts:341

Declare which fields each match projects (id / vector / document / metadata). Required before a search terminal runs. Accepts SelectArgs: '*', field names, [field, config] tuples, or { field: config } maps.

Parameters

Parameter	Type
...args	SelectArg[]

Returns

this

---

then()

then<TR1, TR2>(onfulfilled?:
  | ((value: VectorMatch[]) => TR1 | PromiseLike<TR1>)
| null, onrejected?: ((reason: unknown) => TR2 | PromiseLike<TR2>) | null): PromiseLike<TR1 | TR2>;

Defined in: src/batteries/vector/builder.ts:410

Attaches callbacks for the resolution and/or rejection of the Promise.

Type Parameters

Type Parameter	Default type
TR1	VectorMatch[]
TR2	never

Parameters

Parameter	Type	Description
onfulfilled?	| ((value: VectorMatch[]) => TR1 | PromiseLike<TR1>) | null	The callback to execute when the Promise is resolved.
onrejected?	((reason: unknown) => TR2 | PromiseLike<TR2>) | null	The callback to execute when the Promise is rejected.

Returns

PromiseLike<TR1 | TR2>

A Promise for the completion of which ever callback is executed.

Implementation of

PromiseLike.then;

---

upsert()

upsert(records: VectorRecord[]): Promise<void>;

Defined in: src/batteries/vector/builder.ts:439

Terminal: insert or replace records in the collection.

Parameters

Parameter	Type
records	VectorRecord[]

Returns

Promise<void>

---

where()

Call Signature

where(cb: FilterCallback): this;

Defined in: src/batteries/vector/builder.ts:98

Add a parenthesized condition group via a FilterCallback; ANDed with prior conditions.

Parameters

Parameter	Type
cb	FilterCallback

Returns

this

Inherited from

FilterBuilder.where

Call Signature

where(
   a: string,
   b?: unknown,
   c?: unknown): this;

Defined in: src/batteries/vector/builder.ts:100

Add a condition field op value (or field = value when c is omitted); ANDed with prior conditions.

Parameters

Parameter	Type
a	string
b?	unknown
c?	unknown

Returns

this

Inherited from

FilterBuilder.where

Call Signature

where(obj: Record<string, unknown>): this;

Defined in: src/batteries/vector/builder.ts:102

Add equality conditions for each key of obj; ANDed with prior conditions.

Parameters

Parameter	Type
obj	Record<string, unknown>

Returns

this

Inherited from

FilterBuilder.where

---

whereExists()

whereExists(field: string): this;

Defined in: src/batteries/vector/builder.ts:213

AND the condition that field is present (exists).

Parameters

Parameter	Type
field	string

Returns

this

Inherited from

FilterBuilder.whereExists

---

whereIn()

whereIn(field: string, values: unknown[]): this;

Defined in: src/batteries/vector/builder.ts:198

AND the condition that field's value is one of values.

Parameters

Parameter	Type
field	string
values	unknown[]

Returns

this

Inherited from

FilterBuilder.whereIn

---

whereNot()

Call Signature

whereNot(cb: FilterCallback): this;

Defined in: src/batteries/vector/builder.ts:168

AND a negated parenthesized condition group via a FilterCallback.

Parameters

Parameter	Type
cb	FilterCallback

Returns

this

Inherited from

FilterBuilder.whereNot

Call Signature

whereNot(field: string, value: unknown): this;

Defined in: src/batteries/vector/builder.ts:170

AND the negated equality condition field != value.

Parameters

Parameter	Type
field	string
value	unknown

Returns

this

Inherited from

FilterBuilder.whereNot

---

whereNotIn()

whereNotIn(field: string, values: unknown[]): this;

Defined in: src/batteries/vector/builder.ts:203

AND the condition that field's value is none of values.

Parameters

Parameter	Type
field	string
values	unknown[]

Returns

this

Inherited from

FilterBuilder.whereNotIn

---

whereNull()

whereNull(field: string): this;

Defined in: src/batteries/vector/builder.ts:208

AND the condition that field is absent (does not exist).

Parameters

Parameter	Type
field	string

Returns

this

Inherited from

FilterBuilder.whereNull

---

whereRaw()

Call Signature

whereRaw(sql: string, bindings?: unknown[]): this;

Defined in: src/batteries/vector/builder.ts:218

AND a raw, adapter-dialect filter expressed as SQL text plus positional bindings.

Parameters

Parameter	Type
sql	string
bindings?	unknown[]

Returns

this

Inherited from

FilterBuilder.whereRaw

Call Signature

whereRaw(rawObj: {
  $bindings?: unknown[];
  $dialect: string;
  $raw: unknown;
}): this;

Defined in: src/batteries/vector/builder.ts:220

AND a raw, adapter-dialect filter expressed as a { $dialect, $raw, $bindings } object.

Parameters

Parameter	Type
rawObj	{ $bindings?: unknown[]; $dialect: string; $raw: unknown; }
rawObj.$bindings?	unknown[]
rawObj.$dialect	string
rawObj.$raw	unknown

Returns

this

Inherited from

FilterBuilder.whereRaw