パターンマッチング

agentic search アプリケーションでは、ベクトル検索と grep スタイルのパターンマッチングが互いを補完することがよくあります。ベクトル検索は意味的に関連するエンティティを取得し、パターンマッチングは、エラーコード、ログプレフィックス、メールドメイン、URL パス、識別子などの厳密な文字列構造によってその結果を絞り込みます。

Zilliz Cloud では、これらのパターン制約をスカラーフィルターで表現できます。単純なワイルドカードマッチングには LIKE を、RE2 正規表現には =~ または !~ を使用します。これらのフィルターは query、search、ハイブリッド検索と組み合わせて使用できます。

Note

このページでは、query、search、ハイブリッド検索で使用されるスカラーフィルター式におけるパターンマッチングについて説明します。これらの式はフィールド値を評価するものであり、analyzer が生成するトークンを変更するものではありません。テキスト解析中にトークンをフィルタリングするには、Regex Analyzer Filter を参照してください。

パターンマッチング式は filter パラメーターに記述します。たとえば、次のクエリは E1001 のようなエラーコードを含むログメッセージに一致します。

Python

python

from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

res = client.query(
    collection_name="log_events",
    filter='message =~ "E[0-9]{4}"',
    output_fields=["message", "severity"],
)

Java

java

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.vector.request.QueryReq;
import io.milvus.v2.service.vector.response.QueryResp;
import java.util.Arrays;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("YOUR_CLUSTER_ENDPOINT")
        .build());

QueryResp res = client.query(QueryReq.builder()
        .collectionName("log_events")
        .filter("message =~ \"E[0-9]{4}\"")
        .outputFields(Arrays.asList("message", "severity"))
        .build());

Go

go

import (
    "context"
    "fmt"

    "github.com/milvus-io/milvus/client/v2/milvusclient"
)

ctx := context.Background()
client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "YOUR_CLUSTER_ENDPOINT",
})
if err != nil {
    // handle error
}
defer client.Close(ctx)

res, err := client.Query(ctx, milvusclient.NewQueryOption("log_events").
    WithFilter(`message =~ "E[0-9]{4}"`).
    WithOutputFields("message", "severity"))
if err != nil {
    // handle error
}
fmt.Println(res)

NodeJS

javascript

const { MilvusClient } = require('@zilliz/milvus2-sdk-node');

async function main() {
  const client = new MilvusClient({ address: 'YOUR_CLUSTER_ENDPOINT' });

  const res = await client.query({
    collection_name: 'log_events',
    filter: 'message =~ "E[0-9]{4}"',
    output_fields: ['message', 'severity'],
  });
  console.log(res);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
  --url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/query" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "collectionName": "log_events",
    "filter": "message =~ \"E[0-9]{4}\"",
    "outputFields": ["message", "severity"]
  }'

C++

c++

// cpp

Zilliz CLI

shell

zilliz vector query --collection log_events --filter 'message =~ "E[0-9]{4}"' --output-fields 'message,severity'

このページの例では、filter に割り当てる式に焦点を当てています。同じフィルター式構文は、query、search、ハイブリッド検索など、スカラーフィルターを受け付ける Zilliz Cloud の操作で使用できます。

Notes

フィルター式の左辺のリテラルには、以下に示す例で使用されている message、email などのコレクションフィールド名、または filter = 'struct[0][subfield] =~ "E[0-9]{4}"' のように特定の要素インデックスにある StructArray サブフィールド名を指定できます。

StructArray フィールドにおけるスカラーフィルタリングの詳細については、StructArray Operators を参照してください。

サポートされるフィールド型

パターンマッチングは文字列値で利用できます。

対象	LIKE	Regex =~ / !~	注記
VARCHAR フィールド	Yes	Yes	文字列フィールドにおけるパターンマッチングの一般的な対象です。
VARCHAR キャスト型の JSON パス	Yes	Yes	一致させるには、JSON パスの値が文字列である必要があります。高速化のために JSON パスにインデックスを作成する場合は、json_cast_type="varchar" を設定してください。
ARRAY<VARCHAR> 要素	Yes	Yes	tags[0] のように、インデックスで特定の要素に一致させます。パターンマッチングはすべての要素をスキャンしません。指定したインデックスの要素にのみ適用されます。
数値、Boolean、ベクトル、TEXT、その他の非 VARCHAR の対象	No	No	パターンマッチングは、VARCHAR 値、文字列に解決される JSON パス、またはインデックスが設定された ARRAY<VARCHAR> 要素に対してのみ利用できます。

