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

基本演算子

Zilliz Cloud は、エンティティをフィルタリングするための比較演算子、範囲演算子、算術演算子、論理演算子、NULL 演算子を提供します。各演算子は特定のフィールド型をサポートしています。

Notes

フィルタ式の左辺のリテラルには、以下の例で使用している status、color などのコレクションフィールド名、または filter = 'struct[0][subfield] > 10' のように特定の要素インデックスにある StructArray サブフィールドの名前を指定できます。

StructArray フィールドでのスカラーフィルタリングの詳細については、StructArray 演算子 を参照してください。

比較演算子​

比較演算子は、等しいかどうか、等しくないかどうか、または大小関係に基づいてデータをフィルタリングするために使用します。数値フィールドとテキストフィールドに適用できます。

サポートされる比較演算子​

  • ==(等しい)

  • !=(等しくない)

  • >(より大きい)

  • <(より小さい)

  • >=(以上)

  • <=(以下)

例 1: 等しい演算子(==)によるフィルタリング​

status という名前のフィールドがあり、status が "active" であるすべてのエンティティを検索する場合について考えます。等しい演算子 == を使用できます。

python
filter = 'status == "active"'

例 2: 等しくない演算子(!=)によるフィルタリング​

status が "inactive" ではないエンティティを検索するには、次のようにします。

python
filter = 'status != "inactive"'

例 3: より大きい演算子(>)によるフィルタリング​

age が 30 より大きいすべてのエンティティを検索する場合は、次のようにします。

python
filter = 'age > 30'

例 4: より小さい演算子によるフィルタリング​

price が 100 より小さいエンティティを検索するには、次のようにします。

python
filter = 'price < 100'

例 5: 以上演算子(>=)によるフィルタリング​

rating が 4 以上のすべてのエンティティを検索する場合は、次のようにします。

python
filter = 'rating >= 4'

例 6: 以下演算子によるフィルタリング​

discount が 10% 以下のエンティティを検索するには、次のようにします。

python
filter = 'discount <= 10'

範囲演算子​

範囲演算子は、特定の値のセットに基づいてデータをフィルタリングするのに役立ちます。Zilliz Cloud は、セットのメンバーシップを確認するための IN をサポートしています。

color が "red"、"green"、または "blue" のいずれかであるすべてのエンティティを検索する場合は、次のようにします。

python
filter = 'color in ["red", "green", "blue"]'

これは、値のリストに含まれているかどうかを確認する場合に便利です。

パターン一致演算子​

パターン一致演算子は、ワイルドカードパターンまたは正規表現に基づいて文字列値をフィルタリングするのに役立ちます。

  • LIKE: 文字列値に対して単純なワイルドカードパターンを一致させるために使用します。たとえば、name LIKE "Prod%" は Prod で始まる値に一致します。

  • =~: RE2 正規表現を使用して文字列値を一致させるために使用します。たとえば、code =~ "E[0-9]{4}" は E1001 などのエラーコードを含む値に一致します。

  • !~: RE2 正規表現に一致する文字列値を除外するために使用します。これは NOT (field =~ "pattern") と同等です。

name が Prod で始まるエンティティを検索するには、次のようにします。

python
filter = 'name LIKE "Prod%"'

code に E1001 などのエラーコードが含まれるエンティティを検索するには、次のようにします。

python
filter = 'code =~ "E[0-9]{4}"'

message が DEBUG で始まるエンティティを除外するには、次のようにします。

python
filter = 'message !~ "^DEBUG"'

LIKE と正規表現の選択、サポートされるフィールド型、正規表現の構文、エスケープルール、パフォーマンスの詳細については、パターン一致 を参照してください。Zilliz Cloud では、対象となるパターン一致フィルタを高速化するために、VARCHAR フィールドまたは JSON 文字列パスに NGRAM インデックスを構築することもできます。詳細については、NGRAM を参照してください。

算術演算子​

算術演算子を使用すると、数値フィールドを含む計算に基づいて条件を作成できます。

サポートされる算術演算子​

  • +(加算)

  • -(減算)

  • *(乗算)

  • /(除算)

  • %(剰余)

  • **(べき乗)

例 1: 剰余演算子(%)の使用​

id が偶数(つまり 2 で割り切れる)であるエンティティを検索するには、次のようにします。

python
filter = 'id % 2 == 0'

例 2: べき乗演算子(**)の使用​

price を 2 乗した値が 1000 より大きいエンティティを検索するには、次のようにします。

python
filter = 'price > 1000'

ビット演算子 | PUBLIC​

