外部ボリューム

外部ボリュームは、自身のクラウドオブジェクトストレージ（AWS S3 など）内のバケットまたはパスへの読み取り専用参照であり、Zilliz Cloud がデータをコピーまたは移動することなく、その場でデータにアクセスできるようにします。

このページでは、Web コンソールおよび SDK を使用して外部ボリュームを作成および削除する方法について説明します。

考慮事項

ボリュームは、プロジェクトのクラウドプロバイダーとリージョンに制限されます。たとえば、プロジェクトが AWS us-west-2 にある場合、作成できるボリュームも AWS us-west-2 のみです。
ボリュームをクラスターで使用するには、そのクラスターがボリュームと同じクラウドプロバイダーおよびリージョンに存在している必要があります。
ボリュームを作成および管理するには、Project Admin である必要があります。
ボリュームは一度作成すると、その設定を編集できません。ボリュームの設定を変更する場合は、代わりに希望する設定で新しいボリュームを作成してください。
外部ボリュームの場合、データは自身のバケット内に保持されます。そのため、データファイルは外部ボリューム上ではなく、クラウドオブジェクトストレージ上で管理する必要があります。
各組織では、最大 100 個の外部ボリューム を作成できます。

事前準備

外部ボリュームを作成する前に、AWS S3 バケットを統合する必要があります。ストレージ統合は、作成する外部ボリュームと同じクラウドプロバイダーおよびリージョン内に配置する必要がある点に注意してください。

外部ボリュームを作成する

SDK 経由

python
# Initiate a volume manager
from pymilvus.bulk_writer.volume_manager import VolumeManager

volume_manager = VolumeManager(
    cloud_endpoint="https://api.cloud.zilliz.com",
    api_key="YOUR_API_KEY"
)

volume_name = "external_volume"

# Create an EXTERNAL volume
volume_manager.create_volume(
    project_id="proj-xxxxxxxxxxxxxxxxxxxxxxx",
    region_id="aws-us-west-2",
    volume_name=volume_name,
    volume_type="EXTERNAL",
    storage_integration_id="integ-xxxx",
    path="data/"
)

print(f"\nVolume {volume_name} created")

# Note: description is not supported by VolumeManager.create_volume as of pymilvus v3.0.2.

java
import io.milvus.bulkwriter.VolumeManager;
import io.milvus.bulkwriter.VolumeManagerParam;
import io.milvus.bulkwriter.request.volume.CreateVolumeRequest;

String cloudEndpoint = "https://api.cloud.zilliz.com";
String apiKey = "YOUR_API_KEY";
String projectId = "proj-xxxxxxxxxxxxxxxxxxxxxxx";
String regionId = "aws-us-west-2";
String volumeName = "external_volume";

VolumeManagerParam volumeManagerParam = VolumeManagerParam.newBuilder()
        .withCloudEndpoint(cloudEndpoint)
        .withApiKey(apiKey)
        .build();
VolumeManager volumeManager = new VolumeManager(volumeManagerParam);

CreateVolumeRequest request = CreateVolumeRequest.builder()
        .projectId(projectId)
        .regionId(regionId)
        .volumeName(volumeName)
        .type("EXTERNAL")
        .storageIntegrationId("integ-xxxx")
        .path("data/")
        .build();

volumeManager.createVolume(request);
System.out.printf("%nVolume %s created%n", volumeName);

// Note: description is not supported by CreateVolumeRequest as of milvus-sdk-java-bulkwriter v3.0.10.

// Note: External Volume management with VolumeManager is not supported by milvus-sdk-go as of client/v3.0.0.

rust

// Note: External Volume management with VolumeManager is not supported in milvus-sdk-rust as of v3.0.2.

c++

// Note: External Volume management with VolumeManager is not supported in milvus-sdk-cpp as of v3.0.3.

javascript
import { VolumeManager } from "@zilliz/milvus2-sdk-node";

const volumeManager = new VolumeManager({
    cloudEndpoint: "https://api.cloud.zilliz.com",
    apiKey: "YOUR_API_KEY"
});

const res = await volumeManager.createVolume({
    projectId: "proj-xxxxxxxxxxxxxxxxxxxxxxx",
    regionId: "aws-us-west-2",
    volumeName: "external_volume",
    type: "EXTERNAL",
    storageIntegrationId: "integ-xxxx",
    path: "data/"
});

console.log(res.data);

// Note: description is not supported by VolumeCreateReq as of @zilliz/milvus2-sdk-node v3.0.6.

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/volumes/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxxx",
    "regionId": "aws-us-west-2",
    "volumeName": "external_volume",
    "type": "EXTERNAL",
    "storageIntegrationId": "integ-xxxx",
    "path": "data/",
    "description": "A volume for storing collection data."
}'

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

