milvus-io / milvus-sdk-rust

Rust SDK for Milvus.

Milvus Rust SDK

Rust SDK for Milvus.

This is still in progress, be careful to use it in your production

Get Started

Add the SDK into your project:

cargo add milvus-sdk-rust

Connect to milvus service and create collection:

#[tokio::main]
async fn main() -> Result<(), Error> {
    const URL: &str = "http://localhost:19530";

    let client = Client::new(URL).await?;

    let schema =
        CollectionSchemaBuilder::new("hello_milvus", "a guide example for milvus rust SDK")
            .add_field(FieldSchema::new_primary_int64(
                "id",
                "primary key field",
                true,
            ))
            .add_field(FieldSchema::new_float_vector(
                DEFAULT_VEC_FIELD,
                "feature field",
                256,
            ))
            .build()?;
    let collection = client.create_collection(schema.clone(), None).await?;
    Ok(())
}

Development

Pre-requisites:

• cargo
• protocol-compiler
• docker (for testing)

How to test

Many tests require the Milvus server, the project provide a docker-compose file to setup a Milvus cluster:

docker-compose -f ./docker-compose.yml up -d

You may need to wait for seconds until the system ready

Run all tests:

cargo test

Enable the full backtrace for debugging:

RUST_BACKTRACE=1 cargo test

milvus-sdk-rust's Issues

[Bug]: [UnexpectedError] Assert \"field_meta.get_sizeof() == element.line_sizeof_\"

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I often drop the collection and then recreate the collection. but it always gets some errors inexplicably( I don't do anything else).

When i delete the volumes dir then i reimport the data. It's work when searching.

Expected Behavior

No response

Steps/Code To Reproduce behavior

No response

Environment details

- Hardware/Softward conditions (OS, CPU, GPU, Memory):
- Method of installation (Docker, or from source):
- Milvus version (v0.3.1, or v0.4.0):
- Milvus configuration (Settings you made in `server_config.yaml`):

Anything else?

No response

[Feature]: Change Has_XXX functions into Describe_XXX

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

All of the Milvus API changed, the Has_XXX functions will be deprecated in the future version

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

Rust sdk is slower than go sdk in same collection

It has 77,536 entity count in the collection.

In go sdk:

The average of the results is at 48ms:

❯ go run client/main.go
since time: 47.607644ms
[396 308 515 1928 1311]
[0.99999964 0.99999964 0.99999964 0.99999964 0.99999964]
[6993931090704601089 6993934159068663809 6993926946082131969 6993888636357971969 6993903639333048321]
(base) 
ibuddy in ibuddy-Super-Server in tris/vs-server on  master [?] via 🐹 v1.18.1 
❯ go run client/main.go
since time: 48.362906ms
[1311 695 388 2204 246]
[0.99999964 0.99999964 0.99999964 0.99999964 0.99999964]
[6993903639333048321 6993920792450961409 6993931340936777729 6993881812346998785 6993936299845619713]
(base) 
ibuddy in ibuddy-Super-Server in tris/vs-server on  master [?] via 🐹 v1.18.1 
❯ go run client/main.go
since time: 48.501344ms
[396 308 515 1928 1311]
[0.99999964 0.99999964 0.99999964 0.99999964 0.99999964]
[6993931090704601089 6993934159068663809 6993926946082131969 6993888636357971969 6993903639333048321]

Rust sdk:

It(search time) takes between 180-300ms.

[Feature]: Support Count API

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Milvus support Count API from 2.3.0, we need to support it,
more details about the it can be found here https://milvus.io/docs/query.md#Count-entities

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Adapt to the latest error code design.

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Since 2.3.0 Milvus redesign the error code system, and change the protobuf files, we need to adapt it in SDK

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Index for scalar fields

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Hello,

I've searched through the docs and existing examples and I can't seem to find the implementation for scalar indexes. I tried using create_index on a scalar field, but it failed with Error: Schema(NotVectorField("field_name")), which makes sense since it appears that IndexParams only has fields for embedding indexes.

Does the rust SDK currently have indexing for scalars? If not, is there plan to add that eventually?

Thanks!
Brandon

Describe the solution you'd like.

A type to create scalar indexes.

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

The name should be determined at runtime

milvus-sdk-rust/examples/collection.rs

Line 26 in 01f3011

const NAME: &'static str = "images_test";

I think it would be better if the name should be determined at runtime. The current way is difficult to change through env.

[Feature]: Support session consistency level

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Use session consistency level to reach read-after-write

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Support alias feature

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

As the other SDKs support to create/drop/alter alias for collection, so the Rust SDK do

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Alignment index type with Milvus 2.3.x

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Milvus deprecated some index types in version 2.3.x and add ScaNN index, need to keep aligned.
ref:
https://milvus.io/docs/release_notes.md#ScaNN

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Bug]: how get Vec<SearchResult> into value

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

