コレクションスキーマの変更

コレクションが開発環境から本番環境へ移行する際、そのスキーマは変更されることがよくあります。フィルタリングやアプリケーションロジックのために、source_uri やreview_status といったスカラーフィールドを追加したり、アプリケーションによって生成されたエンベディング用の新しいベクトルフィールドを追加したり、既存のテキストに対する語彙検索のためにBM25関数とその生成されたスパースベクトルフィールドを追加したり、あるいは使用されなくなったフィールドや関数を削除したりすることがあります。 「コレクションスキーマの変更」を使用すると、コレクションを再作成することなく、サポートされているフィールドや関数の変更をその場で行うことができます。

このガイドでは、管理対象コレクションにおけるユーザー定義フィールドおよび、その生成ベクトルフィールドを持つ関数のスキーマ変更について説明します。外部コレクションにフィールドを追加するには、「Alter External Collection Schema」を参照してください。VARCHAR フィールドのmax_length や、ARRAY フィールドのmax_capacity の変更など、フィールドプロパティの変更については、「Alter Collection Field」を参照してください。 動的フィールドの動作については、「動的フィールド」および「コレクションの変更」を参照してください。

制限事項

ユーザー定義フィールドの追加

  • 追加するユーザー定義フィールドは、NULL 許容でなければなりません。add_collection_field() を呼び出す際は、nullable=True を設定してください。既存エンティティの場合、default_value を使用してスカラーフィールドを追加しない限り、追加されるフィールドはNULL となります。

  • ユーザー定義のスカラーフィールドの追加は、Milvus 2.6.x 以降でサポートされています。ユーザー定義のベクトルフィールドの追加は、Milvus 2.6.18 以降でサポートされています。

  • StructArray フィールドの追加は、Milvus 3.0.0 以降でサポートされています。追加する StructArray フィールドは、null 許容でなければなりません。

  • フィールド名は、コレクション内のフィールド間で一意である必要があります。

関数とその生成ベクトルフィールドの追加

  • スキーマの更新ごとに、1 つの関数と 1 つの生成ベクトルフィールドのみを追加できます。

  • サポートされている関数によって、生成されるベクトルフィールドの型が決まります。BM25 は `SPARSE_FLOAT_VECTOR ` フィールドを生成し、MINHASH は `BINARY_VECTOR ` フィールドを生成します。

  • 生成されるベクトルフィールドは新しいフィールドでなければなりません。コレクションスキーマにすでに存在するフィールドを参照することはできません。

  • 生成されるベクトルフィールドは、NULL 許容であってはなりません。

  • この関数で使用される入力フィールドは、コレクション内にすでに存在している必要があります。

  • 既存のコレクションに BM25 または MinHash 関数を追加する場合、関数の入力はVARCHAR フィールドでなければなりません。Milvus では、この入力タイプから既存エンティティに対して生成された出力をバックフィルできないため、このワークフローではTEXT 入力はサポートされていません。

ユーザー定義フィールドの削除

  • コレクション内の主キーフィールド、パーティションキーフィールド、クラスタリングキーフィールド、および最後のベクトルフィールドを削除することはできません。

  • ARRAY<STRUCT> フィールド全体を削除することはできますが、ARRAY<STRUCT> フィールド内の個々のサブフィールドを削除することはできません。

  • 関数の入力フィールドとして使用されているフィールド、または関数の出力フィールドとして生成されたフィールドを直接削除することはできません。関数の出力フィールドを削除するには、そのフィールドを生成する関数を削除してください。

関数とその生成されたベクトルフィールドを削除する

  • このスキーマ変更ワークフローでは、関数を削除すると、その関数、生成されたベクトルフィールド、および関連するインデックスが削除されます。関数の入力フィールドはコレクションのスキーマに残ります。

  • 関数を削除する際、その生成されたベクトルフィールドを削除するとコレクションにベクトルフィールドが一切残らなくなる場合は、関数の削除は拒否されます。

サポートされている追加および削除操作の範囲外でのスキーマ変更を行う場合は、コレクションを再作成するか、移行してください。

既存のコレクションへのフィールドおよび関数の追加

