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

Nullableデフォルト

Zilliz Cloudを使用すると、プライマリフィールドを除くスカラーフィールドのnullable属性とデフォルト値を設定できます。nullable=Trueとしてマークされたフィールドの場合、データを挿入するときにフィールドをスキップするか、直接null値に設定すると、システムはエラーを引き起こすことなくnullとして扱います。フィールドにデフォルト値がある場合、挿入中にフィールドにデータが指定されていない場合、システムは自動的にこの値を適用します。

デフォルト値とnullable属性は、null値を持つデータセットの処理を可能にし、デフォルト値の設定を保持することで、他のデータベースシステムからZilliz Cloudへのデータ移行を効率化します。コレクションを作成する際に、値が不確定なフィールドに対してnullableを有効にしたり、デフォルト値を設定することもできます。

限界​

  • プライマリフィールドを除くスカラーフィールドのみが、デフォルト値とnull許容属性をサポートしています。

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

  • デフォルト値またはnullable属性は、コレクションの作成時にのみ構成でき、その後は変更できません。

  • null属性が有効なスカラーフィールドは、グルーピング検索のgroup_by_fieldとして使用できません。グルーピング検索の詳細については、「グループ検索」を参照してください。

  • NULLとマークされたフィールドはパーティションキーとして使用できません。パーティションキーの詳細については、「パーティションキーを使う」を参照してください。

  • null属性を有効にしたスカラーフィールドにインデックスを作成すると、インデックスからnull値が除外されます。

Nullableな属性​

Nullable属性を使用すると、コレクションにnull値を格納できるため、未知のデータを柔軟に処理できます。

null許容属性を設定する​

コレクションを作成する場合は、nullable=Trueを使用してnullableフィールドを定義します（デフォルトはFalse）。次の例では、user_profiles_nullという名前のコレクションを作成し、ageフィールドをnullableに設定します。

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri='YOUR_CLUSTER_ENDPOINT')

# Define collection schema
schema = client.create_schema(
    auto_id=False,
    enable_dynamic_schema=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, nullable=True) # Nullable field

# Set index params
index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_type="IVF_FLAT", metric_type="L2", params={ "nlist": 128 })

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

エンティティを挿入​

null許容フィールドにデータを挿入する場合は、nullを挿入するか、このフィールドを直接省略してください

data = [
    {"id": 1, "vector": [0.1, 0.2, 0.3, 0.4, 0.5], "age": 30},
    {"id": 2, "vector": [0.2, 0.3, 0.4, 0.5, 0.6], "age": None},
    {"id": 3, "vector": [0.3, 0.4, 0.5, 0.6, 0.7]}
]

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

NULL値を使用した検索とクエリ​

このsearchメソッドを使用した場合、フィールドにnull値が含まれている場合、検索結果はそのフィールドをnullとして返します。

res = client.search(
    collection_name="user_profiles_null",
    data=[[0.1, 0.2, 0.4, 0.3, 0.128]],
    limit=2,
    search_params={"params": {"nprobe": 16}},
    output_fields=["id", "age"]
)

print(res)

# Output
# data: ["[{'id': 1, 'distance': 0.15838398039340973, 'entity': {'age': 30, 'id': 1}}, {'id': 2, 'distance': 0.28278401494026184, 'entity': {'age': None, 'id': 2}}]"]

スカラーフィルターにqueryメソッドを使用すると、null値のフィルター結果はすべてfalseになり、選択されないことを示します。

# Reviewing previously inserted data:
# {"id": 1, "vector": [0.1, 0.2, ..., 0.128], "age": 30}
# {"id": 2, "vector": [0.2, 0.3, ..., 0.129], "age": None}
# {"id": 3, "vector": [0.3, 0.4, ..., 0.130], "age": None}  # Omitted age  column is treated as None

results = client.query(
    collection_name="user_profiles_null",
    filter="age >= 0",
    output_fields=["id", "age"]
)

# Example output:
# [
#     {"id": 1, "age": 30}
# ]
# Note: Entities with `age` as `null` (id 2 and 3) will not appear in the result.