ビット演算子は、整数フィールドが権限、機能フラグ、ステータスビットなどの複数のフラグをエンコードしている場合に便利です。これらの演算子をフィルタ式で使用すると、整数値内の個々のビットを確認、結合、または比較できます。

スカラーフィールドでは、ビット演算子は INT8、INT16、INT32、INT64 などの整数フィールド型に適用されます。

サポートされるビット演算子​

演算子名前一般的な用途
&ビット単位 AND特定のビットが設定されているかどうかを確認します。
|ビット単位 OR比較する前にビットを結合します。
^ビット単位 XOR2 つの値間のビットの差異を比較します。

例: 権限ビットによるフィルタリング​

permissions という名前の整数フィールドがあり、整数内の各ビットが権限フラグを表している場合について考えます。

権限フラグビット値
READ1
WRITE2
SHARE4
ADMIN8

たとえば、permissions = 5 は READ ビットと SHARE ビットが設定されていることを意味します。これは 5 = 1 + 4 であるためです。

SHARE ビットが設定されているエンティティを検索するには、ビット単位 AND(&)を使用します。

python
filter = "(permissions & 4) == 4"

WRITE ビットを設定すると READ + WRITE + SHARE の権限セットになるエンティティを検索するには、ビット単位 OR(|)を使用します。

python
filter = "(permissions | 2) == 7"

権限ビットが READ + WRITE + SHARE と WRITE ビットだけ異なるエンティティを検索するには、ビット単位 XOR(^)を使用します。

python
filter = "(permissions ^ 7) == 2"

注記: 結果を比較する前に、(permissions & 4) == 4 のようにビット演算を常にかっこで囲んでください。

論理演算子​

論理演算子は、複数の条件をより複雑なフィルタ式に結合するために使用します。AND、OR、NOT があります。

サポートされる論理演算子​

  • AND: すべてが真である必要がある複数の条件を結合します。

  • OR: 少なくとも 1 つが真である必要がある条件を結合します。

  • NOT: 条件を否定します。

例 1: AND を使用した条件の結合​

price が 100 より大きく、stock が 50 より大きいすべての商品を検索するには、次のようにします。

python
filter = 'price > 100 AND stock > 50'

例 2: OR を使用した条件の結合​

color が "red" または "blue" のいずれかであるすべての商品を検索するには、次のようにします。

python
filter = 'color == "red" OR color == "blue"'

例 3: NOT を使用した条件の除外​

color が "green" ではないすべての商品を検索するには、次のようにします。

python
filter = 'NOT (color == "green")'

IS NULL 演算子と IS NOT NULL 演算子​

IS NULL と IS NOT NULL を使用して、フィールド値が存在しないエンティティまたは存在するエンティティを検索できます。たとえば、カテゴリのない商品や、検索可能な埋め込みを持つエンティティを検索できます。どちらの演算子も、サポートされるスカラーフィールドとベクトルフィールドに対して同じ意味で機能します。

演算子一致するもの
<field> IS NULL指定したフィールドに NULL 値があるエンティティ
<field> IS NOT NULL指定したフィールドに NULL 以外の値があるエンティティ

サポートされるスカラーフィールドには、Boolean、数値、VARCHAR、JSON、ARRAY の各フィールドが含まれます。これらの演算子は TEXT フィールド をサポートしていません。

Milvus 3.0.3 以降、これらの演算子は通常のベクトルフィールド(FLOAT_VECTOR、BINARY_VECTOR、FLOAT16_VECTOR、BFLOAT16_VECTOR、SPARSE_FLOAT_VECTOR、INT8_VECTOR)もサポートしています。

これらの演算子では大文字と小文字が区別されません。IS NULL と is null、および IS NOT NULL と is not null はそれぞれ同等です。

例: 値が存在しないエンティティまたは存在するエンティティの検索​

products という名前のコレクションがインデックス化され、ロードされている場合について考えます。このコレクションには、id という名前の INT64 主キー、category という名前の NULL 許容 VARCHAR フィールド、および embedding という名前の NULL 許容 3 次元 FLOAT_VECTOR フィールドがあります。すでに次のエンティティが含まれています。

idcategoryembedding
1"book"[0.1, 0.2, 0.3]
2NULL[0.4, 0.5, 0.6]
3"book"NULL

コレクションの作成とデータの挿入は省略します。これらの手順については、NULL 許容フィールド を参照してください。

まだ埋め込みが必要なエンティティを検索するには、embedding IS NULL でクエリを実行します。使用するサーバーに合わせて接続設定を調整してください。

python
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

