메타데이터 필터

Mastra는 MongoDB/Sift 쿼리 구문을 기반으로 모든 벡터 저장소에 걸쳐 통합된 메타데이터 필터링 구문을 제공합니다. 각 벡터 저장소는 이러한 필터를 기본 쿼리 형식으로 변환합니다. 예를 들어 PgVector는 PostgreSQL JSONB 조건자를 사용하는 반면 OracleDB는 메타데이터를 Oracle JSON으로 저장하고 필터를 컴파일하여JSON_VALUE, JSON_EXISTS, REGEXP_LIKE, 그리고LIKE제한된 값이 있는 술어.

기본 예

import { PgVector } from '@mastra/pg'

const store = new PgVector({
  id: 'pg-vector',
  connectionString,
})

const results = await store.query({
  indexName: 'my_index',
  queryVector: queryVector,
  topK: 10,
  filter: {
    category: 'electronics', // Simple equality
    price: { $gt: 100 }, // Numeric comparison
    tags: { $in: ['sale', 'new'] }, // Array membership
  },
})

지원되는 연산자

기본 비교

$eq

지정된 값과 같은 값을 일치시킵니다

{ age: { $eq: 25 } }

Supported by: Couchbase를 제외한 모든 항목

$ne

같지 않은 값을 일치시킵니다

{ status: { $ne: 'inactive' } }

Supported by: Couchbase를 제외한 모든 항목

$gt

초과

{ price: { $gt: 100 } }

Supported by: Couchbase를 제외한 모든 항목

$gte

이상

{ rating: { $gte: 4.5 } }

Supported by: Couchbase를 제외한 모든 항목

$lt

미만

{ stock: { $lt: 20 } }

Supported by: Couchbase를 제외한 모든 항목

$lte

이하

{ priority: { $lte: 3 } }

Supported by: Couchbase를 제외한 모든 항목

배열 연산자

$in

배열에 있는 값 중 하나와 일치시킵니다

{ category: { $in: ["A", "B"] } }

Supported by: Couchbase를 제외한 모든 항목

$nin

어떤 값과도 일치하지 않는 항목을 찾습니다

{ status: { $nin: ["deleted", "archived"] } }

Supported by: Couchbase를 제외한 모든 항목

$all

모든 요소를 포함하는 배열을 일치시킵니다

{ tags: { $all: ["urgent", "high"] } }

Supported by: Astra, Pinecone, Upstash, MongoDB, OracleDB

$elemMatch

조건을 충족하는 배열 요소를 일치시킵니다

{ scores: { $elemMatch: { $gt: 80 } } }

Supported by: libSQL, PgVector, MongoDB, OracleDB

논리 연산자

$and

논리 AND

