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

Null 許容フィールド

Zilliz Cloud は Null 許容フィールドをサポートしており、フィールド値を省略したり、明示的に NULL に設定したりできます。Null 許容性はスキーマレベルで定義され、データ取り込み、インデックス作成、検索、クエリの各操作に一貫して適用されます。

Null 許容フィールドは、次の場合に使用します。

  • 値の欠落を許容する外部システムからデータを取り込みます。
  • 一部のメタデータが任意であるか、データセットの一部にのみ存在します。
  • ベクトル埋め込みを非同期で生成し、後から挿入します。

制限事項​

  • NULL 値を許可するベクトルフィールドでは、IS NULL または IS NOT NULL のフィルター式はサポートされません。ベクトルフィールドの値が NULL かどうかによってエンティティを明示的にフィルターすることはできません。

  • Zilliz Cloud では、NULL 許容の StructArray フィールドは Dedicated クラスターおよび On-Demand クラスターでサポートされています。nullable=True は個々のサブフィールドではなく、親の StructArray フィールドに設定します。NULL は個々の Struct 要素ではなく、StructArray フィールド全体に適用され、親の設定は内部的にサブフィールドへ伝播されます。既存のコレクションに追加する StructArray フィールドは NULL 許容である必要があり、これにより既存のエンティティは新しいフィールドに対して NULL を返すことができます。要素レベルの null 値は、Milvus v3.0.x と互換性のある Dedicated クラスターでサポートされていますが、On-Demand クラスターではまだ利用できません。詳細は、StructArray Limits を参照してください。

  • nullable 属性はフィールドの作成時に定義され、後から変更できません。既存のフィールドに対して Null 許容を有効化または無効化することはできません。

  • Null 許容としてマークされたフィールドは、パーティションキーとして使用できません。パーティションキーフィールドには、常に有効な非 NULL 値を含める必要があります。詳細は、パーティションキーの使用 を参照してください。

Null 許容フィールドとは​

Zilliz Cloud では、フィールドが NULL 値を格納できるかどうかは、nullable という名前のスキーマレベルのフィールド属性によって制御されます。

フィールドが nullable=True で定義されている場合、Zilliz Cloud はデータ取り込み時にそのフィールド値を欠落させることができます。実際には、Zilliz Cloud は次の 2 つの入力を同等として扱い、フィールド値を NULL として格納します。

  • 入力エンティティでフィールドが省略されている場合。
  • フィールドが明示的に NULL に設定されている場合(たとえば、Python の None)。

フィールドが Null 許容として定義されていない場合(デフォルトの動作)、すべてのエンティティはそのフィールドに対して有効な値を指定する必要があります。フィールドを省略したり、明示的に NULL 値を割り当てたりすると、挿入またはインポート操作が失敗します。

nullable 属性は、コレクションスキーマ内のスカラーフィールドとベクトルフィールドの両方でサポートされています。Dedicated クラスターおよび On-Demand クラスターでは、親の StructArray フィールドでもサポートされています。Struct のサブフィールドを個別に NULL 許容として構成しないでください。StructArray の親で NULL 許容性を定義すると、その設定は内部的にサブフィールドへ伝播されます。要素レベルの null 値は、Milvus v3.0.x と互換性のある Dedicated クラスターでサポートされていますが、On-Demand クラスターではまだ利用できません。

📘Notes

Null 許容はフィールド値を欠落させることができるかどうかを決定しますが、フィールドが欠落している場合に使用する値を定義するものではありません。

  • Null 許容フィールドにデフォルト値が構成されていない場合、フィールドを省略すると NULL 値が格納されます。
  • デフォルト値が構成されている場合、Zilliz Cloud は代わりにデフォルト値を格納することがあります。詳細は、Default Values を参照してください。

コレクションスキーマで Null 許容フィールドを定義する​

To use nullable fields, you must enable the nullable attribute when defining the コレクション スキーマ.

この例では、コレクションスキーマで nullable=True を指定した embedding という名前のベクトルフィールドを定義しています。これにより、コレクション内のエンティティは、データ取り込み時にベクトル値を省略したり、明示的に NULL に設定したりできます。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(
uri="YOUR_CLUSTER_ENDPOINT",
token="YOUR_CLUSTER_TOKEN"
)

# Define schema fields
schema = client.create_schema()
schema.add_field("id", DataType.INT64, is_primary=True) # Primary field
schema.add_field(
field_name="embedding",
datatype=DataType.FLOAT_VECTOR,
dim=4,
nullable=True, # Enable the nullable attribute; defaults to False
)

client.create_collection(
collection_name="my_collection",
schema=schema,
)

このスキーマでは、次のようになります。

  • embedding フィールドは明示的に Null 許容としてマークされます。
  • エンティティは、挿入時に embedding フィールドを省略するか、NULL 値を割り当てることができます。
  • NULL 値を許可するかどうかの決定は、コレクションの作成時に固定されます。

わかりやすくするため、以降の例では Null 許容ベクトルフィールド(embedding)に焦点を当てます。Null 許容スカラーフィールドの定義はオプションであり、このガイドの残りの手順に従うために必須ではありません。

任意:Null 許容スカラーフィールドを定義する

スカラーフィールドも、同じ nullable 属性を使用して Null 許容として定義でき、取り込み時には同じルールに従います。例:

