패턴 매칭

에이전트 기반 검색 애플리케이션에서 벡터 검색과 grep 스타일의 패턴 매칭은 종종 서로를 보완합니다. 벡터 검색은 의미적으로 관련성이 있는 엔티티를 검색하는 반면, 패턴 매칭은 오류 코드, 로그 접두사, 이메일 도메인, URL 경로 또는 식별자와 같은 정확한 문자열 구조를 기준으로 해당 결과를 좁혀줍니다.

Milvus에서는 간단한 와일드카드 일치를 위해 LIKE 를, RE2 정규식을 위해 =~ 또는 !~ 를 사용하여 스칼라 필터에서 이러한 패턴 제약 조건을 표현할 수 있습니다. 이러한 필터를 query, search 또는 하이브리드 검색과 결합할 수 있습니다.

패턴 매칭 표현식은 filter 매개변수에 작성됩니다. 예를 들어, 다음 쿼리는 E1001 와 같은 오류 코드가 포함된 로그 메시지와 일치합니다:

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

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

이 페이지의 예제는 filter 에 할당된 표현식에 중점을 둡니다. query, search 및 하이브리드 검색과 같이 스칼라 필터를 허용하는 Milvus 작업에서도 동일한 필터 표현식 구문을 사용할 수 있습니다.

지원되는 필드 유형

패턴 매칭은 문자열 값에 대해 사용할 수 있습니다.

대상	LIKE	정규식 =~ / !~	참고
VARCHAR 필드	예	예	문자열 필드에 대한 패턴 매칭의 일반적인 대상입니다.
JSON VARCHAR 로 형변환된 경로	예	예	정확한 일치를 위해서는 JSON 경로 값이 문자열이어야 합니다. 성능 향상을 위해 JSON 경로에 인덱스를 생성하는 경우, ` json_cast_type="varchar"`을 설정하십시오.
ARRAY<VARCHAR> element	예	예	tags[0] 와 같이 인덱스를 기준으로 특정 요소를 일치시킵니다. 패턴 일치는 모든 요소를 스캔 하지 않으며, 지정된 인덱스의 요소에만 적용됩니다.
숫자, 부울, 벡터, TEXT 또는 기타VARCHAR 가 아닌 대상	아니요	아니요	패턴 매칭은 VARCHAR 값, 문자열로 해석되는 JSON 경로 또는 인덱스가 지정된 ARRAY<VARCHAR> 요소에만 사용할 수 있습니다.

LIKE 또는 정규 표현식(regex) 선택

필요한 패턴을 표현하는 가장 간단한 연산자를 선택하십시오.

문자열을 정확히 일치시켜야 하는 경우, 패턴 매칭 대신 ` == `을 사용하는 것이 좋습니다. 필터가 특정 패턴과 일치해야 할 때만 ` LIKE ` 또는 정규식을 사용하십시오.

요구 사항	권장 연산자	예시	설명
문자열의 정확한 일치	==	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 뒤에 네 자리 숫자가 오는 문자열(예: E1001)과 일치합니다.
대소문자를 구분하지 않는 패턴 일치	=~ 다음과 같이 (?i)	message =~ "(?i)error"	error, ERROR 또는 기타 대소문자 변형과 일치합니다.
정규식 패턴과 일치하는 값 제외	!~	message !~ "^DEBUG"	DEBUG 로 시작하는 문자열을 제외합니다.

간단한 와일드카드 일치를 위해서는 LIKE 를 사용하십시오. 패턴에 문자 클래스, 반복, error|failed 와 같은 선택, 앵커 또는 대소문자 구분 없는 일치가 필요한 경우에는 정규식을 사용하십시오.

LIKE 사용

LIKE 연산자는 문자열 값에 대한 간단한 와일드카드 일치를 위한 것입니다. 다음 와일드카드만 지원합니다:

와일드카드	설명
%	0개 이상의 문자와 일치합니다.
_	정확히 하나의 문자와 일치합니다.

일반적인 LIKE 패턴

% 및 _ 의 위치를 사용하여 일치하는 문자열에서 고정 텍스트가 나타날 위치를 제어합니다.