After obtaining Vec using search, how can I get the specific data of each field, for example, the specific values of the fields?

Expected Behavior

After obtaining Vec using search, how can I directly access the specific values of the fields without using match?

Steps/Code To Reproduce behavior

let nomic = OllamaEmbedder::default().with_model("nomic-embed-text");
    let vec_content:Vec<f32> = nomic.embed_query(msg).await?.into_iter().map(|x|x as f32).collect();
    let collection = client.get_collection("T1").await?;
    let result:Vec<SearchResult> = collection.search(vec![Value::FloatArray(Cow::from(vec_content))],"vec2".to_string(),3,MetricType::L2,vec!["pid","content"], &SearchOption::new()).await?;
    let j = result.first().unwrap();
    for idx in 0..j.size {
        let pids = &j.field.get(0).unwrap().get(idx as usize).unwrap();
        match pids {
            Value::Long(j) => {
                println!("{}", j);
            },
            _ => {}
        }
    }

Environment details

- Milvus version (v2.3.14):

Anything else?

no

[Bug]: Failed to create a collection with a FieldSchema of `varchar` type

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Milvus server returns an error below while creating a collection that has a field of VarChar type:

Error: Server(UnexpectedError, "string data type not supported yet, please use VarChar type instead")

The example code:

#[tokio::main]
async fn main() -> Result<(), Error> {
    const URL: &str = "http://localhost:19530";

    let client = Client::new(URL).await?;

    let schema =
        CollectionSchemaBuilder::new("hello_milvus", "a guide example for milvus rust SDK")
            .add_field(FieldSchema::new_primary_int64("id", "", true))
            .add_field(FieldSchema::new_varchar("name", "desc", 64))  // trigger error here
            .add_field(FieldSchema::new_float_vector(DEFAULT_VEC_FIELD, "", 256))
            .build()?;
    let collection = client.create_collection(schema.clone(), None).await?;

    collection.drop().await?;

    Ok(())
}

Is there a follow-up development plan?

We need the rust version of sdk, and if it's not that fast, we'd like to implement it ourselves based on protobuf once.

Is this stable

I was wondering if this is stable and can be used for testing/prodcution? What stage of dev is it in?

[Bug]: Unexpected server errors

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I tried to put a line of code (for checking the response status) in the Collection::insert method before returning from the method:

pub async fn insert(
    &self,
    fields_data: Vec<FieldColumn>,
    partition_name: Option<&str>,
) -> Result<crate::proto::milvus::MutationResult> {

    ...

    status_to_result(&result.status)?;  // check the response status

    Ok(result)
}

After that, I run the following test code derived from this test function.

#[tokio::test]
async fn collection_basic() -> Result<()> {
    let collection = create_test_collection().await?;

    let embed_data = gen_random_f32_vector(5);

    let embed_column = FieldColumn::new(
        collection.schema().get_field(DEFAULT_VEC_FIELD).unwrap(),
        embed_data,
    );

    collection.insert(vec![embed_column], None).await?;

    clean_test_collection(collection).await?;
    Ok(())
}

** Bugs **

• Bug-1: The following server error was returned:

  Error: Server(UnexpectedError, "num_rows(0) should be greater than 0")

  The root cause of the issue is the FieldColumn::len method. The correct implementation should be

   #[inline]
   pub fn len(&self) -> usize {
       let c = self.value.len() / self.dim as usize;
       if self.value.len() % self.dim as usize == 0 {
           c
       } else {
           c + 1
       }
   }

