Der Zweck der Search API besteht darin, Datenobjekte zu finden, die einer bestimmten Abfrage ähneln, und eine Liste mit Ergebnissen zurückzugeben, die nach Ähnlichkeit sortiert sind. Die Search API unterstützt auch das Filtern.
Die Search API bietet verschiedene Möglichkeiten, nach Datenobjekten zu suchen: Vektorsuche, Volltextsuche und semantische Suche. Außerdem können mehrere Suchanfragen eines beliebigen Typs kombiniert werden, um eine Hybridsuche zu ermöglichen.
Vektorsuche
Bei der Vektorsuche können Sie einen eigenen Abfragevektor angeben. Dies ist die erforderliche Methode zum Suchen nach Einbettungsfeldern, die keine embedding-config haben.
Wenn mehrere vector_search-Felder angegeben sind, werden die Ergebnisse mit gleicher Gewichtung kombiniert.
Im folgenden Beispiel wird gezeigt, wie Sie eine Vektorsuche in einer Sammlung mit der ID COLLECTION_ID durchführen.
REST
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- COLLECTION_ID: Die ID der Sammlung.
- LOCATION: Die Region, in der Sie die Agent Platform verwenden.
- PROJECT_ID: Ihre Projekt-ID in Google Cloud .
HTTP-Methode und URL:
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
JSON-Text anfordern:
{
"vector_search": {
"search_field": "plot_embedding",
"vector": {
"values": [
0.42426406871192845,
0.565685424949238,
0.7071067811865475
]
},
"filter": {
"genre": {
"$eq": "Thriller"
}
},
"top_k": 5,
"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:
{
"results": [
{
"dataObject": {
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
"createTime": "2026-01-31T20:05:06Z",
"updateTime": "2026-02-02T13:59:24Z",
"data": {
"year": 1991,
"title": "The Silence of the Lambs",
"director": "Jonathan Demme",
"genre": "Thriller"
},
"vectors": {
"plot_embedding": {
"dense": {
"values": [
1,
1,
1
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1,
6,
3,
2,
8,
5,
2
],
"indices": [
4065,
13326,
17377,
25918,
28105,
32683,
42998
]
}
},
"genre_embedding": {
"dense": {
"values": [
0.3863801,
0.73934346,
0.16189057,
0.5271367
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.5920452,
0.08301644,
0.12647335,
0.619643,
0.49258286
]
}
}
}
},
"distance": 1.697
},
{
"dataObject": {
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
"createTime": "2026-02-04T14:35:29Z",
"updateTime": "2026-02-04T14:37:29Z",
"data": {
"year": 1995,
"title": "Se7en",
"director": "David Fincher",
"genre": "Thriller"
},
"vectors": {
"genre_embedding": {
"dense": {
"values": [
0.3863801,
0.73934346,
0.16189057,
0.5271367
]
}
},
"plot_embedding": {
"dense": {
"values": [
1,
1,
1
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1,
6,
3,
2,
8,
5,
2
],
"indices": [
4065,
13326,
17377,
25918,
28105,
32683,
42998
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.5920452,
0.08301644,
0.12647335,
0.619643,
0.49258286
]
}
}
}
},
"distance": 1.75
}
]
}
gcloud
Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:
-
SEARCH_VECTOR_FILE: Der lokale Pfad zu einer JSON-Datei, die den dichten oder dünnbesetzten Vektor enthält, mit dem gesucht werden soll.
Beispiel für den Dateiinhalt eines dichten Vektors:
{ "dense": { "values": [ 0.42426406871192845, 0.565685424949238, 0.7071067811865475 ] } }
Beispiel für den Dateiinhalt eines dünnbesetzten Vektors:
{ "sparse": { "indices": [1, 5, 10], "values": [0.1, 0.5, 0.21] } }
- COLLECTION_ID: Die ID der Sammlung.
- LOCATION: Die Region, in der Sie die Agent Platform verwenden.
- PROJECT_ID: Ihre Projekt-ID in Google Cloud .
Führen Sie folgenden Befehl aus:
Linux, macOS oder Cloud Shell
gcloud vector-search collections data-objects search \ --vector-search-field="plot_embedding" \ --vector-from-file=SEARCH_VECTOR_FILE \ --json-filter='{"genre": {"$eq": "Thriller"}}' \ --top-k=5 \ --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 search ` --vector-search-field="plot_embedding" ` --vector-from-file=SEARCH_VECTOR_FILE ` --json-filter='{"genre": {"$eq": "Thriller"}}' ` --top-k=5 ` --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 search ^ --vector-search-field="plot_embedding" ^ --vector-from-file=SEARCH_VECTOR_FILE ^ --json-filter='{"genre": {"$eq": "Thriller"}}' ^ --top-k=5 ^ --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:
---
dataObject:
createTime: '2026-01-31T20:05:06Z'
data:
director: Jonathan Demme
genre: Thriller
title: The Silence of the Lambs
year: 1991
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
updateTime: '2026-02-02T13:59:24Z'
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
distance: 1.697
---
dataObject:
createTime: '2026-02-04T14:35:29Z'
data:
director: David Fincher
genre: Thriller
title: Se7en
year: 1995
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
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
distance: 1.75
Python
from google.cloud import vectorsearch_v1
# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()
# Initialize request
vector_search = vectorsearch_v1.VectorSearch(
search_field="plot_embedding",
vector={"values": [0.1, 0.2, 0.3]},
filter={"genre": {"$eq": "Thriller"}},
top_k=5,
)
request = vectorsearch_v1.SearchDataObjectsRequest(
parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
vector_search=vector_search,
)
# Make the request
response = data_object_search_service_client.search_data_objects(request=request)
# Handle the response
print(response)
Genauigkeit und Leistung der Suche optimieren
Bei Vektorsuchen in dichten ANN-Indizes mit mehr als 100.000 Einbettungen versucht der Agentenabruf standardmäßig, einen optimalen Kompromiss zwischen Recall und Latenz zu finden. Sie können dieses Gleichgewicht für Ihren Anwendungsfall optimieren, indem Sie eine Ziel-Recall-Rate angeben.
Die Werte müssen größer oder gleich 0.00 und kleiner oder gleich 1.00 sein.
Informationen zum Erstellen eines ANN-Index finden Sie unter ANN-Index erstellen.
Im folgenden Beispiel wird gezeigt, wie Sie eine Vektorsuche in einem dichten ANN-Index mit einer Ziel-Recall-Rate von 0.95 durchführen.
REST
HTTP-Methode und URL:
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
JSON-Text der Anfrage:
{
"vectorSearch": {
"searchField": "plot_embedding",
"vector": {
"values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]
},
"topK": 10,
"searchHint": {
"indexHint": {
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
"denseScannParams": {
"targetRecall": 0.95
}
}
},
"outputFields": {
"dataFields": "*",
"vectorFields": "*",
"metadataFields": "*"
}
}
}
gcloud
Speichern Sie den Abfragevektor in einer JSON-Datei, z. B. vector.json:
{
"dense": {
"values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]
}
}
Führen Sie dann den Befehl gcloud vector-search collections data-objects searchaus:
gcloud vector-search collections data-objects search \
--project=PROJECT_ID \
--location=LOCATION \
--collection=COLLECTION_ID \
--vector-search-field=plot_embedding \
--vector-from-file=vector.json \
--use-index=INDEX_ID \
--dense-scann-target-recall=0.95 \
--top-k=10
Python
from google.cloud import vectorsearch_v1
# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()
collection = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"
# Set the target recall rate on the index hint
search_hint = vectorsearch_v1.SearchHint(
index_hint=vectorsearch_v1.SearchHint.IndexHint(
name=f"{collection}/indexes/INDEX_ID",
dense_scann_params=vectorsearch_v1.SearchHint.IndexHint.DenseScannParams(
target_recall=0.95,
),
),
)
# Initialize request
vector_search = vectorsearch_v1.VectorSearch(
search_field="plot_embedding",
vector={"values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]},
top_k=10,
search_hint=search_hint,
output_fields=vectorsearch_v1.OutputFields(
data_fields=["*"],
vector_fields=["*"],
metadata_fields=["*"],
),
)
request = vectorsearch_v1.SearchDataObjectsRequest(
parent=collection,
vector_search=vector_search,
)
# Make the request
response = data_object_search_service_client.search_data_objects(request=request)
# Handle the response
print(response)
Textsuche
Dadurch wird eine Volltextsuche ohne dünnbesetzte Vektoren durchgeführt. Der Standardabfragedialekt „word“ behandelt die gesamte Eingabe als einzelne Suchbegriffe mit einem impliziten AND-Operator. Sie können enhanced_query auf true setzen, um Suchbegriffe zu erweitern, Stemming und das Entfernen von Stoppwörtern zu verarbeiten und zusätzliche Suchoperatoren zuzulassen:
OR: Ein Operator für die Disjunktion, bei dem die Groß-/Kleinschreibung berücksichtigt wird und der Dokumente findet, die mindestens einen der angegebenen Begriffe enthalten. Er gilt nur für die beiden benachbarten Begriffe.": (doppelte Anführungszeichen) für die Suche nach Wortgruppen.-: Der Negationsoperator. Dokumente, die Begriffe enthalten, vor denen er platziert ist, werden ausgeschlossen.
Erweiterte Textsuche
Mit der Agent Retrieval Text Search API können Sie Textsuchen über strukturierte Abfragen mit einer oder mehreren Unterabfragen ausdrücken. So können Sie:
Abgleich mit bestimmten Datenobjekt-Feldern.
Geben Sie den Typ des Abgleichs an:
Pro Begriff, Groß- und Kleinschreibung wird nicht berücksichtigt
Genau, Groß-/Kleinschreibung beachten
Fügen Sie sprachspezifische Erweiterungen hinzu, um nach Wortstämmen, Synonymen, Rechtschreibfehlern und Stoppwörtern (z. B. „ein“, „eine“ und „der“) zu suchen.
Verwenden Sie die booleschen Operatoren
AND,ORundNOT, um Unterabfragen zu kombinieren.Sie können die Reihenfolge der Auswertung steuern, indem Sie Unterabfragen gruppieren.
Erhöhen Sie die Punktzahlbeiträge, um das Ranking zu beeinflussen.
Es gibt drei Arten von Unterabfragen:
Text: Enthält den Suchtext und ein oder mehrere Felder, mit denen abgeglichen werden soll.
Unär: Wendet einen NOT-Vorgang auf eine einzelne Unterabfrage an.
Kombiniert: Wendet den Operator
ANDoderORan, um Unterabfragen zu kombinieren. Kann verwendet werden, um andere kombinierte Unterabfragen zu gruppieren, um die Auswertungsreihenfolge zu steuern.
In den Beispielen auf dieser Seite wird die Sammlung verwendet, die in der folgenden Tabelle dargestellt ist. Es enthält sechs Datenobjekte und definiert die folgenden Felder in seinem Datenschema: die Strings ID, Title, Description und das String-Array Keywords.
| ID | Titel | Beschreibung | Keywords |
|---|---|---|---|
| 1 | The Quick Brown Fox | Ein schneller brauner Fuchs springt mühelos über den faulen Hund. | wild, Wald, Säugetier, orange, Agilität, Raubtier |
| 2 | Lazy Dog Days | Der braune Hund schläft. | Haustier, Haus, Hund, ruhig, faul, gehorsam |
| 3 | Fuchs oder Hund | Der schlaue Fuchs überlistet den Hund. | wild, domestic, conflict, caniformia, mammals, interaction |
| 4 | Braunbären | Schnelle Bewegungen im Wald. | wild, Wald, Bär, Spitzenprädator, Winterschlaf, riesig |
| 5 | Eine schlaue Geschichte | Der Hund springt hoch. | Schläue, Sprünge |
| 6 | Meine faulen Sommertage | Eine Kurzgeschichte über das Entspannen in den Sommerferien. | Sommer, entspannen, Urlaub, Sonne |
Textunterabfragen
Textabfragen werden mit einem oder mehreren Feldern in einem Datenobjekt abgeglichen. Alle strukturierten Abfragen müssen mindestens eine Textabfrage enthalten.
Im folgenden Beispiel wird eine einfache Textabfrage definiert:
"text_search": {
"structured_query": {
"text": {
"text": "fox vs dog"
}
}
}
Standardmäßig wird der Text in einzelne Begriffe aufgeteilt und in den angegebenen Feldern nach jedem Begriff gesucht. Im vorherigen Beispiel wird im Feld Title nach den Begriffen „fox“, „vs“ und „dog“ gesucht.
Für Textabfragen sind die folgenden optionalen Parameter verfügbar:
fields: Ein Array von Feldern, mit denen abgeglichen werden soll. Wenn nicht angegeben, wird standardmäßig mit allen Feldern abgeglichen. Felder werden mit einem implizitenOR-Operator abgeglichen.match_type: Der Typ des Abgleichs, der durchgeführt werden soll. Der Übereinstimmungstyp kannEXACTsein. Das bedeutet, dass das Feld genau mit dem Suchtext übereinstimmen muss. Wenn das Feld ein String-Array ist, wird ein Abgleich mit jedem Element im Array durchgeführt.enhancement: Gibtenabledund einenlanguageCodean, sodass Übereinstimmungen mit Synonymen, Wortstämmen, Rechtschreibfehlern und Stoppwörtern in der fürlanguageCodeangegebenen Sprache (z. B.en-US) durchgeführt werden können. Standardmäßig ist keine Erweiterung festgelegt.boost: Optional. Ein Multiplikator, der auf die Punktzahl der Abfrage angewendet wird. Der Standardwert ist1.0.
Übereinstimmungstyp
Der Parameter match_type gibt an, wie der Suchtext mit dem Wert eines Felds übereinstimmt.
Der Wert des Parameters kann Folgendes sein:
EXACT: Das Feld muss genau mit dem Suchbegriff übereinstimmen. Wenn das Feld ein String-Array ist, wird eine Übereinstimmung mit einem beliebigen Element im Array durchgeführt.
Im folgenden Beispiel wird der Abgleichstyp EXACT angegeben:
"text_search": {
"structured_query": {
"text": {
"text": "Fox vs Dog",
"fields": [ "Title" ],
"match_type": "EXACT"
}
}
}
Übereinstimmungstyp für String-Arrays
Die Ergebnisse der Abfrage werden in der folgenden Tabelle angezeigt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 1,0000 | 3 | Fuchs oder Hund | Der schlaue Fuchs überlistet den Hund. | wild, domestic, conflict, caniformia, mammals, interaction |
Wenn das Feld ein String-Array ist, wird der Suchtext mit jedem Array-Element abgeglichen.
Im folgenden Beispiel wird gezeigt, wie Sie im String-Array Keywords nach dem genauen Text wild suchen:
"text_search": {
"structured_query": {
"text": {
"text": "wild",
"fields": [ "Keywords" ],
"match_type": "EXACT"
}
}
}
Die Ergebnisse der Abfrage werden in der folgenden Tabelle angezeigt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 1,0000 | 3 | Fuchs oder Hund | Der schlaue Fuchs überlistet den Hund. | wild, domestic, conflict, caniformia, mammals, interaction |
| 1,0000 | 4 | Braunbären | Schnelle Bewegungen im Wald. | wild, Wald, Bär, Spitzenprädator, Winterschlaf, riesig |
| 1,0000 | 1 | The Quick Brown Fox | Ein schneller brauner Fuchs springt mühelos über den faulen Hund. | wild, Wald, Säugetier, orange, Agilität, Raubtier |
Erweiterungsfunktionen für Suchanfragen
Suchanfragen können einen optionalen queryEnhancement-Parameter enthalten, um sprachspezifische Verbesserungen anzugeben. Dazu gehören der Abgleich mit Synonymen, Wortstämmen (z. B. „springen“ für „springend“), falschen Schreibweisen und Stoppwörtern (z. B. „ein“, „eine“ und „der“).
Der Parameter ist ein Objekt mit den folgenden Eigenschaften:
enabled: Ein boolescher Wert, der angibt, ob Optimierungen aktiviert werden sollen.languageCode: Ein String, der die Sprache für die Optimierungen angibt (z. B.en-US).
Im folgenden Beispiel werden Optimierungen für die Sprache en-US aktiviert:
"text_search": {
"structured_query": {
"text": {
"text": {
"text": "jump",
"fields": [ "Description" ],
"queryEnhancement": {
"enabled": true,
"languageCode": "en-US"
}
}
}
}
}
Die Ergebnisse der Abfrage werden in der folgenden Tabelle angezeigt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 0,3419 | 1 | The Quick Brown Fox | Ein schneller brauner Fuchs springt mühelos über den faulen Hund. | wild, Wald, Säugetier, orange, Agilität, Raubtier |
| 0,3419 | 5 | Eine schlaue Geschichte | Der Hund springt hoch. | Schläue, Sprünge |
Wenn queryEnhancement nicht angegeben wurde oder enabled den Wert false hatte, würde keine Übereinstimmung gefunden werden.
Kombinierte Unterabfragen
Bei kombinierten Abfragen wird ein boolescher Operator auf zwei oder mehr Unterabfragen angewendet. Die unterstützten Vorgänge sind AND und OR.
Kombinierte Abfragen haben die folgenden Eigenschaften:
op: Der boolesche Operator, der auf die Unterabfragen angewendet werden soll. Der Wert kannANDoderORsein.subQueries: Ein Array von Unterabfragen, die kombiniert werden sollen. Dies kann jeder der unterstützten Unterabfragetypen sein, einschließlich anderer kombinierter Abfragen. Die maximale Verschachtelungstiefe beträgt 2.boost: Optional. Ein Multiplikator, der auf die Punktzahl der Abfrage angewendet wird. Der Standardwert ist1.0.
Konjunktion (AND)
Der Operator AND gleicht Datenobjekte ab, die die Begriffe aller Unterabfragen enthalten.
Im folgenden Beispiel wird gezeigt, wie drei Textabfragen mit dem Operator AND kombiniert werden:
"text_search": {
"structured_query": {
"combine": {
"op": "AND",
"subQueries": [
{
"text": {
"text": "Brown",
"fields": [ "Title" ]
}
},
{
"text": {
"text": "quick",
"fields": [ "Description" ]
}
},
{
"text": {
"text": "forest predator",
"fields": [ "Keywords" ]
}
}
]
}
}
}
Im Beispiel werden Übereinstimmungen nur dann gefunden, wenn alle drei Unterabfragen übereinstimmen.
Die Ergebnisse der Abfrage werden in der folgenden Tabelle angezeigt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 5,0587 | 4 | Braunbären | Schnelle Bewegungen im Wald. | wild, Wald, Bär, Spitzenprädator, Winterschlaf, riesig |
| 5,0587 | 1 | The Quick Brown Fox | Ein schneller brauner Fuchs springt mühelos über den faulen Hund. | wild, Wald, Säugetier, orange, Agilität, Raubtier |
Wenn eine Textunterabfrage mehrere Felder enthält, auf die sie angewendet werden soll, wird ein implizites OR angewendet, wie im folgenden Beispiel gezeigt:
"text_search": {
"structured_query": {
"combine": {
"op": "AND",
"subQueries": [
{
"text": {
"text": "Brown",
"fields": [ "Title", "Description" ]
}
},
{
"text": {
"text": "quick",
"fields": [ "Description" ]
}
},
{
"text": {
"text": "forest predator",
"fields": [ "Keywords" ]
}
}
]
}
}
}
Im obigen Beispiel gilt Folgendes:
Die erste Unterabfrage sucht nach dem Begriff
Brown(Groß-/Kleinschreibung wird nicht berücksichtigt) im FeldTitleoderDescription.Die zweite Unterabfrage gleicht den Begriff
quickim FeldDescriptionab, wobei die Groß-/Kleinschreibung nicht berücksichtigt wird.Die dritte Unterabfrage gleicht die Begriffe
forestundpredatorohne Berücksichtigung der Groß-/Kleinschreibung mit allen Werten im String-Array-FeldKeywordsab.Wenn alle drei Unterabfragen übereinstimmen, wird eine Übereinstimmung für die kombinierte Abfrage gefunden.
Die Ergebnisse der Abfrage werden in der folgenden Tabelle angezeigt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 6,3176 | 1 | The Quick Brown Fox | Ein schneller brauner Fuchs springt mühelos über den faulen Hund. | wild, Wald, Säugetier, orange, Agilität, Raubtier |
| 5,0587 | 4 | Braunbären | Schnelle Bewegungen im Wald. | wild, Wald, Bär, Spitzenprädator, Winterschlaf, riesig |
Disjunktion (OR)
Der Operator OR gleicht Datenobjekte ab, die die Begriffe mindestens einer der Unterabfragen enthalten.
Im folgenden Beispiel wird gezeigt, wie drei Textabfragen mit dem Operator OR kombiniert werden:
"text_search": {
"structured_query": {
"combine": {
"op": "OR",
"subQueries": [
{
"text": {
"text": "Brown",
"fields": [ "Title", "Description" ]
}
},
{
"text": {
"text": "quick",
"fields": [ "Description" ]
}
},
{
"text": {
"text": "forest predator",
"fields": [ "Keywords" ]
}
}
]
}
}
}
Im Beispiel wird eine Übereinstimmung gefunden, wenn eine der drei Unterabfragen übereinstimmt.
Die Ergebnisse der Abfrage werden in der folgenden Tabelle angezeigt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 6,3176 | 1 | The Quick Brown Fox | Ein schneller brauner Fuchs springt mühelos über den faulen Hund. | wild, Wald, Säugetier, orange, Agilität, Raubtier |
| 5,0587 | 4 | Braunbären | Schnelle Bewegungen im Wald. | wild, Wald, Bär, Spitzenprädator, Winterschlaf, riesig |
Gruppierung
Kombinierte Unterabfragen können in anderen kombinierten Unterabfragen verschachtelt werden, um die Auswertungsreihenfolge zu steuern.
Das folgende Beispiel zeigt, wie Unterabfragen gruppiert werden:
"text_search": {
"structured_query": {
"combine": {
"op": "AND",
"subQueries": [
{
"combine": {
"op": "OR",
"subQueries": [
{
"text": {
"text": "Fox",
"fields": [ "Title" ]
}
},
{
"text": {
"text": "jumps",
"fields": [ "Description" ]
}
}
]
}
},
{
"unary": {
"op": "NOT",
"subQuery": {
"text": {
"text": "domestic",
"fields": [ "Keywords" ]
}
}
}
}
]
}
}
}
Das vorherige Beispiel entspricht Folgendem:
(Fox ohne Berücksichtigung der Groß-/Kleinschreibung in Title ODER jumps ohne Berücksichtigung der Groß-/Kleinschreibung in Description) UND NICHT domestic ohne Berücksichtigung der Groß-/Kleinschreibung in einem der Keywords-Elemente.
In der folgenden Tabelle sind die Ergebnisse der Abfrage aufgeführt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 3,5178 | 1 | The Quick Brown Fox | Ein schneller brauner Fuchs springt mühelos über den faulen Hund. | wild, Wald, Säugetier, orange, Agilität, Raubtier |
| 2,2589 | 5 | Eine schlaue Geschichte | Der Hund springt hoch. | Schläue, Sprünge |
Unäre Unterabfragen
Unäre Unterabfragen wenden einen booleschen Vorgang auf eine einzelne Unterabfrage in einer strukturierten Abfrage an. Der Operator NOT ist der einzige unterstützte unäre Vorgang.
Unäre Abfragen haben die folgenden Eigenschaften:
op: Der boolesche Operator, der auf die Unterabfrage angewendet werden soll. Der Wert kannNOTsein.subQuery: Die Unterabfrage, auf die der unäre Vorgang angewendet werden soll.boost: Optional. Ein Multiplikator, der auf die Punktzahl der Abfrage angewendet wird. Der Standardwert ist1.0.
Negation (NOT)
Der Operator NOT stimmt mit Datenobjekten überein, die die Begriffe der Unterabfrage nicht enthalten.
Das folgende Beispiel zeigt, wie der Operator NOT verwendet wird:
"text_search": {
"structured_query": {
"unary": {
"op": "NOT",
"subQuery": {
"text": {
"text": "dog",
"fields": [ "Description" ]
}
}
}
}
}
Die Ergebnisse der Abfrage werden in der folgenden Tabelle angezeigt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 1.000 | 4 | Braunbären | Schnelle Bewegungen im Wald. | wild, Wald, Bär, Spitzenprädator, Winterschlaf, riesig |
| 1.000 | 6 | Meine faulen Sommertage | Eine Kurzgeschichte über das Entspannen in den Sommerferien. | Sommer, entspannen, Urlaub, Sonne |
Wenn der Operator NOT auf ein String-Array angewendet wird, stimmt er mit einem Datenobjekt überein, wenn der Begriff in keinem der Elemente des Arrays enthalten ist.
Im Beispiel wird eine Übereinstimmung gefunden, wenn der Begriff orange (Groß-/Kleinschreibung wird nicht berücksichtigt) in keinem Element des String-Arrays Keywords enthalten ist.
"text_search": {
"structured_query": {
"combine": {
"op": "AND",
"subQueries": [
{
"text": {
"text": "Brown",
"fields": [ "Title" ]
}
},
{
"text": {
"text": "quick",
"fields": [ "Description" ]
}
},
{
"text": {
"text": "forest predator",
"fields": [ "Keywords" ]
}
},
{
"unary": {
"op": "NOT",
"subQuery": {
"text": {
"text": "orange",
"fields": [ "Keywords" ]
}
}
}
}
]
}
}
}
Die Ergebnisse der Abfrage werden in der folgenden Tabelle angezeigt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 6,0587 | 4 | Braunbären | Schnelle Bewegungen im Wald. | wild, Wald, Bär, Spitzenprädator, Winterschlaf, riesig |
Boosting
Jede Unterabfrage kann einen boost-Parameter haben, um einen Multiplikator auf die Punktzahl der Unterabfrage anzuwenden. Standardmäßig haben alle Unterabfragen einen boost von 1.0.
Das folgende Beispiel zeigt, wie Sie eine Unterabfrage optimieren:
"text_search": {
"structured_query": {
"combine": {
"op": "OR",
"subQueries": [
{
"text": {
"text": "fox",
"fields": [ "Title" ]
},
"boost": 1.0
},
{
"text": {
"text": "jumps",
"fields": [ "Description" ]
},
"boost": 1.0
},
{
"text": {
"text": "interaction",
"fields": [ "Keywords" ]
},
"boost": 5.0
}
]
}
}
}
Die Ergebnisse der Abfrage werden in der folgenden Tabelle angezeigt:
| Punktzahl | ID | Titel | Beschreibung | Keywords |
|---|---|---|---|---|
| 7,5534 | 3 | Fuchs oder Hund | Der schlaue Fuchs überlistet den Hund. | wild, domestic, conflict, caniformia, mammals, interaction |
| 2,5178 | 1 | The Quick Brown Fox | Ein schneller brauner Fuchs springt mühelos über den faulen Hund. | wild, Wald, Säugetier, orange, Agilität, Raubtier |
| 1,2589 | 5 | Eine schlaue Geschichte | Der Hund springt hoch. | Schläue, Sprünge |
Semantische Suche
Bei dieser Suche wird Ihre Textanfrage in Einbettungen umgewandelt, um Ergebnisse basierend auf der semantischen Bedeutung zu finden. Dabei wird das in Ihrem Schema definierte embedding-config verwendet, um die Abfrageeinbettung zu generieren. Wenn mehrere vector_search-Felder angegeben sind, werden die Ergebnisse mit gleicher Gewichtung kombiniert.
Mit der Hybridsuche suchen
Mit batch_search_data_objects können Sie mehrere Suchen parallel ausführen (Vektorsuche, Textsuche und semantische Suche). Die Ergebnisse können optional mit dem ReciprocalRankFusion-Ranker kombiniert und in ein Ranking eingeordnet werden. Dabei werden Ergebnissätze mithilfe des RRF-Algorithmus (Reciprocal Rank Fusion) zusammengeführt.
Kombinierte Ergebnisse sortieren
Mit combine.sorts können Sie die kombinierten Ergebnisse einer batch_search_data_objects-Anfrage nach Feldern aus dem Datenschema Ihrer Sammlung neu sortieren, z. B. nach Preis aufsteigend, Jahr absteigend oder einem Status-Flag.
combine.sorts ist in der v1beta-Methode batchSearch verfügbar.
Die Sortierung wird auf die kombinierten Ergebnisse nach RRF und, falls konfiguriert, VertexRanker und vor dem Abschneiden von combine.top_k angewendet.
Es werden nur die Kandidaten sortiert, die von den Suchanfragen abgerufen werden, nicht jedes Datenobjekt in der Sammlung. Sie können beispielsweise die drei neuesten Artikel unter den besten semantischen Übereinstimmungen anfordern, wobei bei gleicher Veröffentlichungszeit die Anzahl der Aufrufe ausschlaggebend ist.
Im Beispiel in diesem Abschnitt werden die folgenden Datenobjekte verwendet. Die Veröffentlichungszeit wird sowohl als ISO 8601-String als auch als Unix-Epochennummer gespeichert. Beide Formate werden chronologisch sortiert.
| ID | Titel | published_at | published_unix | Aufrufe |
|---|---|---|---|---|
| a1 | Fed hält Zinssätze stabil | 2026-09-29T14:00:00Z | 1790690400 | 5200 |
| a2 | Märkte erholen sich aufgrund von Gewinnen | 2026-09-29T14:00:00Z | 1790690400 | 8100 |
| a3 | Ölpreise fallen | 2026-09-28T09:30:00Z | 1790587800 | 12.000 |
| a4 | Tech-Aktien erholen sich | 2026-09-30T08:15:00Z | 1790756100 | 3.000 |
| a5 | Anleiherenditen steigen | 2026-09-27T16:45:00Z | 1790527500 | 9000 |
Das folgende Beispiel zeigt den Text einer Anfrage an die v1beta-Methode dataObjects:batchSearch, die die drei neuesten Artikel zurückgibt, wobei bei Gleichstand die höchste Anzahl an Aufrufen ausschlaggebend ist:
{
"searches": [
{
"vector_search": {
"search_field": "embedding",
"vector": { "values": [0.7, 0.3, 0.1] },
"top_k": 5,
"output_fields": { "data_fields": ["title", "published_at", "views"] }
}
}
],
"combine": {
"ranker": { "rrf": { "weights": [1.0] } },
"top_k": 3,
"sorts": [
{ "field": "published_at", "direction": "DESC" },
{ "field": "views", "direction": "DESC" }
]
}
}
Die Ergebnisse der Anfrage werden in der folgenden Tabelle angezeigt. Wenn Sie nach published_unix statt nach published_at sortieren, erhalten Sie dieselbe Reihenfolge.
| ID | Titel | published_at | Aufrufe |
|---|---|---|---|
| a4 | Tech-Aktien erholen sich | 2026-09-30T08:15:00Z | 3.000 |
| a2 | Märkte erholen sich aufgrund von Gewinnen | 2026-09-29T14:00:00Z | 8100 |
| a1 | Fed hält Zinssätze stabil | 2026-09-29T14:00:00Z | 5200 |
Die Datenobjekte a2 und a1 haben denselben published_at-Wert, daher entscheidet views über ihre Reihenfolge. Das Datenobjekt a3 hat die meisten Aufrufe, ist aber älter, sodass es von combine.top_k ausgeschlossen wird.
Sortierfelder in output_fields für geringere Latenz einbeziehen
Um die kombinierten Ergebnisse zu sortieren, benötigt der Dienst den Wert jedes Sortierfelds für jedes Kandidaten-Datenobjekt. Diese Werte werden aus den Daten gelesen, die jede Suche zurückgibt. Dies wird durch den output_fields dieser Suche gesteuert. Wenn bei einem Kandidaten ein Sortierfeld fehlt, ruft der Dienst die fehlenden Felder vor dem Sortieren in einer zusätzlichen Suche aus dem Speicher ab.
Der Dienst überspringt die Suche nur, wenn jede Suche alle Sortierfelder zurückgibt. Dazu gehören auch Suchanfragen, deren Ergebnisse vom Reranker nicht beibehalten werden, da die Sortierung für Kandidaten aus allen Suchanfragen ausgeführt wird. Wenn in einer Suche in der Anfrage ein Sortierfeld weggelassen wird, wird die Suche ausgeführt.
In der folgenden Anfrage wird beispielsweise nach published_at und views sortiert. Die Vektorsuche gibt beide Felder zurück, die Textsuche jedoch nur title. Daher führt der Dienst die zusätzliche Suche durch:
{
"searches": [
{
"vector_search": {
"search_field": "embedding",
"vector": { "values": [0.7, 0.3, 0.1] },
"top_k": 5,
"output_fields": { "data_fields": ["title", "published_at", "views"] }
}
},
{
"text_search": {
"search_text": "rates",
"data_field_names": ["title"],
"top_k": 5,
"output_fields": { "data_fields": ["title"] }
}
}
],
"combine": {
"ranker": { "rrf": { "weights": [1.0, 1.0] } },
"top_k": 3,
"sorts": [
{ "field": "published_at", "direction": "DESC" },
{ "field": "views", "direction": "DESC" }
]
}
}
Wenn Sie die Suche vermeiden möchten, fügen Sie published_at und views auch dem output_fields der Textsuche hinzu:
"output_fields": { "data_fields": ["title", "published_at", "views"] }
Wenn Sie alle Felder mit "data_fields": ["*"] anfordern, wird die Suche ebenfalls vermieden.
Wenn Sie die Sortierfelder nicht in der Antwort haben möchten, können Sie sie aus output_fields weglassen. Die Anfrage liefert dieselben Ergebnisse in derselben Reihenfolge, nur langsamer. Sortierfelder, die keine Suchanfragen in output_fields enthalten, werden aus der Antwort entfernt.
Sortierspezifikation
Jeder Eintrag in combine.sorts enthält die folgenden Felder:
| Feld | Erforderlich | Beschreibung |
|---|---|---|
field |
Ja | Das Datenfeld, nach dem sortiert werden soll. Verwenden Sie Punktpfade für verschachtelte Felder, z. B. product.price. Das Feld muss im Schema der Sammlung vorhanden sein. |
direction |
Optional | Die Sortierrichtung: ASC oder DESC. Der Standardwert ist ASC. |
Die Einträge werden der Reihe nach angewendet. Der erste Eintrag ist der primäre Sortierschlüssel. Jeder nachfolgende Eintrag wird nur verwendet, wenn die vorherigen Einträge keine eindeutige Sortierung ermöglichen. Wenn Sie die Reihenfolge vorhersehbar machen möchten, wenn Werte häufig kollidieren, fügen Sie weitere Einträge hinzu, z. B. year aufsteigend und dann title aufsteigend.
Wenn Datenobjekte in jedem Sortiereintrag gleich sind, wird das Datenobjekt mit der höheren Ranker-Punktzahl zuerst angezeigt. Der Ranker-Score ist der RRF-Score oder der VertexRanker-Score, wenn ein Reranker konfiguriert ist. Wenn die Punktzahlen ebenfalls gleich sind, werden Datenobjekte nach Datenobjekt-ID in aufsteigender Reihenfolge sortiert, sodass dieselbe Anfrage immer Ergebnisse in derselben Reihenfolge zurückgibt.
Sortierbare Feldtypen
Sie können nach Feldern der folgenden Schematypen sortieren:
Zahl (
numberoderinteger): Werte werden als Gleitkommazahlen mit doppelter Genauigkeit verglichen. Daher können Ganzzahlen, die größer als 253 sind, als gleich angesehen werden.Boolesch: In aufsteigender Reihenfolge wird
falsevortruesortiert.String: Werte werden in UTF-8-Bytereihenfolge verglichen, wobei die Groß-/Kleinschreibung berücksichtigt wird. Beispiel:
"Apple"wird vor"Zebra"sortiert, was wiederum vor"apple"sortiert wird. Wenn die Groß-/Kleinschreibung nicht berücksichtigt werden soll, speichern Sie eine normalisierte Kopie des Felds, z. B. eine Kopie in Kleinbuchstaben, und sortieren Sie nach diesem Feld.Datumsangaben und Zeitstempel: Es gibt keinen speziellen Datumstyp. Speichern Sie diese Werte als ISO 8601-UTC-Strings in einem einheitlichen Format oder als Unix-Epochen-Zahlen.
Sie können nicht nach Array- oder Objektfeldern sortieren.
Datenobjekte, die keinen Wert für ein Sortierfeld haben, werden sowohl für ASC als auch für DESC nach allen Datenobjekten platziert, die einen Wert haben.
Interaktion mit Rankern
RRF: RRF führt die Ergebnisse der Suchen zusammen,
combine.sortsordnet die zusammengeführte Liste neu undcombine.top_kkürzt sie dann.VertexRanker:
combine.sortsordnet die Ausgabe des Rerankers (top_n) vor dem Kürzen (combine.top_k) neu an. Die endgültige Reihenfolge richtet sich nach den Sortiereinträgen, nicht nach der Reranker-Punktzahl. Die Antwort enthält eine Warnung im Feldsearch_response_metadata.warningsmit dem CodeFAILED_PRECONDITIONund der Nachricht"Both sort and a Vertex reranker were configured. The final order reflects the sort, not the reranker score.". Die Anfrage ist trotzdem erfolgreich.
Wenn der VertexRanker-Aufruf fehlschlägt, wird stattdessen combine.sorts auf die RRF-fusionierten Ergebnisse angewendet. Weitere Informationen finden Sie unter Fehlerbehandlung und Warnungen.
Fehler
| Fehlercode | Ursache |
|---|---|
INVALID_ARGUMENT |
combine.sorts[i].field ist leer oder das Feld ist nicht im Schema der Sammlung definiert. |
INVALID_ARGUMENT |
combine.sorts[i].direction ist kein gültiger Wert. |
FAILED_PRECONDITION |
combine.sorts[i].field bezieht sich auf ein Feld, das nicht sortiert werden kann, z. B. ein Array- oder Objektfeld. |