次の表に、各パラメーターの説明を示します。

パラメーター	説明
`projectId`	ボリュームを作成するプロジェクトの ID です。
`regionId`	作成するボリュームのリージョンは、データのインポートまたは移行先として予定しているターゲットクラスターのクラウドプロバイダーおよびリージョンと一致している必要があります。
`volumeName`	作成するボリュームの名前は組織内で一意である必要があり、64 文字以下で、英字またはアンダースコアで始まり、英字、数字、ハイフン、アンダースコアのみを含める必要があります。
`type`	外部ボリュームを作成するには、このパラメーターを `EXTERNAL` に設定します。デフォルトは `MANAGED` です。
`storageIntegrationId`	参照するストレージ統合の ID です。`type=EXTERNAL` の場合に必須です。選択するストレージ統合は、作成する外部ボリュームと同じ組織およびリージョンに属している必要があります。
`path`	ストレージパスです。`type=EXTERNAL` の場合に必須です。
`description`（任意）	作成するボリュームの説明です。最大 255 文字です。

Web コンソール経由

左側のナビゲーションで Volumes をクリックします。

ボリュームページで + Volume をクリックします。

ボリュームの設定を行います。

次の表に、外部ボリュームの作成時に使用する各パラメーターの説明を示します。

パラメーター	説明
名前	ボリューム名は組織内で一意である必要があり、64 文字以下で、英字またはアンダースコアで始まり、英字、数字、ハイフン、アンダースコアのみを含める必要があります。
説明	このパラメーターは任意です。最大 255 文字です。
ボリュームタイプ	ボリュームタイプとして「External」を選択します。
クラウドプロバイダーとリージョン	ボリュームのクラウドプロバイダーおよびリージョンは、データのインポートまたは移行先として予定しているターゲットクラスターのクラウドプロバイダーおよびリージョンと一致している必要があります。
ストレージ統合とパス	ストレージ統合（AWS S3 バケット）は、クラウドストレージへのアクセス設定をカプセル化する認証情報オブジェクトです。パスは、データが配置されている場所へのポインターです（例: `folder/`）。

Create をクリックします。

ボリュームを一覧表示する

プロジェクト内の既存のボリュームをすべて表示できます。

SDK 経由

python
# Initiate a volume manager
from pymilvus.bulk_writer.volume_manager import VolumeManager

volume_manager = VolumeManager(
    cloud_endpoint="https://api.cloud.zilliz.com",
    api_key="YOUR_API_KEY"
)

# List volumes
volume_list = volume_manager.list_volumes(
    project_id="proj-xxxxxxxxxxxxxxxxxxxxxxx",
    current_page=1,
    page_size=10
)

print("\nlistVolumes results:\n", volume_list.json()["data"])

java
import com.google.gson.Gson;
import io.milvus.bulkwriter.VolumeManager;
import io.milvus.bulkwriter.VolumeManagerParam;
import io.milvus.bulkwriter.request.volume.ListVolumesRequest;
import io.milvus.bulkwriter.response.volume.ListVolumesResponse;

VolumeManagerParam volumeManagerParam = VolumeManagerParam.newBuilder()
        .withCloudEndpoint("https://api.cloud.zilliz.com")
        .withApiKey("YOUR_API_KEY")
        .build();
VolumeManager volumeManager = new VolumeManager(volumeManagerParam);

ListVolumesRequest request = ListVolumesRequest.builder()
        .projectId("proj-xxxxxxxxxxxxxxxxxxxxxxx")
        .currentPage(1)
        .pageSize(10)
        .build();
ListVolumesResponse response = volumeManager.listVolumes(request);
System.out.println("listVolumes results: " + new Gson().toJson(response));

// Note: External Volume management with VolumeManager is not supported by milvus-sdk-go as of client/v3.0.0.

rust

// Note: External Volume management with VolumeManager is not supported in milvus-sdk-rust as of v3.0.2.

c++

// Note: External Volume management with VolumeManager is not supported in milvus-sdk-cpp as of v3.0.3.

javascript
import { VolumeManager } from "@zilliz/milvus2-sdk-node";

const volumeManager = new VolumeManager({
    cloudEndpoint: "https://api.cloud.zilliz.com",
    apiKey: "YOUR_API_KEY"
});

const res = await volumeManager.listVolumes({
    projectId: "proj-xxxxxxxxxxxxxxxxxxxxxxx",
    currentPage: 1,
    pageSize: 10
});

console.log(res.data);

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

curl --request GET \
--url "${BASE_URL}/v2/volumes?projectId=proj-xxxxxxxxxxxxxxxxxxxxxxx&currentPage=1&pageSize=10" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json"