LIKE と regex の選び方

必要なパターンを表現できる最も単純な演算子を選んでください。

厳密な文字列一致が必要な場合は、パターンマッチングではなく == の使用を推奨します。フィルターでパターンに一致させる必要がある場合にのみ、LIKE または regex を使用してください。

要件	推奨される演算子	例	説明
文字列の完全一致	==	status == "active"	文字列 active の完全一致です。
単純なプレフィックス一致	LIKE	name LIKE "Prod%"	Prod で始まる文字列に一致します。
単純なサフィックス一致	LIKE	filename LIKE "%.json"	.json で終わる文字列に一致します。
単純な部分文字列一致	LIKE	description LIKE "%vector database%"	文字列内の任意の位置に vector database を含む値に一致します。
構造化されたコードまたは固定長パターンに一致	=~	code =~ "E[0-9]{4}"	E の後に 4 桁の数字が続く文字列を大文字小文字を区別して含むものに一致します。例: E1001。
大文字小文字を区別しないパターンマッチング	(?i) を指定した =~	message =~ "(?i)error"	error、ERROR、その他の大文字小文字のバリエーションに一致します。
regex パターンに一致する値を除外	!~	message !~ "^DEBUG"	DEBUG で始まる文字列を除外します。

単純なワイルドカードマッチングには LIKE を使用します。文字クラス、繰り返し、error|failed のような選択、アンカー、または大文字小文字を区別しないマッチングが必要なパターンには regex を使用します。

LIKE を使う

LIKE 演算子は、文字列値に対する単純なワイルドカードマッチングに使用します。サポートされるワイルドカードは次のものだけです。

ワイルドカード	説明
%	0 文字以上の文字に一致します。
_	ちょうど 1 文字に一致します。

一般的な LIKE パターン

% と _ の位置を使って、一致する文字列内で固定テキストが現れる位置を制御します。

要件	パターン	フィルター例
プレフィックスで始まる	Prod%	filter = 'name LIKE "Prod%"'
サフィックスで終わる	%.json	filter = 'filename LIKE "%.json"'
部分文字列を含む	%vector%	filter = 'description LIKE "%vector%"'
固定位置の 1 文字に一致	AB_%	filter = 'code LIKE "AB_%"'

LIKE のマッチング動作

LIKE は、プレフィックス、サフィックス、部分一致、および固定位置の単一文字一致に使用します。LIKE は [0-9] のような文字クラス、error|failed のような選択、{4} のような繰り返し回数、^ や $ のようなアンカー、(?i) のような大文字小文字を区別しないフラグをサポートしません。これらのパターンには regex を使用してください。

文字列全体の完全一致には == を使用します。LIKE は、フィルターでワイルドカードマッチングが必要な場合にのみ使用してください。

LIKE パターン内でのワイルドカードのエスケープ

LIKE パターンでは、% は任意の文字数に一致し、_ は 1 文字に一致します。%、_、または \ にリテラルとして一致させるには、その文字をバックスラッシュ（\）でエスケープします。

• name LIKE r"\%" は、リテラル値 % に一致します。

• name LIKE r"\_%" は、リテラルの _ で始まる値に一致します。

• name LIKE r"\\%" は、リテラルのバックスラッシュで始まる値に一致します。

r"..." または r'...' と書く raw string literal は、Zilliz Cloud のフィルター式内でバックスラッシュをそのまま保持します。バックスラッシュを含む LIKE および regex パターンでは、これらの使用を推奨します。raw string を使用しない場合、通常の string literal ではパターンが評価される前にエスケープシーケンスが処理されるため、より多くのバックスラッシュが必要になることがあります。

regex を使う

文字クラス、繰り返し、選択、アンカー、大文字小文字を区別しないマッチングなど、正規表現機能が必要な場合は regex フィルターを使用します。Zilliz Cloud は文字列値に対して RE2 正規表現を適用します。

=~ または !~ の右辺は string literal である必要があります。

