enhance: [2.5][GoSDK] Add README and examples for milvusclient (#40747)

Cherry-pick from master pr: #40630 #40643 Related to #31293 --------- Signed-off-by: Congqi Xia <congqi.xia@zilliz.com>
2025-03-19 18:02:18 +08:00 · 2025-03-19 18:02:18 +08:00 · d1359010d0
parent 38127e2c76
commit d1359010d0
6 changed files with 635 additions and 2 deletions
--- a/client/README.md
+++ b/client/README.md
@ -0,0 +1,50 @@
+# Go MilvusClient
+
+[![license](https://img.shields.io/hexpm/l/plug.svg?color=green)](https://github.com/milvus-io/milvus/blob/master/LICENSE)
+[![Go Reference](https://pkg.go.dev/badge/github.com/milvus-io/milvus/client/v2.svg)](https://pkg.go.dev/github.com/milvus-io/milvus/client/v2)
+
+Go MilvusClient for [Milvus](https://github.com/milvus-io/milvus). To contribute code to this project, please read our [contribution guidelines](https://github.com/milvus-io/milvus/blob/master/CONTRIBUTING.md) first.
+
+
+## Getting started
+
+### Prerequisites
+
+Go 1.21 or higher
+
+### Install Milvus Go SDK
+
+1. Use `go get` to install the latest version of the Milvus Go SDK and dependencies:
+
+   ```shell
+   go get -u github.com/milvus-io/milvus/client/v2
+   ```
+
+2. Include the Go MilvusClient in your application:
+
+   ```go
+    import "github.com/milvus-io/milvus/client/v2/milvusclient"
+
+    //...other snippet ...
+    ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	milvusAddr := "YOUR_MILVUS_ENDPOINT"
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+    }
+
+    // Do your work with milvus client
+    ```
+
+### API Documentation
+
+Refer to [https://milvus.io/api-reference/go/v2.5.x/About.md](https://milvus.io/api-reference/go/v2.5.x/About.md) for the Go SDK API documentation.
+
+## Code format
+
+The Go source code is formatted using gci & gofumpt. Please run `make lint-fix` before sumbit a PR.
--- a/client/milvusclient/index_example_test.go
+++ b/client/milvusclient/index_example_test.go
@ -0,0 +1,103 @@
+// Licensed to the LF AI & Data foundation under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// nolint
+package milvusclient_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/milvus-io/milvus/client/v2/entity"
+	"github.com/milvus-io/milvus/client/v2/index"
+	"github.com/milvus-io/milvus/client/v2/milvusclient"
+)
+
+func ExampleClient_CreateIndex() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle err
+	}
+
+	index := index.NewHNSWIndex(entity.COSINE, 32, 128)
+	indexTask, err := cli.CreateIndex(ctx, milvusclient.NewCreateIndexOption("my_collection", "vector", index))
+	if err != nil {
+		// handler err
+	}
+
+	err = indexTask.Await(ctx)
+	if err != nil {
+		// handler err
+	}
+}
+
+func ExampleClient_DescribeIndex() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle err
+	}
+
+	indexInfo, err := cli.DescribeIndex(ctx, milvusclient.NewDescribeIndexOption("my_collection", "my_index"))
+	if err != nil {
+		// handle err
+	}
+	fmt.Println(indexInfo)
+}
+
+func ExampleClient_DropIndex() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle err
+	}
+
+	err = cli.DropIndex(ctx, milvusclient.NewDropIndexOption("my_collection", "my_index"))
+	if err != nil {
+		// handle err
+	}
+}
+
+func ExampleClient_ListIndexes() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle err
+	}
+
+	indexes, err := cli.ListIndexes(ctx, milvusclient.NewListIndexOption("my_collection").WithFieldName("my_vector"))
+	if err != nil {
+		// handle err
+	}
+	fmt.Println(indexes)
+}
--- a/client/milvusclient/maintenance_example_test.go
+++ b/client/milvusclient/maintenance_example_test.go
@ -0,0 +1,132 @@
+// Licensed to the LF AI & Data foundation under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// nolint
+package milvusclient_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/milvus-io/milvus/client/v2/milvusclient"
+)
+
+func ExampleClient_GetLoadState() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	collectionName := `customized_setup_1`
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle err
+	}
+
+	loadState, err := cli.GetLoadState(ctx, milvusclient.NewGetLoadStateOption(collectionName))
+	if err != nil {
+		// handle err
+	}
+	fmt.Println(loadState)
+}
+
+func ExampleClient_RefreshLoad() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	collectionName := `customized_setup_1`
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle err
+	}
+
+	loadTask, err := cli.RefreshLoad(ctx, milvusclient.NewRefreshLoadOption(collectionName))
+	if err != nil {
+		// handle err
+	}
+	err = loadTask.Await(ctx)
+	if err != nil {
+		// handler err
+	}
+}
+
+func ExampleClient_Compact() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	collectionName := `customized_setup_1`
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle err
+	}
+
+	compactID, err := cli.Compact(ctx, milvusclient.NewCompactOption(collectionName))
+	if err != nil {
+		// handle err
+	}
+	fmt.Println(compactID)
+}
+
+func ExampleClient_GetCompactionState() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	compactID := int64(123)
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle err
+	}
+
+	state, err := cli.GetCompactionState(ctx, milvusclient.NewGetCompactionStateOption(compactID))
+	if err != nil {
+		// handle err
+	}
+	fmt.Println(state)
+}
+
+func ExampleClient_Flush() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle err
+	}
+
+	collectionName := `customized_setup_1`
+
+	task, err := cli.Flush(ctx, milvusclient.NewFlushOption(collectionName))
+	if err != nil {
+		// handle err
+	}
+
+	err = task.Await(ctx)
+	if err != nil {
+		// handle err
+	}
+}
--- a/client/milvusclient/read_example_test.go
+++ b/client/milvusclient/read_example_test.go
@ -19,8 +19,10 @@ package milvusclient_test

 import (
 	"context"
+	"fmt"
 	"log"

+	"github.com/milvus-io/milvus/client/v2/column"
 	"github.com/milvus-io/milvus/client/v2/entity"
 	"github.com/milvus-io/milvus/client/v2/milvusclient"
 )
