milvus-sdk-node

KO | EN

gitlite — search

#hacktoberfest #react #ai #typescript #android #deep-learning #docker #macos #nodejs #windows #awesome-list #security #ios #open-source

milvus-sdk-node

(★ 197)

The Official Milvus node.js sdk(client)

File Explorer

Download Latest Version (.zip)

- - Bug_report.md
  - Feature_request.md
- - doc.yml
  - release.yml
  - test.yml
- - icon.svg
  - milvus-logo.svg
- - content.config.ts
  - env.d.ts
  - route-middleware.ts
- .gitignore
- .prettierrc
- astro.config.mjs
- package.json
- tsconfig.json
- yarn.lock
- - LangChain.js
  - package.json
  - README.md
  - yarn.lock
- - BinarySearch.ts
  - Data.ts
  - Database.ts
  - DataQuery.ts
  - DynamicSchema.ts
  - EntityTTL.ts
  - HelloMilvus.ts
  - HelloSparse.ts
  - package.json
  - PartitionKey.ts
  - QueryIterator.ts
  - README.md
  - Server.ts
  - test.ts
  - tsconfig.json
  - yarn.lock
- - .eslintrc.json
  - .gitignore
  - components.json
  - eslint.config.mjs
  - next.config.js
  - package-lock.json
  - package.json
  - postcss.config.js
  - proxy.ts
  - README.md
  - tailwind.config.ts
  - tsconfig.json
  - vercel.json
  - yarn.lock
- - BulkWriter.ts
  - ColumnBuffer.ts
  - index.ts
  - JsonFormatter.ts
  - LocalStorage.ts
  - ParquetFormatter.ts
  - Types.ts
  - VolumeManager.ts
- - client.ts
  - defaults.ts
  - error.ts
  - highLevel.ts
  - index.ts
  - limits.ts
  - milvus.ts
- - BaseClient.ts
  - Collection.ts
  - Data.ts
  - Database.ts
  - GrpcClient.ts
  - MilvusIndex.ts
  - Partition.ts
  - Resource.ts
  - User.ts
- - Alias.ts
  - Collection.ts
  - Database.ts
  - Import.ts
  - index.ts
  - MilvusIndex.ts
  - Partition.ts
  - Role.ts
  - User.ts
  - Vector.ts
- - milvus.base.ts
  - milvus.ts
  - schema.base.ts
- - Client.ts
  - Collection.ts
  - Common.ts
  - Data.ts
  - Database.ts
  - DataTypes.ts
  - GlobalCluster.ts
  - HighLevel.ts
  - Http.ts
  - index.ts
  - Insert.ts
  - MilvusIndex.ts
  - Partition.ts
  - Resource.ts
  - Response.ts
  - Search.ts
  - SearchAggregation.ts
  - Segments.ts
  - User.ts
  - Volume.ts
- - BloomFilter.ts
  - Bytes.ts
  - Connection.ts
  - Data.ts
  - Format.ts
  - Function.ts
  - GlobalTopology.ts
  - Grpc.ts
  - index.ts
  - logger.ts
  - RoaringFilter.ts
  - Schema.ts
  - Search.ts
  - SearchAggregation.ts
  - Validate.ts
- HttpClient.ts
- index.ts
- MilvusClient.ts
- types.ts
- - Collection.spec.ts
- - BulkWriter.spec.ts
  - ParquetFormatter.spec.ts
  - VolumeManager.spec.ts
- - ca.key
  - ca.pem
  - ca.srl
  - client.csr
  - client.key
  - client.pem
  - gen.sh
  - openssl.cnf
  - README.md
  - server.csr
  - server.key
  - server.pem