• Bug-2: After fixing the first bug, still run the test code above, another server error was raised:

  Error: Server(UnexpectedError, "the length(5) of float data should divide the dim(128)")

  Could you please help check the issue? The original Collection::insert method does not contain the response status checking code. Is it correct or not? Looking forward to your reply and thanks a lot!

Expected Behavior

No response

Steps/Code To Reproduce behavior

No response

Environment details

- Hardware/Software conditions (OS, CPU, GPU, Memory):
  Ubuntu-22.04

- Method of installation:
  
  Follow the [steps](https://milvus.io/docs/install_standalone-docker.md) in the official webpage

Anything else?

No response

[Feature]: Add compact data API

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

I will add compact data APIs:

1. describe: Describe collection
2. compact: Compact Data
3. get_compaction_state: Check compaction status

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Crates.io package

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Trying to use Milvus from a Rust service

Describe the solution you'd like.

Is this package going to be available on Crates.io? Trying to use this from a Rust service.

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

Is this meant to support connecting to a milvus instance in Zilliz Cloud? & How do I authenticate?

I've been trying to connect to zilliz cloud instance of milvus but getting:

Error: Grpc(Status { code: Unknown, message: "transport error", source: Some(tonic::transport::Error(Transport, hyper::Error(Http2, Error { kind: GoAway(b"", FRAME_SIZE_ERROR, Library) }))) })

minimal reproduction is putting zilliz connection details into create_has_drop_collection() test, in tests/client.rs I set:

const URL: &str = "http://<zilliz-cloud-db-host-aws>:<zilliz-cloud-db-port>";

when I set it to HTTPS:

const URL: &str = "https://<zilliz-cloud-db-host-aws>:<zilliz-cloud-db-port>";

I got this error instead:

Error: Communication(tonic::transport::Error(Transport, hyper::Error(Connect, HttpsUriWithoutTlsSupport(()))))

I know it's generated, but I changed the connect function in the MilvusServiceClienttonic::transport::Channel impl in the src/proto/milvus.proto.milvus.rs>milvus_service_client>impl MilvusServiceClienttonic::transport::Channel to the following. Note the second commented out line is the original. I also had to enable the "tls" flag in the cargo.toml for the tonic crate

    impl MilvusServiceClient<tonic::transport::Channel> {
        /// Attempt to create a new client by connecting to a given endpoint.
        pub async fn connect<D>(dst: D) -> Result<Self, tonic::transport::Error>
        where
            D: std::convert::TryInto<tonic::transport::Endpoint>,
            D::Error: Into<StdError>,
        {
            // let conn = tonic::transport::Endpoint::new(dst)?.connect().await?;
            let conn = tonic::transport::Endpoint::new(dst)?;
            let conn = if conn.uri().scheme().map(|s| s.as_str()) == Some("https") {
                conn.tls_config(tonic::transport::ClientTlsConfig::new())?
            } else {
                conn
            }.connect().await?;

            Ok(Self::new(conn))
        }
    }

For my troubles I was rewarded with a different error:

Error: Communication(tonic::transport::Error(Transport, hyper::Error(Connect, Custom { kind: InvalidData, error: InvalidCertificateData("invalid peer certificate: UnknownIssuer") })))

I'm now stumped and not sure if connections to zilliz cloud are meant to be supported, please advise.

N.B. I did also test out RPCs with the command line to make sure zilliz cloud was configured properly to accept them. I ran the following while in the milvus-proto/proto folder and it worked splendidly:

grpcurl -import-path . -proto milvus.proto -d '{"collection_name": <collection_name>}' -H 'authorization: <base64_encoded_username:password>' <zilliz-cloud-db-host-aws>:<zilliz-cloud-db-port> milvus.proto.milvus.MilvusService/HasCollection

Actually that reminds me, I don't see anywhere to pass the database username and password in, I was able to get the grpcurl to work by looking through the pymilvus repo to find out how it did authentication. Is authentication a future addition to the rust sdk?

[Feature]: Support range search

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Milvus support range search from 2.3.0, we need to support it,
more details about the it can be found here https://milvus.io/docs/release_notes.md#Range-Search

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Support JSON Datatype

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Since 2.2.9, Milvus support JSON Datatype, we need support it in SDK
see https://milvus.io/docs/v2.2.x/release_notes.md#v229

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Add collection alias api

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

The SDK does not implement the Alias API

Describe the solution you'd like.

I will implement the following APIs:

1. CreateAlias
2. DropAlias
3. AlterAlias

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Implement basic Milvus client in Rust

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

For now, a basic Milvus client requires:

• Implement Connect
• Implement CreateCollection, LoadCollection, ReleaseCollection and DropCollection
• Implement Search and Query
• Implement CreateIndex

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Support Database for managing collection and index

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

from 2.3.0 Milvus support Database, we need support it in SDK

• https://milvus.io/docs/manage_databases.md#Manage-Databases
• milvus-io/milvus#23741

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Add delete entities api and impl Clone for Client

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

We need to implement Clone to extract the client in the web framework.

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Support upsert

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Milvus support upsert API from 2.3.0, we need to support it,
more details about the it can be found here https://milvus.io/api-reference/pymilvus/v2.3.x/Collection/upsert().md

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Bug]: [UnexpectedError] Error in virtual knowhere::DatasetPtr knowhere::IVF_NM::Query

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

