Manage Partitions

A partition is a subset of a collection. Each partition shares the same data structure with its parent collection but contains only a subset of the data in the collection. This page helps you understand how to manage partitions.

Notes

This feature applies only to managed collections.

Overview

When creating a collection, Zilliz Cloud also creates a partition named _default in the collection. If you are not going to add any other partitions, all entities inserted into the collection go into the default partition, and all searches and queries are also carried out within the default partition.

You can add more partitions and insert entities into them based on certain criteria. Then you can restrict your searches and queries within certain partitions, improving search performance.

A collection can have a maximum of 1,024 partitions.

Notes

The Partition Key feature is a search optimization based on partitions and allows Zilliz Cloud to distribute entities into different partitions based on the values in a specific scalar field. This feature helps implement partition-oriented multi-tenancy and improves search performance.

This feature will not be discussed on this page. To find more, refer to Use Partition Key.

List Partitions

When creating a collection, Zilliz Cloud also creates a partition named _default in the collection. You can list the partitions in a collection as follows.

Python

python

from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

res = client.list_partitions(
    collection_name="my_collection"
)

print(res)

# Output
#
# ["_default"]

Java

java

import io.milvus.v2.service.partition.request.ListPartitionsReq;
import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;

import java.util.*;

String CLUSTER_ENDPOINT = "YOUR_CLUSTER_ENDPOINT";
String TOKEN = "YOUR_CLUSTER_TOKEN";

// 1. Connect to Milvus server
ConnectConfig connectConfig = ConnectConfig.builder()
        .uri(CLUSTER_ENDPOINT)
        .token(TOKEN)
        .build();

MilvusClientV2 client = new MilvusClientV2(connectConfig);

ListPartitionsReq listPartitionsReq = ListPartitionsReq.builder()
        .collectionName("my_collection")
        .build();

List<String> partitionNames = client.listPartitions(listPartitionsReq);
System.out.println(partitionNames);

// Output:
// [_default]

Go

go

import (
    "context"
    "fmt"

    milvusclient "github.com/milvus-io/milvus/client/v3/milvusclient"
)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

milvusAddr := "YOUR_CLUSTER_ENDPOINT"

client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: milvusAddr,
    APIKey:  "YOUR_CLUSTER_TOKEN",
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