results = client.query(
collection_name="products",
filter="category IS NULL",
output_fields=["id"],
limit=10,
)
print(sorted(entity["id"] for entity in results))
# Expected: [2]

同じクエリ内の filter を置き換えると、いずれかのフィールドを確認したり、条件を組み合わせたりできます。

フィルタ式一致する ID目的
category IS NULL2カテゴリのないエンティティを検索します。
category IS NOT NULL1, 3カテゴリのあるエンティティを検索します。
embedding IS NULL3埋め込みのないエンティティを検索します。
embedding IS NOT NULL1, 2埋め込みのあるエンティティを検索します。
category IS NOT NULL AND embedding IS NOT NULL1両方の値があるエンティティを検索します。

フィールド値の扱い​

これらの演算子は、保存されているフィールド値を確認します。デフォルト値のない NULL 許容フィールドでは、挿入時にフィールドを省略するか、明示的に NULL を設定すると、NULL が保存されます。デフォルト値が設定されている場合は、保存される内容が変わる可能性があります。詳細については、NULL 許容フィールド および デフォルト値 を参照してください。

フィールド型NULL の動作
VARCHAR空文字列 "" は NULL 以外の値です。
JSONフィールド全体の NULL 値は IS NULL に一致します。{"category": null} のような JSON オブジェクトは、内部の値が NULL でも NULL 以外の値です。
ARRAYフィールド全体の NULL 値は IS NULL に一致します。個々の要素は NULL にできません。また、IS NULL / IS NOT NULL は tags[0] のような配列要素へのアクセスをサポートしていません。配列フィールド を参照してください。
通常のベクトル型NULL はベクトル値が存在しないことを意味します。成分がゼロのベクトルは NULL ではありません。

nullable=False で定義されたサポート対象のフィールドでは、IS NULL はどのエンティティにも一致せず、IS NOT NULL は表示可能なすべてのエンティティに一致します。フィルタ内のその他の条件は引き続き適用されます。

同じ演算子を検索フィルタでも使用できますが、類似検索に参加するには、検索対象フィールドにベクトルを持つエンティティである必要があります。

上記の例のデータを使用して、anns_field="embedding" を指定した検索について考えます。

フィルタ式類似検索の対象となるエンティティ理由
category IS NULL2エンティティ 2 にはカテゴリはありませんが、embedding ベクトルがあります。
embedding IS NULLなしエンティティ 3 はフィルタに一致しますが、クエリベクトルと比較する embedding ベクトルがありません。
embedding IS NOT NULL1, 2どちらのエンティティにも embedding ベクトルがあります。

3 つのフィルタはすべて有効です。embedding に対して embedding IS NULL を指定して検索しても、両方の要件を満たすエンティティがないため、ヒットは返されません。埋め込みがないエンティティを取得するには、上記のように query() を使用します。

ベクトル検索では、検索対象のベクトルフィールドが NULL のエンティティはすでにスキップされるため、embedding IS NOT NULL を指定しても embedding に対する検索の候補はさらに絞り込まれません。ランキング、その他のフィルタ、および検索件数の上限によって、返される候補が決まります。

JSON フィールドと ARRAY フィールドで基本演算子を使用する際のヒント​

Zilliz Cloud クラスターの基本演算子は汎用性が高く、スカラーフィールドに適用できますが、JSON フィールドおよび ARRAY フィールドのキーやインデックスにも効果的に使用できます。

たとえば、price、model、tags などの複数のキーを含む product フィールドがある場合は、常にキーを直接参照してください。

python
filter = 'product["price"] > 1000'

記録された気温の配列の最初の気温が特定の値を超えるレコードを検索するには、次のようにします。

python
filter = 'history_temperatures[0] > 30'

まとめ​

Zilliz Cloud は、データのフィルタリングとクエリを柔軟に行えるさまざまな基本演算子を提供しています。比較演算子、範囲演算子、算術演算子、論理演算子を組み合わせることで、強力なフィルタ式を作成し、検索結果を絞り込んで、必要なデータを効率的に取得できます。

FAQ​

フィルタ条件の一致値リストの長さに制限はありますか(例: filter='color in ["red", "green", "blue"]')?リストが長すぎる場合はどうすればよいですか?

Zilliz Cloud は、フィルタ条件の一致値リストに長さの制限を設けていません。ただし、リストが極端に長いと、クエリのパフォーマンスに大きな影響を与える可能性があります。 フィルタ条件に長い一致値リストや多数の要素を含む複雑な式が含まれる場合は、フィルタテンプレート を使用してクエリのパフォーマンスを向上させることをお勧めします。