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

基本演算子

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:複数の条件を結合し、すべてが true である必要があります。

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

  • 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 IS NULL を指定して embedding を検索しても、両方の要件を満たすエンティティはないため、ヒットは返されません。埋め込みがないエンティティを取得するには、上記のように 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 は、フィルタ条件の一致値リストに長さの制限を設けていません。ただし、リストが過度に長いと、クエリのパフォーマンスに大きく影響する可能性があります。 フィルタ条件に長い一致値リストまたは多数の要素を含む複雑な式が含まれる場合は、クエリのパフォーマンスを向上させるために フィルターテンプレート の使用をお勧めします。