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

Nullable フィールド

Zilliz Cloud は nullable フィールドをサポートしており、フィールド値を欠損させるか、明示的に NULL に設定できます。nullability はスキーマレベルで定義され、データの取り込み、インデックス作成、検索、クエリ操作に一貫して適用されます。

nullable フィールドは次の場合に使用します。

  • 欠損値を許可する外部システムからデータを取り込む場合

  • 一部のメタデータが任意であるか、データセットの一部でのみ利用可能な場合

  • ベクトル埋め込みが非同期に生成され、後から挿入される場合

制限​

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

  • Zilliz Cloud では、nullable な StructArray フィールドは、3.0.x 系の Milvus 3.0.0 以降を実行するオンデマンドクラスターでサポートされています。Serving クラスターは nullable な StructArray フィールドをサポートしていません。nullable=True は個々のサブフィールドではなく、親の StructArray フィールドに設定してください。NULL は個々の Struct 要素ではなく、StructArray フィールド全体に適用され、親の設定は内部的にサブフィールドへ伝播されます。既存のコレクションに追加する StructArray フィールドは、既存のエンティティが新しいフィールドに対して NULL を返せるように nullable である必要があります。詳細については、StructArray の制限 を参照してください。

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

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

nullable フィールドとは​

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

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

  • 入力エンティティからフィールドが省略されている

  • フィールドが明示的に NULL に設定されている（たとえば、Python の None）

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

nullable 属性は、コレクションスキーマ内の スカラーフィールドとベクトルフィールド の両方でサポートされています。サポート対象のオンデマンドクラスターでは、親の StructArray フィールドでもサポートされます。Struct サブフィールドを個別に nullable として設定しないでください。nullability は StructArray の親で定義し、その設定は内部的にサブフィールドへ伝播されます。

Notes

nullability はフィールド値が欠損していてもよいかどうかを決定するものであり、フィールドが欠損しているときにどの値が使用されるかを定義するものではありません。

  • nullable フィールドがデフォルト値なしで設定されている場合、フィールドを省略すると NULL 値として保存されます。

  • デフォルト値が設定されている場合、Zilliz Cloud は代わりにデフォルト値を保存することがあります。詳細については、デフォルト値 を参照してください。

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

nullable フィールドを使用するには、コレクションスキーマを定義するときに nullable 属性を有効にする必要があります。

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

  • エンティティは、挿入時に embedding フィールドを省略したり、NULL 値を割り当てたりできます。

  • NULL 値を許可するかどうかは、コレクションの作成時に固定されます。

以降の例では、わかりやすくするために nullable なベクトルフィールド（embedding）に焦点を当てます。nullable なスカラーフィールドの定義は任意であり、このガイドの残りの内容に従ううえで必須ではありません。

オプション: nullable なスカラーフィールドを定義する

スカラーフィールドも、同じ nullable 属性を使用して nullable として定義でき、取り込み時には同じルールに従います。たとえば、次のとおりです。

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

値が欠損している場合または NULL の場合の挿入動作​

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

次の例では、ステップ 1 で作成したコレクションに 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 として保存します。

nullable フィールドに対するインデックスの動作​

データを挿入した後は、通常どおり nullable フィールドにインデックスを作成できます。主な違いは、インデックスの構築時に Zilliz Cloud が NULL 値をどのように処理するかです。

  • インデックスに追加されるのは、非 NULL 値を持つエンティティのみです。

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

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

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 値を持つエンティティはインデックスに登録され、検索可能な状態になります。

  • embedding が NULL のエンティティはコレクションに残りますが、ベクトルインデックスには含まれません。

nullable フィールドに対する検索の動作​

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

この例の embedding のような nullable なベクトルフィールドの場合、次のとおりです。

  • 有効なベクトル値を持つエンティティのみが評価され、ランク付けされます。

  • NULL のベクトルを持つエンティティがエラーを引き起こすことはありません。

  • 有効なベクトルの数が要求された topK（limit）より少ない場合、Zilliz Cloud は limit より少ない結果を返すことがあります。

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

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

print(res)

この検索では、次のとおりです。

  • 非 NULL の embedding 値を持つエンティティのみが候補として考慮されます。

  • embedding に NULL 値を持つエンティティは評価から除外されます。

  • 返される結果の数は、コレクション内に存在する有効なベクトルの数によって決まります。

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

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

スカラーフィールドは nullable=True で定義でき、ベクトルフィールドと同じ取り込みルールに従います。ただし、NULL のスカラー値はフィルター式では常に false と評価されます。

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

python
expr = "age > 18"

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

同様に、等価比較は NULL 値には一致しません。たとえば、次のとおりです。

python
expr = "status == \"active\""

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

適用されるルール​

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

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

重要なポイント:

  • フィールドに非 NULL のデフォルト値がある場合、nullable が有効かどうかにかかわらず、その値が使用されます。

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

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

  • non-nullable なフィールドに NULL のデフォルト値を設定することは無効であり、エラーの原因になります。

Ctrl I