値がnullのエンティティをクエリするには、空の式""を使用します。

null_results = client.query(
    collection_name="user_profiles_null",
    filter="",
    output_fields=["id", "age"]
)

# Example output:
# [{"id": 2, "age": None}, {"id": 3, "age": None}]

デフォルト値​

デフォルト値は、スカラーフィールドに割り当てられたプリセット値です。挿入時にデフォルトのフィールドに値を指定しない場合、システムは自動的にデフォルト値を使用します。

デフォルト値を設定​

コレクションを作成する際には、default_valueパラメータを使用してフィールドのデフォルト値を定義します。以下の例では、ageのデフォルト値を18に設定し、statusを"active"に設定する方法を示します。

schema = client.create_schema(
    auto_id=False,
    enable_dynamic_schema=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)

index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_type="IVF_FLAT", metric_type="L2", params={ "nlist": 128 })

client.create_collection(collection_name="user_profiles_default", schema=schema, index_params=index_params)

エンティティを挿入​

データを挿入するとき、デフォルト値のフィールドを省略するか、値をnullに設定すると、システムはデフォルト値を使用します。

data = [
    {"id": 1, "vector": [0.1, 0.2, ..., 0.128], "age": 30, "status": "premium"},
    {"id": 2, "vector": [0.2, 0.3, ..., 0.129]},  # `age` and `status` use default values
    {"id": 3, "vector": [0.3, 0.4, ..., 0.130], "age": 25, "status": None},  # `status` uses default value
    {"id": 4, "vector": [0.4, 0.5, ..., 0.131], "age": None, "status": "inactive"}  # `age` uses default value
]

client.insert(collection_name="user_profiles_default", data=data)
📘ノート

nullableとデフォルト値の設定がどのように有効になるかについては、適用されるルールを参照してください。

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

デフォルト値を含むエンティティは、ベクトル検索やスカラーフィルターで他のエンティティと同じように扱われます。検索やクエリ操作の一部としてデフォルト値を含めることができます。

例えば、検索操作では、年齢がデフォルト値の18に設定されたエンティティが結果に含まれます。

res = client.search(
    collection_name="user_profiles_default",
    data=[[0.1, 0.2, 0.4, 0.3, 0.128]],
    search_params={"params": {"nprobe": 16}},
    filter="age == 18",  # 18 is the default value of the `age` field
    limit=10,
    output_fields=["id", "age", "status"]
)

print(res)

# Output
# data: ["[{'id': 2, 'distance': 0.28278401494026184, 'entity': {'id': 2, 'age': 18, 'status': 'active'}}, {'id': 4, 'distance': 0.8315839767456055, 'entity': {'id': 4, 'age': 18, 'status': 'inactive'}}]"]

クエリ操作では、デフォルト値を直接一致またはフィルタリングできます

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

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

適用ルール​

以下の表は、異なる構成の組み合わせにおけるnull許容列とデフォルト値の動作をまとめたものです。これらのルールは、Zilliz Cloudがnull値を挿入しようとした場合やフィールド値が提供されなかった場合にデータを処理する方法を決定します。

Nullableは無効です。

デフォルト値

デフォルト値の型

ユーザー入力

結果を表示

例

✅

✅

非null

なし/null

デフォルト値を使用する

フィールド:age デフォルト値:18

ユーザー入力: null

結果:として保存18

✅

❌

-

なし/null

nullとして保存

フィールド:middle_name デフォルト値:-

ユーザー入力: null

結果: nullとして保存

❌

✅

非null

なし/null

デフォルト値を使用する

フィールド:status デフォルト値:"active"

ユーザー入力: null

結果:"active"として保存されました。

❌

❌

-

なし/null

エラーをスローする

フィールド:email デフォルト値:-

ユーザー入力: null

結果:操作が拒否され、システムがエラーをスローします

❌

✅

null

なし/null

エラーをスローする

フィールド:username デフォルト値: null

ユーザー入力: null

結果:操作が拒否され、システムがエラーをスローします