演算子	意味	例
=~	regex パターンを満たす値に一致します。	filter = 'message =~ "E[0-9]{4}"'
!~	regex パターンを満たす値を除外します。	filter = 'message !~ "^DEBUG"'

raw string literal の使用

バックスラッシュを含む regex パターンには raw string literal を推奨します。r"..." または r'...' と書く raw string では、バックスラッシュがそのまま regex エンジンに渡されます。これにより、通常の string literal で必要になる追加のエスケープを避けられます。

例:

Python

python

filter = 'message =~ r"\d{4}-\d{2}-\d{2}"'

Java

java

String filter = "filename =~ r\"\\.json$\"";

Go

go

filter := `filename =~ r"\.json$"`

NodeJS

javascript

const filter = 'filename =~ r"\\.json$"';

cURL

bash

filter='filename =~ r"\.json$"'

C++

c++

// cpp

Zilliz CLI

shell

zilliz vector query --collection my_collection --filter 'filename =~ r"\.json$"' --output-fields 'filename'

これは、2026-07-01 のような日付形式の値を含む文字列に一致します。

raw string を使用しない場合、通常の string literal では regex パターンが評価される前にエスケープシーケンスが処理されるため、\d、\s、またはエスケープされたリテラル文字のようなパターンには追加のバックスラッシュが必要になることがあります。

一般的な regex パターン

次の例では、Zilliz Cloud のフィルター式で一般的な RE2 構文を使用しています。完全な regex 構文については、RE2 syntax リファレンスを参照してください。

要件	パターン	フィルター例
リテラルテキストを含む	error	filter = 'message =~ "error"'
プレフィックスで始まる	^ERR	filter = 'code =~ "^ERR"'
サフィックスで終わる	\.json$	filter = 'filename =~ "\\.json$"'
数字列に一致	[0-9]+	filter = 'message =~ "[0-9]+"'
固定桁数の数字に一致	[0-9]{4}	filter = 'code =~ "[0-9]{4}"'
メールドメインに一致	@example\.com$	filter = 'email =~ "@example\\.com$"'
大文字小文字を区別せずに一致	(?i)error	filter = 'message =~ "(?i)error"'
文字列全体に一致	^prod-[0-9]+$	filter = 'name =~ "^prod-[0-9]+$"'

複数の単語のいずれか 1 つに一致させるには、| を使った選択を使用します。

Python

python

filter = 'message =~ "error|failed|timeout"'

Java

java

String filter = "message =~ \"error|failed|timeout\"";

Go

go

filter := `message =~ "error|failed|timeout"`

NodeJS

javascript

const filter = 'message =~ "error|failed|timeout"';

cURL

bash

filter='message =~ "error|failed|timeout"'

C++

c++

// cpp

Zilliz CLI

shell

zilliz vector query --collection my_collection --filter 'message =~ "error|failed|timeout"' --output-fields 'message'

regex のメタ文字自体にリテラルとして一致させる場合は、regex パターン内でエスケープしてください。たとえば、リテラルのドット（regex では \.）に一致させるには、Python の filter 文字列では \\. と記述します。

Python

python

filter = 'email =~ "@gmail\\.com$"'

Java

java

String filter = "email =~ \"@gmail\\.com$\"";

Go

go

filter := `email =~ "@gmail\\.com$"`

NodeJS

javascript

const filter = 'email =~ "@gmail\\.com$"';

cURL

bash

filter='email =~ "@gmail\\.com$"'

C++

c++

// cpp

Zilliz CLI

shell

zilliz vector query --collection my_collection --filter 'email =~ "@gmail\\.com$"' --output-fields 'email'

注: Zilliz Cloud の regex フィルターは RE2 構文に従います。regex パターンが RE2 でサポートされていない構文を使用している場合、またはその他の理由で無効な場合、Zilliz Cloud はその filter 式を拒否します。regex のメタ文字、フラグ、マッチング動作の詳細については、RE2 syntax リファレンスを参照してください。

マッチング動作

部分文字列マッチング

Zilliz Cloud の regex マッチングは部分文字列セマンティクスを使用します。パターンはフィールド値全体に一致する必要はありません。たとえば、次のフィルターは E1001 と failed with E1001 after retry の両方に一致します。

Python

python

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

Java

java

String filter = "message =~ \"E[0-9]{4}\"";

Go

go

