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

Nullable & Default

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

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

制限事項​

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

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

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

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

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

  • nullable属性が有効になっているスカラーフィールドにインデックスを作成する場合、null値はインデックスから除外されます。

  • JSONおよびARRAYフィールド: JSONまたはARRAYフィールドに対してIS NULLまたはIS NOT NULL演算子を使用してフィルタリングする場合、これらの演算子はカラムレベルで動作し、つまりJSONオブジェクト全体または配列がnullかどうかのみ評価することを意味します。たとえば、JSONオブジェクト内のキーがnullであれば、IS NULLフィルタでは認識されません。詳細については、基本演算子を参照してください。

Nullable属性​

nullable属性により、null値をコレクションに保存でき、不明なデータを処理する際の柔軟性を提供します。

Nullable属性の設定​

コレクション作成時に、nullable=Trueを使用してnullableフィールドを定義します（デフォルトはFalse）。「my_collection」という名前のコレクションを作成し、ageフィールドをnullableに設定する例を以下に示します。

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri='YOUR_CLUSTER_ENDPOINT')

# コレクションスキーマを定義
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フィールド

# インデックスパラメータを設定
index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_type="AUTOINDEX", metric_type="L2")

# コレクションを作成
client.create_collection(collection_name="my_collection", schema=schema, index_params=index_params)

エンティティの挿入​

nullableフィールドにデータを挿入する際には、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="my_collection", data=data)

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

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

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

print(res)

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

queryメソッドを使用してスカラーフィルタリングを行う場合、null値のフィルタリング結果はすべてfalseになり、つまり選択されません。

# 以前に挿入されたデータの確認:
# {"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}  # 省略されたageカラムはNoneとして扱われる

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

# 例の出力:
# [
#     {"id": 1, "age": 30}
# ]
# 注：`age`が`null`であるエンティティ（id 2および3）は結果に表示されません。

null値を持つエンティティを返すには、以下のようにスカラーのフィルタリング条件なしでクエリを実行します。

📘注釈

フィルタリング条件なしでqueryメソッドを使用すると、null値を持つものを含むコレクション内のすべてのエンティティを取得します。返されるエンティティの数を制限するには、limitパラメータを指定する必要があります。

null_results = client.query(
    collection_name="my_collection",
    filter="",     # フィルタリング条件なしでクエリを実行
    output_fields=["id", "age"],
    limit=10
)

# 例の出力:
# [{"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="AUTOINDEX", metric_type="L2")

client.create_collection(collection_name="my_collection", 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`と`status`はデフォルト値を使用
    {"id": 3, "vector": [0.3, 0.4, ..., 0.130], "age": 25, "status": None},  # `status`はデフォルト値を使用
    {"id": 4, "vector": [0.4, 0.5, ..., 0.131], "age": None, "status": "inactive"}  # `age`はデフォルト値を使用
]

client.insert(collection_name="my_collection", data=data)
📘注釈

nullableとデフォルト値の設定がどのように効果を発揮するかの詳細については、適用ルールを参照してください。

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

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

たとえば、search操作では、ageが18のデフォルト値に設定されているエンティティは結果に含まれます。

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",  # 18は`age`フィールドのデフォルト値
    limit=10,
    output_fields=["id", "age", "status"]
)

print(res)

# 出力
# data: ["[{'id': 2, 'distance': 0.050000004, 'entity': {'id': 2, 'age': 18, 'status': 'active'}}, {'id': 4, 'distance': 0.45000002, 'entity': {'id': 4, 'age': 18, 'status': 'inactive'}}]"]

query操作では、デフォルト値を直接照合またはフィルタリングできます。

# `age`がデフォルト値(18)と等しいすべてのエンティティをクエリ
default_age_results = client.query(
    collection_name="my_collection",
    filter="age == 18",
    output_fields=["id", "age", "status"]
)

# `status`がデフォルト値("active")と等しいすべてのエンティティをクエリ
default_status_results = client.query(
    collection_name="my_collection",
    filter='status == "active"',
    output_fields=["id", "age", "status"]
)

適用ルール​

以下の表は、nullable列とデフォルト値が異なる設定の組み合わせで動作する際の概要をまとめています。これらのルールは、null値を挿入しようとしたときやフィールド値が提供されない場合に、Zilliz Cloudがデータをどのように処理するかを決定します。

Nullable

デフォルト値

デフォルト値の型

ユーザー入力

結果

例

✅

✅

Non-null

None/null

デフォルト値を使用

フィールド: age

デフォルト値: 18

ユーザー入力: null

結果: 18として格納

✅

❌

-

None/null

nullとして格納

フィールド: middle_name

デフォルト値: -

ユーザー入力: null

結果: nullとして格納

❌

✅

Non-null

None/null

デフォルト値を使用

フィールド: status

デフォルト値: "active"

ユーザー入力: null

結果: "active"として格納

❌

❌

-

None/null

エラーをスロー

フィールド: email

デフォルト値: -

ユーザー入力: null

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

❌

✅

Null

None/null

エラーをスロー

フィールド: username

デフォルト値: null

ユーザー入力: null

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