Query API의 목적은 필터를 사용하여 컬렉션에서 데이터 객체를 검색하는 것입니다. 이는 데이터베이스 테이블을 쿼리하고 SQL WHERE 절을 사용하는 것과 비슷합니다. 집계를 사용하여 필터와 일치하는 데이터 객체의 개수를 가져올 수도 있습니다.
필터 표현식 언어
Vector Search 2.0은 KNN/ANN 검색 기능 외에도 커스텀 쿼리 언어를 사용한 다양한 쿼리 기능을 제공합니다. 쿼리 언어는 다음 표에 설명되어 있습니다.
| 필터 | 설명 | 지원되는 형식 | 예 |
|---|---|---|---|
| $eq | 데이터 객체를 지정된 값과 동일한 필드 값과 일치시킵니다. | 숫자, 문자열, 불리언 | {"genre": {"$eq": "documentary"}} |
| $ne | 지정된 값과 다른 필드 값을 가진 데이터 객체와 일치시킵니다. | 숫자, 문자열, 불리언 | {"genre": {"$ne": "drama"}} |
| $gt | 데이터 객체를 지정된 값보다 큰 필드 값과 일치시킵니다. | 숫자 | {"year": {"$gt": 2019}} |
| $gte | 데이터 객체를 지정된 값보다 크거나 동일한 필드 값과 일치시킵니다. | 숫자 | {"year": {"$gte": 2020}} |
| $lt | 데이터 객체를 지정된 값보다 작은 필드 값과 일치시킵니다. | 숫자 | {"year": {"$lt": 2020}} |
| $lte | 데이터 객체를 지정된 값보다 작거나 동일한 필드 값과 일치시킵니다. | 숫자 | {"year": {"$lte": 2020}} |
| $in | 데이터 객체를 지정된 배열에 있는 필드 값과 일치시킵니다. | 문자열 | {"genre": {"$in": ["comedy", "documentary"]}} |
| $nin | 데이터 객체를 지정된 배열에 없는 필드 값과 일치시킵니다. | 문자열 | {"genre": {"$nin": ["comedy", "documentary"]}} |
| $and | 논리적 AND 로 쿼리 절을 조인합니다. | - | {"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} |
| $or | 논리적 OR 로 쿼리 절을 조인합니다. | - | {"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} |
| $all | 필드의 배열 값에 지정된 모든 값이 포함된 문서를 선택합니다. | - | {"colors": {"$all": ["red", "blue"]}} |
컬렉션 쿼리
다음 예시에서는 필터를 사용하여 ID가 COLLECTION_ID인 컬렉션의 데이터 객체를 쿼리하는 방법을 보여줍니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- COLLECTION_ID: 컬렉션의 ID
- LOCATION: 에이전트 플랫폼을 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID
HTTP 메서드 및 URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:query
JSON 요청 본문:
{
"page_size": 10,
"page_token": "",
"filter": {
"$or": [
{
"director": {
"$eq": "Akira Kurosawa"
}
},
{
"$and": [
{
"director": {
"$eq": "David Fincher"
}
},
{
"genre": {
"$ne": "Thriller"
}
}
]
}
]
},
"output_fields": {
"data_fields": "*",
"vector_fields": "*",
"metadata_fields": "*"
}
}
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
다음과 비슷한 JSON 응답이 표시됩니다.
{
"dataObjects": [
{
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
"createTime": "2026-02-04T14:35:29Z",
"updateTime": "2026-02-04T14:37:29Z",
"data": {
"title": "Seven Samurai",
"director": "Akira Kurosawa",
"genre": "Action",
"year": 1954
},
"vectors": {
"genre_embedding": {
"dense": {
"values": [
0.3863801,
0.73934346,
0.16189057,
0.5271367
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1,
6,
3,
2,
8,
5,
2
],
"indices": [
4065,
13326,
17377,
25918,
28105,
32683,
42998
]
}
},
"plot_embedding": {
"dense": {
"values": [
1,
1,
1
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.5920452,
0.08301644,
0.12647335,
0.619643,
0.49258286
]
}
}
}
},
{
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
"createTime": "2026-02-04T15:35:29Z",
"updateTime": "2026-02-04T15:37:29Z",
"data": {
"title": "The Social Network",
"director": "David Fincher",
"genre": "Drama",
"year": 2010
},
"vectors": {
"genre_embedding": {
"dense": {
"values": [
0.1,
0.2,
0.3,
0.4
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1
],
"indices": [
1000
]
}
},
"plot_embedding": {
"dense": {
"values": [
0.1,
0.1,
0.1
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.1,
0.2,
0.3,
0.4,
0.5
]
}
}
}
}
]
}
gcloud
아래의 명령어 데이터를 사용하기 전에, 다음을 바꿉니다.
- COLLECTION_ID: 컬렉션의 ID
- LOCATION: 에이전트 플랫폼을 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
gcloud beta vector-search collections data-objects query \ --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' \ --output-data-fields='*' \ --output-vector-fields='*' \ --output-metadata-fields='*' \ --collection=COLLECTION_ID \ --location=LOCATION \ --project=PROJECT_ID
Windows(PowerShell)
gcloud beta vector-search collections data-objects query ` --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' ` --output-data-fields='*' ` --output-vector-fields='*' ` --output-metadata-fields='*' ` --collection=COLLECTION_ID ` --location=LOCATION ` --project=PROJECT_ID
Windows(cmd.exe)
gcloud beta vector-search collections data-objects query ^ --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' ^ --output-data-fields='*' ^ --output-vector-fields='*' ^ --output-metadata-fields='*' ^ --collection=COLLECTION_ID ^ --location=LOCATION ^ --project=PROJECT_ID
다음과 비슷한 응답이 표시됩니다.
---
createTime: '2026-02-04T14:35:29Z'
data:
director: Akira Kurosawa
genre: Action
title: Seven Samurai
year: 1954
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
updateTime: '2026-02-04T14:37:29Z'
vectors:
genre_embedding:
dense:
values:
- 0.38638
- 0.739343
- 0.161891
- 0.527137
plot_embedding:
dense:
values:
- 1.0
- 1.0
- 1.0
soundtrack_embedding:
dense:
values:
- 0.592045
- 0.0830164
- 0.126473
- 0.619643
- 0.492583
sparse_embedding:
sparse:
indices:
- 4065
- 13326
- 17377
- 25918
- 28105
- 32683
- 42998
values:
- 1.0
- 6.0
- 3.0
- 2.0
- 8.0
- 5.0
- 2.0
---
createTime: '2026-02-04T15:35:29Z'
data:
director: David Fincher
genre: Drama
title: The Social Network
year: 2010
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
updateTime: '2026-02-04T15:37:29Z'
vectors:
genre_embedding:
dense:
values:
- 0.1
- 0.2
- 0.3
- 0.4
plot_embedding:
dense:
values:
- 0.1
- 0.1
- 0.1
soundtrack_embedding:
dense:
values:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
sparse_embedding:
sparse:
indices:
- 1000
values:
- 1.0
Python
from google.cloud import vectorsearch_v1beta
# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()
# Initialize request
request = vectorsearch_v1beta.QueryDataObjectsRequest(
parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
filter={
"$or": [
{"director": {"$eq": "Akira Kurosawa"}},
{
"$and": [
{"director": {"$eq": "David Fincher"}},
{"genre": {"$ne": "Thriller"}},
]
},
]
},
)
# Make the request
page_result = data_object_search_service_client.query_data_objects(request=request)
# Handle the response
for response in page_result:
print(response)
집계를 실행하려면 aggregate 엔드포인트를 사용하고 요청 본문에 집계 유형을 지정합니다.
다음 예시에서는 ID가 COLLECTION_ID인 컬렉션의 모든 데이터 객체를 계산하는 방법을 보여줍니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- COLLECTION_ID: 컬렉션의 ID
- LOCATION: 에이전트 플랫폼을 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID
HTTP 메서드 및 URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate
JSON 요청 본문:
{
"aggregate": "count"
}
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
다음과 비슷한 JSON 응답이 표시됩니다.
{
"aggregateResults": [
{
"count": 1000
}
]
}
gcloud
아래의 명령어 데이터를 사용하기 전에, 다음을 바꿉니다.
- COLLECTION_ID: 컬렉션의 ID
- LOCATION: 에이전트 플랫폼을 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
gcloud beta vector-search collections data-objects aggregate \ --aggregation-method=count \ --collection=COLLECTION_ID \ --location=LOCATION \ --project=PROJECT_ID
Windows(PowerShell)
gcloud beta vector-search collections data-objects aggregate ` --aggregation-method=count ` --collection=COLLECTION_ID ` --location=LOCATION ` --project=PROJECT_ID
Windows(cmd.exe)
gcloud beta vector-search collections data-objects aggregate ^ --aggregation-method=count ^ --collection=COLLECTION_ID ^ --location=LOCATION ^ --project=PROJECT_ID
다음과 비슷한 응답이 표시됩니다.
aggregateResults: - count: 1000
Python
from google.cloud import vectorsearch_v1beta
# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()
# Initialize request
request = vectorsearch_v1beta.AggregateDataObjectsRequest(
parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
aggregate="COUNT",
)
# Make the request
response = data_object_search_service_client.aggregate_data_objects(request=request)
# Handle the response
print(response)
다음 단계
- 데이터 객체를 검색하는 방법 알아보기