filter := `message =~ "E[0-9]{4}"`

NodeJS

javascript

const filter = 'message =~ "E[0-9]{4}"';

cURL

bash

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

C++

c++

// cpp

Zilliz CLI

shell

zilliz vector query --collection log_events --filter 'message =~ "E[0-9]{4}"' --output-fields 'message,severity'

フィールド値全体に一致させるには、^ と $ のアンカーを使用します。

Python

python

# Match only values that are exactly E followed by four digits
filter = 'code =~ "^E[0-9]{4}$"'

Java

java

// Match only values that are exactly E followed by four digits
String filter = "code =~ \"^E[0-9]{4}$\"";

Go

go

// Match only values that are exactly E followed by four digits
filter := `code =~ "^E[0-9]{4}$"`

NodeJS

javascript

// Match only values that are exactly E followed by four digits
const filter = 'code =~ "^E[0-9]{4}$"';

cURL

bash

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

C++

c++

// cpp

Zilliz CLI

shell

zilliz vector query --collection my_collection --filter 'code =~ "^E[0-9]{4}$"' --output-fields 'code'

Nullable な VARCHAR フィールド

regex フィルターは null 値に一致しません。これは =~ と !~ の両方に当てはまります。regex パターンに一致するものを除外しつつ null 値を保持する場合は、明示的に OR field IS NULL を追加してください。

Python

python

filter = 'message !~ "^DEBUG" OR message IS NULL'

Java

java

String filter = "message !~ \"^DEBUG\" OR message IS NULL";

Go

go

filter := `message !~ "^DEBUG" OR message IS NULL`

NodeJS

javascript

const filter = 'message !~ "^DEBUG" OR message IS NULL';

cURL

bash

filter='message !~ "^DEBUG" OR message IS NULL'

C++

c++

// cpp

Zilliz CLI

shell

zilliz vector query --collection log_events --filter 'message !~ "^DEBUG" OR message IS NULL' --output-fields 'message,severity'

JSON パス

JSON パスの場合、パスが存在しない、null、または非文字列値に解決されるときは、regex フィルターの動作が異なります。

フィルター	missing/null/non-string 値を含むか	注記
json_field["path"] =~ "pattern"	No	regex パターンを満たす文字列値にのみ一致します。
json_field["path"] !~ "pattern"	Yes	パスが存在しない、null、非文字列、または regex パターンに一致しない文字列であるエンティティを返します。

インデックスによるパターンマッチングの高速化

Zilliz Cloud は、文字列フィールドに対して、VARCHAR フィールドや JSON 文字列パスに対する LIKE および regex フィルターと併用できるいくつかのインデックスタイプ（NGRAM、STL_SORT、INVERTED、BITMAP など）をサポートしています。パターンマッチングはインデックスなしでも動作しますが、インデックスによって大規模なデータセットでのパフォーマンスを改善できます。

インデックスの有効性は、パターン式、Zilliz Cloud が固定リテラルの部分文字列を抽出できるかどうか、および対象フィールドのカーディナリティと分布によって異なります。name LIKE "Prod%" のようなプレフィックス形式のパターンは、description LIKE "%vector%" や filename LIKE "%.json" のような中間一致やサフィックス形式のパターンとは異なるインデックス戦略が有効な場合があります。

次の表を出発点として使用し、その後、実際のワークロードでベンチマークしてください。

パターンまたはデータの特性	検討すべきインデックス	注記
message =~ "error.*timeout" や message LIKE "%database%" のように、固定リテラルの部分文字列を含む	NGRAM	Zilliz Cloud がパターンから意味のあるリテラル部分文字列を抽出できる場合に役立ちます。詳細は NGRAM を参照してください。
プレフィックス、完全一致、または等価一致に近い文字列フィルター。特にカーディナリティが低〜中程度のフィールド	STL_SORT、INVERTED、または BITMAP	フィールドに繰り返し値がある場合や、フィルターが完全一致に近い場合に、より効果的です。詳細は STL_SORT、INVERTED、BITMAP を参照してください。
固定リテラルを含まない regex パターン、または文字クラス、短いトークン、ワイルドカードが主体のパターン	インデックスによる高速化に依存する前にベンチマークする	これらのパターンはインデックスの選択性が限定的で、より広範なスキャンにフォールバックする可能性があります。