필수 조건	패턴	필터 예시
접두사로 시작하는 경우	Prod%	filter = 'name LIKE "Prod%"'
접미사로 끝남	%.json	filter = 'filename LIKE "%.json"'
부분 문자열 포함	%vector%	filter = 'description LIKE "%vector%"'
고정된 위치의 한 글자와 일치	AB_%	filter = 'code LIKE "AB_%"'

LIKE 일치 동작

접두사, 접미사, 포함, 고정 위치의 단일 문자 일치를 위해서는 LIKE 를 사용하십시오. LIKE 는 [0-9] 와 같은 문자 클래스, error|failed 와 같은 선택, {4} 와 같은 반복 횟수, ^ 또는 $ 와 같은 앵커, (?i) 와 같은 대소문자 구분 없음 플래그를 지원하지 않습니다. 이러한 패턴의 경우 정규 표현식(regex)을 사용하십시오.

문자열 전체가 정확히 일치하는 경우 == 를 사용하십시오. 필터에 와일드카드 일치가 필요한 경우에만 LIKE 를 사용하십시오.

LIKE 패턴에서 와일드카드 이스케이프 처리

LIKE 패턴에서 % 는 0개 이상의 문자와 일치하고, _ 는 정확히 하나의 문자와 일치합니다. %, _ 또는 \ 를 문자 그대로 일치시키려면 백슬래시(\)로 문자를 이스케이프 처리하십시오:

• name LIKE r"\%" % 라는 리터럴 값과 일치합니다.
• name LIKE r"\_%" 리터럴 _ 로 시작하는 값과 일치합니다.
• name LIKE r"\\%" 리터럴 백슬래시로 시작하는 값과 일치합니다.

r"..." 또는 r'...' 형태로 작성된 원시 문자열 리터럴은 Milvus 필터 표현식에서 백슬래시를 그대로 유지합니다. 백슬래시가 포함된 LIKE 및 정규식 패턴의 경우 원시 문자열을 사용하는 것이 권장됩니다. 원시 문자열을 사용하지 않을 경우, 일반 문자열 리터럴은 패턴이 평가되기 전에 이스케이프 시퀀스를 처리하므로 더 많은 백슬래시가 필요할 수 있습니다.

정규 표현식 사용Compatible with Milvus 3.0.x

패턴에 문자 클래스, 반복, 선택, 앵커 또는 대소문자 구분 없는 일치와 같은 정규 표현식 기능이 필요한 경우 정규 표현식 필터를 사용하십시오. Milvus는 문자열 값에 RE2 정규 표현식을 적용합니다.

=~ 또는 !~ 의 우측은 반드시 문자열 리터럴이어야 합니다.

연산자	의미	예
=~	정규식 패턴을 만족하는 값과 일치합니다.	filter = 'message =~ "E[0-9]{4}"'
!~	정규식 패턴을 만족하는 값을 제외합니다.	filter = 'message !~ "^DEBUG"'

원시 문자열 리터럴 사용

백슬래시가 포함된 정규 표현식 패턴의 경우 원시 문자열 리터럴을 사용하는 것이 좋습니다. r"..." 또는 r'...' 형식으로 작성된 원시 문자열에서는 백슬래시가 그대로 정규 표현식 엔진으로 전달됩니다. 이를 통해 일반 문자열 리터럴에서 필요한 추가 이스케이프 처리를 피할 수 있습니다.

예를 들어:

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

이는 2026-07-01 과 같은 날짜 형식의 값을 포함하는 문자열과 일치합니다.

생 문자열을 사용하지 않을 경우, 일반 문자열 리터럴은 정규식 패턴이 평가되기 전에 이스케이프 시퀀스를 처리하므로, \d, \s 또는 이스케이프 처리된 리터럴 문자와 같은 패턴에는 추가적인 백슬래시가 필요할 수 있습니다.

일반적인 정규 표현식 패턴

다음 예제는 Milvus 필터 표현식에서 흔히 사용되는 RE2 구문을 보여줍니다. 전체 정규식 구문에 대해서는 RE2 구문 참조를 참조하십시오.

요구 사항	패턴	필터 예시
리터럴 텍스트 포함	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]+$"'

여러 단어 중 하나를 일치시키려면 | 를 사용하여 선택지를 지정합니다:

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