@ -199,6 +201,87 @@ func ExampleClient_Search_offsetLimit() {
 	}
 }

-// func ExampleClient_Search_useLevel() {
+func ExampleClient_Get() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()

-// }
+	milvusAddr := "127.0.0.1:19530"
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		log.Fatal("failed to connect to milvus server: ", err.Error())
+	}
+
+	defer cli.Close(ctx)
+
+	rs, err := cli.Get(ctx, milvusclient.NewQueryOption("quick_setup").
+		WithIDs(column.NewColumnInt64("id", []int64{1, 2, 3})))
+	if err != nil {
+		// handle error
+	}
+
+	fmt.Println(rs.GetColumn("id"))
+}
+
+func ExampleClient_Query() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	milvusAddr := "127.0.0.1:19530"
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		log.Fatal("failed to connect to milvus server: ", err.Error())
+	}
+
+	defer cli.Close(ctx)
+
+	rs, err := cli.Query(ctx, milvusclient.NewQueryOption("quick_setup").
+		WithFilter("emb_type == 3").
+		WithOutputFields("id", "emb_type"))
+	if err != nil {
+		// handle error
+	}
+
+	fmt.Println(rs.GetColumn("id"))
+}
+
+func ExampleClient_HybridSearch() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	milvusAddr := "127.0.0.1:19530"
+	token := "root:Milvus"
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+		APIKey:  token,
+	})
+	if err != nil {
+		log.Fatal("failed to connect to milvus server: ", err.Error())
+	}
+
+	defer cli.Close(ctx)
+
+	queryVector := []float32{0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592}
+	sparseVector, _ := entity.NewSliceSparseEmbedding([]uint32{1, 21, 100}, []float32{0.1, 0.2, 0.3})
+
+	resultSets, err := cli.HybridSearch(ctx, milvusclient.NewHybridSearchOption(
+		"quick_setup",
+		3,
+		milvusclient.NewAnnRequest("dense_vector", 10, entity.FloatVector(queryVector)),
+		milvusclient.NewAnnRequest("sparse_vector", 10, sparseVector),
+	).WithReranker(milvusclient.NewRRFReranker()))
+	if err != nil {
+		log.Fatal("failed to perform basic ANN search collection: ", err.Error())
+	}
+
+	for _, resultSet := range resultSets {
+		log.Println("IDs: ", resultSet.IDs)
+		log.Println("Scores: ", resultSet.Scores)
+	}
+}
--- a/client/milvusclient/resource_group_example_test.go
+++ b/client/milvusclient/resource_group_example_test.go
@ -0,0 +1,148 @@
+// Licensed to the LF AI & Data foundation under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// nolint
+package milvusclient_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/milvus-io/milvus/client/v2/entity"
+	"github.com/milvus-io/milvus/client/v2/milvusclient"
+)
+
+func ExampleClient_CreateResourceGroup() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+	}
+
+	defer cli.Close(ctx)
+
+	err = cli.CreateResourceGroup(ctx, milvusclient.NewCreateResourceGroupOption("my_rg"))
+	if err != nil {
+		// handle error
+	}
+}
+
+func ExampleClient_UpdateResourceGroup() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+	}
+
+	defer cli.Close(ctx)
+
+	err = cli.UpdateResourceGroup(ctx, milvusclient.NewUpdateResourceGroupOption("my_rg", &entity.ResourceGroupConfig{
+		Requests: entity.ResourceGroupLimit{NodeNum: 10},
+		Limits:   entity.ResourceGroupLimit{NodeNum: 10},
+		NodeFilter: entity.ResourceGroupNodeFilter{
+			NodeLabels: map[string]string{"my_label1": "a"},
+		},
+	}))
+	if err != nil {
+		// handle error
+	}
+}
+
+func ExampleClient_TransferReplica() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+	}
+
+	defer cli.Close(ctx)
+
+	err = cli.TransferReplica(ctx, milvusclient.NewTransferReplicaOption("quick_setup", "rg_1", "rg_2", 1))
+	if err != nil {
+		// handle error
+	}
+}
+
+func ExampleClient_DropResourceGroup() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+	}
+
+	defer cli.Close(ctx)
+
+	err = cli.DropResourceGroup(ctx, milvusclient.NewDropResourceGroupOption("my_rg"))
+	if err != nil {
+		// handle error
+	}
+}
+
+func ExampleClient_DescribeResourceGroup() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+	}
+
+	defer cli.Close(ctx)
+
+	rg, err := cli.DescribeResourceGroup(ctx, milvusclient.NewDescribeResourceGroupOption("my_rg"))
+	if err != nil {
+		// handle error
+	}
+	fmt.Println(rg)
+}
+
+func ExampleClient_ListResourceGroups() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+	}
+
+	defer cli.Close(ctx)
+
+	rgNames, err := cli.ListResourceGroups(ctx, milvusclient.NewListResourceGroupsOption())
+	if err != nil {
+		// handle error
+	}
+	fmt.Println(rgNames)
+}
--- a/client/milvusclient/write_example_test.go
+++ b/client/milvusclient/write_example_test.go
@ -0,0 +1,117 @@
+// Licensed to the LF AI & Data foundation under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// nolint
+package milvusclient_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/milvus-io/milvus/client/v2/milvusclient"
+)
+
+func ExampleClient_Insert_columnbase() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+	}
+
+	defer cli.Close(ctx)
+
+	resp, err := cli.Insert(ctx, milvusclient.NewColumnBasedInsertOption("quick_setup").
+		WithInt64Column("id", []int64{1, 2, 3, 4, 5, 6, 7, 8, 9}).
+		WithVarcharColumn("color", []string{"pink_8682", "red_7025", "orange_6781", "pink_9298", "red_4794", "yellow_4222", "red_9392", "grey_8510", "white_9381", "purple_4976"}).
+		WithFloatVectorColumn("vector", 5, [][]float32{
+			{0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592},
+			{0.19886812562848388, 0.06023560599112088, 0.6976963061752597, 0.2614474506242501, 0.838729485096104},
+			{0.43742130801983836, -0.5597502546264526, 0.6457887650909682, 0.7894058910881185, 0.20785793220625592},
+			{0.3172005263489739, 0.9719044792798428, -0.36981146090600725, -0.4860894583077995, 0.95791889146345},
+			{0.4452349528804562, -0.8757026943054742, 0.8220779437047674, 0.46406290649483184, 0.30337481143159106},
+			{0.985825131989184, -0.8144651566660419, 0.6299267002202009, 0.1206906911183383, -0.1446277761879955},
+			{0.8371977790571115, -0.015764369584852833, -0.31062937026679327, -0.562666951622192, -0.8984947637863987},
+			{-0.33445148015177995, -0.2567135004164067, 0.8987539745369246, 0.9402995886420709, 0.5378064918413052},
+			{0.39524717779832685, 0.4000257286739164, -0.5890507376891594, -0.8650502298996872, -0.6140360785406336},
+			{0.5718280481994695, 0.24070317428066512, -0.3737913482606834, -0.06726932177492717, -0.6980531615588608},
+		}),
+	)
+	if err != nil {
+		// handle err
+	}
+	fmt.Println(resp)
+}
+
+func ExampleClient_Upsert_columnBase() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+	}
+
+	defer cli.Close(ctx)
+
+	resp, err := cli.Upsert(ctx, milvusclient.NewColumnBasedInsertOption("quick_setup").
+		WithInt64Column("id", []int64{1, 2, 3, 4, 5, 6, 7, 8, 9}).
+		WithVarcharColumn("color", []string{"pink_8682", "red_7025", "orange_6781", "pink_9298", "red_4794", "yellow_4222", "red_9392", "grey_8510", "white_9381", "purple_4976"}).
+		WithFloatVectorColumn("vector", 5, [][]float32{
+			{0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592},
+			{0.19886812562848388, 0.06023560599112088, 0.6976963061752597, 0.2614474506242501, 0.838729485096104},
+			{0.43742130801983836, -0.5597502546264526, 0.6457887650909682, 0.7894058910881185, 0.20785793220625592},
+			{0.3172005263489739, 0.9719044792798428, -0.36981146090600725, -0.4860894583077995, 0.95791889146345},
+			{0.4452349528804562, -0.8757026943054742, 0.8220779437047674, 0.46406290649483184, 0.30337481143159106},
+			{0.985825131989184, -0.8144651566660419, 0.6299267002202009, 0.1206906911183383, -0.1446277761879955},
+			{0.8371977790571115, -0.015764369584852833, -0.31062937026679327, -0.562666951622192, -0.8984947637863987},
+			{-0.33445148015177995, -0.2567135004164067, 0.8987539745369246, 0.9402995886420709, 0.5378064918413052},
+			{0.39524717779832685, 0.4000257286739164, -0.5890507376891594, -0.8650502298996872, -0.6140360785406336},
+			{0.5718280481994695, 0.24070317428066512, -0.3737913482606834, -0.06726932177492717, -0.6980531615588608},
+		}),
+	)
+	if err != nil {
+		// handle err
+	}
+	fmt.Println(resp)
+}
+
+func ExampleClient_Delete() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	cli, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
+		Address: milvusAddr,
+	})
+	if err != nil {
+		// handle error
+	}
+
+	defer cli.Close(ctx)
+
+	res, err := cli.Delete(ctx, milvusclient.NewDeleteOption("quick_setup").
+		WithInt64IDs("id", []int64{1, 2, 3}))
+	if err != nil {
+		// handle error
+	}
+
+	fmt.Println(res.DeleteCount)
+}