partitionNames, err := client.ListPartitions(ctx, milvusclient.NewListPartitionOption("my_collection"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

fmt.Println(partitionNames)

// Output
//
// ["_default"]

Rust

rust

use milvus::v2::prelude::*;

let client = ClientV2::new(
    &ConnectConfig::new()
        .uri("YOUR_CLUSTER_ENDPOINT")
        .token("YOUR_CLUSTER_TOKEN"),
)
.await?;

let partitions = client
    .list_partitions(
        ListPartitionsRequest::builder()
            .collection_name("my_collection")
            .build()?,
    )
    .await?;
println!("{:?}", partitions.partition_names());

// Output
//
// ["_default"]

C++

c++

#include <iostream>
#include "milvus/MilvusClientV2.h"

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"YOUR_CLUSTER_ENDPOINT", "YOUR_CLUSTER_TOKEN"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

milvus::ListPartitionsResponse response;
status = client->ListPartitions(milvus::ListPartitionsRequest()
                                    .WithCollectionName("my_collection"),
                                response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

for (auto& info : response.PartitionInfos()) {
    std::cout << "\t" << info.Name() << std::endl;
}

NodeJS

javascript

import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";

const address = "YOUR_CLUSTER_ENDPOINT";
const token = "YOUR_CLUSTER_TOKEN";
const client = new MilvusClient({address, token});

let res = await client.listPartitions({
    collection_name: "my_collection"
})

console.log(res);

// Output
// ["_default"]

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/partitions/list" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection"
}'

# {
#     "code": 0,
#     "data": [
#         "_default"
#     ]
# }

Create Partition

You can add more partitions to the collection and insert entities into these partitions based on certain criteria.

Python

python

client.create_partition(
    collection_name="my_collection",
    partition_name="partitionA"
)

res = client.list_partitions(
    collection_name="my_collection"
)

print(res)

# Output
#
# ["_default", "partitionA"]

Java

java

import io.milvus.v2.service.partition.request.CreatePartitionReq;
import io.milvus.v2.service.partition.request.ListPartitionsReq;
import java.util.List;

CreatePartitionReq createPartitionReq = CreatePartitionReq.builder()
        .collectionName("my_collection")
        .partitionName("partitionA")
        .build();

client.createPartition(createPartitionReq);

ListPartitionsReq listPartitionsReq = ListPartitionsReq.builder()
        .collectionName("my_collection")
        .build();

List<String> partitionNames = client.listPartitions(listPartitionsReq);
System.out.println(partitionNames);

// Output:
// [_default, partitionA]

Go

go

import (
    "fmt"

    milvusclient "github.com/milvus-io/milvus/client/v3/milvusclient"
)

err = client.CreatePartition(ctx, milvusclient.NewCreatePartitionOption("my_collection", "partitionA"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

partitionNames, err := client.ListPartitions(ctx, milvusclient.NewListPartitionOption("my_collection"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

fmt.Println(partitionNames)
// Output
// ["_default", "partitionA"]

Rust

rust

use milvus::v2::prelude::*;

client
    .create_partition(
        CreatePartitionRequest::builder()
            .collection_name("my_collection")
            .partition_name("partitionA")
            .build()?,
    )
    .await?;

let partitions = client
    .list_partitions(
        ListPartitionsRequest::builder()
            .collection_name("my_collection")
            .build()?,
    )
    .await?;
println!("{:?}", partitions.partition_names());

// Output
//
// ["_default", "partitionA"]

C++

c++

auto status = client->CreatePartition(milvus::CreatePartitionRequest()
                                         .WithCollectionName("my_collection")
                                         .WithPartitionName("partitionA"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

milvus::ListPartitionsResponse response;
status = client->ListPartitions(milvus::ListPartitionsRequest().WithCollectionName("my_collection"), response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

for (auto& info : response.PartitionInfos()) {
    std::cout << "\t" << info.Name() << std::endl;
}

NodeJS

javascript

await client.createPartition({
    collection_name: "my_collection",
    partition_name: "partitionA"
})

res = await client.listPartitions({
    collection_name: "my_collection"
})

console.log(res)

// Output
// ["_default", "partitionA"]

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/partitions/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionName": "partitionA"
}'

# {
#     "code": 0,
#     "data": {}
# }

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/partitions/list" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection"
}'

# {
#     "code": 0,
#     "data": [
#         "_default",
#         "partitionA"
#     ]
# }

Check for a Specific Partition

The following code snippets demonstrate how to check whether a partition exists in a specific collection.

Python

python

res = client.has_partition(
    collection_name="my_collection",
    partition_name="partitionA"
)

print(res)

# Output
#
# True

Java

java

import io.milvus.v2.service.partition.request.HasPartitionReq;

HasPartitionReq hasPartitionReq = HasPartitionReq.builder()
        .collectionName("my_collection")
        .partitionName("partitionA")
        .build();

Boolean hasPartitionRes = client.hasPartition(hasPartitionReq);
System.out.println(hasPartitionRes);

// Output:
// true

Go

go

import (
    "fmt"

    milvusclient "github.com/milvus-io/milvus/client/v3/milvusclient"
)

result, err := client.HasPartition(ctx, milvusclient.NewHasPartitionOption("my_collection", "partitionA"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

fmt.Println(result)

// Output:
// true

Rust

rust

use milvus::v2::prelude::*;

let has = client
    .has_partition(
        HasPartitionRequest::builder()
            .collection_name("my_collection")
            .partition_name("partitionA")
            .build()?,
    )
    .await?;
println!("{}", has.exists());

// Output
//
// true

C++

c++

milvus::HasPartitionResponse response;
auto status = client->HasPartition(milvus::HasPartitionRequest()
                                    .WithCollectionName("my_collection")
                                    .WithPartitionName("partitionA"),
                                   response);
std::cout << response.Has() << std::endl;

NodeJS

javascript

res = await client.hasPartition({
    collection_name: "my_collection",
    partition_name: "partitionA"
})

console.log(res.value)

// Output
// true

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/partitions/has" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionName": "partitionA"
}'

# {
#     "code": 0,
#     "data": {
#        "has": true
#     }
# }

Load and Release Partitions

You can separately load or release one or certain partitions.

Load Partitions

You can separately load specific partitions in a collection. It is worth noting that the load status of a collection stays unloaded if there is an unloaded partition in the collection.

Python

python

client.load_partitions(
    collection_name="my_collection",
    partition_names=["partitionA"]
)

res = client.get_load_state(
    collection_name="my_collection",
    partition_name="partitionA"
)

print(res)
# Output
#
# {
#     "state": "<LoadState: Loaded>"
# }

Java

java

import io.milvus.v2.service.partition.request.LoadPartitionsReq;
import io.milvus.v2.service.collection.request.GetLoadStateReq;
import java.util.Collections;

LoadPartitionsReq loadPartitionsReq = LoadPartitionsReq.builder()
        .collectionName("my_collection")
        .partitionNames(Collections.singletonList("partitionA"))
        .build();

client.loadPartitions(loadPartitionsReq);

GetLoadStateReq getLoadStateReq = GetLoadStateReq.builder()
        .collectionName("my_collection")
        .partitionName("partitionA")
        .build();

Boolean getLoadStateRes = client.getLoadState(getLoadStateReq);
System.out.println(getLoadStateRes);

// True

Go

go

import (
    "fmt"

    milvusclient "github.com/milvus-io/milvus/client/v3/milvusclient"
)

task, err := client.LoadPartitions(ctx, milvusclient.NewLoadPartitionsOption("my_collection", "partitionA"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

// sync wait collection to be loaded
err = task.Await(ctx)
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

state, err := client.GetLoadState(ctx, milvusclient.NewGetLoadStateOption("my_collection", "partitionA"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
fmt.Println(state)

Rust

rust

use milvus::v2::prelude::*;

client
    .load_partitions(
        LoadPartitionsRequest::builder()
            .collection_name("my_collection")
            .partition_names(["partitionA"])
            .build()?,
    )
    .await?;

let state = client
    .get_load_state(
        GetLoadStateRequest::builder()
            .collection_name("my_collection")
            .partition_names(["partitionA"])
            .build()?,
    )
    .await?;
println!("{:?}", state.state());

// Output
//
// Loaded

C++

c++

auto status = client->LoadPartitions(milvus::LoadPartitionsRequest()
                                        .WithCollectionName("my_collection")
                                        .AddPartitionName("partitionA"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

milvus::GetLoadStateResponse response;
status = client->GetLoadState(milvus::GetLoadStateRequest()
                                .WithCollectionName("my_collection")
                                .AddPartitionName("partitionA"),
                              response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}
std::cout << std::to_string(response.State()) << std::endl;

NodeJS

javascript

await client.loadPartitions({
    collection_name: "my_collection",
    partition_names: ["partitionA"]
})

res = await client.getLoadState({
    collection_name: "my_collection",
    partition_names: ["partitionA"]
})

console.log(res)

// Output
//
// LoadStateLoaded
//

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/partitions/load" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionNames": ["partitionA"]
}'

# {
#     "code": 0,
#     "data": {}
# }

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/get_load_state" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionNames": ["partitionA"]
}'

# {
#     "code": 0,
#     "data": {
#         "loadProgress": 100,
#         "loadState": "LoadStateLoaded",
#         "message": ""
#     }
# }

Release Partitions

You can also release specific partitions.

Python

python

client.release_partitions(
    collection_name="my_collection",
    partition_names=["partitionA"]
)

res = client.get_load_state(
    collection_name="my_collection",
    partition_name="partitionA"
)

print(res)

# Output
#
# {
#     "state": "<LoadState: NotLoad>"
# }

Java

java

import io.milvus.v2.service.partition.request.ReleasePartitionsReq;
import io.milvus.v2.service.collection.request.GetLoadStateReq;
import java.util.Collections;

ReleasePartitionsReq releasePartitionsReq = ReleasePartitionsReq.builder()
        .collectionName("my_collection")
        .partitionNames(Collections.singletonList("partitionA"))
        .build();

client.releasePartitions(releasePartitionsReq);

GetLoadStateReq getLoadStateReq = GetLoadStateReq.builder()
        .collectionName("my_collection")
        .partitionName("partitionA")
        .build();

Boolean getLoadStateRes = client.getLoadState(getLoadStateReq);
System.out.println(getLoadStateRes);

// False

Go

go

import (
    "fmt"

    milvusclient "github.com/milvus-io/milvus/client/v3/milvusclient"
)

err = client.ReleasePartitions(ctx, milvusclient.NewReleasePartitionsOptions("my_collection", "partitionA"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

state, err := client.GetLoadState(ctx, milvusclient.NewGetLoadStateOption("my_collection", "partitionA"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
fmt.Println(state)

Rust

rust

use milvus::v2::prelude::*;

client
    .release_partitions(
        ReleasePartitionsRequest::builder()
            .collection_name("my_collection")
            .partition_names(["partitionA"])
            .build()?,
    )
    .await?;

let state = client
    .get_load_state(
        GetLoadStateRequest::builder()
            .collection_name("my_collection")
            .partition_names(["partitionA"])
            .build()?,
    )
    .await?;
println!("{:?}", state.state());

// Output
//
// NotLoad

C++

c++

auto status = client->ReleasePartitions(milvus::ReleasePartitionsRequest()
                                .WithCollectionName("my_collection")
                                .AddPartitionName("partitionA"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

milvus::GetLoadStateResponse response;
status = client->GetLoadState(milvus::GetLoadStateRequest()
                                .WithCollectionName("my_collection")
                                .AddPartitionName("partitionA"),
                              response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}
std::cout << std::to_string(response.State()) << std::endl;

NodeJS

javascript

await client.releasePartitions({
    collection_name: "my_collection",
    partition_names: ["partitionA"]
})

res = await client.getLoadState({
    collection_name: "my_collection",
    partition_names: ["partitionA"]
})

console.log(res)

// Output
//
// LoadStateNotLoad
//

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/partitions/release" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionNames": ["partitionA"]
}'

# {
#     "code": 0,
#     "data": {}
# }

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/get_load_state" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionNames": ["partitionA"]
}'

# {
#     "code": 0,
#     "data": {
#         "loadProgress": 0,
#         "loadState": "LoadStateNotLoad",
#         "message": ""
#     }
# }

Data Operations Within Partitions

Insert and Delete Entities

You can perform insert, upsert, and delete operations in specific operations. For details, refer to

• Insert Entities into Partition

• Upsert Entities into Partition

• Delete Entities from Partition

Search and Query

You can conduct searches and queries within specific partitions. For details, refer to

• Conduct ANN Searches within Partitions

• Conduct Metadata Filtering within Partitions

Drop Partition

You can drop partitions that are no longer needed. Before dropping a partition, ensure that the partition has been released.

Python

python

client.release_partitions(
    collection_name="my_collection",
    partition_names=["partitionA"]
)

client.drop_partition(
    collection_name="my_collection",
    partition_name="partitionA"
)

res = client.list_partitions(
    collection_name="my_collection"
)

print(res)

# ["_default"]

Java

java

import io.milvus.v2.service.partition.request.DropPartitionReq;
import io.milvus.v2.service.partition.request.ReleasePartitionsReq;
import io.milvus.v2.service.partition.request.ListPartitionsReq;
import java.util.Collections;
import java.util.List;

ReleasePartitionsReq releasePartitionsReq = ReleasePartitionsReq.builder()
        .collectionName("my_collection")
        .partitionNames(Collections.singletonList("partitionA"))
        .build();

client.releasePartitions(releasePartitionsReq);

DropPartitionReq dropPartitionReq = DropPartitionReq.builder()
        .collectionName("my_collection")
        .partitionName("partitionA")
        .build();

client.dropPartition(dropPartitionReq);

ListPartitionsReq listPartitionsReq = ListPartitionsReq.builder()
        .collectionName("my_collection")
        .build();

List<String> partitionNames = client.listPartitions(listPartitionsReq);
System.out.println(partitionNames);

// Output:
// [_default]

Go

go

import (
    "fmt"

    milvusclient "github.com/milvus-io/milvus/client/v3/milvusclient"
)

err = client.ReleasePartitions(ctx, milvusclient.NewReleasePartitionsOptions("my_collection", "partitionA"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

err = client.DropPartition(ctx, milvusclient.NewDropPartitionOption("my_collection", "partitionA"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

partitionNames, err := client.ListPartitions(ctx, milvusclient.NewListPartitionOption("my_collection"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
fmt.Println(partitionNames)

Rust

rust

use milvus::v2::prelude::*;

client
    .release_partitions(
        ReleasePartitionsRequest::builder()
            .collection_name("my_collection")
            .partition_names(["partitionA"])
            .build()?,
    )
    .await?;

client
    .drop_partition(
        DropPartitionRequest::builder()
            .collection_name("my_collection")
            .partition_name("partitionA")
            .build()?,
    )
    .await?;

let partitions = client
    .list_partitions(
        ListPartitionsRequest::builder()
            .collection_name("my_collection")
            .build()?,
    )
    .await?;
println!("{:?}", partitions.partition_names());

// Output
//
// ["_default"]

C++

c++

auto status = client->ReleasePartitions(milvus::ReleasePartitionsRequest()
                                            .WithCollectionName("my_collection")
                                            .AddPartitionName("partitionA"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

status = client->DropPartition(milvus::DropPartitionRequest()
                                .WithCollectionName("my_collection")
                                .WithPartitionName("partitionA"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

milvus::ListPartitionsResponse response;
status = client->ListPartitions(milvus::ListPartitionsRequest()
                                    .WithCollectionName("my_collection"),
                                response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

for (auto& info : response.PartitionInfos()) {
    std::cout << "\t" << info.Name() << std::endl;
}

NodeJS

javascript

await client.releasePartitions({
    collection_name: "my_collection",
    partition_names: ["partitionA"]
})

await client.dropPartition({
    collection_name: "my_collection",
    partition_name: "partitionA"
})

res = await client.listPartitions({
    collection_name: "my_collection"
})

console.log(res)

// Output
// ["_default"]

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/partitions/release" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionNames": ["partitionA"]
}'

# {
#     "code": 0,
#     "data": {}
# }

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/partitions/drop" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionName": "partitionA"
}'

# {
#     "code": 0,
#     "data": {}
# }

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/partitions/list" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection"
}'

# {
#     "code": 0,
#     "data": [
#         "_default"
#     ]
# }