Mit der Query API können Sie Datenobjekte aus einer Sammlung mithilfe eines Filters abrufen. Das ist ähnlich wie bei einer Abfrage einer Datenbanktabelle mit einer SQL-WHERE-Klausel. Sie können auch die Aggregation verwenden, um die Anzahl der Datenobjekte zu ermitteln, die einem Filter entsprechen.
Sprache für Filterausdrücke
Neben der KNN-/ANN-Suchfunktion bietet Vector Search 2.0 vielseitige Abfragefunktionen mit einer benutzerdefinierten Abfragesprache. Die Abfragesprache wird in der folgenden Tabelle erläutert.
| Filter | Beschreibung | Unterstützte Datentypen | Beispiel |
|---|---|---|---|
| $eq | Entspricht Datenobjekten mit Feldwerten, die gleich einem angegebenen Wert sind. | Zahl, String, boolescher Wert | {"genre": {"$eq": "documentary"}} |
| $ne | Entspricht Datenobjekten mit Feldwerten, die nicht gleich einem angegebenen Wert sind. | Zahl, String, boolescher Wert | {"genre": {"$ne": "drama"}} |
| $gt | Entspricht Datenobjekten mit Feldwerten, die größer als ein angegebener Wert sind. | Zahl | {"year": {"$gt": 2019}} |
| $gte | Entspricht Datenobjekten mit Feldwerten, die größer oder gleich einem angegebenen Wert sind. | Zahl | {"year": {"$gte": 2020}} |
| $lt | Entspricht Datenobjekten mit Feldwerten, die kleiner als ein angegebener Wert sind. | Zahl | {"year": {"$lt": 2020}} |
| $lte | Entspricht Datenobjekten mit Feldwerten, die kleiner oder gleich einem angegebenen Wert sind. | Zahl | {"year": {"$lte": 2020}} |
| $in | Entspricht Datenobjekten mit Feldwerten, die in einem angegebenen Array enthalten sind. | String | {"genre": {"$in": ["comedy", "documentary"]}} |
| $nin | Entspricht Datenobjekten mit Feldwerten, die nicht in einem angegebenen Array enthalten sind. | String | {"genre": {"$nin": ["comedy", "documentary"]}} |
| $and | Verknüpft Abfrageklauseln mit einem logischen AND. | - | {"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} |
| $or | Verknüpft Abfrageklauseln mit einem logischen OR. | - | {"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} |
| $all | Wählt die Dokumente aus, in denen der Arraywert eines Felds alle angegebenen Werte enthält. | - | {"colors": {"$all": ["red", "blue"]}} |
Sammlungen abfragen
Im folgenden Beispiel wird gezeigt, wie Sie mit einem Filter nach Datenobjekten in einer Sammlung mit der ID COLLECTION_ID suchen.
REST
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- COLLECTION_ID: Die ID der Sammlung
- LOCATION: Die Region, in der Sie Agent Platform verwenden
- PROJECT_ID: Ihre Google Cloud Projekt-ID.
HTTP-Methode und URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:query
JSON-Text anfordern:
{
"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": "*"
}
}
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:
{
"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
Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:
- COLLECTION_ID: Die ID der Sammlung
- LOCATION: Die Region, in der Sie Agent Platform verwenden
- PROJECT_ID: Ihre Google Cloud Projekt-ID.
Führen Sie folgenden Befehl aus:
Linux, macOS oder 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
Sie sollten eine Antwort ähnlich der folgenden erhalten:
---
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)
Um eine Aggregation auszuführen, verwenden Sie den Endpunkt aggregate und geben den Aggregationstyp im Anfragetext an.
Im folgenden Beispiel wird gezeigt, wie Sie alle Datenobjekte in einer Sammlung mit der ID COLLECTION_ID zählen.
REST
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- COLLECTION_ID: Die ID der Sammlung
- LOCATION: Die Region, in der Sie Agent Platform verwenden
- PROJECT_ID: Ihre Google Cloud Projekt-ID.
HTTP-Methode und URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate
JSON-Text anfordern:
{
"aggregate": "count"
}
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:
{
"aggregateResults": [
{
"count": 1000
}
]
}
gcloud
Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:
- COLLECTION_ID: Die ID der Sammlung
- LOCATION: Die Region, in der Sie Agent Platform verwenden
- PROJECT_ID: Ihre Google Cloud Projekt-ID.
Führen Sie folgenden Befehl aus:
Linux, macOS oder 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
Sie sollten eine Antwort ähnlich der folgenden erhalten:
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)
Nächste Schritte
- Informationen zum Suchen nach Datenobjekten.