Lo scopo dell'API Search è trovare oggetti dati simili a una determinata query e restituire un elenco di risultati classificati (in base alla somiglianza). L'API Search supporta anche i filtri.
L'API Search offre diversi modi per cercare oggetti di dati: ricerca vettoriale, ricerca a testo intero e ricerca semantica. Inoltre, è possibile combinare più ricerche di qualsiasi tipo per ottenere una ricerca ibrida.
Vector Search
Vector Search ti consente di fornire il tuo vettore di query. Questo è il metodo obbligatorio per la ricerca di campi di embedding che non hanno un embedding-config.
Se vengono forniti più campi vector_search, i risultati vengono combinati utilizzando
pesi uguali.
L'esempio seguente mostra come eseguire una ricerca vettoriale su una raccolta con ID COLLECTION_ID.
REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- COLLECTION_ID: l'ID della raccolta.
- LOCATION: la regione in cui utilizzi Agent Platform.
- PROJECT_ID: il tuo ID progetto Google Cloud .
Metodo HTTP e URL:
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
Corpo JSON della richiesta:
{
"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": "*"
}
}
}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{
"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
Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
-
SEARCH_VECTOR_FILE: il percorso locale di un file JSON contenente il vettore denso o sparso con cui eseguire la ricerca.
Esempio di contenuti del file per un vettore denso:
{ "dense": { "values": [ 0.42426406871192845, 0.565685424949238, 0.7071067811865475 ] } }
Esempio di contenuti del file per un vettore sparso:
{ "sparse": { "indices": [1, 5, 10], "values": [0.1, 0.5, 0.21] } }
- COLLECTION_ID: l'ID della raccolta.
- LOCATION: la regione in cui utilizzi Agent Platform.
- PROJECT_ID: il tuo ID progetto Google Cloud .
Esegui questo comando:
Linux, macOS o 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
Dovresti ricevere una risposta simile alla seguente:
---
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)
Ottimizzazione dell'accuratezza e delle prestazioni della ricerca
Per le ricerche Vector Search su indici ANN densi con più di 100.000 embedding, Agent Retrieval, per impostazione predefinita, tenta di fornire un compromesso ottimale tra richiamo e latenza. Puoi ottimizzare questo equilibrio per il tuo caso d'uso specificando un tasso di richiamo target.
I valori devono essere maggiori o uguali a 0.00 e minori o uguali a 1.00.
Per informazioni su come creare un indice ANN, consulta Creazione di un indice ANN.
L'esempio seguente mostra come eseguire una Vector Search su un indice ANN denso con un tasso di richiamo target di 0.95.
REST
Metodo HTTP e URL:
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
Corpo JSON della richiesta:
{
"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
Salva il vettore di query in un file JSON, ad esempio vector.json:
{
"dense": {
"values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]
}
}
Quindi esegui il comando gcloud vector-search collections data-objects search:
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)
Ricerca testo
In questo modo viene eseguita una ricerca a testo intero senza vettori sparsi. Il dialetto di query "word" predefinito tratta l'intero input come singoli termini di ricerca con un operatore AND implicito. Puoi impostare enhanced_query su true per espandere i termini di ricerca, gestire lo stemming, la rimozione delle stop word e consentire operatori di ricerca aggiuntivi:
OR: un operatore di disgiunzione sensibile alle maiuscole che corrisponde ai documenti contenenti almeno uno dei termini specificati. Si applica solo ai due termini adiacenti.": (virgolette doppie) per la ricerca di frasi.-: l'operatore di negazione. Esclude i documenti contenenti i termini che lo precedono.
Ricerca testuale avanzata
L'API di ricerca testuale Agent Retrieval ti consente di esprimere ricerche testuali tramite query strutturate contenenti una o più subquery, consentendoti di:
Crea corrispondenze con campi specifici di Data Objects.
Specifica il tipo di corrispondenza da eseguire:
Per termine, senza distinzione tra maiuscole e minuscole
Esattamente, sensibile alle maiuscole
Includono miglioramenti specifici per lingua per trovare corrispondenze con radici dei termini, sinonimi, errori ortografici e parole non significative (come "un", "uno" e "una").
Utilizza gli operatori booleani
AND,OReNOTper combinare le sottoquery.Controlla l'ordine di valutazione raggruppando le sottoquery.
Aumenta i contributi dei punteggi per influenzare i ranking.
Esistono tre tipi di subquery:
Testo: fornisce il testo di ricerca e uno o più campi da confrontare.
Combinata: applica l'operatore
ANDoORper combinare le subquery e può essere utilizzata per raggruppare altre subquery combinate per controllare l'ordine di valutazione.
Gli esempi in questa pagina utilizzano la raccolta mostrata nella tabella seguente. Contiene sei oggetti dati e definisce i seguenti campi nel relativo schema di dati: le stringhe ID, Title, Description e l'array di stringhe Keywords.
| ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|
| 1 | The Quick Brown Fox | Una rapida volpe marrone salta facilmente sul cane pigro. | selvaggio, foresta, mammifero, arancione, agilità, predatore |
| 2 | Lazy Dog Days | Il cane marrone dorme. | domestico, animale domestico, casa, canino, calmo, pigro, obbediente |
| 3 | Volpe o cane? | La volpe veloce supera il cane. | selvatici, domestici, conflitto, caniformia, mammiferi, interazione |
| 4 | Orsi bruni | Movimenti rapidi nella foresta. | selvaggio, foresta, ursino, superpredatore, letargo, gigante |
| 5 | Una storia astuta | Il cane salta in alto. | astuzia, salti |
| 6 | My Lazy Days of Summer | Una breve storia sul relax durante le vacanze estive. | estate, relax, vacanza, sole |
Sottoquery di testo
Le query di testo corrispondono a uno o più campi di un oggetto dati. Tutte le query strutturate devono contenere almeno una query di testo.
L'esempio seguente definisce una query di testo di base:
"text_search": {
"structured_query": {
"text": {
"text": "fox vs dog"
}
}
}
Per impostazione predefinita, il testo viene suddiviso in singoli termini e ogni termine viene cercato nei campi specificati. Nell'esempio precedente, i termini "fox", "vs" e "dog" vengono cercati nel campo Title.
Le query di testo hanno i seguenti parametri facoltativi:
fields: un array di campi da confrontare. Se non specificato, per impostazione predefinita viene eseguita la corrispondenza con tutti i campi. I campi vengono abbinati a un operatoreORimplicito.match_type: il tipo di corrispondenza da eseguire. Il tipo di corrispondenza può essereEXACT, che specifica che il campo deve corrispondere esattamente al testo di ricerca. Se il campo è un array di stringhe, viene eseguita una corrispondenza con qualsiasi elemento dell'array.enhancement: specificaenablede unlanguageCode, consentendo di eseguire corrispondenze con sinonimi, radici, errori ortografici e parole non significative nella lingua specificata perlanguageCode(ad esempio,en-US). Il valore predefinito è nessun miglioramento.boost: (Facoltativo) Un moltiplicatore da applicare al punteggio della query. Il valore predefinito è1.0.
Tipo di corrispondenza
Il parametro match_type specifica in che modo il testo di ricerca corrisponde al valore di un campo.
Il valore del parametro può essere:
EXACT: il campo deve corrispondere esattamente al termine di ricerca. Se il campo è un array di stringhe, viene eseguita una corrispondenza con qualsiasi elemento dell'array.
L'esempio seguente specifica il tipo di corrispondenza EXACT:
"text_search": {
"structured_query": {
"text": {
"text": "Fox vs Dog",
"fields": [ "Title" ],
"match_type": "EXACT"
}
}
}
Tipo di corrispondenza per gli array di stringhe
I risultati della query sono mostrati nella tabella seguente:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 1,0000 | 3 | Volpe o cane? | La volpe veloce supera il cane. | selvatici, domestici, conflitto, caniformia, mammiferi, interazione |
Quando il campo è un array di stringhe, il testo di ricerca viene confrontato con qualsiasi elemento dell'array.
L'esempio seguente mostra come cercare il testo esatto wild nell'array di stringhe Keywords:
"text_search": {
"structured_query": {
"text": {
"text": "wild",
"fields": [ "Keywords" ],
"match_type": "EXACT"
}
}
}
I risultati della query sono mostrati nella tabella seguente:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 1,0000 | 3 | Volpe o cane? | La volpe veloce supera il cane. | selvatici, domestici, conflitto, caniformia, mammiferi, interazione |
| 1,0000 | 4 | Orsi bruni | Movimenti rapidi nella foresta. | selvaggio, foresta, ursino, superpredatore, letargo, gigante |
| 1,0000 | 1 | The Quick Brown Fox | Una rapida volpe marrone salta facilmente sul cane pigro. | selvaggio, foresta, mammifero, arancione, agilità, predatore |
Miglioramenti delle query
Le query di ricerca possono includere un parametro queryEnhancement facoltativo per specificare
miglioramenti specifici per la lingua. Sono incluse le corrispondenze con sinonimi, radici (ad esempio, la radice "salt" di "saltare"), errori ortografici e parole non significative (come "un", "uno" e "una").
Il parametro è un oggetto con le seguenti proprietà:
enabled: un valore booleano che specifica se attivare i miglioramenti.languageCode: una stringa che specifica la lingua per i miglioramenti (ad esempioen-US).
L'esempio seguente attiva i miglioramenti per la lingua en-US:
"text_search": {
"structured_query": {
"text": {
"text": {
"text": "jump",
"fields": [ "Description" ],
"queryEnhancement": {
"enabled": true,
"languageCode": "en-US"
}
}
}
}
}
I risultati della query sono mostrati nella tabella seguente:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 0,3419 | 1 | The Quick Brown Fox | Una rapida volpe marrone salta facilmente sul cane pigro. | selvaggio, foresta, mammifero, arancione, agilità, predatore |
| 0,3419 | 5 | Una storia astuta | Il cane salta in alto. | astuzia, salti |
Se queryEnhancement non è stato specificato o enabled era false, non verrà trovata alcuna corrispondenza.
Sottoquery combinate
Le query combinate applicano un'operazione booleana a due o più sottoquery. Le operazioni supportate sono AND e OR.
Le query combinate hanno le seguenti proprietà:
op: l'operatore booleano da applicare alle sottoquery. Il valore può essereANDoOR.subQueries: un array di sottoquery da combinare. Possono essere uno qualsiasi dei tipi di subquery supportati, incluse altre query combinate. La profondità massima di nidificazione è 2.boost: (Facoltativo) Un moltiplicatore da applicare al punteggio della query. Il valore predefinito è1.0.
Congiunzione (AND)
L'operatore AND trova gli oggetti dati che contengono i termini di tutte le sottoquery.
L'esempio seguente mostra come combinare tre query di testo utilizzando l'operatore AND:
"text_search": {
"structured_query": {
"combine": {
"op": "AND",
"subQueries": [
{
"text": {
"text": "Brown",
"fields": [ "Title" ]
}
},
{
"text": {
"text": "quick",
"fields": [ "Description" ]
}
},
{
"text": {
"text": "forest predator",
"fields": [ "Keywords" ]
}
}
]
}
}
}
Nell'esempio, le corrispondenze vengono trovate solo se tutte e tre le query secondarie corrispondono.
I risultati della query sono mostrati nella tabella seguente:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 5,0587 | 4 | Orsi bruni | Movimenti rapidi nella foresta. | selvaggio, foresta, ursino, superpredatore, letargo, gigante |
| 5,0587 | 1 | The Quick Brown Fox | Una rapida volpe marrone salta facilmente sul cane pigro. | selvaggio, foresta, mammifero, arancione, agilità, predatore |
Quando una sottoquery di testo ha più campi per i quali trovare corrispondenze, viene applicato un OR implicito, come mostrato nell'esempio seguente:
"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" ]
}
}
]
}
}
}
Nell'esempio precedente:
La prima sottoquery corrisponde al termine senza distinzione tra maiuscole e minuscole
Brownnel campoTitleoDescription.La seconda subquery corrisponde al termine
quicksenza distinzione tra maiuscole e minuscole nel campoDescription.La terza subquery corrisponde ai termini senza distinzione tra maiuscole e minuscole
forestepredatorin uno qualsiasi dei valori nel campo dell'array di stringheKeywords.Se tutte e tre le sottoquery corrispondono, viene trovata una corrispondenza per la query combinata.
I risultati della query sono mostrati nella tabella seguente:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 6,3176 | 1 | The Quick Brown Fox | Una rapida volpe marrone salta facilmente sul cane pigro. | selvaggio, foresta, mammifero, arancione, agilità, predatore |
| 5,0587 | 4 | Orsi bruni | Movimenti rapidi nella foresta. | selvaggio, foresta, ursino, superpredatore, letargo, gigante |
Disgiunzione (OR)
L'operatore OR corrisponde agli oggetti dati che contengono i termini di almeno una delle
sottoquery.
L'esempio seguente mostra come combinare tre query di testo utilizzando l'operatore OR:
"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" ]
}
}
]
}
}
}
Nell'esempio, viene trovata una corrispondenza se una delle tre sottoquery corrisponde.
I risultati della query sono mostrati nella tabella seguente:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 6,3176 | 1 | The Quick Brown Fox | Una rapida volpe marrone salta facilmente sul cane pigro. | selvaggio, foresta, mammifero, arancione, agilità, predatore |
| 5,0587 | 4 | Orsi bruni | Movimenti rapidi nella foresta. | selvaggio, foresta, ursino, superpredatore, letargo, gigante |
Raggruppamento
Le sottoquery combinate possono essere nidificate all'interno di altre sottoquery combinate per controllare l'ordine di valutazione.
L'esempio seguente mostra come raggruppare le sottoquery:
"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" ]
}
}
}
}
]
}
}
}
L'esempio precedente equivale a quanto segue:
(Fox senza distinzione tra maiuscole e minuscole in Title OR jumps senza distinzione tra maiuscole e minuscole in Description) AND NOT domestic senza distinzione tra maiuscole e minuscole in uno qualsiasi degli elementi Keywords.
La tabella seguente mostra i risultati della query:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 3,5178 | 1 | The Quick Brown Fox | Una rapida volpe marrone salta facilmente sul cane pigro. | selvaggio, foresta, mammifero, arancione, agilità, predatore |
| 2,2589 | 5 | Una storia astuta | Il cane salta in alto. | astuzia, salti |
Subquery unarie
Le sottoquery unarie applicano un'operazione booleana a una singola sottoquery in una query strutturata. L'operatore NOT è l'unica operazione unaria supportata.
Le query unarie hanno le seguenti proprietà:
op: l'operatore booleano da applicare alla sottoquery. Il valore può essereNOT.subQuery: la sottoquery a cui applicare l'operazione unaria.boost: (Facoltativo) Un moltiplicatore da applicare al punteggio della query. Il valore predefinito è1.0.
Negazione (NOT)
L'operatore NOT corrisponde agli oggetti dati che non contengono i termini della
subquery.
L'esempio seguente mostra come utilizzare l'operatore NOT:
"text_search": {
"structured_query": {
"unary": {
"op": "NOT",
"subQuery": {
"text": {
"text": "dog",
"fields": [ "Description" ]
}
}
}
}
}
I risultati della query sono mostrati nella tabella seguente:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 1000 | 4 | Orsi bruni | Movimenti rapidi nella foresta. | selvaggio, foresta, ursino, superpredatore, letargo, gigante |
| 1000 | 6 | My Lazy Days of Summer | Una breve storia sul relax durante le vacanze estive. | estate, relax, vacanza, sole |
Se applicato a un array di stringhe, l'operatore NOT corrisponde a un oggetto dati se il termine non è contenuto in nessuno degli elementi dell'array.
Nell'esempio, viene trovata una corrispondenza se il termine orange, senza distinzione tra maiuscole e minuscole, non è contenuto in nessun elemento dell'array di stringhe Keywords.
"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" ]
}
}
}
}
]
}
}
}
I risultati della query sono mostrati nella tabella seguente:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 6.0587 | 4 | Orsi bruni | Movimenti rapidi nella foresta. | selvaggio, foresta, ursino, superpredatore, letargo, gigante |
Potenziamento
Qualsiasi subquery può avere un parametro boost per applicare un moltiplicatore al punteggio della subquery. Per impostazione predefinita, tutte le query secondarie hanno un boost di 1.0.
L'esempio seguente mostra come eseguire il boosting di una sottoquery:
"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
}
]
}
}
}
I risultati della query sono mostrati nella tabella seguente:
| Punteggio | ID | Titolo | Descrizione | Parole chiave |
|---|---|---|---|---|
| 7,5534 | 3 | Volpe o cane? | La volpe veloce supera il cane. | selvatici, domestici, conflitto, caniformia, mammiferi, interazione |
| 2,5178 | 1 | The Quick Brown Fox | Una rapida volpe marrone salta facilmente sul cane pigro. | selvaggio, foresta, mammifero, arancione, agilità, predatore |
| 1,2589 | 5 | Una storia astuta | Il cane salta in alto. | astuzia, salti |
Ricerca semantica
Questa ricerca converte la query di testo in embedding per trovare risultati in base al significato semantico. Utilizza il embedding-config definito nello schema per generare l'embedding della query. Se vengono forniti più campi vector_search, i risultati vengono combinati utilizzando pesi uguali.
Ricerca utilizzando la ricerca ibrida
Utilizza batch_search_data_objects per eseguire più ricerche in parallelo (ricerca vettoriale, ricerca testuale e ricerca semantica). I risultati possono essere facoltativamente combinati e classificati utilizzando il ranker ReciprocalRankFusion, che unisce i set di risultati utilizzando l'algoritmo Reciprocal Rank Fusion (RRF).
Ordinamento dei risultati combinati
Utilizza combine.sorts per riordinare i risultati combinati di una richiesta batch_search_data_objects in base ai campi dello schema dei dati della tua raccolta, ad esempio prezzo crescente, anno decrescente o un flag di stato.
combine.sorts è disponibile nel metodo v1beta
batchSearch.
L'ordinamento viene applicato ai risultati combinati dopo RRF e, se configurato,
VertexRanker, e prima del troncamento di combine.top_k.
Vengono ordinati solo i candidati recuperati dalle ricerche, non tutti gli oggetti dati della raccolta. Ad esempio, puoi richiedere i tre articoli più recenti tra le corrispondenze semantiche principali, con i pareggi sul tempo di pubblicazione risolti in base al numero di visualizzazioni, in un'unica richiesta.
L'esempio in questa sezione utilizza i seguenti oggetti di dati. L'ora di pubblicazione viene memorizzata sia come stringa ISO 8601 sia come numero di epoca di Unix. Entrambi i formati vengono ordinati in ordine cronologico.
| ID | titolo | published_at | published_unix | autorizzate |
|---|---|---|---|---|
| a1 | La Fed mantiene i tassi invariati | 2026-09-29T14:00:00Z | 1790690400 | 5200 |
| a2 | I mercati si riprendono grazie agli utili | 2026-09-29T14:00:00Z | 1790690400 | 8100 |
| a3 | I prezzi del petrolio scendono | 2026-09-28T09:30:00Z | 1790587800 | 12000 |
| a4 | Rimbalzo dei titoli tecnologici | 2026-09-30T08:15:00Z | 1790756100 | 3000 |
| a5 | I rendimenti delle obbligazioni aumentano | 2026-09-27T16:45:00Z | 1790527500 | 9000 |
L'esempio seguente mostra il corpo di una richiesta al metodo v1beta dataObjects:batchSearch che restituisce i tre articoli più recenti, con i pareggi risolti in base al numero di visualizzazioni più elevato:
{
"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" }
]
}
}
I risultati della richiesta sono mostrati nella tabella seguente. L'ordinamento in base a published_unix anziché a published_at restituisce lo stesso ordine.
| ID | titolo | published_at | autorizzate |
|---|---|---|---|
| a4 | Rimbalzo dei titoli tecnologici | 2026-09-30T08:15:00Z | 3000 |
| a2 | I mercati si riprendono grazie agli utili | 2026-09-29T14:00:00Z | 8100 |
| a1 | La Fed mantiene i tassi invariati | 2026-09-29T14:00:00Z | 5200 |
Gli oggetti dati a2 e a1 hanno lo stesso valore published_at, quindi views
decide il loro ordine. L'oggetto dati a3 ha il maggior numero di visualizzazioni, ma è più vecchio, quindi combine.top_k lo esclude.
Includi i campi di ordinamento in output_fields per una latenza inferiore
Per ordinare i risultati combinati, il servizio richiede il valore di ogni campo di ordinamento per ogni oggetto dati candidato. Legge questi valori dai dati restituiti da ogni ricerca, che è controllata dal output_fields della ricerca. Se un candidato non ha un campo di ordinamento, il servizio recupera i campi mancanti dallo spazio di archiviazione in una ricerca aggiuntiva prima dell'ordinamento.
Il servizio salta la ricerca solo quando ogni ricerca restituisce ogni campo di ordinamento. Sono incluse le ricerche i cui risultati non vengono conservati dal reranker, perché l'ordinamento viene eseguito sui candidati di tutte le ricerche. Se una ricerca nella richiesta omette un campo di ordinamento, la richiesta esegue la ricerca.
Ad esempio, la seguente richiesta ordina per published_at e views. La Vector Search restituisce entrambi i campi, ma la Ricerca testuale restituisce solo title, quindi il servizio esegue la ricerca aggiuntiva:
{
"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" }
]
}
}
Per evitare la ricerca, aggiungi published_at e views anche al parametro output_fields della Ricerca testuale:
"output_fields": { "data_fields": ["title", "published_at", "views"] }
Anche la richiesta di tutti i campi con "data_fields": ["*"] evita la ricerca.
Se non vuoi i campi di ordinamento nella risposta, puoi comunque ometterli da output_fields. La richiesta restituisce gli stessi risultati nello stesso ordine, ma più lentamente. I campi di ordinamento che non contengono richieste di ricerca in output_fields vengono rimossi dalla risposta.
Specifica di ordinamento
Ogni voce in combine.sorts ha i seguenti campi:
| Campo | Obbligatorio | Descrizione |
|---|---|---|
field |
Sì | Il campo di dati in base al quale ordinare. Utilizza percorsi con punti per i campi nidificati, ad esempio product.price. Il campo deve esistere nello schema della raccolta. |
direction |
Facoltativo | La direzione di ordinamento: ASC o DESC. Il valore predefinito è ASC. |
Le voci vengono applicate in ordine. La prima voce è la chiave di ordinamento principale e ogni voce successiva risolve solo i pareggi lasciati dalle voci precedenti. Per rendere l'ordine prevedibile quando i valori spesso entrano in conflitto, aggiungi altre voci, ad esempio year in ordine crescente e poi title in ordine crescente.
Quando gli oggetti dati sono uguali in ogni voce di ordinamento, l'oggetto dati con il punteggio di ranking più alto viene visualizzato per primo. Il punteggio del ranker è il punteggio RRF o il punteggio VertexRanker se è configurato un reranker. Se anche i punteggi sono uguali, gli oggetti dati vengono ordinati in base all'ID oggetto dati in ordine crescente, in modo che la stessa richiesta restituisca sempre i risultati nello stesso ordine.
Tipi di campi ordinabili
Puoi ordinare in base ai campi dei seguenti tipi di schema:
Numero (
numberointeger): i valori vengono confrontati come numeri in rappresentazione in virgola mobile a doppia precisione, pertanto i numeri interi maggiori di 253 potrebbero essere considerati uguali.Booleano: in ordine crescente,
falseviene ordinato prima ditrue.Stringa: i valori vengono confrontati nell'ordine dei byte UTF-8, che è sensibile alle maiuscole. Ad esempio,
"Apple"viene ordinato prima di"Zebra", che viene ordinato prima di"apple". Per l'ordinamento senza distinzione tra maiuscole e minuscole, archivia una copia normalizzata del campo, ad esempio una copia in minuscolo, e ordina in base a quel campo.Date e timestamp: non esiste un tipo di data dedicato. Memorizza questi valori come stringhe UTC ISO 8601 in un formato coerente o come numeri di epoca di Unix.
Non puoi ordinare in base ai campi di array o oggetti.
Gli oggetti dati che non hanno un valore per un campo di ordinamento vengono posizionati dopo tutti gli oggetti dati che lo hanno, sia per ASC che per DESC.
Interazione con i sistemi di ranking
RRF: RRF unisce i risultati delle ricerche,
combine.sortsriordina l'elenco unito e poicombine.top_klo tronca.VertexRanker:
combine.sortsriordina l'output ditop_ndel reranker prima del troncamento dicombine.top_k. L'ordine finale segue le voci di ordinamento, non il punteggio del reranker. La risposta include un avviso nel camposearch_response_metadata.warningscon il codiceFAILED_PRECONDITIONe il messaggio"Both sort and a Vertex reranker were configured. The final order reflects the sort, not the reranker score.". La richiesta viene comunque eseguita correttamente.
Se la chiamata VertexRanker non va a buon fine, ai risultati uniti con RRF viene applicato combine.sorts. Per saperne di più, consulta
Gestione degli errori e avvisi.
Errori
| Codice di errore | Causa |
|---|---|
INVALID_ARGUMENT |
combine.sorts[i].field è vuoto o il campo non è definito nello schema della raccolta. |
INVALID_ARGUMENT |
combine.sorts[i].direction non è un valore valido. |
FAILED_PRECONDITION |
combine.sorts[i].field fa riferimento a un campo che non può essere ordinato, ad esempio un campo di array o di oggetti. |