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

基本演算子

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 ** 2 > 1000'

ビット演算子​

ビット演算子は、整数フィールドがパーミッション、機能フラグ、ステータスビットなどの複数のフラグをエンコードしている場合に役立ちます。これらの演算子をフィルタ式で使用すると、整数値の個々のビットをチェック、結合、または比較できます。

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

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

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

例:パーミッションビットによるフィルタリング​

permissions という名前の整数フィールドがあり、整数の各ビットがパーミッションフラグを表しているとします:

パーミッションフラグビット値
READ1
WRITE2
SHARE4
ADMIN8

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

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] のような配列要素へのアクセスをサポートしていません。Array フィールド を参照してください。
通常のベクトル型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 は、フィルタ条件内のマッチ値リストの長さに制限を設けていません。ただし、リストが過度に長いと、クエリのパフォーマンスに大きく影響する可能性があります。 フィルタ条件に長いマッチ値リストや、要素の多い複雑な式が含まれる場合は、クエリのパフォーマンスを向上させるために フィルタテンプレート の使用をお勧めします。