מטרת ה-Query API היא לאחזר אובייקטים של נתונים מאוסף באמצעות מסנן. זה דומה להרצת שאילתה על טבלה במסד נתונים ושימוש בסעיף WHERE ב-SQL. אפשר גם להשתמש בצבירה כדי לקבל ספירה של אובייקטי נתונים שתואמים למסנן.
שפת ביטוי הסינון
בנוסף לפונקציונליות של חיפוש KNN/ANN, Agent Retrieval מספק יכולות שאילתה מגוונות באמצעות שפת שאילתות בהתאמה אישית. בטבלה הבאה מוסברת שפת השאילתה.
| מסנן | תיאור | הסוגים הנתמכים | דוגמה |
|---|---|---|---|
| $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 | התאמה לאובייקטים של נתונים עם ערכי שדות שנמצאים במערך שצוין. | String | {"genre": {"$in": ["comedy", "documentary"]}} |
| $nin | התאמה של אובייקטי נתונים עם ערכי שדות שלא נמצאים במערך שצוין. | String | {"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"]}} |
| $search | התאמה לאובייקטים של נתונים עם ערכי שדות שמכילים אסימון שתואם לערך שצוין. האופרטור הזה זמין רק באזור us multiregion כשמשתמשים בו כחלק מחיפוש וקטורי באינדקס. | String | {"content": {"$search": "blue"}} |
שליחת שאילתות לאוספים
הדוגמה הבאה ממחישה איך להשתמש במסנן כדי לשלוח שאילתה על אובייקטים של נתונים באוסף עם המזהה COLLECTION_ID.
REST
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- COLLECTION_ID: המזהה של האוסף.
- LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
ה-method של ה-HTTP וכתובת ה-URL:
POST https://vectorsearch.googleapis.com/v1/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: המזהה של האוסף.
- LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
מריצים את הפקודה הבאה:
Linux, macOS או Cloud Shell
gcloud 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 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 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_v1
# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()
# Initialize request
request = vectorsearch_v1.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 ומציינים את סוג הצבירה בגוף הבקשה.
בדוגמה הבאה אפשר לראות איך סופרים את כל אובייקטי הנתונים באוסף עם המזהה COLLECTION_ID.
REST
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- COLLECTION_ID: המזהה של האוסף.
- LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
ה-method של ה-HTTP וכתובת ה-URL:
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate
תוכן בקשת JSON:
{
"aggregate": "count"
}
כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:
אתם אמורים לקבל תגובת JSON שדומה לזו:
{
"aggregateResults": [
{
"count": 1000
}
]
}
gcloud
לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:
- COLLECTION_ID: המזהה של האוסף.
- LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
מריצים את הפקודה הבאה:
Linux, macOS או Cloud Shell
gcloud vector-search collections data-objects aggregate \ --aggregation-method=count \ --collection=COLLECTION_ID \ --location=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud vector-search collections data-objects aggregate ` --aggregation-method=count ` --collection=COLLECTION_ID ` --location=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud 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_v1
# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()
# Initialize request
request = vectorsearch_v1.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)