ユーザー定義フィールドを追加する場合と、ベクトルフィールドを生成する関数を追加する場合で、適切なワークフローを選択してください:

いずれの場合も、新しいフィールド名はコレクション内に既に存在してはならず、フィールドの総数はMilvusのフィールド数制限を超えてはなりません。詳細については、「Milvusの制限事項」を参照してください。

ユーザー定義のスカラーフィールドの追加Compatible with Milvus 2.6.x

add_collection_field() を使用して、既存のコレクションにユーザー定義のスカラーフィールドを追加します。

これは、動的フィールドに任意のキーを格納することとは異なります。スキーマの更新が反映されると、新しいスカラーフィールドはコレクションスキーマの正規の一部となります。このフィールドへの値の挿入やアップサート、サポートされている場合はインデックスの作成、クエリや検索フィルターでの使用、およびクエリや検索結果での返却が可能になります。

既存エンティティは新しいフィールドが存在する以前に挿入されているため、追加するすべてのユーザー定義スカラーフィールドはNULL許容でなければなりません:

  • nullable=True を指定し、default_value を指定せずにスカラーフィールドを追加した場合、既存のエンティティは新しいフィールドに対してNULL を返します。

  • nullable=True を指定し、default_value も指定してスカラーフィールドを追加した場合、既存のエンティティはその新しいフィールドに対してNULL を返します。

スカラーフィルタ式は、NULL 形式のスカラー値とは一致しません。詳細については、「Nullable Fields」を参照してください。

例:Null 許容スカラーフィールドの追加

次の例では、product_catalog という名前の既存のコレクションに、Null 許容のsource フィールドを追加します。

from pymilvus import DataType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.add_collection_field(
    collection_name="product_catalog",
    field_name="source",
    data_type=DataType.VARCHAR,
    max_length=128,
    nullable=True,
)

フィールドが追加されると、コレクションにすでに存在していたエンティティは、source に対してNULL を返します。新しいエンティティは、挿入またはアップサート時にsource を設定できます。

例:デフォルト値を持つスカラーフィールドを追加する

既存のエンティティが `NULL` ではなく具体的な値を返すようにするには、スカラーフィールドを追加する際に `default_value ` を指定します。次の例では、review_status フィールドを追加し、デフォルト値として `"unreviewed" ` を使用しています。

from pymilvus import DataType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.add_collection_field(
    collection_name="product_catalog",
    field_name="review_status",
    data_type=DataType.VARCHAR,
    max_length=32,
    nullable=True,
    default_value="unreviewed",
)

フィールドが追加された後、コレクションにすでに存在していたエンティティは、review_status に対して"unreviewed" を返します。新しいエンティティは、異なる値を設定することも、値が指定されていない場合はデフォルト値を使用することもできます。

StructArray フィールドの追加Compatible with Milvus 3.0.0

add_collection_struct_field() を使用して、Struct 要素の配列を受け入れる StructArray フィールドを追加します。StructArray フィールドを追加するには、次の手順に従います。

  1. サポートされているデータ型で構成される必要なサブフィールドを含む Struct スキーマを作成します。適用可能なデータ型については、「StructArray の制限」を参照してください。

  2. 上記で作成した Struct スキーマを参照し、add_collection_struct_field() でフィールドの最大容量を設定します。

  3. リクエスト内で `nullable=True ` を設定します。

例:Null 許容の StructArray フィールドを追加する

from pymilvus import DataType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

# Create a Struct schema.
struct_schema = client.create_struct_field_schema()

# Add scalar fields to the Struct.
struct_schema.add_field("text", DataType.VARCHAR, max_length=65535)
struct_schema.add_field("chapter", DataType.VARCHAR, max_length=512)

# Add vector fields to the Struct with mmap enabled.
struct_schema.add_field("text_vector", DataType.FLOAT_VECTOR, mmap_enabled=True, dim=5)
struct_schema.add_field("chapter_vector", DataType.FLOAT_VECTOR, mmap_enabled=True, dim=5)

client.add_collection_struct_field(
    collection_name="books",
    field_name="chunks",
    struct_schema=struct_schema,
    max_capacity=1024,
    nullable=True,
)