정규식 메타문자를 리터럴로 일치시키려면, 정규식 패턴에서 해당 문자를 이스케이프 처리하십시오. 예를 들어, 리터럴 점(정규식에서 `\. `)을 일치시키려면, Python 필터 문자열에 ` \\. `를 작성하십시오:

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

참고: Milvus 정규식 필터는 RE2 구문을 따릅니다. 정규식 패턴이 RE2에서 지원하지 않는 구문을 사용하거나 기타 이유로 유효하지 않은 경우, Milvus는 해당 필터 표현식을 거부합니다. 정규식 메타문자, 플래그 및 일치 동작에 대한 자세한 내용은 RE2 구문 참조를 참조하십시오.

일치 동작

부분 문자열 일치

Milvus 정규식 일치는 부분 문자열 의미를 사용합니다. 패턴이 필드 값 전체와 일치할 필요는 없습니다. 예를 들어, 다음 필터는 E1001 과 failed with E1001 after retry 모두에 일치합니다:

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

필드 값 전체와 일치시키려면 ^ 및 $ 앵커를 사용하십시오:

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

Null이 허용되는 VARCHAR 필드

정규식 필터는 null 값과 일치하지 않습니다. 이는 =~ 및 !~ 모두에 적용됩니다. 정규식 패턴을 제외하되 null 값은 유지하려면 OR field IS NULL 를 명시적으로 추가하십시오:

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

JSON 경로

JSON 경로의 경우, 경로가 누락되었거나 null이거나 문자열이 아닌 값으로 해석될 때 정규식 필터의 동작이 달라집니다:

필터	누락/null/문자가 아닌 값을 포함하나요?	참고
json_field["path"] =~ "pattern"	아니요	정규식 패턴을 만족하는 문자열 값만 일치시킵니다.
json_field["path"] !~ "pattern"	예	경로가 누락되었거나, null이거나, 문자열이 아니거나, 정규식 패턴과 일치하지 않는 문자열인 엔티티를 반환합니다.

인덱스를 사용하여 패턴 일치 속도 향상

Milvus는 문자열 필드에 대해 여러 인덱스 유형을 지원하며, 이러한 인덱스는 VARCHAR 필드 또는 JSON 문자열 경로(예: NGRAM, STL_SORT, INVERTED, BITMAP)에 대한 LIKE 및 정규식 필터와 함께 사용할 수 있습니다. 패턴 매칭은 인덱스 없이도 작동할 수 있지만, 인덱스를 사용하면 대용량 데이터셋에서 성능이 향상될 수 있습니다.

인덱스의 효과는 패턴 표현식, Milvus가 고정된 리터럴 부분 문자열을 추출할 수 있는지 여부, 그리고 대상 필드의 카디널리티와 분포에 따라 달라집니다. name LIKE "Prod%" 와 같은 접두사 스타일 패턴은 description LIKE "%vector%" 또는 filename LIKE "%.json" 와 같은 중위 또는 접미사 패턴과는 다른 인덱스 전략을 적용할 때 더 나은 성능을 보일 수 있습니다.

다음 표를 참고로 삼은 후, 실제 워크로드를 사용하여 벤치마크를 수행하십시오:

패턴 또는 데이터 특성	고려할 인덱스	참고 사항
message =~ "error.*timeout" 와 같이 고정된 리터럴 부분 문자열을 포함하는 경우, 또는 message LIKE "%database%"	NGRAM	Milvus가 패턴에서 의미 있는 리터럴 부분 문자열을 추출할 수 있는 경우 도움이 됩니다. 자세한 내용은 NGRAM을 참조하십시오.
접두사, 정확한 일치 또는 등가성 문자열 필터(특히 카디널리티가 낮거나 중간 정도인 필드에서)	STL_SORT, INVERTED, 또는 BITMAP	필드에 중복된 값이 있거나 필터가 완전 일치에 가까운 경우 더 효과적일 수 있습니다. 자세한 내용은 STL_SORT, INVERTED 및 BITMAP을 참조하십시오.
고정 리터럴이 없는 정규식 패턴, 또는 문자 클래스, 짧은 토큰, 와일드카드가 주를 이루는 패턴	인덱스 가속화에 의존하기 전에 벤치마크를 수행하십시오	이러한 패턴은 인덱스 선택성이 제한적일 수 있으며, 더 광범위한 스캔으로 전환될 수 있습니다.