> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 메타데이터 필터

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

## 기본 예

```typescript
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()`를 사용하세요.

```typescript
// 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개

## 관련 항목

- [아스트라](https://mastra.zisheng.pro/ko/reference/vectors/astra)
- [크로마](https://mastra.zisheng.pro/ko/reference/vectors/chroma)
- [Cloudflare 벡터화](https://mastra.zisheng.pro/ko/reference/vectors/vectorize)
- [libSQL](https://mastra.zisheng.pro/ko/reference/vectors/libsql)
- [몽고DB](https://mastra.zisheng.pro/ko/reference/vectors/mongodb)
- [오라클DB](https://mastra.zisheng.pro/ko/reference/vectors/oracledb)
- [Pg스토어](https://mastra.zisheng.pro/ko/reference/vectors/pg)
- [솔방울](https://mastra.zisheng.pro/ko/reference/vectors/pinecone)
- [Qdrant](https://mastra.zisheng.pro/ko/reference/vectors/qdrant)
- [업스태시](https://mastra.zisheng.pro/ko/reference/vectors/upstash)
- [Amazon S3 벡터](https://mastra.zisheng.pro/ko/reference/vectors/s3vectors)