When i called search api :

let vec_field = "embedding";

        let top_k = 5;
        let metric_type = milvus::index::MetricType::L2;
        let output_fields: Vec<String> = vec!["id".into(), "product_id".into()];

        let mut params = SearchOption::new();
        params.set_consistency_level(ConsistencyLevel::Session);
        // params.insert(k, v);
        params.add_param("index_type", "IVF_FLAT");
        params.add_param("nprobe", "16");

        let data: Vec<Value> = search_data
            .iter()
            .map(|s| Value::FloatArray(s.into()))
            .collect();

        let result = self
            .search(data, vec_field, top_k, metric_type, output_fields, &params)
            .await?;

        Ok(result)

Expected Behavior

Search results

Steps/Code To Reproduce behavior

UnexpectedError "fail to search on all shard leaders, err=All attempts results:\nattempt #1:code: UnexpectedError, error: fail to Search, QueryNode ID=25, reason=Search 25 failed, reason [UnexpectedError] Error in virtual knowhere::DatasetPtr knowhere::IVF_NM::Query(const DatasetPtr&, const Config&, faiss::BitsetView) at IndexIVF_NM.cpp:216: [json.exception.type_error.302] type must be number, but is string err %!w(<nil>)\nattempt #2:context canceled\n"

### Environment details

```markdown
- Hardware/Softward conditions (OS, CPU, GPU, Memory):  Linux
- Method of installation (Docker, or from source): docker
- Milvus version (v0.3.1, or v0.4.0): 2.2.6-2.2.8
- Milvus configuration (Settings you made in `server_config.yaml`):

Anything else?

In previous versions, everything worked fine with it.

[Feature]: Remove load_unblocked and create_index_unblocked

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

As all methods are async, we don't need the unblocked methods

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

[Feature]: Add the remaining partition APIs

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

I willl add the apis:

1. drop_partition
2. load_partitions
3. release_partitions

Also, there are some warnings under the rust clippy rules. I'll fix it.

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response

Example error: index doesn't exist

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

When I ran the example "examples/collections.rs", I got the error message:

failed to run hello milvus: Server(UnexpectedError, "index doesn't exist, collectionID 440648455792968346")

Is this example outdated?

In addition, when will the first stable version be released? Thanks a lot!

[Bug]: UnexpectedError "string data type not supported yet, please use VarChar type instead"

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

When i add a varchar field:
...
.add_field(FieldSchema::new_varchar("code", "", 32))

dtype should be DataType::VarChar in L353

Expected Behavior

ok

Steps/Code To Reproduce behavior

No response

Environment details

- Hardware/Softward conditions (OS, CPU, GPU, Memory):
- Method of installation (Docker, or from source):
- Milvus version (v0.3.1, or v0.4.0):
- Milvus configuration (Settings you made in `server_config.yaml`):

Anything else?

No response

[Feature]: Remove time travel related code

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe.

Since 2.3.0 Milvus deprecatd time travel feature, we should remove it in rust sdk

Describe the solution you'd like.

No response

Describe an alternate solution.

No response

Anything else? (Additional Context)

No response