Interface ZVecCollection

Represents a collection in Zvec.

interface ZVecCollection {
    path: string;
    schema: ZVecCollectionSchema;
    options: ZVecCollectionOptions;
    stats: { docCount: number; indexCompleteness: Record<string, number> };
    insertSync(docs: ZVecDocInput): ZVecStatus;
    insertSync(docs: ZVecDocInput[]): ZVecStatus[];
    upsertSync(docs: ZVecDocInput): ZVecStatus;
    upsertSync(docs: ZVecDocInput[]): ZVecStatus[];
    updateSync(docs: ZVecDocInput): ZVecStatus;
    updateSync(docs: ZVecDocInput[]): ZVecStatus[];
    deleteSync(ids: string): ZVecStatus;
    deleteSync(ids: string[]): ZVecStatus[];
    deleteByFilterSync(filter: string): ZVecStatus;
    deleteByFilter(filter: string): Promise<ZVecStatus>;
    querySync(params: ZVecQuery): ZVecDoc[];
    query(params: ZVecQuery): Promise<ZVecDoc[]>;
    multiQuerySync(params: ZVecMultiQuery): ZVecDoc[];
    multiQuery(params: ZVecMultiQuery): Promise<ZVecDoc[]>;
    groupByQuerySync(params: ZVecGroupByQuery): ZVecGroupResult[];
    groupByQuery(params: ZVecGroupByQuery): Promise<ZVecGroupResult[]>;
    fetchSync(ids: string | string[]): Record<string, ZVecDoc>;
    fetchSync(
        params: {
            ids: string | string[];
            outputFields?: string[];
            includeVector?: boolean;
        },
    ): Record<string, ZVecDoc>;
    iterDocsSync(options?: ZVecIteratorOptions): ZVecDocIterator;
    optimizeSync(options?: ZVecOptimizeOptions): void;
    optimize(options?: ZVecOptimizeOptions): Promise<void>;
    closeSync(): void;
    destroySync(): void;
    addColumnSync(
        params: {
            fieldSchema: ZVecFieldSchema;
            expression?: string;
            options?: ZVecAddColumnOptions;
        },
    ): void;
    dropColumnSync(fieldName: string): void;
    alterColumnSync(
        params: {
            columnName: string;
            newColumnName?: string;
            fieldSchema?: ZVecFieldSchema;
            options?: ZVecAlterColumnOptions;
        },
    ): void;
    createIndexSync(
        params: {
            fieldName: string;
            indexParams:
                | ZVecFlatIndexParams
                | ZVecHnswIndexParams
                | ZVecHnswRabitqIndexParams
                | ZVecIVFIndexParams
                | ZVecIvfRabitqIndexParams
                | ZVecDiskAnnIndexParams
                | ZVecInvertIndexParams
                | ZVecFtsIndexParams;
            indexOptions?: ZVecCreateIndexOptions;
        },
    ): void;
    dropIndexSync(fieldName: string): void;
}

Methods

insertSync

insertSync(docs: ZVecDocInput): ZVecStatus
Inserts a single document into the collection.
Parameters
- docs: ZVecDocInput
  A single document to insert.
Returns ZVecStatus
The status of the operation.
- Defined in index.d.ts:1376
insertSync(docs: ZVecDocInput[]): ZVecStatus[]
Inserts a batch of documents into the collection.
Parameters
- docs: ZVecDocInput[]
  An array of documents to insert.
Returns ZVecStatus[]
An array of statuses of the operation.
- Defined in index.d.ts:1383

upsertSync

upsertSync(docs: ZVecDocInput): ZVecStatus
Inserts a single document into the collection, or updates it if it already exists based on its ID.
Parameters
- docs: ZVecDocInput
  A single document to upsert.
Returns ZVecStatus
The status of the operation.
- Defined in index.d.ts:1390
upsertSync(docs: ZVecDocInput[]): ZVecStatus[]
Inserts a batch of documents into the collection, or updates them if they already exist based on their ID.
Parameters
- docs: ZVecDocInput[]
  An array of documents to upsert.
Returns ZVecStatus[]
An array of statuses of the operation.
- Defined in index.d.ts:1397

updateSync

updateSync(docs: ZVecDocInput): ZVecStatus
Updates a single existing document by ID. Only specified fields and vectors are updated; others remain unchanged.
Parameters
- docs: ZVecDocInput
  A single document containing the updated data.