python
schema.add_field(
field_name="age",
datatype=DataType.INT64,
nullable=True,
)

欠落値または NULL 値がある場合の挿入動作​

コレクションスキーマでフィールドが Null 許容として定義されると、Zilliz Cloud はデータ取り込み時にそのフィールド値を欠落させたり、明示的に NULL に設定したりできます。

次の例では、コレクションスキーマでの Null 許容フィールドの定義で作成したコレクションに 3 つのエンティティを挿入し、これらの異なるケースを示します。

python
data = [
{
"id": 1,
"embedding": [0.1, 0.2, 0.3, 0.4],
},
{
"id": 2,
"embedding": None, # Explicitly set to NULL
},
{
"id": 3, # Field omitted → stored as NULL
},
]

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

この例では、次のようになります。

  • エンティティ id = 1 は有効なベクトル値を指定します。
  • エンティティ id = 2 は、embedding フィールドに明示的に NULL 値を割り当てます。
  • エンティティ id = 3 は embedding フィールドを完全に省略し、Zilliz Cloud はそれを NULL として格納します。

Null 許容フィールドのインデックス動作​

データを挿入した後、通常どおり Null 許容フィールドにインデックスを構築できます。主な違いは、インデックス構築時に Zilliz Cloud が NULL 値を処理する方法です。

  • 非 NULL 値を持つエンティティのみがインデックスに追加されます。
  • NULL 値を持つエンティティはスキップされ、インデックス構築には参加しません。

Null 許容ベクトルフィールドの場合、これは有効なベクトルを持つエンティティのみがベクトル類似性検索の対象になることを意味します。

python
# Set index parameters
index_params = client.prepare_index_params()
index_params.add_index(
field_name="embedding",
index_type="AUTOINDEX",
metric_type="COSINE",
)

# Create index
client.create_index(
collection_name="my_collection",
index_params=index_params,
)

# Load collection for future search operations
client.load_collection(collection_name="my_collection")

この時点では、次のようになります。

  • 有効な埋め込み値を持つエンティティはインデックス化され、検索の準備が整います。
  • embedding が NULL のエンティティはコレクションに残りますが、ベクトルインデックスには含まれません。

Null 許容フィールドの検索動作​

Null 許容フィールドで検索操作を実行すると、Zilliz Cloud は検索に使用されるフィールドに非 NULL 値を持つエンティティのみを評価します。ベクトルフィールドが NULL のエンティティは自動的にスキップされます。

この例の embedding のような Null 許容ベクトルフィールドでは、次のようになります。

  • 有効なベクトル値を持つエンティティのみが評価され、ランク付けされます。
  • NULL ベクトルを持つエンティティによってエラーが発生することはありません。
  • 有効なベクトルの数が要求された topK(limit)より少ない場合、Zilliz Cloud は limit より少ない結果を返すことがあります。

次の例では、Null 許容ベクトルフィールド embedding に対してベクトル検索を実行します。

python
res = client.search(
collection_name="my_collection",
data=[[0.1, 0.2, 0.3, 0.4]],
anns_field="embedding",
limit=3,
search_params={"metric_type": "COSINE"},
output_fields=["embedding"],
)

print(res)

この検索では、次のようになります。

  • 非 NULL の embedding 値を持つエンティティのみが候補として考慮されます。
  • embedding に NULL 値を持つエンティティは評価から除外されます。
  • 返される結果の数は、コレクション内に存在する有効なベクトルの数によって異なります。

クエリとフィルタリングへの影響​

これまでの例では、ベクトルフィールドに焦点を当てました。このセクションでは、スカラーフィルター式で NULL 値がどのように動作するかについて説明します。

スカラーフィールドは nullable=True で定義でき、ベクトルフィールドと同じ取り込みルールに従います。ただし、NULL のスカラー値は、フィルター式では常に false と評価されます。スカラーフィールドが NULL かどうかによってエンティティを選択するには、IS NULL または IS NOT NULL を使用します。

たとえば、Null 許容のスカラーフィールド age がある場合、次のフィルターは age が 18 より大きいエンティティを選択します。

python
expr = "age > 18"

age が NULL のエンティティは、NULL 値がフィルター条件を満たさないため、結果から除外されます。

同様に、等価チェックは NULL 値に一致しません。例:

python
expr = 'status == "active"'

status が NULL のエンティティは、結果から除外されます。

Null 許容フィールドとデフォルト値​

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

Null 許容の有効化デフォルト値ユーザー入力(NULL または省略)結果
はいはい(非 NULL)NULL または省略デフォルト値を使用します。
はいいいえNULL または省略NULL として格納します。
いいえはい(非 NULL)NULL または省略デフォルト値を使用します。
いいえいいえNULL または省略エラーをスローします。
いいえはい(NULL のデフォルト値)NULL または省略エラーをスローします。

主なポイント:

  • When a field has a non-NULL default value, that value is used regardless of whether nullable is enabled.
  • nullable=True でデフォルト値が設定されていない場合、フィールドには NULL が格納されます。
  • nullable=False でデフォルト値が設定されていない場合、挿入はエラーで失敗します。
  • Null 非許容フィールドに NULL のデフォルト値を設定することは無効であり、エラーの原因になります。

デフォルト値の完全な例と API の使用方法については、デフォルト値 を参照してください。