{ $and: [{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }

Supported by: Vectorize, Couchbase를 제외한 모든 항목

$or

논리 OR

{ $or: [{ status: "active" }, { priority: "high" }] }

Supported by: Vectorize, Couchbase를 제외한 모든 항목

$not

논리 NOT

{ price: { $not: { $lt: 100 } } }

Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB

$nor

논리 NOR

{ $nor: [{ status: "deleted" }, { archived: true }] }

Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB

요소 연산자

$exists

필드가 있는 문서를 일치시킵니다

{ rating: { $exists: true } }

Supported by: Vectorize, Chroma, Couchbase를 제외한 모든 항목

사용자 정의 연산자

$contains

텍스트에 부분 문자열이 포함되어 있는지 확인합니다

{ description: { $contains: "sale" } }

Supported by: Upstash, libSQL, PgVector, OracleDB

$regex

정규 표현식과 일치시킵니다

{ name: { $regex: "^test" } }

Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB

$size

배열 길이를 확인합니다

{ tags: { $size: 3 } }

Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB

$geo

지리 공간 쿼리

{ location: { $geo: { type: "radius", ... } } }

Supported by: Qdrant

$datetime

날짜 및 시간 범위 쿼리

{ created: { $datetime: { range: { gt: "2024-01-01" } } } }

Supported by: Qdrant

$hasId

벡터 ID 존재 여부를 확인합니다

{ $hasId: ["id1", "id2"] }

Supported by: Qdrant

$hasVector

벡터 존재 여부를 확인합니다

{ $hasVector: true }

Supported by: Qdrant

일반적인 규칙 및 제한 사항

1. 필드 이름은 다음을 수행할 수 없습니다.

   • 중첩된 필드를 참조하지 않는 한 점(.)을 포함합니다.
   • $로 시작하거나 null 문자를 포함합니다.
   • 빈 문자열이어야 함

2. 값은 다음과 같아야 합니다.

   • 유효한 JSON 유형(문자열, 숫자, 부울, 객체, 배열)
   • 정의되지 않음
   • 연산자에 대해 올바르게 입력됨(예: 숫자 비교를 위한 숫자)

3. 논리 연산자:

   • 유효한 조건을 포함해야 합니다.
   • 비워둘 수 없습니다.
   • 올바르게 중첩되어야 합니다.
   • 최상위 수준에서만 사용하거나 다른 논리 연산자 내에 중첩할 수 있습니다.
   • 필드 수준에서 사용하거나 필드 내부에 중첩할 수 없습니다.
   • 연산자 내부에서는 사용할 수 없습니다.
   • 유효한:{ "$and": [{ "field": { "$gt": 100 } }] }
   • 유효한:{ "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }
   • 유효하지 않은:{ "field": { "$and": [{ "$gt": 100 }] } }
   • 유효하지 않은:{ "field": { "$gt": { "$and": [{...}] } } }

4. $not 연산자:

   • 객체여야 합니다.
   • 비워둘 수 없습니다.
   • 필드 수준 또는 최상위 수준에서 사용할 수 있습니다.
   • 유효한:{ "$not": { "field": "value" } }
   • 유효한:{ "field": { "$not": { "$eq": "value" } } }

5. 연산자 중첩:

   • 논리 연산자에는 직접 연산자가 아닌 필드 조건이 포함되어야 합니다.
   • 유효한:{ "$and": [{ "field": { "$gt": 100 } }] }
   • 유효하지 않은:{ "$and": [{ "$gt": 100 }] }

매장별 참고 사항

아스트라

• 중첩된 필드 쿼리는 점 표기법을 사용하여 지원됩니다.
• 배열 필드는 메타데이터에서 배열로 명시적으로 정의되어야 합니다.
• 메타데이터 값은 대소문자를 구분합니다.

크로마DB

• 필터는 필터링된 필드가 메타데이터에 존재하는 결과만 반환합니다.
• 빈 메타데이터 필드는 필터 결과에 포함되지 않습니다.
• 부정 일치의 경우 메타데이터 필드가 있어야 합니다(예: $ne는 필드가 누락된 문서와 일치하지 않습니다).

Cloudflare 벡터화

• 필터링을 사용하려면 메타데이터를 명시적으로 인덱싱해야 합니다.
• 필터링할 필드를 인덱싱하려면 createMetadataIndex()를 사용하세요.
• Vectorize 인덱스당 메타데이터 인덱스는 최대 10개입니다.
• 문자열 값은 처음 64바이트까지만 인덱싱됩니다(UTF-8 경계에서 잘림).
• 숫자 값은 float64 정밀도를 사용합니다.
• 필터 JSON은 2048바이트 미만이어야 합니다.
• 필드 이름에는 점(.)을 포함할 수 없으며 $로 시작할 수 없습니다.
• 필드 이름은 512자로 제한됩니다.
• 필터링된 결과에 포함할 새 메타데이터 인덱스를 만든 후에는 벡터를 다시 삽입해야 합니다.
• 매우 큰 데이터세트(벡터 약 1,000만 개 이상)에서는 범위 쿼리의 정확도가 낮아질 수 있습니다.

libSQL

• 점 표기법으로 중첩된 객체 쿼리 지원
• 배열 필드는 유효한 JSON 배열이 포함되어 있는지 확인하기 위해 검증됩니다.
• 숫자 비교를 통해 적절한 유형 처리 유지
• 조건의 빈 배열은 정상적으로 처리됩니다.
• 효율적인 쿼리를 위해 메타데이터가 JSONB 열에 저장됩니다.

오라클DB

• 메타데이터는 각 VECTOR 행과 함께 Oracle JSON으로 저장됩니다.
• 스칼라 비교에는 JSON_VALUE를 사용하고, 배열, 존재 여부 및 요소 일치 검사에는 JSON_EXISTS를 사용합니다.
• $regex는 Oracle의 REGEXP_LIKE를 사용하며, 문자열 $contains는 대소문자를 구분하지 않는 LIKE를 사용합니다.
• 중첩 필드는 점 표기법으로 지원되며 따옴표로 묶인 Oracle JSON 경로로 변환됩니다.
• 사용자가 제공한 메타데이터 값은 SQL에 삽입되지 않고 매개변수로 바인딩됩니다.

Pg벡터

• PostgreSQL의 기본 JSON 쿼리 기능을 완벽하게 지원합니다.
• 기본 배열 함수를 사용하여 배열 작업을 효율적으로 처리
• 숫자, 문자열 및 부울에 대한 적절한 유형 처리
• 중첩 필드 쿼리는 내부적으로 PostgreSQL의 JSON 경로 구문을 사용합니다.
• 효율적인 인덱싱을 위해 메타데이터가 JSONB 열에 저장됩니다.

솔방울

• 메타데이터 필드 이름은 512자로 제한됩니다.
• 숫자 값은 ±1e38 범위 내에 있어야 합니다.
• 메타데이터의 배열은 총 크기가 64KB로 제한됩니다.
• 중첩된 객체는 점 표기법으로 평면화됩니다.
• 메타데이터 업데이트가 전체 메타데이터 개체를 대체합니다.

Qdrant

• 중첩 조건을 사용하는 고급 필터링을 지원합니다.
• 필터링하려면 페이로드(메타데이터) 필드를 명시적으로 인덱싱해야 합니다.
• 필터링할 필드를 인덱싱하려면 createPayloadIndex()를 사용하세요.

// Index a field before filtering on it
await store.createPayloadIndex({
  indexName: 'my_index',
  fieldName: 'source',
  fieldSchema: 'keyword', // 'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'
})

// Now filtering works
const results = await store.query({
  indexName: 'my_index',
  queryVector: queryVector,
  filter: { source: 'document-a' },
})

• 지리공간 쿼리의 효율적인 처리
• null 및 빈 값에 대한 특수 처리
• 벡터별 필터링 기능
• 날짜/시간 값은 RFC 3339 형식이어야 합니다.

업스태시

• 메타데이터 필드 키는 512자로 제한됩니다.
• 쿼리 크기가 제한되므로 큰 IN 절은 피하세요.
• 필터에서는 null/정의되지 않은 값을 지원하지 않습니다.
• 내부적으로 SQL과 유사한 구문으로 변환됩니다.
• 문자열 비교는 대소문자를 구분합니다.
• 메타데이터 업데이트는 원자적으로 수행됩니다.

MongoDB

• 메타데이터 필터에 MongoDB/Sift 쿼리 구문을 완전히 지원합니다.
• 모든 표준 비교, 배열, 논리 및 요소 연산자를 지원합니다.
• 메타데이터의 중첩 필드와 배열을 지원합니다.
• 필터링은 각각 filter 및 documentFilter 옵션을 사용하여 metadata와 원본 문서 콘텐츠 모두에 적용할 수 있습니다.
• filter는 메타데이터 객체에 적용되고, documentFilter는 원본 문서 필드에 적용됩니다.
• 필터 크기나 복잡성에 인위적인 제한은 없습니다(MongoDB 쿼리 제한에 따라 달라짐).
• 최적의 성능을 위해 메타데이터 필드를 인덱싱하는 것이 좋습니다.

카우치베이스

• 현재 메타데이터 필터는 지원되지 않습니다. 필터링은 결과를 검색한 후 클라이언트 측에서 수행하거나 더 복잡한 쿼리의 경우 Couchbase SDK의 검색 기능을 직접 사용하여 수행해야 합니다.

Amazon S3 벡터

• 동등 비교 값은 기본 형식(문자열/숫자/부울)이어야 합니다. 동등 비교에는 null/undefined, 배열, 객체 및 Date를 사용할 수 없습니다. 범위 연산자에는 숫자 또는 Date를 사용할 수 있습니다(Date는 epoch 밀리초로 정규화됨).
• $in/$nin에는 비어 있지 않은 기본 형식 값의 배열이 필요합니다. Date 요소를 사용할 수 있으며 epoch 밀리초로 정규화됩니다. 배열 동등 비교는 지원되지 않습니다.
• 암시적 AND는 정규화됩니다({a:1,b:2} → {$and:[{a:1},{b:2}]). 논리 연산자는 필드 조건을 포함하고 비어 있지 않은 배열을 사용해야 합니다. 루트 또는 다른 논리 연산자 내부에만 나타날 수 있으며 필드 값 내부에는 사용할 수 없습니다.
• 인덱스를 생성할 때 nonFilterableMetadataKeys에 나열된 키는 저장되지만 필터링할 수 없습니다. 이 설정은 변경할 수 없습니다.
• $exists에는 부울 값이 필요합니다.
• 정의되지 않음/null/빈 필터는 필터가 없는 것으로 처리됩니다.
• 각 메타데이터 키 이름은 63자로 제한됩니다.
• 벡터당 총 메타데이터: 최대 40KB(필터링 가능 + 필터링 불가능)
• 벡터당 총 메타데이터 키: 최대 10개
• 벡터당 필터링 가능한 메타데이터: 최대 2KB
• 벡터 인덱스당 필터링할 수 없는 메타데이터 키: 최대 10개

관련 항목

• 아스트라
• 크로마
• Cloudflare 벡터화
• libSQL
• 몽고DB
• 오라클DB
• Pg스토어
• 솔방울
• Qdrant
• 업스태시
• Amazon S3 벡터