Zvec Node.js

https://zvec.org/api-reference/nodejs
Admin
Zvec Node.js provides a robust API for Zvec, a high-performance vector search engine, enabling...
Tokens:10,155
Snippets:116
Trust Score:4.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### ZVecInitialize(options: ZVecInitOptions): void

Source: https://zvec.org/api-reference/nodejs/functions/ZVecInitialize.html

Initializes global Zvec configurations. This function should be called only once at the start of your application.

```APIDOC
## ZVecInitialize(options: ZVecInitOptions): void

### Description
Initializes global Zvec configurations. This function should be called only once at the start of your application.

### Parameters
- **options** (ZVecInitOptions) - Required - Configuration parameters.

### Returns
- **void**
```

--------------------------------

### ZVecInitOptions

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecInitOptions.html

Configuration interface for Zvec initialization.

```APIDOC
## ZVecInitOptions

### Description
Configuration options for initializing Zvec globally.

### Properties
- **logType** (ZVecLogType) - Optional - Type of log output. Default: ZVecLogType.CONSOLE
- **logLevel** (ZVecLogLevel) - Optional - Log level for messages. Default: ZVecLogLevel.WARN
- **logDir** (string) - Optional - Directory for log files (used when logType is 'FILE'). Default: './logs'
- **logBaseName** (string) - Optional - Base name for log files (used when logType is 'FILE'). Default: 'zvec.log'
- **logFileSize** (number) - Optional - Maximum size of each log file in bytes (used when logType is 'FILE'). Default: 2048
- **logOverdueDays** (number) - Optional - Number of days to keep old log files (used when logType is 'FILE'). Default: 7
- **queryThreads** (number) - Optional - Number of threads for query execution. Default: undefined
- **optimizeThreads** (number) - Optional - Number of threads for background tasks. Default: undefined
- **invertToForwardScanRatio** (number) - Optional - Threshold to switch from inverted-index filtering to forward scan. Default: undefined
- **bruteForceByKeysRatio** (number) - Optional - Threshold to use brute-force key lookup over index lookup. Default: undefined
- **ftsBruteForceByKeysRatio** (number) - Optional - Threshold to switch FTS scan strategy for highly selective candidates. Default: undefined
- **jiebaDictDir** (string) - Optional - Directory containing jieba tokenizer dictionary files. Default: undefined
```

--------------------------------

### ZVecGetIOBackendDescription()

Source: https://zvec.org/api-reference/nodejs/functions/ZVecGetIOBackendDescription.html

Returns a human-readable description of the active DiskANN I/O backend.

```APIDOC
## ZVecGetIOBackendDescription()

### Description
Returns a human-readable description of the active DiskANN I/O backend.

### Signature
`ZVecGetIOBackendDescription(): string`

### Returns
- **string** - A description of the active DiskANN I/O backend.
```

--------------------------------

### ZVecCreateAndOpen(path, schema, options)

Source: https://zvec.org/api-reference/nodejs/functions/ZVecCreateAndOpen.html

Creates and opens a Zvec collection.

```APIDOC
## ZVecCreateAndOpen

### Description
Creates and opens a Zvec collection at the specified path.

### Signature
`ZVecCreateAndOpen(path: string, schema: ZVecCollectionSchema, options?: ZVecCollectionOptions): ZVecCollection`

### Parameters
- **path** (string) - Required - The file system path where the collection will be created.
- **schema** (ZVecCollectionSchema) - Required - The schema defining the collection's structure.
- **options** (ZVecCollectionOptions) - Optional - Optional parameters for opening the collection.

### Returns
- **ZVecCollection** - An instance of ZVecCollection.
```

--------------------------------

### ZVecOpen(path: string, options?: ZVecCollectionOptions)

Source: https://zvec.org/api-reference/nodejs/functions/ZVecOpen.html

Opens an existing Zvec collection from the specified file system path.

```APIDOC
## ZVecOpen(path: string, options?: ZVecCollectionOptions)

### Description
Opens an existing Zvec collection located at the specified file system path.

### Parameters
- **path** (string) - Required - The file system path where the collection is stored.
- **options** (ZVecCollectionOptions) - Optional - Optional parameters for opening the collection.

### Returns
- **ZVecCollection** - An instance of ZVecCollection.
```

--------------------------------

### ZVecSetDefaultJiebaDictDir(dir: string): void

Source: https://zvec.org/api-reference/nodejs/functions/ZVecSetDefaultJiebaDictDir.html

Registers the process-wide default jieba dictionary directory.

```APIDOC
## ZVecSetDefaultJiebaDictDir

### Description
Registers the process-wide default jieba dictionary directory.

### Signature
`ZVecSetDefaultJiebaDictDir(dir: string): void`

### Parameters
- **dir** (string) - Required - The path to the jieba dictionary directory.

### Returns
- **void**
```

--------------------------------

### ZVecGetDefaultJiebaDictDir()

Source: https://zvec.org/api-reference/nodejs/functions/ZVecGetDefaultJiebaDictDir.html

Retrieves the process-wide default jieba dictionary directory path.

```APIDOC
## ZVecGetDefaultJiebaDictDir()

### Description
Reads the process-wide default jieba dictionary directory.

### Signature
`ZVecGetDefaultJiebaDictDir(): string`

### Returns
- **string** - The path to the default jieba dictionary directory.
```

--------------------------------

### ZVecCreateIndexOptions

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCreateIndexOptions.html

Configuration options for creating a new index on a field.

