@zilliz/milvus2-sdk-node 2.2.6 → 2.2.7

package/README.md

@@ -5,7 +5,7 @@
 
 # Milvus2-sdk-node
 
-Node.js sdk for [Milvus](https://github.com/milvus-io/milvus).
+The official [Milvus](https://github.com/milvus-io/milvus) client for Node.js.
 
 ## Compatibility
 
@@ -25,19 +25,178 @@ The following collection shows Milvus versions and recommended @zilliz/milvus2-s
 
 ## Installation
 
+The recommended way to get started using the Milvus node.js client is by using npm (Node package manager) to install the dependency in your project.
+
 ```javascript
 npm install @zilliz/milvus2-sdk-node
+# or ...
+yarn add @zilliz/milvus2-sdk-node
+```
+
+This will download the Milvus node.js client and add a dependency entry in your package.json file.
+
+## Quick Start
+
+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](https://milvus.io/).
+
+### Create the package.json file
+
+First, create a directory where your application will live.
+
+```
+mkdir myProject
+cd myProject
+```
+
+Enter the following command and answer the questions to create the initial structure for your new project:
+
+```shell
+npm init -y
+```
+
+Next, install this client as a dependency.
+
+```shell
+npm install @zilliz/milvus2-sdk-node
+```
+
+### Start a milvus server
+
+```shell
+# Download the milvus standalone yaml file
+$ wget https://github.com/milvus-io/milvus/releases/download/v2.2.6/milvus-standalone-docker-compose.yml -O docker-compose.yml
+
+# start the milvus server
+sudo docker-compose up -d
+```
+
+### 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.
+
+```javascript
+import { MilvusClient, DataType } from '@zilliz/milvus2-sdk-node';
+
+const IP = 'your-milvus-ip';
+
+// connect to milvus
+const client = new MilvusClient(IP);
+```
+
+### define schema for collection
+
+```javascript
+// define schema
+const collection_name = `book`;
+const dim = 128;
+const schema = [
+  {
+    name: `book_id`,
+    description: `customized primary id`,
+    data_type: DataType.Int64,
+    is_primary_key: true,
+    autoID: false,
+  },
+  {
+    name: `word_count`,
+    description: `word count`,
+    data_type: DataType.Int64,
+  },
+  {
+    name: `book_intro`,
+    description: `word count`,
+    data_type: DataType.FloatVector,
+    type_params: {
+      dim: dim,
+    },
+  },
+];
+```
+
+### create collection
+
+```javascript
+await client.createCollection({
+  collection_name,
+  description: `my first collection`,
+  fields: schema,
+});
+```
+
+### prepare data
+
+```javascript
+// generate mock data
+const fields_data = [];
+
+// generate mock data
+for (let i = 0; i < 1000; i++) {
+  // create a new object with random values for each field
+  const r = {
+    book_id: Math.floor(Math.random() * 100000), // generate a random book ID
+    word_count: Math.floor(Math.random() * 1000), // generate a random word count
+    book_intro: [...Array(dim)].map(() => Math.random()), // generate a random vector for book_intro
+  };
+  // add the new object to the fields_data array
+  fields_data.push(r);
+}
 ```
 
-More documentation, you can refer [Milvus offical website](https://milvus.io/).
+### insert data into collection
 
-## Example
+```javascript
+await client.insert({
+  collection_name,
+  fields_data,
+});
+```
 
-1. [Hello World](https://github.com/milvus-io/milvus-sdk-node/blob/main/example/HelloMilvus.ts)
-2. [Create a collection](https://milvus.io/docs/create_collection.md)
-3. [Insert data](https://milvus.io/docs/insert_data.md)
-4. [Build index](https://milvus.io/docs/build_index.md)
-5. [Do vector search](https://milvus.io/docs/search.md)
+### create index and load collection into memory
+
+```javascript
+// create index
+await client.createIndex({
+  collection_name,
+  field_name: 'book_intro',
+  index_name: 'myindex',
+  extra_params: {
+    index_type: 'IVF_FLAT',
+    metric_type: 'L2',
+  },
+});
+// load collection
+await client.loadCollectionSync({
+  collection_name,
+});
+```
+
+### vector search
+
+```javascript
+// Generate a random search vector
+const searchVector = [...Array(dim)].map(() => Math.random());
+
+// Perform a vector search on the collection
+const res = await client.search({
+  collection_name,
+  vectors: [searchVector],
+  search_params: {
+    anns_field: 'book_intro', // specify the field to search on
+    metric_type: 'L2', // specify the distance metric to use
+    params: JSON.stringify({ nprobe: 64 }), // specify the search parameters
+    topk: 1, // specify the number of nearest neighbors to return
+  },
+  output_fields: ['book_id', 'word_count'], // specify the fields to return in the search results
+  vector_type: DataType.FloatVector, // specify the data type of the vectors
+});
+```
+
+## Next Steps
+
+- [What is Milvus](https://milvus.io/)
+- [Milvus Node SDK API reference](https://milvus.io/api-reference/node/v2.2.x/About.md)
+- [Attu, Milvus GUI tool, based on Milvus node.js SDK](https://github.com/zilliztech/attu)
+- [Feder, anns index visuliazation tool](https://github.com/zilliztech/feder)
 
 ## How to contribute
 
@@ -47,8 +206,3 @@ More documentation, you can refer [Milvus offical website](https://milvus.io/).
    2. `git submodule update --remote`
 3. Add feature in milvus folder.
 4. Run test `yarn test -- test/Your-test-for-your-feature.spec.ts`
-
-## Others
-
-- [Attu](https://github.com/zilliztech/attu) which is a Milvus web interface tool, depends on Milvus node.js SDK.
-- [Feder](https://github.com/zilliztech/feder) which is a visualization tool for visualize hnsw, faiss and other index.

package/dist/milvus/BaseClient.d.ts

@@ -1,17 +1,18 @@
 import { Root } from 'protobufjs';
-import { Client } from '@grpc/grpc-js';
+import { Client, ChannelOptions } from '@grpc/grpc-js';
+import { MilvusClientConfig } from '.';
 export declare class BaseClient {
     schemaProto: Root;
     milvusProto: Root;
     grpcClient: Client;
+    timeout: number;
     /**
-     * Connect to milvus grpc client.
-     *
-     * @param address milvus address like: 127.0.0.1:19530
-     * @param ssl ssl connect or not, default is false
-     * @param username After created user in Milvus, username is required
-     * @param password After created user in Milvus, password is required
+     * Connect to a Milvus gRPC client.
      *
+     * @param configOrAddress The configuration object or the Milvus address as a string.
+     * @param ssl Whether to use SSL or not. Default is false.
+     * @param username The username for authentication. Required if password is provided.
+     * @param password The password for authentication. Required if username is provided.
      */
-    constructor(address: string, ssl?: boolean, username?: string, password?: string);
+    constructor(configOrAddress: MilvusClientConfig | string, ssl?: boolean, username?: string, password?: string, channelOptions?: ChannelOptions);
 }

package/dist/milvus/BaseClient.js

@@ -1,4 +1,15 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -9,27 +20,40 @@ var protobufjs_1 = __importDefault(require("protobufjs"));
 var grpc_js_1 = require("@grpc/grpc-js");
 var _1 = require(".");
 var utils_1 = require("../utils");
-// pathes
+// path
 var protoPath = path_1.default.resolve(__dirname, '../proto/proto/milvus.proto');
 var schemaProtoPath = path_1.default.resolve(__dirname, '../proto/proto/schema.proto');
 // Base Client
 var BaseClient = /** @class */ (function () {
     /**
-     * Connect to milvus grpc client.
-     *
-     * @param address milvus address like: 127.0.0.1:19530
-     * @param ssl ssl connect or not, default is false
-     * @param username After created user in Milvus, username is required
-     * @param password After created user in Milvus, password is required
+     * Connect to a Milvus gRPC client.
      *
+     * @param configOrAddress The configuration object or the Milvus address as a string.
+     * @param ssl Whether to use SSL or not. Default is false.
+     * @param username The username for authentication. Required if password is provided.
+     * @param password The password for authentication. Required if username is provided.
      */
-    function BaseClient(address, ssl, username, password) {
+    function BaseClient(configOrAddress, ssl, username, password, channelOptions) {
+        var config;
+        // If a configuration object is provided, use it. Otherwise, create a new object with the provided parameters.
+        if (typeof configOrAddress === 'object') {
+            config = configOrAddress;
+        }
+        else {
+            config = {
+                address: configOrAddress,
+                ssl: ssl,
+                username: username,
+                password: password,
+                channelOptions: channelOptions,
+            };
+        }
         // check if address is set
-        if (!address) {
+        if (!config.address) {
             throw new Error(_1.ERROR_REASONS.MILVUS_ADDRESS_IS_REQUIRED);
         }
         // if we need to create auth interceptors
-        var needAuth = username !== undefined && password !== undefined;
+        var needAuth = config.username !== undefined && config.password !== undefined;
         // get Milvus GRPC service
         var MilvusService = (0, utils_1.getGRPCService)({
             protoPath: protoPath,
@@ -37,20 +61,25 @@ var BaseClient = /** @class */ (function () {
         });
         // create interceptors
         var interceptors = needAuth
-            ? (0, utils_1.getAuthInterceptor)(username, password)
+            ? (0, utils_1.getAuthInterceptor)(config.username, config.password)
             : null;
         // load proto
         this.schemaProto = protobufjs_1.default.loadSync(schemaProtoPath);
         this.milvusProto = protobufjs_1.default.loadSync(protoPath);
-        // create grpc client
-        this.grpcClient = new MilvusService((0, utils_1.formatAddress)(address), // format the address
-        ssl ? grpc_js_1.credentials.createSsl() : grpc_js_1.credentials.createInsecure(), // create SSL or insecure credentials
-        {
-            interceptors: [interceptors],
+        // setup timeout
+        this.timeout =
+            typeof config.timeout === 'string'
+                ? (0, utils_1.parseTimeToken)(config.timeout)
+                : config.timeout || _1.DEFAULT_CONNECT_TIMEOUT;
+        // options
+        var options = __assign({ interceptors: [interceptors], 
             // Milvus default max_receive_message_length is 100MB, but Milvus support change max_receive_message_length .
             // So SDK should support max_receive_message_length unlimited.
-            'grpc.max_receive_message_length': -1, // set max_receive_message_length to unlimited
-        });
+            'grpc.max_receive_message_length': -1 }, config.channelOptions);
+        // create grpc client
+        this.grpcClient = new MilvusService((0, utils_1.formatAddress)(config.address), // format the address
+        ssl ? grpc_js_1.credentials.createSsl() : grpc_js_1.credentials.createInsecure(), // create SSL or insecure credentials
+        options);
     }
     return BaseClient;
 }());

package/dist/milvus/BaseClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"BaseClient.js","sourceRoot":"","sources":["../../milvus/BaseClient.ts"],"names":[],"mappings":";;;;;;AAAA,8CAAwB;AACxB,0DAA4C;AAC5C,yCAAoD;AACpD,sBAAkC;AAClC,kCAA6E;AAE7E,SAAS;AACT,IAAM,SAAS,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,6BAA6B,CAAC,CAAC;AACzE,IAAM,eAAe,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,6BAA6B,CAAC,CAAC;AAE/E,cAAc;AACd;IAQE;;;;;;;;OAQG;IACH,oBACE,OAAe,EACf,GAAa,EACb,QAAiB,EACjB,QAAiB;QAEjB,0BAA0B;QAC1B,IAAI,CAAC,OAAO,EAAE;YACZ,MAAM,IAAI,KAAK,CAAC,gBAAa,CAAC,0BAA0B,CAAC,CAAC;SAC3D;QAED,yCAAyC;QACzC,IAAM,QAAQ,GAAG,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,CAAC;QAElE,0BAA0B;QAC1B,IAAM,aAAa,GAAG,IAAA,sBAAc,EAAC;YACnC,SAAS,WAAA;YACT,WAAW,EAAE,mCAAmC,EAAE,iCAAiC;SACpF,CAAC,CAAC;QAEH,sBAAsB;QACtB,IAAM,YAAY,GAAG,QAAQ;YAC3B,CAAC,CAAC,IAAA,0BAAkB,EAAC,QAAQ,EAAE,QAAQ,CAAC;YACxC,CAAC,CAAC,IAAI,CAAC;QAET,aAAa;QACb,IAAI,CAAC,WAAW,GAAG,oBAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QACtD,IAAI,CAAC,WAAW,GAAG,oBAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAEhD,qBAAqB;QACrB,IAAI,CAAC,UAAU,GAAG,IAAI,aAAa,CACjC,IAAA,qBAAa,EAAC,OAAO,CAAC,EAAE,qBAAqB;QAC7C,GAAG,CAAC,CAAC,CAAC,qBAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,qBAAW,CAAC,cAAc,EAAE,EAAE,qCAAqC;QACnG;YACE,YAAY,EAAE,CAAC,YAAY,CAAC;YAC5B,6GAA6G;YAC7G,8DAA8D;YAC9D,iCAAiC,EAAE,CAAC,CAAC,EAAE,8CAA8C;SACtF,CACF,CAAC;IACJ,CAAC;IACH,iBAAC;AAAD,CAAC,AA1DD,IA0DC;AA1DY,gCAAU"}
+{"version":3,"file":"BaseClient.js","sourceRoot":"","sources":["../../milvus/BaseClient.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,8CAAwB;AACxB,0DAA4C;AAC5C,yCAAoE;AACpE,sBAA+E;AAC/E,kCAKkB;AAElB,OAAO;AACP,IAAM,SAAS,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,6BAA6B,CAAC,CAAC;AACzE,IAAM,eAAe,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,6BAA6B,CAAC,CAAC;AAE/E,cAAc;AACd;IAUE;;;;;;;OAOG;IACH,oBACE,eAA4C,EAC5C,GAAa,EACb,QAAiB,EACjB,QAAiB,EACjB,cAA+B;QAE/B,IAAI,MAA0B,CAAC;QAE/B,8GAA8G;QAC9G,IAAI,OAAO,eAAe,KAAK,QAAQ,EAAE;YACvC,MAAM,GAAG,eAAe,CAAC;SAC1B;aAAM;YACL,MAAM,GAAG;gBACP,OAAO,EAAE,eAAe;gBACxB,GAAG,KAAA;gBACH,QAAQ,UAAA;gBACR,QAAQ,UAAA;gBACR,cAAc,gBAAA;aACf,CAAC;SACH;QAED,0BAA0B;QAC1B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE;YACnB,MAAM,IAAI,KAAK,CAAC,gBAAa,CAAC,0BAA0B,CAAC,CAAC;SAC3D;QAED,yCAAyC;QACzC,IAAM,QAAQ,GACZ,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC;QAEjE,0BAA0B;QAC1B,IAAM,aAAa,GAAG,IAAA,sBAAc,EAAC;YACnC,SAAS,WAAA;YACT,WAAW,EAAE,mCAAmC,EAAE,iCAAiC;SACpF,CAAC,CAAC;QAEH,sBAAsB;QACtB,IAAM,YAAY,GAAG,QAAQ;YAC3B,CAAC,CAAC,IAAA,0BAAkB,EAAC,MAAM,CAAC,QAAS,EAAE,MAAM,CAAC,QAAS,CAAC;YACxD,CAAC,CAAC,IAAI,CAAC;QAET,aAAa;QACb,IAAI,CAAC,WAAW,GAAG,oBAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QACtD,IAAI,CAAC,WAAW,GAAG,oBAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAEhD,gBAAgB;QAChB,IAAI,CAAC,OAAO;YACV,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;gBAChC,CAAC,CAAC,IAAA,sBAAc,EAAC,MAAM,CAAC,OAAO,CAAC;gBAChC,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,0BAAuB,CAAC;QAEhD,UAAU;QACV,IAAM,OAAO,cACX,YAAY,EAAE,CAAC,YAAY,CAAC;YAC5B,6GAA6G;YAC7G,8DAA8D;YAC9D,iCAAiC,EAAE,CAAC,CAAC,IAClC,MAAM,CAAC,cAAc,CACzB,CAAC;QAEF,qBAAqB;QACrB,IAAI,CAAC,UAAU,GAAG,IAAI,aAAa,CACjC,IAAA,qBAAa,EAAC,MAAM,CAAC,OAAO,CAAC,EAAE,qBAAqB;QACpD,GAAG,CAAC,CAAC,CAAC,qBAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,qBAAW,CAAC,cAAc,EAAE,EAAE,qCAAqC;QACnG,OAAO,CACR,CAAC;IACJ,CAAC;IACH,iBAAC;AAAD,CAAC,AAtFD,IAsFC;AAtFY,gCAAU"}

package/dist/milvus/Collection.d.ts

@@ -474,56 +474,56 @@ export declare class Collection extends BaseClient {
      */
     getReplicas(data: GetReplicaReq): Promise<ReplicasResponse>;
     /**
-   * Get loading progress of a collection
-   *
-   * @param data
-   *  | Property | Type | Description |
-   *  | :-- | :-- | :-- |
-   *  | collection_name | string | the name of the collection |
-   *  | timeout? | number | An optional duration of time in millisecond to allow for the RPC. If it is set to undefined, the client keeps waiting until the server responds or error occurs. Default is undefined |
-   *
-   * @returns
-   *  | Property | Description |
-   *  | :-- | :-- |
-   *  | status | { error_code: number, reason: string } |
-   *  | total_row_num | the total number of rows in the collection |
-   *  | total_loaded_row_num | the total number of loaded rows in the collection |
-   *
-   * @throws {Error} if `collection_name` property is not present in `data`
-   *
-   * #### Example
-   *
-   * ```
-   *  new milvusClient(MILUVS_ADDRESS).getLoadingProgress({
-   *    collection_name: 'my_collection',
-   *  });
-   * ```
-   */
+     * Get loading progress of a collection
+     *
+     * @param data
+     *  | Property | Type | Description |
+     *  | :-- | :-- | :-- |
+     *  | collection_name | string | the name of the collection |
+     *  | timeout? | number | An optional duration of time in millisecond to allow for the RPC. If it is set to undefined, the client keeps waiting until the server responds or error occurs. Default is undefined |
+     *
+     * @returns
+     *  | Property | Description |
+     *  | :-- | :-- |
+     *  | status | { error_code: number, reason: string } |
+     *  | total_row_num | the total number of rows in the collection |
+     *  | total_loaded_row_num | the total number of loaded rows in the collection |
+     *
+     * @throws {Error} if `collection_name` property is not present in `data`
+     *
+     * #### Example
+     *
+     * ```
+     *  new milvusClient(MILUVS_ADDRESS).getLoadingProgress({
+     *    collection_name: 'my_collection',
+     *  });
+     * ```
+     */
     getLoadingProgress(data: GetLoadingProgressReq): Promise<GetLoadingProgressResponse>;
     /**
-   * Get the loading state of a collection
-   *
-   * @param data
-   *  | Property | Type | Description |
-   *  | :-- | :-- | :-- |
-   *  | collection_name | string | the name of the collection |
-   *  | timeout? | number | An optional duration of time in milliseconds to allow for the RPC. If it is set to undefined, the client keeps waiting until the server responds or an error occurs. Default is undefined |
-   *
-   * @returns
-   *  | Property | Description |
-   *  | :-- | :-- |
-   *  | status | { error_code: number, reason: string } |
-   *  | state | the loading state of the collection |
-   *
-   * @throws {Error} if `collection_name` property is not present in `data`
-   *
-   * #### Example
-   *
-   * ```
-   *  new milvusClient(MILUVS_ADDRESS).getLoadState({
-   *    collection_name: 'my_collection',
-   *  });
-   * ```
-   */
+     * Get the loading state of a collection
+     *
+     * @param data
+     *  | Property | Type | Description |
+     *  | :-- | :-- | :-- |
+     *  | collection_name | string | the name of the collection |
+     *  | timeout? | number | An optional duration of time in milliseconds to allow for the RPC. If it is set to undefined, the client keeps waiting until the server responds or an error occurs. Default is undefined |
+     *
+     * @returns
+     *  | Property | Description |
+     *  | :-- | :-- |
+     *  | status | { error_code: number, reason: string } |
+     *  | state | the loading state of the collection |
+     *
+     * @throws {Error} if `collection_name` property is not present in `data`
+     *
+     * #### Example
+     *
+     * ```
+     *  new milvusClient(MILUVS_ADDRESS).getLoadState({
+     *    collection_name: 'my_collection',
+     *  });
+     * ```
+     */
     getLoadState(data: GetLoadStateReq): Promise<GetLoadStateResponse>;
 }