メインコンテンツまでスキップ
バージョン: User Guides (Cloud)

既存のコレクションにフィールドを追加する

Milvusでは、既存のコレクションに新しいフィールドを動的に追加できます。これにより、アプリケーションの要件変化に応じてデータスキーマを柔軟に進化させることができます。このガイドでは、実用的な例を用いてさまざまなシナリオでのフィールド追加方法を紹介します。

注意事項​

コレクションにフィールドを追加する前に、以下の重要なポイントを確認してください：

  • スカラーフィールド（INT64、VARCHAR、FLOAT、DOUBLEなど）を追加できます。ベクターフィールドは既存のコレクションに追加できません。

  • 新しいフィールドは、新しいフィールドの値を持たない既存のエンティティに対応するため、nullable（nullable=True）である必要があります。

  • ロード済みのコレクションにフィールドを追加すると、メモリ使用量が増加します。

  • コレクションごとのフィールド総数には上限があります。詳細については、Milvus 制限s を参照してください。

  • フィールド名は静的フィールド内で一意である必要があります。

  • 最初に enable_dynamic_field=True を指定せずに作成されたコレクションに対して、後から $meta フィールドを追加して動的フィールド機能を有効にすることはできません。

前提条件​

このガイドでは、以下の環境が整っていることを前提としています：

  • 実行中の Milvus インスタンス

  • Milvus SDK がインストール済み

  • 既存のコレクション

📘**Need help setting up?**

コレクションの作成および基本操作については、Create Collection を参照してください。

基本的な使い方​

from pymilvus import MilvusClient, DataType

# Connect to your Milvus server
client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT"  # Replace with your Milvus server URI
)

シナリオ 1: Null 許容フィールドを迅速に追加する​

コレクションを拡張する最も簡単な方法は、Null 許容フィールドを追加することです。これは、データに新しい属性を素早く追加したい場合に最適です。

# Add a nullable field to an existing collection
# This operation:
# - Returns almost immediately (non-blocking)
# - Makes the field available for use with minimal delay
# - Sets NULL for all existing entities
client.add_collection_field(
    collection_name="product_catalog",
    field_name="created_timestamp",  # Name of the new field to add
    data_type=DataType.INT64,        # Data type must be a scalar type
    nullable=True                    # Must be True for added fields
    # Allows NULL values for existing entities
)

期待される動作:

  • 既存のエンティティは、新しいフィールドに対して NULL を持つ

  • 新しいエンティティは、NULL または実際の値のいずれかを持つことができる

  • フィールドの可用性は、内部スキーマ同期により、ほぼ即座に（最小限の遅延で）発生する

  • 同期期間が短時間経過した後、即時クエリ可能となる

# Example query result
{
    'id': 1, 
    'created_timestamp': None  # New field shows NULL for existing entities
}

シナリオ 2: デフォルト値を持つフィールドを追加する​

既存のエンティティに NULL ではなく意味のある初期値を持たせたい場合は、デフォルト値を指定します。

# Add a field with default value
# This operation:
# - Sets the default value for all existing entities
# - Makes the field available with minimal delay
# - Maintains data consistency with the default value
client.add_collection_field(
    collection_name="product_catalog",
    field_name="priority_level",     # Name of the new field
    data_type=DataType.VARCHAR,      # String type field
    max_length=20,                   # Maximum string length
    nullable=True,                   # Required for added fields
    default_value="standard"         # Value assigned to existing entities
    # Also used for new entities if no value provided
)

期待される動作:

  • 既存のエンティティは、新しく追加されたフィールドに対してデフォルト値（"standard"）を持つことになります。

  • 新しいエンティティは、デフォルト値を上書きすることも、値が指定されない場合はそのデフォルト値を使用することもできます。

  • フィールドの可用性は、ごくわずかな遅延でほぼ即座に発生します。

  • 短い同期期間の後、すぐに即時クエリ可能になります。