StructArrayフィールドが追加されると、コレクションにすでに存在するエンティティは、すべてのサブフィールドにおいてchunks に対してNULL を返します。新しいエンティティを挿入する際は、すべてのサブフィールドがNULL であるか、有効な値を持っていることを確認してください。一部のサブフィールドがNULL に設定され、他のサブフィールドが有効な値に設定されたエンティティを挿入すると、エラーが発生します。

ユーザー定義のベクトルフィールドを追加するCompatible with Milvus 2.6.18+

アプリケーションが埋め込みを生成し、ベクトル値をMilvusに書き込む場合は、`add_collection_field() `を使用してユーザー定義のベクトルフィールドを追加してください。

追加されるすべてのユーザー定義ベクトルフィールドは、Nullableでなければなりません。既存のエンティティについては、upsertまたはバックフィルワークフローを通じてベクトル値を書き込むまで、新しいベクトルフィールドの値はNULL となります。新しいエンティティは、挿入時にこのベクトルフィールドを含めることができます。ベクトル検索では、ベクトル値がNULL であるエンティティはスキップされます。詳細については、「Nullableフィールド」を参照してください。

例: NULL 許容のベクトルフィールドを追加する

次の例では、embedding_v2 という名前のヌル許容の密ベクトルフィールドを既存のコレクションに追加します。dim には、アプリケーションによって生成される埋め込みの次元数を設定してください。

from pymilvus import DataType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.add_collection_field(
    collection_name="product_catalog",
    field_name="embedding_v2",
    data_type=DataType.FLOAT_VECTOR,
    dim=768,
    nullable=True,
)

フィールドを追加した後、検索を行う前に、新しいベクトルフィールドに対してインデックスを作成してください:

index_params = client.prepare_index_params()

index_params.add_index(
    field_name="embedding_v2",
    index_type="AUTOINDEX",
    metric_type="COSINE",
)

client.create_index(
    collection_name="product_catalog",
    index_params=index_params,
)

既存エンティティの `embedding_v2 ` には `NULL ` が設定されており、このフィールドで検索を行うとスキップされます。既存のエンティティを `embedding_v2` を通じて検索可能にするには、upsert またはバックフィルワークフローを通じて NULL 以外のベクトル値を書き込んでください。新しいエンティティは、挿入時に `embedding_v2 ` を含めることができます。

関数とその生成ベクトルフィールドの追加Compatible with Milvus 3.0.x

このワークフローは、Milvusが既存のコレクションにすでに格納されているデータから新しいベクトルフィールドを生成する必要がある場合に使用します。この操作により、3つの関連するスキーマ要素が追加されます:

  • 1つ以上の既存の入力フィールドから読み込む関数定義。

  • 関数の出力を格納する新しいベクトルフィールド。

  • 新しいベクトルフィールドにバインドされたインデックス定義。

たとえば、BM25関数は既存のVARCHAR フィールドを読み取り、語彙検索用のSPARSE_FLOAT_VECTOR フィールドを生成します。また、MinHash関数は、近似重複検出用のBINARY_VECTOR フィールドを生成します。このワークフローでは、関数の入力フィールドを追加または置換することはありません。

この機能を利用するには、Storage V3が必要です。有効化の手順および互換性に関する注意事項については、「Storage V3」を参照してください。

既存のコレクションに関数とその生成されたベクトルフィールドを追加するには、スキーマバージョンの圧縮およびストレージバージョンの圧縮も必要です。いずれかの設定が無効になっている場合、Milvusはリクエストを拒否します。これらの追加の前提条件は、既存のコレクションを変更する場合にのみ適用されます。初期のコレクションスキーマで関数を定義する場合、この既存データのバックフィルワークフローは使用されません。

サポートされている関数によって、生成されるベクトルフィールドの型が決まります:

関数生成されるベクトルフィールドの型代表的な入力フィールド代表的なユースケース
BM25SPARSE_FLOAT_VECTORアナライザーが有効なVARCHAR フィールド語彙検索およびキーワードの関連性
MINHASHBINARY_VECTORVARCHAR フィールド近似重複の検出

各関数の動作の詳細については、「BM25関数」および「MinHash関数」を参照してください。