```APIDOC
## ZVecCreateIndexOptions

### Description
Configuration options for creating a new index on a field.

### Properties
- **concurrency** (number) - Optional - Number of threads to use during index creation. If 0, auto-detect is used. Default: 0.
```

--------------------------------

### Default logDir configuration

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecInitOptions.html

Default directory path for log files.

```typescript
'./logs'
```

--------------------------------

### Define ZVecCreateIndexOptions Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCreateIndexOptions.html

The interface structure for index creation configuration.

```typescript
interface ZVecCreateIndexOptions {  
concurrency?: number;  
}
```

--------------------------------

### ZVecDiskAnnQueryParams Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecDiskAnnQueryParams.html

Configuration parameters for DiskANN index queries.

```APIDOC
## ZVecDiskAnnQueryParams

### Description
Query-time parameters for searches performed against a DiskANN index.

### Properties
- **radius** (number) - Optional - Search radius for range queries. Used in combination with top-k to filter results. Default: 0.0 (disabled).
- **isLinear** (boolean) - Optional - If True, forces brute-force linear search instead of using the index. Default: false.
- **isUsingRefiner** (boolean) - Optional - Whether to use refiner for the query. Default: false.
- **indexType** (number) - Required - Must be 5 (ZVecIndexType.DISKANN).
- **listSize** (number) - Optional - Candidate list size used during search. Larger values improve recall but slow down search. Default: 300.
```

--------------------------------

### Default logFileSize configuration

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecInitOptions.html

Default maximum size for log files in bytes.

```typescript
2048
```

--------------------------------

### new ZVecCollectionSchema(params)

Source: https://zvec.org/api-reference/nodejs/classes/ZVecCollectionSchema.html

Creates a new instance of a collection schema.

```APIDOC
## constructor(params)

### Description
Creates a new collection schema instance.

### Parameters
- **params** (object) - Required
  - **name** (string) - Required: The name of the collection.
  - **vectors** (ZVecVectorSchema | ZVecVectorSchema[]) - Optional: An array of vector schemas or a single vector schema object.
  - **fields** (ZVecFieldSchema | ZVecFieldSchema[]) - Optional: An array of scalar field schemas or a single scalar field schema object.

### Returns
- **ZVecCollectionSchema** - The created collection schema instance.
```

--------------------------------

### toString()

Source: https://zvec.org/api-reference/nodejs/classes/ZVecCollectionSchema.html

Returns a string representation of the schema.

```APIDOC
## toString()

### Description
Returns a formatted string representation of the collection schema.

### Returns
- **string** - The string representation.
```

--------------------------------

### Default enableMMAP Value

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollectionOptions.html

The default setting for the enableMMAP property.

```text
true
```

--------------------------------

### Define ZVecInitOptions interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecInitOptions.html

Interface definition for global Zvec initialization options.

```typescript
interface ZVecInitOptions {  
logType?: ZVecLogType;  
logLevel?: ZVecLogLevel;  
logDir?: string;  
logBaseName?: string;  
logFileSize?: number;  
logOverdueDays?: number;  
queryThreads?: number;  
optimizeThreads?: number;  
invertToForwardScanRatio?: number;  
bruteForceByKeysRatio?: number;  
ftsBruteForceByKeysRatio?: number;  
jiebaDictDir?: string;  
}
```

--------------------------------

### ZVecGetIOBackendType()

Source: https://zvec.org/api-reference/nodejs/functions/ZVecGetIOBackendType.html

Retrieves the active I/O backend type used for DiskANN disk reads.

```APIDOC
## ZVecGetIOBackendType()

### Description
Returns the active I/O backend used for DiskANN disk reads.

### Signature
`ZVecGetIOBackendType(): ZVecIOBackendType`

### Returns
- **ZVecIOBackendType** - The type of the active I/O backend.
```

--------------------------------

### Default Values for IVF Query Parameters

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecIVFQueryParams.html

Default configuration values for the optional properties of the ZVecIVFQueryParams interface.

```text
0.0 (disabled)
```

```text
false
```

```text
false
```

```text
10
```

--------------------------------

### ZVecFtsQuery

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFtsQuery.html

Interface definition for full-text search queries.

```APIDOC
## ZVecFtsQuery

### Description
Full-text search clause. Provide exactly one of `queryString` or `matchString`.

### Properties
- **queryString** (string) - Optional - Query parser expression.
- **matchString** (string) - Optional - Literal match string.
```

--------------------------------

### ZVecCollection SDK Methods

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

The ZVecCollection interface provides a comprehensive set of synchronous and asynchronous methods for interacting with collection data and schema.

