メインコンテンツまでスキップ

デフォルト値

Zilliz Cloud では、スカラーフィールド（プライマリーフィールドを除く）にデフォルト値を設定できます。フィールドにデフォルト値が設定されている場合、挿入時にデータが指定されないと、Zilliz Cloud は自動的にこの値を適用します。

デフォルト値を使用すると、既存のデフォルト値設定を保持したまま、他のデータベースシステムから Zilliz Cloud へのデータ移行を簡素化できます。また、挿入時点で値が確定していないフィールドにもデフォルト値を使用できます。

制限事項​

  • デフォルト値をサポートするのはスカラーフィールドのみです。プライマリーフィールドとベクトルフィールドにはデフォルト値を設定できません。

  • JSON フィールドと ARRAY フィールドはデフォルト値をサポートしていません。

  • デフォルト値はコレクションの作成時にのみ設定でき、作成後に変更することはできません。

デフォルト値を設定する​

コレクションを作成する際は、add_field() の default_value パラメーターを使用して、フィールドのデフォルト値を定義します。

次の例では、デフォルト値を持つ2つのスカラーフィールドを含むコレクションを作成します。age のデフォルト値は 18、status のデフォルト値は "active" です。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri='YOUR_CLUSTER_ENDPOINT')

# Drop the collection if it already exists
if client.has_collection("my_collection"):
    client.drop_collection("my_collection")

# Define collection schema
schema = client.create_schema(
    auto_id=False,
    enable_dynamic_field=True,
)

schema.add_field(field_name="id", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="vector", datatype=DataType.FLOAT_VECTOR, dim=5)
schema.add_field(field_name="age", datatype=DataType.INT64, default_value=18)
schema.add_field(field_name="status", datatype=DataType.VARCHAR, default_value="active", max_length=10)

# Set index params
index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_type="AUTOINDEX", metric_type="L2")

# Create collection
client.create_collection(collection_name="my_collection", schema=schema, index_params=index_params)

# Load the collection
client.load_collection("my_collection")

エンティティを挿入する​

データを挿入する際、デフォルト値が設定されたフィールドを省略するか、明示的に NULL に設定すると、Zilliz Cloud は自動的に設定済みのデフォルト値を使用します。

python
data = [
    # All fields provided explicitly
    {"id": 1, "vector": [0.1, 0.2, 0.3, 0.4, 0.5], "age": 30, "status": "premium"},
    # age and status omitted → both use default values (18 and "active")
    {"id": 2, "vector": [0.2, 0.3, 0.4, 0.5, 0.6]},
    # status set to None → uses default value "active"
    {"id": 3, "vector": [0.3, 0.4, 0.5, 0.6, 0.7], "age": 25, "status": None},
    # age set to None → uses default value 18
    {"id": 4, "vector": [0.4, 0.5, 0.6, 0.7, 0.8], "age": None, "status": "inactive"}
]

client.insert(collection_name="my_collection", data=data)

# Flush so the inserted rows are immediately queryable
client.flush(collection_name="my_collection")

デフォルト値を使用した検索とクエリ​

デフォルト値を含むエンティティは、ベクトル検索およびスカラーフィルタリングにおいて、他のエンティティと同じように動作します。search 操作と query 操作の両方で、デフォルト値によるフィルタリングが可能です。

次の例では、age がデフォルト値 18 と等しいエンティティを検索します。

python
res = client.search(
    collection_name="my_collection",
    data=[[0.1, 0.2, 0.4, 0.3, 0.5]],
    search_params={"params": {"nprobe": 16}},
    filter="age == 18",
    limit=10,
    output_fields=["id", "age", "status"]
)

print("Search results (age == 18):")
for hit in res[0]:
    print(f"  id: {hit['id']}, age: {hit['entity']['age']}, status: {hit['entity']['status']}")
想定される出力
plaintext
Output:
Search results (age == 18):
  id: 2, age: 18, status: active
  id: 4, age: 18, status: inactive

デフォルト値を直接照合してエンティティをクエリすることもできます。

python
# Query entities where age equals the default value (18)
default_age_results = client.query(
    collection_name="my_collection",
    filter="age == 18",
    output_fields=["id", "age", "status"]
)

print("\nQuery results (age == 18):")
for r in default_age_results:
    print(f"  id: {r['id']}, age: {r['age']}, status: {r['status']}")

# Query entities where status equals the default value ("active")
default_status_results = client.query(
    collection_name="my_collection",
    filter='status == "active"',
    output_fields=["id", "age", "status"]
)

print("\nQuery results (status == 'active'):")
for r in default_status_results:
    print(f"  id: {r['id']}, age: {r['age']}, status: {r['status']}")
想定される出力
plaintext
Query results (age == 18):
  id: 2, age: 18, status: active
  id: 4, age: 18, status: inactive

Query results (status == 'active'):
  id: 2, age: 18, status: active
  id: 3, age: 25, status: active

適用されるルール​

フィールドに nullable と default_value の両方が設定されている場合、挿入時に NULL が入力されたとき、またはフィールド値が欠落したときに Zilliz Cloud がどのように処理するかは、次のルールで決まります。

Null 許容デフォルト値ユーザー入力結果
（NULL 以外）NULL または省略デフォルト値を使用します。
NULL または省略NULL として保存されます。
（NULL 以外）NULL または省略デフォルト値を使用します。
NULL または省略エラーが発生します。
（NULL）NULL または省略エラーが発生します。

主なポイント:

  • フィールドに NULL 以外のデフォルト値が設定されている場合、nullable が有効かどうかに関係なく、その値が使用されます。

  • nullable=True でデフォルト値が設定されていない場合、フィールドには NULL が保存されます。

  • nullable=False でデフォルト値が設定されていない場合、挿入はエラーで失敗します。

  • Null 許容でないフィールドに NULL のデフォルト値を設定することは無効で、エラーが発生します。

このページは役に立ちましたか？
Ctrl I