生成されるベクトルフィールドは、コレクション内に既に存在してはならず、また null 許容であってはなりません。関数の入力フィールドは、既に存在している必要があります。

例: BM25 関数とその生成されたスパースベクトルフィールドを追加する

次の例では、text_bm25 という名前のBM25関数と、その生成されるスパースベクトルフィールドであるtext_sparse を、既存のコレクションに追加します。コレクションには、アナライザーが有効化されたtext という名前のVARCHAR フィールドがすでに存在している必要があります。

from pymilvus import DataType, Function, FunctionType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

sparse_field = client.create_field_schema(
    name="text_sparse",
    data_type=DataType.SPARSE_FLOAT_VECTOR,
    desc="BM25-generated sparse vector field",
)

bm25_function = Function(
    name="text_bm25",
    input_field_names=["text"],
    output_field_names=["text_sparse"],
    function_type=FunctionType.BM25,
)

index_params = client.prepare_index_params()

index_params.add_index(
    field_name="text_sparse",
    index_type="SPARSE_INVERTED_INDEX",
    metric_type="BM25",
    params={
        "inverted_index_algo": "DAAT_MAXSCORE",
        "bm25_k1": 1.2,
        "bm25_b": 0.75,
    },
)

client.add_function_field(
    collection_name="product_catalog",
    field_schema=sparse_field,
    func=bm25_function,
    index_params=index_params,
)

index_params オブジェクトには、新しい関数出力フィールド用のインデックス定義が正確に 1 つ含まれている必要があります。Milvus は、関数、その生成されたベクトルフィールド、およびバウンドインデックス定義を、同じスキーマ変更として追加します。add_function_field() の後に、create_index() を個別に呼び出さないでください。

概念的には、この操作により、以下のFunction、生成された出力フィールド、およびバインドされたインデックス定義が追加されます:

New Function:
  name: "text_bm25"
  type: BM25
  input_field_names: ["text"]
  output_field_names: ["text_sparse"]

New generated output field:
  name: "text_sparse"
  data_type: SPARSE_FLOAT_VECTOR
  nullable: false

Bound index:
  field_name: "text_sparse"
  index_type: SPARSE_INVERTED_INDEX
  metric_type: BM25

リクエストが成功すると、describe_collection() は、コレクションスキーマ内の新しいtext_bm25 関数とその生成されたtext_sparse ベクトルフィールドの両方を返します。Milvusは、新しいエンティティが書き込まれる際に、その関数出力を生成します。 既存のエンティティについては、Milvusはバックグラウンドでのコンパクションを通じて、生成されたベクトルフィールドを非同期的に埋めます。スキーマの可視性は、スキーマの更新が成功したことを確認するものではありますが、すべての既存のエンティティに対するバックフィルが完了したことを示すものではありません。完全なBM25検索ワークフローについては、「全文検索」を参照してください。

Milvusは、近似重複検出のためのMinHash関数およびそれによって生成されるバイナリベクトルフィールドもサポートしています。MinHash関数はFunctionType.MINHASH を使用し、新しいBINARY_VECTOR 出力フィールドに書き込みを行います。設定の詳細については、「MinHash関数」を参照してください。

既存のコレクションからフィールドおよび関数を削除する

ユーザー定義フィールドがコレクションモデルの一部でなくなった場合は、そのフィールドを直接削除できます。関数とその生成されたベクトルフィールドを削除するには、その関数を削除してください。Milvusは、同じスキーマ変更の中で、生成されたフィールドとそのインデックスを削除します。

ユーザー定義フィールドの削除Compatible with Milvus 3.0.x

drop_collection_field() を使用して、コレクションモデルの一部でなくなったユーザー定義のスカラー、ベクトル、または StructArray フィールドを削除します。

フィールドを削除すると、まずコレクションスキーマとフィールドの可視性が変更されます:

  • drop_collection_field() が成功すると、コレクションスキーマが更新されます。describe_collection() は削除されたフィールドを返さなくなり、クエリや検索ではoutput_fields でそのフィールドを返すことができなくなり、式内での使用もできなくなります。

  • 削除されたフィールドに基づいて作成されたインデックスは、スキーマの更新の一環としてクリーンアップされます。