# Example query result
{
    'id': 1,
    'priority_level': 'standard'  # Shows default value for existing entities
}

FAQ​

$meta フィールドを追加することで動的スキーマ機能を有効にできますか？​

いいえ、add_collection_field を使用して $meta フィールドを追加し、動的フィールド機能を有効にすることはできません。たとえば、以下のコードは動作しません：

# ❌ This is NOT supported
client.add_collection_field(
    collection_name="existing_collection",
    field_name="$meta",
    data_type=DataType.JSON  # This operation will fail
)

動的スキーマ機能を有効にするには、以下の手順に従います。

  • 新しいコレクション: コレクション作成時に enable_dynamic_field を True に設定します。詳細については、コレクションの作成を参照してください。

  • 既存のコレクション: コレクションレベルのプロパティ dynamicfield.enabled を True に設定します。詳細については、コレクションの変更を参照してください。

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

コレクションで動的フィールドが有効になっている場合（$meta が存在する）、既存の動的フィールドキーと同じ名前を持つ静的フィールドを追加できます。この場合、新たに追加された静的フィールドが動的フィールドキーをマスクしますが、元の動的データは保持されます。

フィールド名の競合を避けるため、実際にフィールドを追加する前に、既存のフィールドおよび動的フィールドキーを確認し、適切な名前を選定することを推奨します。

シナリオ例:

# Original collection with dynamic field enabled
# Insert data with dynamic field keys
data = [{
    "id": 1,
    "my_vector": [0.1, 0.2, ...],
    "extra_info": "this is a dynamic field key",  # Dynamic field key as string
    "score": 99.5                                 # Another dynamic field key
}]
client.insert(collection_name="product_catalog", data=data)

# Add static field with same name as existing dynamic field key
client.add_collection_field(
    collection_name="product_catalog",
    field_name="extra_info",         # Same name as dynamic field key
    data_type=DataType.INT64,        # Data type can differ from dynamic field key
    nullable=True                    # Must be True for added fields
)

# Insert new data after adding static field
new_data = [{
    "id": 2,
    "my_vector": [0.3, 0.4, ...],
    "extra_info": 100,               # Now must use INT64 type (static field)
    "score": 88.0                    # Still a dynamic field key
}]
client.insert(collection_name="product_catalog", data=new_data)

期待される動作:

  • 既存のエンティティは、新しい静的フィールド extra_info に対して NULL を持つ

  • 新しいエンティティは、静的フィールドのデータ型（INT64）を使用する必要がある

  • 元の動的フィールドのキー値は保持され、$meta 構文を介してアクセス可能

  • 静的フィールドは通常のクエリにおいて動的フィールドのキーをマスクする

静的フィールドと動的フィールドの両方の値にアクセスする方法:

# 1. Query static field only (dynamic field key is masked)
results = client.query(
    collection_name="product_catalog",
    filter="id == 1",
    output_fields=["extra_info"]
)
# Returns: {"id": 1, "extra_info": None}  # NULL for existing entity

# 2. Query both static and original dynamic values
results = client.query(
    collection_name="product_catalog", 
    filter="id == 1",
    output_fields=["extra_info", "$meta['extra_info']"]
)
# Returns: {
#     "id": 1,
#     "extra_info": None,                           # Static field value (NULL)
#     "$meta['extra_info']": "this is a dynamic field key"  # Original dynamic value
# }

# 3. Query new entity with static field value
results = client.query(
    collection_name="product_catalog",
    filter="id == 2", 
    output_fields=["extra_info"]
)
# Returns: {"id": 2, "extra_info": 100}  # Static field value

新しいフィールドが利用可能になるまでどのくらい時間がかかりますか？​

追加されたフィールドはほぼ即座に利用可能になりますが、Milvusクラスター全体で内部スキーマ変更をブロードキャストする際に、ごく短い遅延が発生する可能性があります。この同期処理により、すべてのノードが新しいフィールドを含むスキーマ更新を認識し、そのフィールドを含むクエリを処理できるようになります。