Ricerca di oggetti di dati

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 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)

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.

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, OR e NOT per 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.

  • Unario: applica un'operazione NOT a una singola subquery.

  • Combinata: applica l'operatore AND o OR per 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 operatore OR implicito.

  • match_type: il tipo di corrispondenza da eseguire. Il tipo di corrispondenza può essere EXACT, 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: specifica enabled e un languageCode, consentendo di eseguire corrispondenze con sinonimi, radici, errori ortografici e parole non significative nella lingua specificata per languageCode (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 esempio en-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ò essere AND o OR.

  • 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 Brown nel campo Title o Description.

  • La seconda subquery corrisponde al termine quick senza distinzione tra maiuscole e minuscole nel campo Description.

  • La terza subquery corrisponde ai termini senza distinzione tra maiuscole e minuscole forest e predator in uno qualsiasi dei valori nel campo dell'array di stringhe Keywords.

  • 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ò essere NOT.

  • 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

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.

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 (number o integer): 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, false viene ordinato prima di true.

  • 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.sorts riordina l'elenco unito e poi combine.top_k lo tronca.

  • VertexRanker: combine.sorts riordina l'output di top_n del reranker prima del troncamento di combine.top_k. L'ordine finale segue le voci di ordinamento, non il punteggio del reranker. La risposta include un avviso nel campo search_response_metadata.warnings con il codice FAILED_PRECONDITION e 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.