- - Alias.spec.ts
  - Basic.spec.ts
  - BatchDescribeCollection.spec.ts
  - BFloat16Vector.spec.ts
  - BinaryVector.spec.ts
  - BulkWriter.e2e.spec.ts
  - BulkWriterIterator.e2e.spec.ts
  - BulkWriterNullable.e2e.spec.ts
  - BulkWriterParquet.e2e.spec.ts
  - ClusteringKey.spec.ts
  - Collection.spec.ts
  - Compaction.spec.ts
  - Data.spec.ts
  - Database.spec.ts
  - DynamicSchema.spec.ts
  - ElementLevel.spec.ts
  - ExternalCollection.spec.ts
  - FileResource.spec.ts
  - Float16Vector.spec.ts
  - FlushAll.spec.ts
  - FullTextSearch.spec.ts
  - FunctionFieldBackfill.e2e.spec.ts
  - Geometry.spec.ts
  - GlobalCluster.spec.ts
  - HighLevel.spec.ts
  - Highlight.spec.ts
  - Import.spec.ts
  - Index.spec.ts
  - Insert.spec.ts
  - Int8Vector.spec.ts
  - Iterator.spec.ts
  - KeywordMatch.spec.ts
  - MilvusClient.spec.ts
  - MultipleVectors.spec.ts
  - NullableVector.spec.ts
  - PartialLoad.spec.ts
  - Partition.spec.ts
  - PartitionKey.spec.ts
  - Replica.spec.ts
  - Resource.spec.ts
  - SearchAggregation.spec.ts
  - Segment.spec.ts
  - Snapshot.spec.ts
  - SparseVector.array.spec.ts
  - SparseVector.coo.spec.ts
  - SparseVector.csr.spec.ts
  - SparseVector.dict.spec.ts
  - Struct.spec.ts
  - StructArrayAdvanced.spec.ts
  - Text.spec.ts
  - TextEmbedding.spec.ts
  - Timestamptz.spec.ts
  - TruncateCollection.spec.ts
  - Upsert.spec.ts
  - UpsertArrayPartialOp.spec.ts
  - User.spec.ts
- - client.spec.ts
  - cloud.spec.ts
  - fetch.spec.ts
  - import.spec.ts
  - node-fetch.spec.ts
  - serverless.spec.ts
  - test.ts
- - bench.ts
  - bulkwriter-bench.ts
  - bulkwriter-vs-insert-bench.ts
  - collection.ts
  - const.ts
  - data.ts
  - index.ts
  - ip.ts
  - utils.ts
- - BloomFilter.spec.ts
  - Bytes.spec.ts
  - Collection.spec.ts
  - Compaction.spec.ts
  - Connection.spec.ts
  - Data.spec.ts
  - Format.spec.ts
  - Function.spec.ts
  - GlobalConnection.spec.ts
  - GlobalTopology.spec.ts
  - Grpc.spec.ts
  - ProtoJson.spec.ts
  - ReplicateConfiguration.spec.ts
  - Rerank.spec.ts
  - RoaringFilter.spec.ts
  - Schema.spec.ts
  - Search.spec.ts
  - SearchAggregation.spec.ts
  - Test.spec.ts
  - Validate.spec.ts
.babelrc
.gitignore
.gitmodules
.prettierrc
3.0_change.md
AGENTS.md
build.js
CLAUDE.md
CODE_OF_CONDUCT.md
codecov.yml
CONTRIBUTING.md
doc.js
jest.config.js
LICENSE
llms.txt
package.json
proto
README.md
Retry.md
sdk.json
SECURITY.md
tsconfig.json
typedoc.json
yarn.lock

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# @zilliz/milvus2-sdk-node