```APIDOC
## ZVecCollection Methods

### Data Operations
- `insertSync(docs: ZVecDocInput | ZVecDocInput[]): ZVecStatus | ZVecStatus[]` - Inserts documents into the collection.
- `upsertSync(docs: ZVecDocInput | ZVecDocInput[]): ZVecStatus | ZVecStatus[]` - Upserts documents into the collection.
- `updateSync(docs: ZVecDocInput | ZVecDocInput[]): ZVecStatus | ZVecStatus[]` - Updates existing documents.
- `deleteSync(ids: string | string[]): ZVecStatus` - Deletes documents by ID.
- `deleteByFilterSync(filter: string): ZVecStatus` - Deletes documents matching a filter synchronously.
- `deleteByFilter(filter: string): Promise<ZVecStatus>` - Deletes documents matching a filter asynchronously.

### Querying
- `querySync(params: ZVecQuery): ZVecDoc[]` - Executes a query synchronously.
- `query(params: ZVecQuery): Promise<ZVecDoc[]>` - Executes a query asynchronously.
- `multiQuerySync(params: ZVecMultiQuery): ZVecDoc[]` - Executes multiple queries synchronously.
- `multiQuery(params: ZVecMultiQuery): Promise<ZVecDoc[]>` - Executes multiple queries asynchronously.
- `groupByQuerySync(params: ZVecGroupByQuery): ZVecGroupResult[]` - Executes a group-by query synchronously.
- `groupByQuery(params: ZVecGroupByQuery): Promise<ZVecGroupResult[]>` - Executes a group-by query asynchronously.
- `fetchSync(ids: string | string[] | params): Record<string, ZVecDoc>` - Fetches documents by ID or parameters.

### Management & Schema
- `optimizeSync(options?: ZVecOptimizeOptions): void` - Optimizes the collection synchronously.
- `optimize(options?: ZVecOptimizeOptions): Promise<void>` - Optimizes the collection asynchronously.
- `closeSync(): void` - Closes the collection connection.
- `destroySync(): void` - Destroys the collection.
- `addColumnSync(params: { fieldSchema, expression?, options? }): void` - Adds a column to the schema.
- `dropColumnSync(fieldName: string): void` - Drops a column from the schema.
- `alterColumnSync(params: { columnName, newColumnName?, fieldSchema?, options? }): void` - Alters an existing column.
- `createIndexSync(params: { fieldName, indexParams, indexOptions? }): void` - Creates an index on a field.
- `dropIndexSync(fieldName: string): void` - Drops an index from a field.
```

--------------------------------

### ZVecHnswQueryParams Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecHnswQueryParams.html

Configuration parameters for HNSW index queries.

```APIDOC
## ZVecHnswQueryParams

### Description
Query-time parameters for searches performed against an HNSW index.

### Properties
- **indexType** (number) - Required - Must be 1 (ZVecIndexType.HNSW).
- **radius** (number) - Optional - Search radius for range queries. Default: 0.0 (disabled).
- **isLinear** (boolean) - Optional - If true, forces brute-force linear search. Default: false.
- **isUsingRefiner** (boolean) - Optional - Whether to use a refiner for the query. Default: false.
- **ef** (number) - Optional - Size of the dynamic candidate list during search. Default: 300.
```

--------------------------------

### Default logBaseName configuration

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecInitOptions.html

Default base filename for log files.

```typescript
'zvec.log'
```

--------------------------------

### ZVecDiskAnnIndexParams Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecDiskAnnIndexParams.html

Configuration object for defining DiskANN index parameters.

```APIDOC
## Interface: ZVecDiskAnnIndexParams

### Description
Configuration parameters for a DiskANN index on a vector field.

### Properties
- **indexType** (number) - Required - Must be 5 (ZVecIndexType.DISKANN).
- **metricType** (ZVecMetricType) - Optional - Distance metric used for similarity computation. Default: ZVecMetricType.IP.
- **maxDegree** (number) - Optional - Maximum out-degree of each graph node. Default: 100.
- **listSize** (number) - Optional - Candidate list size used during graph construction. Default: 50.
- **pqChunkNum** (number) - Optional - Maximum number of PQ chunks for product quantization. Default: 0.
- **quantizeType** (ZVecQuantizeType) - Optional - Optional quantization type for vector compression. Default: ZVecQuantizeType.UNDEFINED.
- **quantizerParams** (ZVecQuantizerParams) - Optional - Optional quantizer-specific configuration.
```

--------------------------------

### Default logLevel configuration

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecInitOptions.html

Default value for the log level.

```typescript
ZVecLogLevel.WARN
```

--------------------------------

### Default topkPerGroup Value

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecGroupByQuery.html

The default maximum number of documents to return per group.

```text
3
```

--------------------------------

### createIndexSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Creates an index on a specific column in the collection.

```APIDOC
## createIndexSync(params)

### Description
Creates an index on a specific column in the collection.

### Parameters
- **params** (object) - Required
  - **fieldName** (string) - Required - The name of the column to create the index on.
  - **indexParams** (ZVecFlatIndexParams | ZVecHnswIndexParams | ZVecHnswRabitqIndexParams | ZVecIVFIndexParams | ZVecDiskAnnIndexParams | ZVecInvertIndexParams | ZVecFtsIndexParams) - Required - The configuration parameters defining the index type and properties.
  - **indexOptions** (ZVecCreateIndexOptions) - Optional - Optional parameters for the index creation operation.

### Returns
- **void**

### Throws
- If the operation fails.
```

--------------------------------

### Default topk Value

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecMultiQuery.html

The default number of documents returned when topk is not specified.

```text
10
```

--------------------------------

### Default thread configuration

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecInitOptions.html

Default behavior for thread count settings.

```typescript
undefined // Let the system decide
```

--------------------------------

### ZVecHnswRabitqQueryParams Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecHnswRabitqQueryParams.html

The structure defining parameters for HNSW-RaBitQ index queries.

```typescript
interface ZVecHnswRabitqQueryParams {  
radius?: number;  
isLinear?: boolean;  
isUsingRefiner?: boolean;  
indexType: 4;  
ef?: number;  
}
```

--------------------------------

### ZVecHnswRabitqIndexParams Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecHnswRabitqIndexParams.html

The structure defining the configuration parameters for the HNSW-RaBitQ index.

```typescript
interface ZVecHnswRabitqIndexParams {  
indexType: 4;  
metricType?: ZVecMetricType;  
totalBits?: number;  
numClusters?: number;  
m?: number;  
efConstruction?: number;  
sampleCount?: number;  
}
```

