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

Nullable & Default

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

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

制限事項​

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

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

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

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

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

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

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

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)

デフォルト値を持つデータの挿入​

フィールドにデフォルト値が設定されている場合、そのフィールドをデータに含めないことで、システムが自動的にデフォルト値を適用します。

data = [
    {"id": 1, "vector": [0.1, 0.2, 0.3, 0.4, 0.5], "age": 25}, # ageは25になる（デフォルト値18は上書き）
    {"id": 2, "vector": [0.2, 0.3, 0.4, 0.5, 0.6]},           # ageは18になる（デフォルト値）
    {"id": 3, "vector": [0.3, 0.4, 0.5, 0.6, 0.7], "status": "inactive"} # statusは"inactive"になる
]

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

デフォルト値のクエリ​

デフォルト値が設定されているフィールドをクエリすると、対応するデフォルト値が返されます。

results = client.query(
    collection_name="my_collection",
    filter="id in [1, 2, 3]",
    output_fields=["id", "age", "status"]
)

print(results)

# 出力例：
# [
#     {"id": 1, "age": 25, "status": "active"},  # ageは25（明示的に指定）、statusはデフォルト値
#     {"id": 2, "age": 18, "status": "active"},  # ageはデフォルト値、statusはデフォルト値
#     {"id": 3, "age": 18, "status": "inactive"} # ageはデフォルト値、statusは明示的に指定
# ]

Nullableとデフォルト値の組み合わせ​

nullable=Trueを設定したフィールドにデフォルト値を設定することはできません。これらの属性は互いに排他的です。フィールドにはnull値を許可するか、デフォルト値を設定するかのどちらか一方のみを指定できます。

注意事項​

  1. null値とデフォルト値の優先順位：

    • null値を明示的に指定した場合、デフォルト値は無視されます。
    • フィールドがnullableでない場合、null値を挿入しようとするとエラーが発生します。

  2. スカラーインデックスとnull値：

    • nullableフィールドにインデックスを作成すると、null値はインデックスから除外されます。
    • これはフィルタリングおよびクエリ結果に影響を与える可能性があります。

  3. データクエリにおけるnull値の扱い：

    • null値を持つフィールドは、フィルタリング式で>=や==などの比較演算子で一致しません。
    • IS NULLまたはIS NOT NULL演算子を使用してnull値を明示的に照会する必要があります。

  4. データ型の互換性：

    • デフォルト値は、フィールドのデータ型と互換性がある必要があります。
    • 例えば、整数型のフィールドに文字列型のデフォルト値を設定すると、エラーになります。

これらのコンセプトを理解し、正しく適用することで、Zilliz Cloudコレクションのデータスキーマを効果的に設計および管理できます。