Official Node.js SDK for [Milvus](https://github.com/milvus-io/milvus) vector database. Provides gRPC and HTTP clients for vector similarity search, metadata filtering, and full collection/index/user management.

**Package**: `@zilliz/milvus2-sdk-node` | **Node.js**: v18+ | **License**: Apache-2.0

[![npm version](https://img.shields.io/npm/v/@zilliz/milvus2-sdk-node)](https://www.npmjs.com/package/@zilliz/milvus2-sdk-node)
[![downloads](https://img.shields.io/npm/dw/@zilliz/milvus2-sdk-node)](https://www.npmjs.com/package/@zilliz/milvus2-sdk-node)
[![codecov](https://codecov.io/gh/milvus-io/milvus-sdk-node/branch/main/graph/badge.svg?token=Zu5FwWstwI)](https://codecov.io/gh/milvus-io/milvus-sdk-node)

## Installation

```bash
npm install @zilliz/milvus2-sdk-node
# or
yarn add @zilliz/milvus2-sdk-node
```

## Compatibility

| Milvus version | SDK version | Install command                             |
| :------------: | :---------: | :------------------------------------------ |
|    v2.6.0+     |  **latest** | `yarn add @zilliz/milvus2-sdk-node@latest`  |
|    v2.5.0+     |   v2.5.0    | `yarn add @zilliz/milvus2-sdk-node@2.5.12`  |
|    v2.4.0+     |   v2.4.9    | `yarn add @zilliz/milvus2-sdk-node@2.4.9`   |

## Quick Start

### Connect to Milvus

```typescript
import { MilvusClient } from '@zilliz/milvus2-sdk-node';

// Local Milvus
const client = new MilvusClient({ address: 'localhost:19530' });

// With authentication
const client = new MilvusClient({
  address: 'localhost:19530',
  username: 'root',
  password: 'milvus',
});

// Zilliz Cloud
const client = new MilvusClient({
  address: 'your-endpoint.zillizcloud.com',
  token: 'your-api-key',
});

// Wait for connection to be ready
await client.connectPromise;
```

### Create Collection, Insert, and Search

```typescript
import {
  MilvusClient,
  DataType,
  MetricType,
} from '@zilliz/milvus2-sdk-node';

const client = new MilvusClient({ address: 'localhost:19530' });

// 1. Create collection with schema
await client.createCollection({
  collection_name: 'my_collection',
  fields: [
    { name: 'id', data_type: DataType.Int64, is_primary_key: true, autoID: true },
    { name: 'text', data_type: DataType.VarChar, max_length: 512 },
    { name: 'vector', data_type: DataType.FloatVector, dim: 128 },
  ],
  index_params: [
    {
      field_name: 'vector',
      index_type: 'HNSW',
      metric_type: MetricType.COSINE,
      params: { M: 16, efConstruction: 256 },
    },
  ],
  enable_dynamic_field: true,
});

// 2. Load into memory (required before search/query)
await client.loadCollection({ collection_name: 'my_collection' });

// 3. Insert data
await client.insert({
  collection_name: 'my_collection',
  data: [
    { vector: Array(128).fill(0.1), text: 'doc1' },
    { vector: Array(128).fill(0.2), text: 'doc2' },
  ],
});

// 4. Search
const results = await client.search({
  collection_name: 'my_collection',
  data: [Array(128).fill(0.1)],
  limit: 10,
  output_fields: ['text'],
});
console.log(results.results);
```

---

## API Reference

### Imports

```typescript
// Main client
import { MilvusClient } from '@zilliz/milvus2-sdk-node';

// HTTP client (for environments without gRPC support)
import { HttpClient } from '@zilliz/milvus2-sdk-node';

// Enums and constants
import {
  DataType,
  MetricType,
  IndexType,
  ConsistencyLevelEnum,
  ErrorCode,
} from '@zilliz/milvus2-sdk-node';

// Bulk writer for large-scale imports
import { BulkWriter } from '@zilliz/milvus2-sdk-node';
```

### Client Configuration

```typescript
new MilvusClient({
  address: string;              // Required. "host:port" or "https://host:port"
  token?: string;               // Auth token (username:password or API key)
  username?: string;            // Username for auth
  password?: string;            // Password for auth
  ssl?: boolean;                // Enable SSL/TLS
  database?: string;            // Default database name
  timeout?: number | string;    // Request timeout in ms (or string like '30s')
  maxRetries?: number;          // Max retry attempts (default: 3)
  retryDelay?: number;          // Retry delay in ms (default: 10)
  logLevel?: string;            // 'debug' | 'info' | 'warn' | 'error'
  trace?: boolean;              // Enable OpenTelemetry tracing
  tls?: {                       // TLS certificate configuration
    rootCertPath?: string;
    privateKeyPath?: string;
    certChainPath?: string;
    serverName?: string;
    skipCertCheck?: boolean;
  };
  pool?: {                      // Connection pool (generic-pool options)
    max?: number;               // Max connections (default: 10)
    min?: number;               // Min connections (default: 2)
  };
});
```

---

### Data Operations

#### insert

Insert rows into a collection.

```typescript
await client.insert({
  collection_name: string;
  data: Record<string, any>[];      // Array of row objects
  partition_name?: string;
});
// Returns: { succ_index: number[], err_index: number[], IDs: string[] | number[], ... }
```

#### upsert

Insert or update rows (matched by primary key).

```typescript
await client.upsert({
  collection_name: string;
  data: Record<string, any>[];
  partition_name?: string;
  partial_update?: boolean;
  field_ops?: Array<{
    field_name: string;
    op: 'REPLACE' | 'ARRAY_APPEND' | 'ARRAY_REMOVE';
  }>;
});
```

Partial array upsert can append to or remove from existing Array fields:

```typescript
import { FieldPartialUpdateOpType } from '@zilliz/milvus2-sdk-node';

await client.upsert({
  collection_name: 'articles',
  data: [{ id: 1, tags: ['featured'] }],
  field_ops: [
    { field_name: 'tags', op: FieldPartialUpdateOpType.ARRAY_APPEND },
  ],
});
```

#### delete

Delete rows by filter expression or primary key IDs.

```typescript
// By filter
await client.delete({
  collection_name: 'articles',
  filter: 'age > 18',
});

// By IDs
await client.delete({
  collection_name: 'articles',
  ids: [1, 2, 3],
});
```

#### search

Vector similarity search.

```typescript
const results = await client.search({
  collection_name: string;
  data?: number[][] | number[]; // Query vector(s), not required when ids is provided
  ids?: (string | number)[];    // Primary key IDs for Search By PK
  limit?: number;               // Top-K results (default: 100)
  output_fields?: string[];     // Fields to return
  filter?: string;              // Scalar filter expression
  metric_type?: MetricType;     // Distance metric
  params?: {                    // Index-specific search params
    ef?: number;                // HNSW ef (search width)
    nprobe?: number;            // IVF nprobe
    radius?: number;            // Range search radius
    range_filter?: number;      // Range search filter
  };
  consistency_level?: ConsistencyLevelEnum;
  partition_names?: string[];
  group_by_field?: string;      // Group results by field
});
// Returns: { results: [{ id, score, ...output_fields }], ... }
```

Search by primary key IDs without providing query vectors:

```typescript
const results = await client.search({
  collection_name: 'articles',
  ids: [1, 2, 3],
  output_fields: ['title', 'category'],
});
```

Search aggregation supports bucket metrics, top hits, and nested buckets.

```typescript
const results = await client.search({
  collection_name: 'products',
  data: [0.1, 0.2, 0.3, 0.4],
  output_fields: ['category', 'brand', 'price'],
  search_aggregation: {
    fields: ['category'],
    size: 5,
    metrics: {
      item_count: { op: 'count', field_name: '*' },
      avg_price: { op: 'avg', field_name: 'price' },
    },
    order: [{ key: 'avg_price', direction: 'desc' }],
    top_hits: {
      size: 2,
      sort: [{ field_name: 'price', direction: 'asc' }],
    },
    sub_aggregation: {
      fields: ['brand'],
      size: 3,
    },
  },
});

// A single query vector returns AggregationBucket[].
// Multiple query vectors return AggregationBucket[][].
console.log(results.agg_buckets);
```

#### query

Query rows with scalar filter expression.

```typescript
const results = await client.query({
  collection_name: string;
  filter: string;               // Boolean expression, e.g. 'age > 18 AND status == "active"'
  output_fields?: string[];     // Fields to return (default: all)
  limit?: number;
  offset?: number;
  group_by_fields?: string[];   // Scalar fields used to group aggregation results
  consistency_level?: ConsistencyLevelEnum;
  partition_names?: string[];
});
// Returns: { data: Record<string, any>[] }
```

Aggregation functions are specified in `output_fields`. The supported functions
are `count`, `min`, `max`, `sum`, and `avg`.

```typescript
const results = await client.query({
  collection_name: 'sales',
  filter: 'price > 0',
  group_by_fields: ['category'],
  output_fields: [
    'category',
    'count(price)',
    'min(price)',
    'max(price)',
    'sum(price)',
    'avg(price)',
  ],
});
```

#### get

Get rows by primary key IDs.

```typescript
const results = await client.get({
  collection_name: string;
  ids: (string | number)[];
  output_fields?: string[];
});
```

#### count

Count rows matching a filter.

```typescript
const result = await client.count({
  collection_name: string;
  filter?: string;
});
// Returns: { data: number }
```

#### searchIterator

Paginated vector search using async iterator.

```typescript
const iterator = await client.searchIterator({
  collection_name: string;
  data: number[];
  batchSize: number;
  limit: number;
  output_fields?: string[];
  filter?: string;
  expr?: string;
});

for await (const batch of iterator) {
  console.log(batch);  // Array of results per batch
}
```

#### queryIterator

Paginated query using async iterator.

```typescript
const iterator = await client.queryIterator({
  collection_name: string;
  filter?: string;
  batchSize: number;
  limit: number;
  output_fields?: string[];
  expr?: string;
});

for await (const batch of iterator) {
  console.log(batch);
}
```

#### hybridSearch

Multi-vector search combining results from multiple vector fields with reranking.

```typescript
const results = await client.hybridSearch({
  collection_name: string;
  rerank: WeightedReranker | RRFReranker;  // Reranking strategy
  requests: Array<{
    data: number[][];
    anns_field: string;
    params?: Record<string, any>;
    limit?: number;
    filter?: string;
  }>;
  limit: number;
  output_fields?: string[];
});
```

---

### Collection Management

#### createCollection

```typescript
await client.createCollection({
  collection_name: string;
  fields: FieldType[];               // Define schema fields
  index_params?: CreateIndexParam[];  // Create indexes at collection creation time
  enable_dynamic_field?: boolean;     // Allow inserting fields not in schema
  consistency_level?: ConsistencyLevelEnum;
  num_partitions?: number;
});
// Note: call loadCollection() after creation before search/query
```

#### Other collection operations

```typescript
await client.hasCollection({ collection_name });          // { value: boolean }
await client.describeCollection({ collection_name });     // Schema, fields, properties
await client.batchDescribeCollections({ collection_names: string[] });  // Describe multiple collections
await client.showCollections();                           // List all collections
await client.loadCollection({ collection_name });         // Load into memory
await client.releaseCollection({ collection_name });      // Release from memory
await client.refreshLoad({ collection_name });            // Refresh loaded collection
await client.dropCollection({ collection_name });         // Delete collection
await client.renameCollection({ collection_name, new_collection_name });
await client.truncateCollection({ collection_name });     // Clear all data
await client.getLoadState({ collection_name });           // Loading status
await client.getCollectionStatistics({ collection_name });
await client.alterCollectionProperties({ collection_name, properties });
await client.alterCollectionFieldProperties({ collection_name, field_name, properties });
await client.dropCollectionProperties({ collection_name, delete_keys: string[] });
await client.addCollectionFunction({ collection_name, functions });
await client.dropCollectionFunction({ collection_name, functions });
```

---

### Index Management

```typescript
// Create index
await client.createIndex({
  collection_name: string;
  field_name: string;
  index_type?: IndexType;       // Default: AUTOINDEX
  metric_type?: MetricType;     // Default: COSINE
  params?: Record<string, any>; // e.g. { M: 16, efConstruction: 256 }
  index_name?: string;
});

// Other index operations
await client.describeIndex({ collection_name, field_name? });
await client.listIndexes({ collection_name });
await client.getIndexStatistics({ collection_name, index_name? });
await client.dropIndex({ collection_name, field_name, index_name? });
await client.getIndexState({ collection_name, field_name? });
await client.getIndexBuildProgress({ collection_name, field_name? });
await client.alterIndexProperties({ collection_name, index_name, properties });
await client.dropIndexProperties({ collection_name, index_name, delete_keys: string[] });
```

---

### Partition Management

```typescript
await client.createPartition({ collection_name, partition_name });
await client.hasPartition({ collection_name, partition_name });
await client.listPartitions({ collection_name });
await client.loadPartitions({ collection_name, partition_names: string[] });
await client.releasePartitions({ collection_name, partition_names: string[] });
await client.dropPartition({ collection_name, partition_name });
```

---

### Database Management

```typescript
await client.createDatabase({ db_name });
await client.listDatabases();
await client.describeDatabase({ db_name });
await client.alterDatabaseProperties({ db_name, properties });
await client.dropDatabaseProperties({ db_name, delete_keys: string[] });
await client.dropDatabase({ db_name });
```

---

### User & Role Management (RBAC)

```typescript
// Users
await client.createUser({ username, password });
await client.updateUser({ username, oldPassword, newPassword });
await client.deleteUser({ username });
await client.listUsers();

// Roles
await client.createRole({ roleName });
await client.dropRole({ roleName });
await client.listRoles();
await client.addUserToRole({ username, roleName });
await client.removeUserFromRole({ username, roleName });

// Privileges
await client.grantPrivilege({ roleName, object, objectName, privilegeName });
await client.revokePrivilege({ roleName, object, objectName, privilegeName });
await client.listGrants({ roleName });

// V2 privilege API
await client.grantPrivilegeV2({ role, privilege, collection_name, db_name });
await client.revokePrivilegeV2({ role, privilege, collection_name, db_name });
```

---

### Alias Management

```typescript
await client.createAlias({ collection_name, alias });
await client.dropAlias({ alias });
await client.alterAlias({ collection_name, alias });
await client.describeAlias({ alias });
await client.listAliases({ collection_name });
```

---

### Resource Group Management

```typescript
await client.createResourceGroup({ resource_group, config });
await client.listResourceGroups();
await client.describeResourceGroup({ resource_group });
await client.dropResourceGroup({ resource_group });
await client.transferReplica({ source_resource_group, target_resource_group, collection_name, num_replica });
```

---

### Bulk Import

#### BulkWriter — Generate import files offline

```typescript
import { BulkWriter, DataType } from '@zilliz/milvus2-sdk-node';

const writer = new BulkWriter({
  schema: {
    fields: [
      { name: 'id', data_type: DataType.Int64, is_primary_key: true },
      { name: 'vector', data_type: DataType.FloatVector, dim: 128 },
      { name: 'title', data_type: DataType.VarChar, max_length: 256 },
    ],
  },
  format: 'parquet',  // 'json' or 'parquet'
  localPath: './bulk_data',
  chunkSize: 128 * 1024 * 1024,  // 128 MB per file
});

// Append rows
for (const row of rows) {
  await writer.append(row);
}

// Finalize and get file paths
const batchFiles = await writer.close();
// batchFiles: [['./bulk_data/batch_0/1.parquet'], ...]
```

#### Server-side import

```typescript
// Trigger bulk import (files must be on Milvus-accessible storage)
await client.bulkInsert({ collection_name, files: ['data.json'] });

// Check import status
await client.getImportState({ taskId });
await client.listImportTasks({ collection_name });
```

---

### Flush & Compaction

```typescript
await client.flush({ collection_names: string[] });
await client.flushSync({ collection_names: string[] });       // Wait for completion
await client.flushAll();                                       // Flush all collections
await client.flushAllSync();                                   // Flush all and wait for completion
await client.compact({ collection_name });
await client.getCompactionState({ compactionID });
```

---

### System Operations

```typescript
await client.getVersion();                        // Milvus server version
await client.checkHealth();                       // Server health status
await client.reconnectToPrimary();                // Force reconnect to primary node
await client.runAnalyzer({ text, analyzer });     // Test text analyzer tokenization
```

---

## Data Types

### Scalar Types

| DataType enum        | TypeScript value  | Notes                                 |
| -------------------- | ----------------- | ------------------------------------- |
| `DataType.Bool`      | `boolean`         |                                       |
| `DataType.Int8`      | `number`          |                                       |
| `DataType.Int16`     | `number`          |                                       |
| `DataType.Int32`     | `number`          |                                       |
| `DataType.Int64`     | `number \| string` | Use string for values > 2^53         |
| `DataType.Float`     | `number`          |                                       |
| `DataType.Double`    | `number`          |                                       |
| `DataType.VarChar`   | `string`          | Requires `max_length`                 |
| `DataType.JSON`      | `object`          |                                       |
| `DataType.Array`     | `any[]`           | Requires `element_type`, `max_capacity` |

### Vector Types

| DataType enum                | Data format                        | Field param   |
| ---------------------------- | ---------------------------------- | ------------- |
| `DataType.FloatVector`       | `number[]`                         | `dim: number` |
| `DataType.BinaryVector`      | `number[]` (uint8 bytes)           | `dim: number` |
| `DataType.Float16Vector`     | `number[]`                         | `dim: number` |
| `DataType.BFloat16Vector`    | `number[]`                         | `dim: number` |
| `DataType.Int8Vector`        | `number[]`                         | `dim: number` |
| `DataType.SparseFloatVector` | `Record<number, number>` or array  | no dim needed |

### Field Definition

```typescript
interface FieldType {
  name: string;
  data_type: DataType;
  is_primary_key?: boolean;
  autoID?: boolean;
  dim?: number;                    // Required for vector types
  max_length?: number;             // Required for VarChar
  element_type?: DataType;         // Required for Array
  max_capacity?: number;           // Required for Array
  default_value?: any;
  is_partition_key?: boolean;
  enable_analyzer?: boolean;       // For full-text search
  analyzer_params?: object;
}
```

---

## Enums & Constants

### MetricType

```typescript
MetricType.L2          // Euclidean distance (smaller = more similar)
MetricType.IP          // Inner product (larger = more similar)
MetricType.COSINE      // Cosine similarity (larger = more similar)
MetricType.HAMMING     // Hamming distance (binary vectors)
MetricType.JACCARD     // Jaccard distance (binary vectors)
MetricType.BM25        // BM25 relevance (sparse/text)
```

### IndexType

```typescript
IndexType.AUTOINDEX    // Automatic selection (recommended)
IndexType.HNSW         // High recall, in-memory
IndexType.IVF_FLAT     // Balanced speed/recall
IndexType.IVF_SQ8      // Compressed IVF
IndexType.IVF_PQ       // High compression IVF
IndexType.FLAT         // Brute-force (exact)
IndexType.DISKANN      // On-disk index
IndexType.BIN_FLAT     // Binary brute-force
IndexType.BIN_IVF_FLAT // Binary IVF
IndexType.SPARSE_INVERTED_INDEX  // Sparse vectors
IndexType.SPARSE_WAND           // Sparse vectors (WAND)
```

### ConsistencyLevelEnum

```typescript
ConsistencyLevelEnum.Strong      // Read-after-write guarantee
ConsistencyLevelEnum.Session     // Session-level consistency
ConsistencyLevelEnum.Bounded     // Bounded staleness
ConsistencyLevelEnum.Eventually  // Best performance
```

### ErrorCode

```typescript
ErrorCode.SUCCESS             // Operation succeeded
ErrorCode.UnexpectedError     // Internal error
ErrorCode.CollectionNotExists // Collection not found
ErrorCode.IllegalArgument     // Invalid argument
ErrorCode.RateLimit           // Rate limited
```

---

## Filter Expressions

Used in `search({ filter })`, `query({ filter })`, `delete({ filter })`.

```
# Comparison
age > 18
price <= 99.9
status == "active"
name != "test"

# Logical operators
age > 18 AND status == "active"
price < 10 OR price > 100
NOT (status == "deleted")

# IN operator
id IN [1, 2, 3]
category IN ["books", "music"]

# String matching
title LIKE "hello%"         # Starts with "hello"
title LIKE "%world"         # Ends with "world"

# Array operations
ARRAY_CONTAINS(tags, "ai")
ARRAY_LENGTH(tags) > 3

# JSON field access
metadata["key"] == "value"
metadata["nested"]["field"] > 10

# Template expressions (parameterized)
await client.query({
  collection_name: 'test',
  filter: 'age > {min_age}',
  filter_params: { min_age: 18 },
});
```

---

## HTTP Client

For environments where gRPC is not available (Cloudflare Workers, Vercel Edge, AWS Lambda).

```typescript
import { HttpClient } from '@zilliz/milvus2-sdk-node';

const client = new HttpClient({
  endpoint: 'localhost:19530',    // or Zilliz Cloud endpoint
  username: 'root',               // optional
  password: 'milvus',             // optional
  token: 'your-api-key',          // optional (for Zilliz Cloud)
  database: 'default',            // optional
  timeout: 60000,                 // optional, ms
});

// Same API surface as MilvusClient for data operations
await client.createCollection({ ... });
await client.insert({ ... });
await client.search({ ... });
await client.query({ ... });
```

---

## Error Handling

```typescript
import { ErrorCode } from '@zilliz/milvus2-sdk-node';

try {
  const res = await client.createCollection({ ... });
  if (res.error_code !== ErrorCode.SUCCESS) {
    console.error('Milvus error:', res.reason);
  }
} catch (err) {
  console.error('Connection/transport error:', err.message);
}
```

---

## Common Patterns

### Hybrid Search (vector + scalar filter)

```typescript
const results = await client.search({
  collection_name: 'products',
  data: [queryVector],
  limit: 20,
  filter: 'category == "electronics" AND price < 500',
  output_fields: ['name', 'price', 'category'],
});
```

### Dynamic Fields

```typescript
// Enable dynamic fields on collection
await client.createCollection({
  collection_name: 'flexible',
  fields: [
    { name: 'id', data_type: DataType.Int64, is_primary_key: true, autoID: true },
    { name: 'vector', data_type: DataType.FloatVector, dim: 128 },
  ],
  enable_dynamic_field: true,
});

await client.loadCollection({ collection_name: 'flexible' });

// Insert with arbitrary fields — extra fields stored dynamically
await client.insert({
  collection_name: 'flexible',
  data: [
    { vector: [...], color: 'red', score: 0.95 },
    { vector: [...], color: 'blue', tags: ['a', 'b'] },
  ],
});

// Query dynamic fields
await client.query({
  collection_name: 'flexible',
  filter: 'color == "red"',
  output_fields: ['color', 'score'],
});
```

### Sparse Vector Search (e.g. BM25)

```typescript
await client.createCollection({
  collection_name: 'docs',
  fields: [
    { name: 'id', data_type: DataType.Int64, is_primary_key: true, autoID: true },
    { name: 'sparse_vector', data_type: DataType.SparseFloatVector },
  ],
});

await client.insert({
  collection_name: 'docs',
  data: [
    { sparse_vector: { 0: 0.5, 10: 0.3, 200: 0.8 } },   // dict format
    { sparse_vector: { 1: 0.1, 50: 0.9 } },
  ],
});

await client.search({
  collection_name: 'docs',
  data: [{ 0: 0.5, 10: 0.3 }],
  anns_field: 'sparse_vector',
  limit: 10,
});
```

### Partition Key (auto-routing)

```typescript
await client.createCollection({
  collection_name: 'multi_tenant',
  fields: [
    { name: 'id', data_type: DataType.Int64, is_primary_key: true, autoID: true },
    { name: 'tenant', data_type: DataType.VarChar, max_length: 64, is_partition_key: true },
    { name: 'vector', data_type: DataType.FloatVector, dim: 128 },
  ],
  num_partitions: 16,
});

// Milvus automatically routes by partition key
await client.search({
  collection_name: 'multi_tenant',
  data: [queryVector],
  filter: 'tenant == "user_123"',   // Scoped to partition
  limit: 10,
});
```

---

### Advanced Features

For detailed guides on advanced features, visit the documentation:

- **[Hybrid Search](docs/src/content/docs/operations/hybrid-search.mdx)** — Multi-vector search with reranking
- **[Full-Text Search](docs/src/content/docs/advanced/full-text-search.mdx)** — BM25 keyword search with text analyzers
- **[Iterators](docs/src/content/docs/operations/iterators.mdx)** — Paginate through large result sets
- **[Global Cluster](docs/src/content/docs/advanced/global-cluster.mdx)** — Multi-region failover support

---

## Links

- [Full Documentation](https://milvus-io.github.io/milvus-sdk-node)
- [Milvus Documentation](https://milvus.io/docs)
- [GitHub Repository](https://github.com/milvus-io/milvus-sdk-node)
- [Zilliz Cloud](https://cloud.zilliz.com/)
- [Examples](https://github.com/milvus-io/milvus-sdk-node/tree/main/examples)

milvus-sdk-node

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

milvus-sdk-node

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README