Returns ZVecStatus
The status of the operation.
- Defined in index.d.ts:1405
updateSync(docs: ZVecDocInput[]): ZVecStatus[]
Updates multiple existing documents by ID. Only specified fields and vectors are updated; others remain unchanged.
Parameters
- docs: ZVecDocInput[]
  An array of documents containing the updated data.
Returns ZVecStatus[]
An array of statuses of the operation.
- Defined in index.d.ts:1413

deleteSync

deleteSync(ids: string): ZVecStatus
Deletes a single document by its ID.
Parameters
- ids: string
  A single document ID to delete.
Returns ZVecStatus
The status of the operation.
- Defined in index.d.ts:1420
deleteSync(ids: string[]): ZVecStatus[]
Deletes multiple documents by their IDs.
Parameters
- ids: string[]
  An array of document IDs to delete.
Returns ZVecStatus[]
An array of statuses of the operation.
- Defined in index.d.ts:1427

deleteByFilterSync

deleteByFilterSync(filter: string): ZVecStatus
Deletes documents based on a filter expression.
Parameters
- filter: string
  A string representing the filter expression.
Returns ZVecStatus
The status of the operation.
- Defined in index.d.ts:1434

deleteByFilter

deleteByFilter(filter: string): Promise<ZVecStatus>
Asynchronously deletes documents based on a filter expression.
Parameters
- filter: string
  A string representing the filter expression.
Returns Promise<ZVecStatus>
A promise that resolves with the status of the operation.
- Defined in index.d.ts:1441

querySync

querySync(params: ZVecQuery): ZVecDoc[]
Performs a search query against the collection.
Parameters
- params: ZVecQuery
  The query parameters.
Returns ZVecDoc[]
An array of documents matching the query.
- Defined in index.d.ts:1448

query

query(params: ZVecQuery): Promise<ZVecDoc[]>
Asynchronously performs a search query against the collection.
Parameters
- params: ZVecQuery
  The query parameters.
Returns Promise<ZVecDoc[]>
A promise that resolves with an array of documents matching the query.
- Defined in index.d.ts:1455

multiQuerySync

multiQuerySync(params: ZVecMultiQuery): ZVecDoc[]
Performs multiple searches against the collection and merges their candidates.
Parameters
- params: ZVecMultiQuery
  The multi-query parameters.
Returns ZVecDoc[]
An array of documents matching the combined query.
- Defined in index.d.ts:1462

multiQuery

multiQuery(params: ZVecMultiQuery): Promise<ZVecDoc[]>
Asynchronously performs multiple searches against the collection and merges their candidates.
Parameters
- params: ZVecMultiQuery
  The multi-query parameters.
Returns Promise<ZVecDoc[]>
A promise that resolves with an array of documents matching the combined query.
- Defined in index.d.ts:1469

groupByQuerySync

groupByQuerySync(params: ZVecGroupByQuery): ZVecGroupResult[]
Performs a vector search and groups results by a scalar field.
Parameters
- params: ZVecGroupByQuery
Returns ZVecGroupResult[]
- Defined in index.d.ts:1474

groupByQuery

groupByQuery(params: ZVecGroupByQuery): Promise<ZVecGroupResult[]>
Asynchronously performs a vector search and groups results by a scalar field.
Parameters
- params: ZVecGroupByQuery
Returns Promise<ZVecGroupResult[]>
- Defined in index.d.ts:1479

fetchSync

fetchSync(ids: string | string[]): Record<string, ZVecDoc>
Fetches documents by their IDs.
Parameters
- ids: string | string[]
  A single document ID or an array of document IDs to fetch.
Returns Record<string, ZVecDoc>
An object mapping the requested IDs to their corresponding documents. If an ID is not found, it will not be present in the returned object.
- Defined in index.d.ts:1486
fetchSync(
    params: {
        ids: string | string[];
        outputFields?: string[];
        includeVector?: boolean;
    },
): Record<string, ZVecDoc>
Fetches documents by their IDs.
Parameters
- params: { ids: string | string[]; outputFields?: string[]; includeVector?: boolean }
  Fetch parameters.
  - ids: string | string[]
    A single document ID or an array of document IDs to fetch.
  - OptionaloutputFields?: string[]
    Scalar fields to include. If undefined, all scalar fields are returned. An empty array returns no scalar fields.
  - OptionalincludeVector?: boolean
    Whether to include vector data in fetched documents. Defaults to true.