Web コンソール経由

外部ボリュームの詳細を表示する

特定のボリュームの詳細を確認できます。

SDK 経由

python
# Initiate a volume manager
from pymilvus.bulk_writer.volume_manager import VolumeManager

volume_manager = VolumeManager(
    cloud_endpoint="https://api.cloud.zilliz.com",
    api_key="YOUR_API_KEY"
)

volume_name = "external_volume"

# Describe an external volume
volume_info = volume_manager.describe_volume(
    volume_name=volume_name
)

print("\ndescribeVolume result:\n", volume_info.json()["data"])

java
import com.google.gson.Gson;
import io.milvus.bulkwriter.VolumeManager;
import io.milvus.bulkwriter.VolumeManagerParam;
import io.milvus.bulkwriter.request.volume.DescribeVolumeRequest;
import io.milvus.bulkwriter.response.volume.VolumeInfo;

String cloudEndpoint = "https://api.cloud.zilliz.com";
String apiKey = "YOUR_API_KEY";
String volumeName = "external_volume";

VolumeManagerParam volumeManagerParam = VolumeManagerParam.newBuilder()
        .withCloudEndpoint(cloudEndpoint)
        .withApiKey(apiKey)
        .build();
VolumeManager volumeManager = new VolumeManager(volumeManagerParam);

DescribeVolumeRequest request = DescribeVolumeRequest.builder()
        .volumeName(volumeName)
        .build();
VolumeInfo volumeInfo = volumeManager.describeVolume(request);
System.out.println("describeVolume result: " + new Gson().toJson(volumeInfo));

// Note: External Volume management with VolumeManager is not supported by milvus-sdk-go as of client/v3.0.0.

rust

// Note: External Volume management with VolumeManager is not supported in milvus-sdk-rust as of v3.0.2.

c++

// Note: External Volume management with VolumeManager is not supported in milvus-sdk-cpp as of v3.0.3.

javascript
import { VolumeManager } from "@zilliz/milvus2-sdk-node";

const volumeManager = new VolumeManager({
    cloudEndpoint: "https://api.cloud.zilliz.com",
    apiKey: "YOUR_API_KEY"
});

const res = await volumeManager.describeVolume({
    volumeName: "external_volume"
});

console.log(res.data);

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"
export VOLUME_NAME="external_volume"

curl --request GET \
--url "${BASE_URL}/v2/volumes/${VOLUME_NAME}" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json"

# {
#     "code": 0,
#     "data": {
#         "volumeName": "external_volume",
#         "type": "EXTERNAL",
#         "regionId": "aws-us-west-2",
#         "storageIntegrationId": "integ-xxxx",
#         "path": "data/",
#         "status": "RUNNING",
#         "createTime": "2024-04-15T12:00:00Z"
#     }
# }

Web コンソール経由

外部ボリュームを削除する

外部ボリュームが不要になったら、いつでも削除できます。

外部ボリュームを削除すると、Zilliz Cloud からボリュームのメタデータのみが削除されます。データはクラウドオブジェクトストレージ内にそのまま保持されます。

SDK 経由

python
# Initiate a volume manager
from pymilvus.bulk_writer.volume_manager import VolumeManager

volume_manager = VolumeManager(
    cloud_endpoint="https://api.cloud.zilliz.com",
    api_key="YOUR_API_KEY"
)

volume_name = "external_volume"

# Delete an external volume
volume_manager.delete_volume(
    volume_name=volume_name
)

print(f"\nVolume {volume_name} deleted")

java
import io.milvus.bulkwriter.VolumeManager;
import io.milvus.bulkwriter.VolumeManagerParam;
import io.milvus.bulkwriter.request.volume.DeleteVolumeRequest;

String cloudEndpoint = "https://api.cloud.zilliz.com";
String apiKey = "YOUR_API_KEY";
String volumeName = "external_volume";

VolumeManagerParam volumeManagerParam = VolumeManagerParam.newBuilder()
        .withCloudEndpoint(cloudEndpoint)
        .withApiKey(apiKey)
        .build();
VolumeManager volumeManager = new VolumeManager(volumeManagerParam);

DeleteVolumeRequest request = DeleteVolumeRequest.builder()
        .volumeName(volumeName)
        .build();

volumeManager.deleteVolume(request);
System.out.printf("%nVolume %s deleted%n", volumeName);

// Note: External Volume management with VolumeManager is not supported by milvus-sdk-go as of client/v3.0.0.

rust

// Note: External Volume management with VolumeManager is not supported in milvus-sdk-rust as of v3.0.2.

c++

// Note: External Volume management with VolumeManager is not supported in milvus-sdk-cpp as of v3.0.3.