--------------------------------

### optimizeSync / optimize

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Optimizes the collection's internal structures for better performance.

```APIDOC
## optimizeSync(options?: ZVecOptimizeOptions)

### Description
Synchronously optimizes the collection's internal structures.

### Parameters
- **options** (ZVecOptimizeOptions) - Optional - Optional parameters for the operation.

## optimize(options?: ZVecOptimizeOptions)

### Description
Asynchronously optimizes the collection's internal structures.

### Parameters
- **options** (ZVecOptimizeOptions) - Optional - Optional parameters for the operation.

### Returns
- **Promise<void>** - A promise that resolves when optimization is complete.
```

--------------------------------

### querySync / query

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Performs a search query against the collection, available in both synchronous and asynchronous versions.

```APIDOC
## querySync(params: ZVecQuery): ZVecDoc[]
## query(params: ZVecQuery): Promise<ZVecDoc[]>

### Description
Performs a search query against the collection.

### Parameters
- **params** (ZVecQuery) - Required - The query parameters.

### Returns
- **ZVecDoc[] | Promise<ZVecDoc[]>** - An array of documents matching the query.
```

--------------------------------

### fetchSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Fetches documents by their IDs from the collection.

```APIDOC
## fetchSync(ids: string | string[])

### Description
Fetches documents by their IDs.

### Parameters
- **ids** (string | string[]) - Required - 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.

## fetchSync(params: { ids: string | string[]; outputFields?: string[]; includeVector?: boolean; })

### Description
Fetches documents by their IDs with optional field filtering and vector inclusion.

### Parameters
- **params** (object) - Required
  - **ids** (string | string[]) - Required - A single document ID or an array of document IDs to fetch.
  - **outputFields** (string[]) - Optional - Scalar fields to include. If undefined, all scalar fields are returned.
  - **includeVector** (boolean) - Optional - 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.
```

--------------------------------

### ZVecAddColumnOptions

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecAddColumnOptions.html

Configuration options for adding a new column to a collection.

```APIDOC
## Interface: ZVecAddColumnOptions

### Description
Configuration options for adding a new column to a collection.

### Properties
- **concurrency** (number) - Optional - Number of threads to use when backfilling data for the new column. If 0, auto-detect is used. Default: 0.
```

--------------------------------

### Default Values for ZVecQuery Properties

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecQuery.html

Default values for various optional properties within the ZVecQuery interface.

```text
10
```

```text
undefined
```

```text
undefined
```

```text
undefined
```

```text
false
```

```text
undefined
```

```text
undefined
```

--------------------------------

### ZVecFtsQueryParams

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFtsQueryParams.html

Interface definition for full-text search query parameters.

```APIDOC
## Interface: ZVecFtsQueryParams

### Description
Query-time parameters for full-text search operations.

### Properties
- **indexType** (number) - Required - Must be 11 (ZVecIndexType.FTS).
- **defaultOperator** (string) - Optional - Default boolean operator for adjacent bare terms. Supported values are "AND" and "OR"; empty string defaults to "OR".
```

--------------------------------

### Default Parameter Values

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecDiskAnnQueryParams.html

Default values for the optional properties within the ZVecDiskAnnQueryParams interface.

```text
0.0 (disabled)
```

```text
false
```

```text
false
```

```text
300
```

--------------------------------

### Default logType configuration

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecInitOptions.html

Default value for the log output type.

```typescript
ZVecLogType.CONSOLE
```

--------------------------------

### ZVecCollectionOptions Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollectionOptions.html

The structure defining configuration options for collection management.

```typescript
interface ZVecCollectionOptions {  
readOnly?: boolean;  
enableMMAP?: boolean;  
}
```

--------------------------------

### ZVecQuantizerParams

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecQuantizerParams.html

Configuration interface for vector quantization parameters.

```APIDOC
## Interface: ZVecQuantizerParams

### Description
Additional configuration for vector quantization.

### Properties
- **enableRotate** (boolean) - Optional - Whether to rotate vectors before integer quantization to reduce quantization error. Defaults to `false`.
```

--------------------------------

### Define ZVecDiskAnnIndexParams Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecDiskAnnIndexParams.html

The structure of the DiskANN index configuration object.

```typescript
interface ZVecDiskAnnIndexParams {  
indexType: 5;  
metricType?: ZVecMetricType;  
maxDegree?: number;  
listSize?: number;  
pqChunkNum?: number;  
quantizeType?: ZVecQuantizeType;  
quantizerParams?: ZVecQuantizerParams;  
}
```

--------------------------------

### Default Tokenizer Configuration

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFtsIndexParams.html

The default value for the tokenizerName property.

```json
"standard"
```

--------------------------------

### ZVecIVFQueryParams

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecIVFQueryParams.html

Interface definition for IVF index query parameters.

```APIDOC
## Interface: ZVecIVFQueryParams

### Description
Query-time parameters for searches performed against an IVF index.

### Properties
- **radius** (number) - Optional - Search radius for range queries. Used in combination with top-k to filter results. Default: 0.0 (disabled).
- **isLinear** (boolean) - Optional - If True, forces brute-force linear search instead of using the index. Default: false.
- **isUsingRefiner** (boolean) - Optional - Whether to use refiner for the query. Default: false.
- **indexType** (number) - Required - Must be 2 (ZVecIndexType.IVF).
- **nprobe** (number) - Optional - Number of closest clusters (inverted lists) to search. Higher values improve recall but increase latency. Default: 10.
```

--------------------------------