Returns Record<string, ZVecDoc>
An object mapping the requested IDs to their corresponding documents. If an ID is not found, it will not be present in the returned object.
- Defined in index.d.ts:1496

iterDocsSync

iterDocsSync(options?: ZVecIteratorOptions): ZVecDocIterator
Traverse all documents using an isolated snapshot created when this method is called.

Documents written after the iterator is created are not visible to it. On writable collections, creating the snapshot may seal the current writing segment. Traversal order is unspecified.

While an iterator is open, collection close/destroy, optimize, index DDL, and column DDL operations are rejected. Writes, queries, and fetches remain available. Exhaust the iterator, exit its for...of loop, or call closeSync() to release this restriction.

This is a synchronous API and may block the Node.js event loop while loading and converting documents.
Parameters
- Optionaloptions: ZVecIteratorOptions
  Optional output field and vector selection.
Returns ZVecDocIterator
A synchronous document iterator.
- Defined in index.d.ts:1521

optimizeSync

optimizeSync(options?: ZVecOptimizeOptions): void
Optimizes the collection's internal structures for better performance.
Parameters
- Optionaloptions: ZVecOptimizeOptions
  Optional parameters for the operation.
Returns void
Throws
If the operation fails.
- Defined in index.d.ts:1528

optimize

optimize(options?: ZVecOptimizeOptions): Promise<void>
Asynchronously optimizes the collection's internal structures for better performance.
Parameters
- Optionaloptions: ZVecOptimizeOptions
  Optional parameters for the operation.
Returns Promise<void>
A promise that resolves when optimization is complete.

Rejects
If the operation fails.
- Defined in index.d.ts:1536

closeSync

closeSync(): void
Closes the collection and releases its resources. After calling this method, the collection object should not be used.

Returns void
Throws
If the operation fails.
- Defined in index.d.ts:1543

destroySync

destroySync(): void
Permanently deletes the collection from disk. After calling this method, the collection object should not be used.

Returns void
Throws
If the operation fails.
- Defined in index.d.ts:1550

addColumnSync

addColumnSync(
    params: {
        fieldSchema: ZVecFieldSchema;
        expression?: string;
        options?: ZVecAddColumnOptions;
    },
): void
Adds a new column to the collection.
Parameters
- params: {
      fieldSchema: ZVecFieldSchema;
      expression?: string;
      options?: ZVecAddColumnOptions;
  }
  An object containing the parameters for the operation.
  - fieldSchema: ZVecFieldSchema
    The schema definition for the new column.
  - Optionalexpression?: string
    Optional expression to compute values for existing documents.
  - Optionaloptions?: ZVecAddColumnOptions
    Optional parameters for the operation.
Returns void
Throws
If the operation fails.
- Defined in index.d.ts:1560

dropColumnSync

dropColumnSync(fieldName: string): void
Permanently deletes a column from the collection. After dropping, the data and schema for this column are removed.
Parameters
- fieldName: string
  The name of the column to drop.
Returns void
Throws
If the operation fails.
- Defined in index.d.ts:1572

alterColumnSync

alterColumnSync(
    params: {
        columnName: string;
        newColumnName?: string;
        fieldSchema?: ZVecFieldSchema;
        options?: ZVecAlterColumnOptions;
    },
): void
Alters an existing column in the collection. You can either rename the column or modify its schema.
Parameters
- params: {
      columnName: string;
      newColumnName?: string;
      fieldSchema?: ZVecFieldSchema;
      options?: ZVecAlterColumnOptions;
  }
  An object containing the parameters for the operation.
  - columnName: string
    The current name of the column to alter.
  - OptionalnewColumnName?: string
    The new name for the column (mutually exclusive with fieldSchema).
  - OptionalfieldSchema?: ZVecFieldSchema
    The new schema definition for the column (mutually exclusive with newColumnName).
  - Optionaloptions?: ZVecAlterColumnOptions
    Optional parameters for the operation.
Returns void
Throws
If the operation fails.
- Defined in index.d.ts:1584

createIndexSync

