Milvus2-sdk-node

The official Milvus client for Node.js.

Compatibility

The following table shows the recommended @zilliz/milvus2-sdk-node versions for different Milvus versions:

Milvus version	Node sdk version	Installation
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
v2.3.0+	v2.3.5	yarn add @zilliz/milvus2-sdk-node@2.3.5
v2.2.0+	v2.3.5	yarn add @zilliz/milvus2-sdk-node@2.3.5

Dependencies

• Milvus
• Zilliz Cloud
• Node: v18+

Installation

You can use npm (Node package manager) or Yarn to install the @zilliz/milvus2-sdk-node dependency in your project:

1npm install @zilliz/milvus2-sdk-node
2# or ...
3yarn add @zilliz/milvus2-sdk-node

Milvus TLS Guide

Please refer to this doc.

Code Examples

This table organizes the examples by technology, providing a brief description and the directory where each example can be found.

Technology	Example	Directory
Next.js	Next.js app example	examples/nextjs
Node.js	Basic Node.js examples for Milvus	examples/milvus
Langchain.js	Basic Langchain.js example	examples/langchain

Basic usages

This guide will show you how to set up a simple application using Node.js and Milvus. Its scope is only how to set up the node.js client and perform the simple CRUD operations. For more in-depth coverage, see the Milvus official website.

Start a Milvus server

1# Start Milvus with script
2wget https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh
3bash standalone_embed.sh start

Connect to Milvus

Create a new app.js file and add the following code to try out some basic vector operations using the Milvus node.js client. More details on the API reference.

1import { MilvusClient, DataType } from '@zilliz/milvus2-sdk-node';
2
3const address = 'your-milvus-ip-with-port';
4const username = 'your-milvus-username'; // optional username
5const password = 'your-milvus-password'; // optional password
6
7// connect to milvus
8const client = new MilvusClient({ address, username, password });
9// wait until connecting finished
10await client.connectPromise;

Create a collection

In Milvus, the concept of the collection is like the table in traditional RDBMS, eg: mysql or postgres. Before creating a collection, you need to define a schema, then just call the createCollection method.

Define schema for collection

A schema defines the fields of a collection, such as the names and data types of the fields that make up the vectors. More details of how to define schema and advanced usage can be found in API reference.

1// define schema
2const collection_name = `hello_milvus`;
3const dim = 128;
4const schema = [
5  {
6    name: 'age',
7    description: 'ID field',
8    data_type: DataType.Int64,
9    is_primary_key: true,
10    autoID: true,
11  },
12  {
13    name: 'vector',
14    description: 'Vector field',
15    data_type: DataType.FloatVector,
16    dim: 8,
17  },
18  { name: 'height', description: 'int64 field', data_type: DataType.Int64 },
19  {
20    name: 'name',
21    description: 'VarChar field',
22    data_type: DataType.VarChar,
23    max_length: 128,
24  },
25],

Create the collection

1await client.createCollection({
2  collection_name,
3  fields: schema,
4});

Prepare data

The data format utilized by the Milvus Node SDK comprises an array of objects. In each object, the key should correspond to the field name defined in the schema. The value type for the key should match the data_type specified in the field of the schema.

1const fields_data = [
2  {
3    name: 'zlnmh',
4    vector: [
5      0.11878310581111173, 0.9694947902934701, 0.16443679307243175,
6      0.5484226189097237, 0.9839246709011924, 0.5178387104937776,
7      0.8716926129208069, 0.5616972243831446,
8    ],
9    height: 20405,
10  },
11  {
12    name: '5lr9y',
13    vector: [
14      0.9992090731236536, 0.8248790611809487, 0.8660083940881405,
15      0.09946359318481224, 0.6790698063908669, 0.5013786801063624,
16      0.795311915725105, 0.9183033261617566,
17    ],
18    height: 93773,
19  },
20  {
21    name: 'nes0j',
22    vector: [
23      0.8761291569818763, 0.07127366044153227, 0.775648976160332,
24      0.5619757601304878, 0.6076543120476996, 0.8373907516027586,
25      0.8556140171597648, 0.4043893119391049,
26    ],
27    height: 85122,
28  },
29];

Insert data into collection

Once we have the data, you can insert data into the collection by calling the insert method.

1await client.insert({
2  collection_name,
3  data,
4});

Create index

By creating an index and loading the collection into memory, you can improve the performance of search and retrieval operations in Milvus, making it faster and more efficient to work with large-scale datasets.

1// create index
2await client.createIndex({
3  collection_name, // required
4  field_name: 'vector', // optional if you are using milvus v2.2.9+
5  index_name: 'myindex', // optional
6  index_type: 'HNSW', // optional if you are using milvus v2.2.9+
7  params: { efConstruction: 10, M: 4 }, // optional if you are using milvus v2.2.9+
8  metric_type: 'L2', // optional if you are using milvus v2.2.9+
9});

Milvus supports several different types of indexes, each of which is optimized for different use cases and data distributions. Some of the most commonly used index types in Milvus include HNSW, IVF_FLAT, IVF_SQ8, IVF_PQ. When creating an index in Milvus, you must choose an appropriate index type based on your specific use case and data distribution.

Load collection

When you create a collection in Milvus, the collection data is initially stored on disk, and it is not immediately available for search and retrieval. In order to search or retrieve data from the collection, you must first load the collection into memory using the loadCollectionSync method.

1// load collection
2await client.loadCollectionSync({
3  collection_name,
4});

vector search

Now you can perform vector search on your collection.

1// get the search vector
2const searchVector = fields_data[0].vector;
3
4// Perform a vector search on the collection
5const res = await client.search({
6  // required
7  collection_name, // required, the collection name
8  data: searchVector, // required, vector used to compare other vectors in milvus
9  // optionals
10  filter: 'height > 0', // optional, filter expression
11  params: { nprobe: 64 }, // optional, specify the search parameters
12  limit: 10, // optional, specify the number of nearest neighbors to return
13  output_fields: ['height', 'name'], // optional, specify the fields to return in the search results,
14});

Next Steps

• Attu, Using GUI to manage Milvus

other useful links

• What is Milvus
• Milvus Node SDK API reference
• Feder, anns index visualization tool

How to contribute

1. yarn install
2. Fetch milvus proto
   1. git submodule init (if this is your first time)
   2. git submodule update --remote
3. Add feature in milvus folder.
4. Run test yarn test -- test/Your-test-for-your-feature.spec.ts