### ZVecMultiQuery Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecMultiQuery.html

The ZVecMultiQuery interface defines the structure for combining multiple search queries into a single result set.

```APIDOC
## Interface: ZVecMultiQuery

### Description
Multi-query object used to combine multiple vector and/or full-text searches. Each sub-query contributes candidates, which are then combined into a single result list using a specified rerank strategy.

### Properties
- **queries** (ZVecSubQuery[]) - Required - Sub-queries to execute and merge. At least two are required.
- **topk** (number) - Optional - Number of final documents to return. Default: 10.
- **filter** (string) - Optional - Boolean expression to pre-filter candidates for every sub-query.
- **includeVector** (boolean) - Optional - Whether to include vector data in results. Default: false.
- **outputFields** (string[]) - Optional - Scalar fields to include. If undefined, all fields are returned.
- **rerank** (object) - Optional - Strategy for merging sub-query candidates. If omitted, reciprocal rank fusion with rank constant 60 is used.

### Rerank Strategies
- **rrf**: { type: "rrf"; rankConstant?: number } - Reciprocal rank fusion. Default rankConstant is 60.
- **weighted**: { type: "weighted"; weights: number[] } - Weighted score fusion. The length of weights must match the length of queries.
```

--------------------------------

### ZVecQuery Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecQuery.html

The ZVecQuery interface is used to configure search parameters for vector and full-text queries.

```APIDOC
## Interface: ZVecQuery

### Description
Query object used to perform searches against a collection, including vector similarity, full-text, and scalar filtering.

### Properties
- **fieldName** (string) - Optional - The name of the vector field to search against.
- **topk** (number) - Optional - Number of nearest neighbors to return. Default: 10.
- **vector** (ZVecVector) - Optional - The query vector. Can be a standard JavaScript array, a typed array, or a sparse vector object map.
- **fts** (ZVecFtsQuery) - Optional - Full-text search clause.
- **filter** (string) - Optional - Boolean expression to pre-filter candidates.
- **includeVector** (boolean) - Optional - Whether to include vector data in results. Default: false.
- **outputFields** (string[]) - Optional - Scalar fields to include. If undefined, all fields are returned.
- **params** (ZVecHnswQueryParams | ZVecHnswRabitqQueryParams | ZVecIVFQueryParams | ZVecDiskAnnQueryParams | ZVecFtsQueryParams) - Optional - Query-time parameters to fine-tune search behavior.
```

--------------------------------

### Default List Size

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecDiskAnnIndexParams.html

The default candidate list size used during graph construction.

```typescript
50
```

--------------------------------

### multiQuerySync / multiQuery

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Performs multiple searches against the collection and merges candidates, available in both synchronous and asynchronous versions.

```APIDOC
## multiQuerySync(params: ZVecMultiQuery): ZVecDoc[]
## multiQuery(params: ZVecMultiQuery): Promise<ZVecDoc[]>

### Description
Performs multiple searches against the collection and merges their candidates.

### Parameters
- **params** (ZVecMultiQuery) - Required - The multi-query parameters.

### Returns
- **ZVecDoc[] | Promise<ZVecDoc[]>** - An array of documents matching the combined query.
```

--------------------------------

### Default Parameter Values

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecIVFIndexParams.html

Default values for optional configuration properties in the IVF index.

```typescript
ZVecMetricType.IP
```

```typescript
10
```

```typescript
10
```

```typescript
ZVecQuantizeType.UNDEFINED
```

--------------------------------

### Define ZVecFtsIndexParams Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFtsIndexParams.html

The structure required to configure a full-text search index.

```typescript
interface ZVecFtsIndexParams {  
indexType: 11;  
tokenizerName?: string;  
filters?: string[];  
extraParams?: string;  
}
```

--------------------------------

### closeSync / destroySync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Lifecycle management methods for closing or deleting a collection.

```APIDOC
## closeSync()

### Description
Closes the collection and releases its resources.

## destroySync()

### Description
Permanently deletes the collection from disk.
```

--------------------------------

### Define ZVecFtsQuery Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFtsQuery.html

The interface structure for full-text search, requiring exactly one of the two optional properties.

```typescript
interface ZVecFtsQuery {  
queryString?: string;  
matchString?: string;  
}
```

--------------------------------

### insertSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Inserts a single document or a batch of documents into the collection.

```APIDOC
## insertSync(docs: ZVecDocInput): ZVecStatus
## insertSync(docs: ZVecDocInput[]): ZVecStatus[]

### Description
Inserts a single document or a batch of documents into the collection.

### Parameters
- **docs** (ZVecDocInput | ZVecDocInput[]) - Required - A single document or an array of documents to insert.

### Returns
- **ZVecStatus | ZVecStatus[]** - The status or array of statuses of the operation.
```

--------------------------------

### Define ZVecOptimizeOptions Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecOptimizeOptions.html

Interface definition for configuring optimization parameters.

```typescript
interface ZVecOptimizeOptions {  
concurrency?: number;  
}
```

--------------------------------

### Default Total Bits

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecHnswRabitqIndexParams.html

The default number of bits used for RaBitQ quantization.

```typescript
7
```

--------------------------------

### fields()

Source: https://zvec.org/api-reference/nodejs/classes/ZVecCollectionSchema.html

Retrieves all scalar field schemas.

```APIDOC
## fields()

### Description
Gets the array of scalar field schemas.

### Returns
- **ZVecFieldSchema[]** - An array of scalar field schema objects.
```

--------------------------------

### ZVecQuery Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecQuery.html