javascript
import { VolumeManager } from "@zilliz/milvus2-sdk-node";

const volumeManager = new VolumeManager({
    cloudEndpoint: "https://api.cloud.zilliz.com",
    apiKey: "YOUR_API_KEY"
});

const res = await volumeManager.deleteVolume({
    volumeName: "external_volume"
});

console.log(res.data);

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"
export VOLUME_NAME="external_volume"

curl --request DELETE \
--url "${BASE_URL}/v2/volumes/${VOLUME_NAME}" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json"

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

Web コンソール経由

1
左側のナビゲーションで Volumes をクリックします。
2
Actions 列の ... をクリックし、Delete を選択します。
3
ボリューム名を入力し、Delete をクリックします。

よくある質問

請求書の未払いにより組織が凍結された場合、ボリュームはどうなりますか？

組織が凍結されると、無料トライアルと従量課金制の両方を含むすべての管理対象ボリュームと、そこに保存されているすべてのファイルが削除され、復元できません。外部ボリュームも凍結され、新しい操作には使用できなくなりますが、自身のバケット内のデータには影響ありません。

ボリュームの使用を継続するには、まず未払いの請求書をすべて精算してください。

外部ボリュームと外部ストレージからの直接インポートの違いは何ですか？

どちらも、自身の S3 または GCS バケットからデータをインポートできます。主な違いは次のとおりです。

外部ボリュームでは、認証情報管理のために AWS S3 バケットを Zilliz Cloud と統合する必要があります。認証情報は一度設定すれば、複数のボリュームや操作で再利用できます。データエンジニアはクラウドストレージキーへ直接アクセスする必要がありません。
直接の外部ストレージインポートでは、各インポートリクエストごとに認証情報（access key と secret key）を提供する必要があります。これは単発のインポートにはより簡単ですが、認証情報の分離や再利用性は提供されません。

外部ボリュームの作成後に、そのストレージ統合やパスを変更できますか？

いいえ。外部ボリュームの作成後は、ストレージ統合とパスを変更できません。別のストレージ統合またはパスを使用するには、新しい外部ボリュームを作成してください。

アクティブなジョブまたは外部コレクションから参照されている外部ボリュームを削除できますか？

いいえ。下流の外部コレクションまたはアクティブなジョブがそのボリュームを参照している場合、削除はブロックされます。

外部ボリュームを使用すると、データ転送料金は発生しますか？

いいえ。外部ボリュームは、クラスターと同じクラウドプロバイダーおよびリージョン内に存在している必要があります。すべてのデータアクセスは同じリージョン内で行われるため、Zilliz Cloud ではリージョン間のデータ転送料金は発生しません。

ボリュームのステータスは何を意味しますか？

次の表に、可能なボリュームステータスを示します。

ステータス	説明
Available	このボリュームはアクティブで、使用可能です。
Frozen	組織は未払いの請求書により凍結されています。このボリュームは新しい操作には使用できません。ボリュームの使用を継続するには、請求書をお支払いください。
Error	ストレージ統合の検証に失敗しました。設定を確認して再試行してください。該当するストレージ統合は次のとおりです。 AWS S3 バケット,

ステータス

説明

Available

このボリュームはアクティブで、使用可能です。

Frozen

組織は未払いの請求書により凍結されています。このボリュームは新しい操作には使用できません。ボリュームの使用を継続するには、請求書をお支払いください。

Error

ストレージ統合の検証に失敗しました。設定を確認して再試行してください。

該当するストレージ統合は次のとおりです。

AWS S3 バケット,

外部ボリューム

考慮事項

事前準備

外部ボリュームを作成する

左側のナビゲーションで Volumes をクリックします。

ボリュームページで + Volume をクリックします。

ボリュームの設定を行います。

Create をクリックします。

ボリュームを一覧表示する

外部ボリュームの詳細を表示する

外部ボリュームを削除する

左側のナビゲーションで Volumes をクリックします。

Actions 列の ... をクリックし、Delete を選択します。

ボリューム名を入力し、Delete をクリックします。

よくある質問

考慮事項​

事前準備​

外部ボリュームを作成する​

左側のナビゲーションで Volumes をクリックします。

ボリュームページで + Volume をクリックします。

ボリュームの設定を行います。

Create をクリックします。

ボリュームを一覧表示する​

外部ボリュームの詳細を表示する​

外部ボリュームを削除する​

左側のナビゲーションで Volumes をクリックします。

Actions 列の ... をクリックし、Delete を選択します。

ボリューム名を入力し、Delete をクリックします。

よくある質問​

考慮事項

事前準備

外部ボリュームを作成する

ボリュームを一覧表示する

外部ボリュームの詳細を表示する

外部ボリュームを削除する

よくある質問