ストレージのクリーンアップは、スキーマのクリーンアップとは別に行われます。詳細については、「フィールドの削除後、ストレージ領域はいつ解放されますか?」を参照してください。

例:ユーザー定義のスカラーフィールドを削除する

次の例では、experiment_tag がproduct_catalog 内のユーザー定義スカラーフィールドであると仮定し、コレクションからこのフィールドを削除します。

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.drop_collection_field(
    collection_name="product_catalog",
    field_name="experiment_tag",
)

フィールドを削除した後、describe_collection() を呼び出して、そのフィールドがスキーマから削除されたことを確認できます。

例: StructArrayフィールドの削除

次の例では、chunks がmy_collection 内の StructArray フィールドであると仮定し、コレクションからこのフィールドを削除します。

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.drop_collection_field(
    collection_name="my_collection",
    field_name="chunks",
)

例:ユーザー定義のベクトルフィールドを削除する

ベクトルフィールドも同様の `drop_collection_field() ` メソッドで削除できますが、削除後もコレクションには少なくとも 1 つのベクトルフィールドが残っている必要があります。これは、一時的に複数のベクトル表現を保持し、後でそのうちの 1 つに統一するコレクションの場合に役立ちます。

以下の例では、image_vector が `hybrid_catalog` 内のユーザー定義ベクトルフィールドであり、コレクションには `text_vector` などの別のベクトルフィールドが依然として残っていることを前提としています。

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.drop_collection_field(
    collection_name="hybrid_catalog",
    field_name="image_vector",
)

image_vector がコレクション内の最後のベクトル場である場合、削除操作は拒否されます。

関数とその生成されたベクトル場を削除するCompatible with Milvus 3.0.x

BM25 関数や、それによって生成された疎ベクトルフィールドなど、関数やその生成されたベクトルフィールドが不要になった場合に、この操作を使用します。

関数名を引数として `drop_function_field() ` を呼び出します。Milvus は、関数の入力フィールドを保持したまま、その関数、生成されたベクトルフィールド、および関連するインデックスを削除します。

例:BM25関数とその生成された疎ベクトルフィールドを削除する

以下の例では、text_bm25 がproduct_catalog 内の BM25 関数であり、text_sparse という名前の疎ベクトル出力フィールドを生成すると仮定します。

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.drop_function_field(
    collection_name="product_catalog",
    function_name="text_bm25",
)

操作が成功すると、describe_collection() は削除された関数やその生成されたベクトルフィールドを返さなくなります。関数の入力フィールドはスキーマに残ります。

関数の出力フィールドを削除することで、コレクションにベクトルフィールドが一切残らなくなる場合、この操作は拒否されます。

よくある質問

フィールドや関数を追加するには、どのメソッドを使用すればよいですか?

add_collection_field() を使用して、ユーザー定義のスカラーフィールドまたはベクトルフィールドを追加します。

要素が同じ Struct スキーマを共有する配列フィールドが必要な場合は、add_collection_struct_field() を使用して StructArray フィールドを追加してください。

add_function_field() を使用して、関数、その生成されたベクトルフィールド、およびバインドされたインデックスの定義を、同じスキーマ変更で追加します。

追加されたユーザー定義フィールドはなぜNULL許容でなければならないのですか?

既存エンティティは、新しいフィールドが存在する前に挿入されたため、そのフィールドの値を持っていません。nullable=True を設定することで、アプリケーションが値を書き込むまで、またはスカラーフィールドの場合はデフォルト値が適用されるまで、Milvus はその欠落値を `NULL ` として表現します。

このルールは、add_collection_field() で追加されたユーザー定義のスカラーフィールドおよびユーザー定義のベクトルフィールド、ならびにadd_collection_struct_field() で追加された StructArray フィールドに適用されます。関数によって生成されたベクトルフィールドには適用されません。これらのフィールドは NULL 許容にできません。

ユーザー定義フィールドを追加した後、既存エンティティにはどのような影響がありますか?

ユーザー定義のスカラーフィールドの場合、default_value を設定しない限り、既存のエンティティはNULL を返します。default_value を設定した場合、既存のエンティティはそのデフォルト値を返します。