The core interface structure for defining search queries against a collection.

```typescript
interface ZVecQuery {  
fieldName?: string;  
topk?: number;  
vector?: ZVecVector;  
fts?: ZVecFtsQuery;  
filter?: string;  
includeVector?: boolean;  
outputFields?: string[];  
params?:  
| ZVecHnswQueryParams  
| ZVecHnswRabitqQueryParams  
| ZVecIVFQueryParams  
| ZVecDiskAnnQueryParams  
| ZVecFtsQueryParams;  
}
```

--------------------------------

### HNSW Index Parameter Defaults

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecHnswIndexParams.html

Default values for various HNSW index configuration properties.

```typescript
ZVecMetricType.IP
```

```typescript
50
```

```typescript
500
```

```typescript
ZVecQuantizeType.UNDEFINED
```

```typescript
false
```

--------------------------------

### groupByQuerySync / groupByQuery

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Performs a vector search and groups results by a scalar field, available in both synchronous and asynchronous versions.

```APIDOC
## groupByQuerySync(params: ZVecGroupByQuery): ZVecGroupResult[]
## groupByQuery(params: ZVecGroupByQuery): Promise<ZVecGroupResult[]>

### Description
Performs a vector search and groups results by a scalar field.

### Parameters
- **params** (ZVecGroupByQuery) - Required - The group by query parameters.

### Returns
- **ZVecGroupResult[] | Promise<ZVecGroupResult[]>** - An array of grouped results.
```

--------------------------------

### ZVecFlatIndexParams Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFlatIndexParams.html

The base interface structure for configuring a flat index.

```typescript
interface ZVecFlatIndexParams {  
indexType: 3;  
metricType?: ZVecMetricType;  
quantizeType?: ZVecQuantizeType;  
quantizerParams?: ZVecQuantizerParams;  
}
```

--------------------------------

### ZVecIVFIndexParams Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecIVFIndexParams.html

The base interface structure for defining IVF index parameters.

```typescript
interface ZVecIVFIndexParams {  
indexType: 2;  
metricType?: ZVecMetricType;  
nList?: number;  
nIters?: number;  
quantizeType?: ZVecQuantizeType;  
quantizerParams?: ZVecQuantizerParams;  
}
```

--------------------------------

### Define ZVecFtsQueryParams Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFtsQueryParams.html

The interface structure for full-text search parameters, requiring a specific index type.

```typescript
interface ZVecFtsQueryParams {  
indexType: 11;  
defaultOperator?: string;  
}
```

--------------------------------

### Default Token Filters Configuration

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFtsIndexParams.html

The default value for the filters property.

```json
["lowercase"]
```

--------------------------------

### ZVecIVFQueryParams Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecIVFQueryParams.html

The structure defining query-time parameters for IVF index searches.

```typescript
interface ZVecIVFQueryParams {  
radius?: number;  
isLinear?: boolean;  
isUsingRefiner?: boolean;  
indexType: 2;  
nprobe?: number;  
}
```

--------------------------------

### Default Quantize Type

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecDiskAnnIndexParams.html

The default quantization type for vector compression.

```typescript
ZVecQuantizeType.UNDEFINED
```

--------------------------------

### vectors()

Source: https://zvec.org/api-reference/nodejs/classes/ZVecCollectionSchema.html

Retrieves all vector field schemas.

```APIDOC
## vectors()

### Description
Gets the array of vector field schemas.

### Returns
- **ZVecVectorSchema[]** - An array of vector schema objects.
```

--------------------------------

### Default Number of Clusters

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecHnswRabitqIndexParams.html

The default number of clusters used in RaBitQ quantization.

```typescript
16
```

--------------------------------

### Default groupCount Value

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecGroupByQuery.html

The default maximum number of groups to return.

```text
2
```

--------------------------------

### ZVecDiskAnnQueryParams Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecDiskAnnQueryParams.html

The structure of the query parameters required for DiskANN index operations.

```typescript
interface ZVecDiskAnnQueryParams {  
radius?: number;  
isLinear?: boolean;  
isUsingRefiner?: boolean;  
indexType: 5;  
listSize?: number;  
}
```

--------------------------------

### Define ZVecAlterColumnOptions Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecAlterColumnOptions.html

Interface definition for configuring column alteration options.

```typescript
interface ZVecAlterColumnOptions {  
concurrency?: number;  
}
```

--------------------------------

### ZVecHnswQueryParams Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecHnswQueryParams.html

The structure defining query-time parameters for HNSW index searches.

```typescript
interface ZVecHnswQueryParams {  
radius?: number;  
isLinear?: boolean;  
isUsingRefiner?: boolean;  
indexType: 1;  
ef?: number;  
}
```

--------------------------------

### updateSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Updates existing documents by ID, modifying only specified fields and vectors.

```APIDOC
## updateSync(docs: ZVecDocInput): ZVecStatus
## updateSync(docs: ZVecDocInput[]): ZVecStatus[]

### Description
Updates a single existing document or multiple existing documents by ID. Only specified fields and vectors are updated; others remain unchanged.

### Parameters
- **docs** (ZVecDocInput | ZVecDocInput[]) - Required - A single document or an array of documents containing the updated data.

### Returns
- **ZVecStatus | ZVecStatus[]** - The status or array of statuses of the operation.
```

--------------------------------

### Define ZVecHnswIndexParams Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecHnswIndexParams.html

The structure for configuring an HNSW index, requiring indexType to be set to 1.