createIndexSync(
    params: {
        fieldName: string;
        indexParams:
            | ZVecFlatIndexParams
            | ZVecHnswIndexParams
            | ZVecHnswRabitqIndexParams
            | ZVecIVFIndexParams
            | ZVecIvfRabitqIndexParams
            | ZVecDiskAnnIndexParams
            | ZVecInvertIndexParams
            | ZVecFtsIndexParams;
        indexOptions?: ZVecCreateIndexOptions;
    },
): void
Creates an index on a specific column in the collection.
Parameters
- params: {
      fieldName: string;
      indexParams:
          | ZVecFlatIndexParams
          | ZVecHnswIndexParams
          | ZVecHnswRabitqIndexParams
          | ZVecIVFIndexParams
          | ZVecIvfRabitqIndexParams
          | ZVecDiskAnnIndexParams
          | ZVecInvertIndexParams
          | ZVecFtsIndexParams;
      indexOptions?: ZVecCreateIndexOptions;
  }
  An object containing the parameters for the operation.
  - fieldName: string
    The name of the column to create the index on.
  - indexParams:
        | ZVecFlatIndexParams
        | ZVecHnswIndexParams
        | ZVecHnswRabitqIndexParams
        | ZVecIVFIndexParams
        | ZVecIvfRabitqIndexParams
        | ZVecDiskAnnIndexParams
        | ZVecInvertIndexParams
        | ZVecFtsIndexParams
    The configuration parameters defining the index type and properties.
  - OptionalindexOptions?: ZVecCreateIndexOptions
    Optional parameters for the index creation operation.
Returns void
Throws
If the operation fails.
- Defined in index.d.ts:1599

dropIndexSync

dropIndexSync(fieldName: string): void
Drops (removes) an existing index from the collection.
Parameters
- fieldName: string
  The name of the column whose index should be dropped.
Returns void
Throws
If the operation fails.
- Defined in index.d.ts:1618

Properties

`Readonly`path

path: string

Gets the file system path associated with this collection.

`Readonly`schema

schema: ZVecCollectionSchema

Gets the schema defining the structure of this collection.

`Readonly`options

options: ZVecCollectionOptions

Gets the options used when this collection was opened/created.

`Readonly`stats

stats: { docCount: number; indexCompleteness: Record<string, number> }

Gets statistics about this collection.

Interface ZVecCollection

Index

Methods

Properties

Methods

insertSync

Parameters

Returns ZVecStatus

Parameters

Returns ZVecStatus[]

upsertSync

Parameters

Returns ZVecStatus

Parameters

Returns ZVecStatus[]

updateSync

Parameters

Returns ZVecStatus

Parameters

Returns ZVecStatus[]

deleteSync

Parameters

Returns ZVecStatus

Parameters

Returns ZVecStatus[]

deleteByFilterSync

Parameters

Returns ZVecStatus

deleteByFilter

Parameters

Returns Promise<ZVecStatus>

querySync

Parameters

Returns ZVecDoc[]

query

Parameters

Returns Promise<ZVecDoc[]>

multiQuerySync

Parameters

Returns ZVecDoc[]

multiQuery

Parameters

Returns Promise<ZVecDoc[]>

groupByQuerySync

Parameters

Returns ZVecGroupResult[]

groupByQuery

Parameters

Returns Promise<ZVecGroupResult[]>

fetchSync

Parameters

Returns Record<string, ZVecDoc>

Parameters

ids: string | string[]

OptionaloutputFields?: string[]

OptionalincludeVector?: boolean

Returns Record<string, ZVecDoc>

iterDocsSync

Parameters

Returns ZVecDocIterator

optimizeSync

Parameters

Returns void

Throws

optimize

Parameters

Returns Promise<void>

Rejects

closeSync

Returns void

Throws

destroySync

Returns void

Throws

addColumnSync

Parameters

fieldSchema: ZVecFieldSchema

Optionalexpression?: string

Optionaloptions?: ZVecAddColumnOptions

Returns void

`Optional`outputFields?: string[]

`Optional`includeVector?: boolean

`Optional`expression?: string

`Optional`options?: ZVecAddColumnOptions

`Optional`newColumnName?: string

`Optional`fieldSchema?: ZVecFieldSchema

`Optional`options?: ZVecAlterColumnOptions

indexParams:
| ZVecFlatIndexParams
| ZVecHnswIndexParams
| ZVecHnswRabitqIndexParams
| ZVecIVFIndexParams
| ZVecIvfRabitqIndexParams
| ZVecDiskAnnIndexParams
| ZVecInvertIndexParams
| ZVecFtsIndexParams

`Optional`indexOptions?: ZVecCreateIndexOptions

`Readonly`path

`Readonly`schema

`Readonly`options

`Readonly`stats