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[]>;
    fetchSync(ids: string | string[]): Record<string, ZVecDoc>;
    fetchSync(
        params: {
            ids: string | string[];
            outputFields?: string[];
            includeVector?: boolean;
        },
    ): Record<string, ZVecDoc>;
    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
                | 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:1146
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:1153

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:1160
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:1167

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:1175
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:1183

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:1190
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:1197

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:1204

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:1211

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:1218

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:1225

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:1232

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:1239

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:1246
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:1256

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:1267

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:1275

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:1282

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:1289

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:1299

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:1311

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:1323

createIndexSync

createIndexSync(
    params: {
        fieldName: string;
        indexParams:
            | ZVecFlatIndexParams
            | ZVecHnswIndexParams
            | ZVecHnswRabitqIndexParams
            | ZVecIVFIndexParams
            | 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
          | 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
        | 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:1338

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:1356

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[]>

fetchSync

Parameters

Returns Record<string, ZVecDoc>

Parameters

ids: string | string[]

OptionaloutputFields?: string[]

OptionalincludeVector?: boolean

Returns Record<string, ZVecDoc>

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

Throws

dropColumnSync

Parameters

Returns void

Throws

alterColumnSync

Parameters

columnName: string

OptionalnewColumnName?: string

`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
| ZVecDiskAnnIndexParams
| ZVecInvertIndexParams
| ZVecFtsIndexParams

`Optional`indexOptions?: ZVecCreateIndexOptions

`Readonly`path

`Readonly`schema

`Readonly`options

`Readonly`stats