```typescript
interface ZVecHnswIndexParams {  
indexType: 1;  
metricType?: ZVecMetricType;  
m?: number;  
efConstruction?: number;  
quantizeType?: ZVecQuantizeType;  
useContiguousMemory?: boolean;  
quantizerParams?: ZVecQuantizerParams;  
}
```

--------------------------------

### Define ZVecQuantizerParams Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecQuantizerParams.html

Defines the structure for vector quantization parameters including the optional enableRotate property.

```typescript
interface ZVecQuantizerParams {  
enableRotate?: boolean;  
}
```

--------------------------------

### field(fieldName)

Source: https://zvec.org/api-reference/nodejs/classes/ZVecCollectionSchema.html

Retrieves a specific scalar field schema by its name.

```APIDOC
## field(fieldName)

### Description
Retrieves a scalar field schema by its name.

### Parameters
- **fieldName** (string) - Required: The name of the field to retrieve.

### Returns
- **ZVecFieldSchema** - The requested field schema.

### Throws
- **Error** if the field with the given name is not found.
```

--------------------------------

### ZVecMultiQuery Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecMultiQuery.html

The structure of the multi-query object defining sub-queries, ranking strategies, and result filtering.

```typescript
interface ZVecMultiQuery {  
queries: ZVecSubQuery[];  
topk?: number;  
filter?: string;  
includeVector?: boolean;  
outputFields?: string[];  
rerank?:  
| { type: "rrf"; rankConstant?: number }  
| { type: "weighted"; weights: number[] };  
}
```

--------------------------------

### addColumnSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Adds a new column to the collection.

```APIDOC
## addColumnSync(params: { fieldSchema: ZVecFieldSchema; expression?: string; options?: ZVecAddColumnOptions; })

### Description
Adds a new column to the collection.

### Parameters
- **params** (object) - Required
  - **fieldSchema** (ZVecFieldSchema) - Required - The schema definition for the new column.
  - **expression** (string) - Optional - Optional expression to compute values for existing documents.
  - **options** (ZVecAddColumnOptions) - Optional - Optional parameters for the operation.
```

--------------------------------

### Default Value for IndexParams Property

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFieldSchema.html

The default value for the indexParams property when not explicitly set.

```text
undefined
```

--------------------------------

### isZVecError(error: unknown): error is ZVecError

Source: https://zvec.org/api-reference/nodejs/functions/isZVecError.html

A type guard function used to verify if an caught error is an instance of ZVecError.

```APIDOC
## isZVecError(error: unknown)

### Description
Type guard for narrowing an `unknown` caught value to a ZVecError. Use this in `catch (e: unknown)` blocks to safely access `e.code`.

### Parameters
- **error** (unknown) - Required - The error object caught in a catch block.

### Returns
- **boolean** (error is ZVecError) - Returns true if the object is a ZVecError, false otherwise.
```

--------------------------------

### Default Value for Nullable Property

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFieldSchema.html

The default value for the nullable property when not explicitly set.

```text
false
```

--------------------------------

### ZVecInvertIndexParams Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecInvertIndexParams.html

Defines the structure for inverted index configuration parameters.

```typescript
interface ZVecInvertIndexParams {  
indexType: 10;  
enableRangeOptimization?: boolean;  
enableExtendedWildcard?: boolean;  
}
```

--------------------------------

### ZVecLogLevel

Source: https://zvec.org/api-reference/nodejs/variables/ZVecLogLevel.html

The ZVecLogLevel constant defines the available log levels as a numeric enum object.

```APIDOC
## ZVecLogLevel

### Description
Numeric enum object defining supported log levels in Zvec.

### Type Declaration
- **DEBUG**: 0 (Readonly)
- **INFO**: 1 (Readonly)
- **WARN**: 2 (Readonly)
- **ERROR**: 3 (Readonly)
- **FATAL**: 4 (Readonly)
```

--------------------------------

### upsertSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Inserts a document or updates it if it already exists based on its ID.

```APIDOC
## upsertSync(docs: ZVecDocInput): ZVecStatus
## upsertSync(docs: ZVecDocInput[]): ZVecStatus[]

### Description
Inserts a single document or a batch of documents into the collection, or updates them if they already exist based on their ID.

### Parameters
- **docs** (ZVecDocInput | ZVecDocInput[]) - Required - A single document or an array of documents to upsert.

### Returns
- **ZVecStatus | ZVecStatus[]** - The status or array of statuses of the operation.
```

--------------------------------

### Default efConstruction

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecHnswRabitqIndexParams.html

The default size of the dynamic candidate list for nearest neighbors during index construction.

```typescript
500
```

--------------------------------

### Define ZVecFieldSchema Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFieldSchema.html

The core interface structure for defining a scalar field schema.

```typescript
interface ZVecFieldSchema {  
name: string;  
dataType: ZVecDataType;  
nullable?: boolean;  
indexParams?: ZVecInvertIndexParams | ZVecFtsIndexParams;  
}
```

--------------------------------

### Default Concurrency Value

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecAlterColumnOptions.html

The default value for the concurrency property.

```text
0
```

--------------------------------

### ZVecAddColumnOptions Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecAddColumnOptions.html

Defines the structure for column addition options, including the optional concurrency property.

```typescript
interface ZVecAddColumnOptions {  
concurrency?: number;  
}
```

--------------------------------

### Default Metric Type

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecDiskAnnIndexParams.html

The default distance metric used for similarity computation.

```typescript
ZVecMetricType.IP
```

--------------------------------

### Default Operator Value

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecFtsQueryParams.html

The default value for the optional defaultOperator property.

```text
""
```

--------------------------------

### dropColumnSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Permanently deletes a column from the collection.

```APIDOC
## dropColumnSync(fieldName: string)

### Description
Permanently deletes a column from the collection.

### Parameters
- **fieldName** (string) - Required - The name of the column to drop.
```

--------------------------------

### vector(vectorName)

Source: https://zvec.org/api-reference/nodejs/classes/ZVecCollectionSchema.html

Retrieves a specific vector field schema by its name.

```APIDOC
## vector(vectorName)

### Description
Retrieves a vector field schema by its name.

### Parameters
- **vectorName** (string) - Required: The name of the vector field to retrieve.

### Returns
- **ZVecVectorSchema** - The requested vector schema.

### Throws
- **Error** if the vector field with the given name is not found.
```

--------------------------------

### ZVecGroupByQuery Interface Definition

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecGroupByQuery.html

The core interface structure for defining a grouped vector query.

```typescript
interface ZVecGroupByQuery {  
fieldName: string;  
vector: ZVecVector;  
groupByFieldName: string;  
groupCount?: number;  
topkPerGroup?: number;  
filter?: string;  
includeVector?: boolean;  
outputFields?: string[];  
params?:  
| ZVecHnswQueryParams  
| ZVecHnswRabitqQueryParams  
| ZVecIVFQueryParams  
| ZVecDiskAnnQueryParams;  
}
```

--------------------------------

### Default Max Degree

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecDiskAnnIndexParams.html

The default maximum out-degree of each graph node.

```typescript
100
```

--------------------------------

### dropIndexSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Drops (removes) an existing index from the collection.

```APIDOC
## dropIndexSync(fieldName)

### Description
Drops (removes) an existing index from the collection.

### Parameters
- **fieldName** (string) - Required - The name of the column whose index should be dropped.

### Returns
- **void**

### Throws
- If the operation fails.
```

--------------------------------

### Define ZVecVectorSchema Interface

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecVectorSchema.html

Structure definition for the ZVecVectorSchema interface.

```typescript
interface ZVecVectorSchema {  
name: string;  
dataType: ZVecDataType;  
dimension?: number;  
indexParams?:  
| ZVecFlatIndexParams  
| ZVecHnswIndexParams  
| ZVecHnswRabitqIndexParams  
| ZVecIVFIndexParams  
| ZVecDiskAnnIndexParams;  
}
```

--------------------------------

### deleteSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Deletes a single document or multiple documents by their IDs.

```APIDOC
## deleteSync(ids: string): ZVecStatus
## deleteSync(ids: string[]): ZVecStatus[]

### Description
Deletes a single document or multiple documents by their IDs.

### Parameters
- **ids** (string | string[]) - Required - A single document ID or an array of document IDs to delete.

### Returns
- **ZVecStatus | ZVecStatus[]** - The status or array of statuses of the operation.
```

--------------------------------

### ZVecDataType

Source: https://zvec.org/api-reference/nodejs/variables/ZVecDataType.html

A constant object containing numeric identifiers for various scalar, vector, and array data types supported by Zvec.

```APIDOC
## ZVecDataType

### Description
Numeric enum object defining supported data types in Zvec. Scalar types are used with ZVecFieldSchema, while vector types are used with ZVecVectorSchema.

### Members
- **STRING**: 2
- **BOOL**: 3
- **INT32**: 4
- **INT64**: 5
- **UINT32**: 6
- **UINT64**: 7
- **FLOAT**: 8
- **DOUBLE**: 9
- **VECTOR_FP16**: 22
- **VECTOR_FP32**: 23
- **VECTOR_FP64**: 24
- **VECTOR_INT8**: 26
- **SPARSE_VECTOR_FP16**: 30
- **SPARSE_VECTOR_FP32**: 31
- **ARRAY_STRING**: 41
- **ARRAY_BOOL**: 42
- **ARRAY_INT32**: 43
- **ARRAY_INT64**: 44
- **ARRAY_UINT32**: 45
- **ARRAY_UINT64**: 46
- **ARRAY_FLOAT**: 47
- **ARRAY_DOUBLE**: 48
```

--------------------------------

### alterColumnSync

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Alters an existing column in the collection.

```APIDOC
## alterColumnSync(params: { columnName: string; newColumnName?: string; fieldSchema?: ZVecFieldSchema; options?: ZVecAlterColumnOptions; })

### Description
Alters an existing column in the collection by renaming it or modifying its schema.

### Parameters
- **params** (object) - Required
  - **columnName** (string) - Required - The current name of the column to alter.
  - **newColumnName** (string) - Optional - The new name for the column.
  - **fieldSchema** (ZVecFieldSchema) - Optional - The new schema definition for the column.
  - **options** (ZVecAlterColumnOptions) - Optional - Optional parameters for the operation.
```

--------------------------------

### Default RRF Rank Constant

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecMultiQuery.html

The default rank constant used for Reciprocal Rank Fusion.

```text
60
```

--------------------------------

### deleteByFilterSync / deleteByFilter

Source: https://zvec.org/api-reference/nodejs/interfaces/ZVecCollection.html

Deletes documents based on a filter expression, available in both synchronous and asynchronous versions.

```APIDOC
## deleteByFilterSync(filter: string): ZVecStatus
## deleteByFilter(filter: string): Promise<ZVecStatus>

### Description
Deletes documents based on a filter expression.

### Parameters
- **filter** (string) - Required - A string representing the filter expression.

### Returns
- **ZVecStatus | Promise<ZVecStatus>** - The status of the operation.
```
Tokens:
Raw