ユーザー定義のベクトルフィールドの場合、既存のエンティティでは新しいベクトルフィールドの値がNULL となります。追加されたフィールドに対するベクトル検索では、ベクトル値がNULL であるエンティティはスキップされます。既存のエンティティを新しいベクトルフィールドで検索可能にするには、upsertまたはバックフィルワークフローを通じてNULL以外のベクトル値を書き込んでください。新しいエンティティは、挿入時に新しいベクトルフィールドを含めることができます。

StructArrayフィールドの場合、既存のエンティティは、そのすべてのサブフィールドにわたって、新しいStructArrayフィールドに対してNULL を返します。新しいエンティティは、すべてのサブフィールドに対してNULL を指定するか、すべてのサブフィールドに対して有効な値を指定する必要があります。

既存のコレクションにBM25語彙検索を追加することはできますか?

はい。コレクションにすでにアナライザーが有効化されたVARCHAR フィールドが存在する場合、BM25関数とその生成されたスパースベクトルフィールドを追加して、語彙検索を行うことができます。このワークフローでは、Milvusは関数、新しいSPARSE_FLOAT_VECTOR 出力フィールド、およびバウンドインデックスの定義を、同じスキーマ変更として追加します。 このスキーマ変更ワークフローでは、既存のTEXT フィールドをBM25の入力として使用することはできません。TEXT 入力を使用するには、コレクションの作成時にフィールドとBM25関数を定義してください。

add_function_field() を呼び出す際は、新しい出力フィールド用のmetric_type="BM25" を含むSPARSE_INVERTED_INDEX インデックスを1つ持つindex_params オブジェクトを指定してください。Milvusは、同じスキーマ変更の一環として、インデックス定義を生成されたフィールドにバインドします。

関数とその生成されたベクトルフィールドを削除するにはどうすればよいですか?

関数名を引数としてdrop_function_field() を呼び出します。このスキーマ変更ワークフローにおいて、Milvusは関数、その生成されたベクトルフィールド、および関連するインデックスをまとめて削除しますが、関数の入力フィールドは保持されます。

コレクションのスキーマを変更した後、待機する必要がありますか?

通常、手動で待機する必要はありません。次の操作が更新されたスキーマに依存する場合は、まず `describe_collection() ` を呼び出して、Milvus が現在返しているスキーマを確認することができます。

分散デプロイ環境では、Milvus コンポーネントがコレクションのメタデータを更新する間に、わずかな伝播遅延が生じる場合があります。スキーマ変更直後の操作がスキーマ関連のエラーで失敗した場合は、スキーマを更新してから操作を再試行してください。

フィールドを削除した後、ストレージ領域はいつ解放されますか?

フィールドを削除すると、そのフィールドは現在のスキーマおよび通常のクエリ/検索の対象から除外されますが、そのフィールドの履歴データはオブジェクトストレージから直ちに物理的に削除されるわけではありません。

ストレージ容量は、後のコンパクション処理中に解放されます。コンパクションとは、既存のデータファイルを、よりコンパクトな新しいファイルに再編成するバックグラウンドプロセスです。フィールドが削除された後、新たにコンパクションされたファイルは現在のスキーマに従い、削除されたフィールドは除外されます。Milvusは、フィールドの削除後に即座に、あるいは特定のタイミングでストレージ容量が削減されることを保証するものではありません。

動的フィールドキーと同じ名前のスカラーフィールドを追加するとどうなりますか?

動的フィールドが有効になっている場合、既存の動的フィールドキーと同じ名前のスカラーフィールドを追加できます。新しいスカラーフィールドは、通常のクエリ出力において動的フィールドキーをマスクしますが、元の動的データは `$meta` に保持されます。

たとえば、既存エンティティに「source 」という名前の動的キーが格納されており、後で「source 」という名前のスカラーフィールドを追加した場合、「source 」に対する通常の出力では、スカラーフィールドが参照されます。元の動的値にアクセスするには、「$meta 」というパス構文(例:$meta["source"] )を使用してください。

翻訳DeepL

目次

マネージド Milvus を無料で試す

Zilliz Cloud は手間いらず、Milvus を基盤に 10 倍高速です。

始める
フィードバック

このページは役に立ちましたか ?