Ricerca di oggetti di dati

Lo scopo dell'API Search è trovare oggetti di dati simili a una determinata query e restituire un elenco di risultati classificati (in base alla somiglianza). L'API Search supporta anche il filtraggio.

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.

La ricerca vettoriale ti consente di fornire il tuo vettore di query. Questo è il metodo obbligatorio per la ricerca di campi di incorporamento 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 in una raccolta con l'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 Cloud de Confiance by S3NS ID progetto.

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 Cloud de Confiance by S3NS ID progetto.

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 della precisione e del rendimento della ricerca

Per le ricerche vettoriali su indici ANN densi con più di 100.000 embedding, Agent Retrieval tenta per impostazione predefinita di fornire un compromesso ottimale tra richiamo e latenza. Puoi perfezionare 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, vai a Creazione di un indice ANN.

Il seguente esempio mostra come eseguire una ricerca vettoriale su un indice ANN denso con un tasso di recupero 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 della 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

Esegue la ricerca a testo intero senza vettori sparsi. Il dialetto della query "parola" 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 le variazioni, rimuovere le 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 che contengono i termini che lo precedono.

Ricerca avanzata di testo

L'API di ricerca testuale Agent Retrieval consente di esprimere le ricerche testuali tramite query strutturate contenenti una o più query secondarie, consentendoti di:

  • Corrispondenza con campi specifici degli oggetti di dati.

  • Specifica il tipo di corrispondenza da eseguire:

    • Per termine, senza distinzione tra maiuscole e minuscole

    • Esattamente, sensibile alle maiuscole

  • Includi miglioramenti per lingua per la corrispondenza con le radici dei termini, sinonimi, errori ortografici e stop word (come "un", "una" e "il").

  • Utilizza gli operatori booleani AND, OR e NOT per combinare le sottoquery.

  • Controlla l'ordine di valutazione raggruppando le sottoquery.

  • Aumenta i contributi al punteggio 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 sottoquery.

  • Combinato: applica l'operatore AND o OR per combinare le sottoquery e può essere utilizzato per raggruppare altre sottoquery combinate per controllare l'ordine di valutazione.

Gli esempi in questa pagina utilizzano la raccolta mostrata nella tabella seguente. Contiene sei oggetti di dati e definisce i seguenti campi nello schema dei 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 sopra il 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 contro cane La volpe astuta inganna il cane. selvaggio, domestico, conflitto, caniformi, mammiferi, interazione
4 Brown Bears Movimenti rapidi nella foresta. selvaggio, foresta, orso, predatore all'apice, 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 vengono confrontate con uno o più campi in 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 "volpe", "vs" e "cane" vengono cercati nel campo Title.

Le query di testo hanno i seguenti parametri facoltativi:

  • fields: un array di campi da confrontare. Se non specificato, il valore predefinito è la corrispondenza con tutti i campi. I campi vengono abbinati con 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 stop word 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 della query. Se il campo è un array di stringhe, la corrispondenza viene eseguita 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 vengono visualizzati nella tabella seguente:

Punteggio ID Titolo Descrizione Parole chiave
1.0000 3 Volpe contro cane La volpe astuta inganna il cane. selvaggio, domestico, conflitto, caniformi, 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 vengono visualizzati nella tabella seguente:

Punteggio ID Titolo Descrizione Parole chiave
1.0000 3 Volpe contro cane La volpe astuta inganna il cane. selvaggio, domestico, conflitto, caniformi, mammiferi, interazione
1.0000 4 Brown Bears Movimenti rapidi nella foresta. selvaggio, foresta, orso, predatore all'apice, letargo, gigante
1.0000 1 The Quick Brown Fox Una rapida volpe marrone salta facilmente sopra il cane pigro. selvaggio, foresta, mammifero, arancione, agilità, predatore

Miglioramenti alle query

Le query di ricerca possono includere un parametro queryEnhancement facoltativo per specificare miglioramenti specifici per la lingua. Ciò include la corrispondenza con sinonimi, radici (ad esempio, la radice "salta" di "saltare"), ortografia errata e stop word (come "un", "una" e "il").

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

Il seguente esempio 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 vengono visualizzati nella tabella seguente:

Punteggio ID Titolo Descrizione Parole chiave
0,3419 1 The Quick Brown Fox Una rapida volpe marrone salta facilmente sopra il 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. Questi possono essere uno qualsiasi dei tipi di sottoquery supportati, incluse altre query combinate. Esiste una profondità di nidificazione massima di 2.

    • boost: (Facoltativo) Un moltiplicatore da applicare al punteggio della query. Il valore predefinito è 1.0.

Congiunzione (AND)

L'operatore AND corrisponde agli 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 create solo se tutte e tre le sottoquery corrispondono.

I risultati della query vengono visualizzati nella tabella seguente:

Punteggio ID Titolo Descrizione Parole chiave
5,0587 4 Brown Bears Movimenti rapidi nella foresta. selvaggio, foresta, orso, predatore all'apice, letargo, gigante
5,0587 1 The Quick Brown Fox Una rapida volpe marrone salta facilmente sopra il cane pigro. selvaggio, foresta, mammifero, arancione, agilità, predatore

Quando una sottoquery di testo ha più campi su cui 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 sottoquery corrisponde al termine quick senza distinzione tra maiuscole e minuscole nel campo Description.

  • La terza sottoquery 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 nella query combinata.

I risultati della query vengono visualizzati nella tabella seguente:

Punteggio ID Titolo Descrizione Parole chiave
6,3176 1 The Quick Brown Fox Una rapida volpe marrone salta facilmente sopra il cane pigro. selvaggio, foresta, mammifero, arancione, agilità, predatore
5,0587 4 Brown Bears Movimenti rapidi nella foresta. selvaggio, foresta, orso, predatore all'apice, 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 vengono visualizzati nella tabella seguente:

Punteggio ID Titolo Descrizione Parole chiave
6,3176 1 The Quick Brown Fox Una rapida volpe marrone salta facilmente sopra il cane pigro. selvaggio, foresta, mammifero, arancione, agilità, predatore
5,0587 4 Brown Bears Movimenti rapidi nella foresta. selvaggio, foresta, orso, predatore all'apice, letargo, gigante

Raggruppamento

Le sottoquery combinate possono essere nidificate all'interno di altre sottoquery combinate per controllare l'ordine di valutazione.

Il seguente esempio 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 è equivalente al seguente: (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 seguente tabella mostra i risultati della query:

Punteggio ID Titolo Descrizione Parole chiave
3.5178 1 The Quick Brown Fox Una rapida volpe marrone salta facilmente sopra il cane pigro. selvaggio, foresta, mammifero, arancione, agilità, predatore
2,2589 5 Una storia astuta Il cane salta in alto. astuzia, salti

Sottoquery 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 sottoquery.

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 vengono visualizzati nella tabella seguente:

Punteggio ID Titolo Descrizione Parole chiave
1000 4 Brown Bears Movimenti rapidi nella foresta. selvaggio, foresta, orso, predatore all'apice, 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 alcun 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 vengono visualizzati nella tabella seguente:

Punteggio ID Titolo Descrizione Parole chiave
6.0587 4 Brown Bears Movimenti rapidi nella foresta. selvaggio, foresta, orso, predatore all'apice, letargo, gigante

Potenziamento

Qualsiasi sottoquery può avere un parametro boost per applicare un moltiplicatore al punteggio della sottoquery. Per impostazione predefinita, tutte le sottoquery hanno un boost di 1.0.

Il seguente esempio mostra come aumentare l'importanza 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 vengono visualizzati nella tabella seguente:

Punteggio ID Titolo Descrizione Parole chiave
7,5534 3 Volpe contro cane La volpe astuta inganna il cane. selvaggio, domestico, conflitto, caniformi, mammiferi, interazione
2,5178 1 The Quick Brown Fox Una rapida volpe marrone salta facilmente sopra il 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 basati sul significato semantico. Utilizza embedding-config definito nello schema per generare l'incorporamento 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 di testo e ricerca semantica). I risultati possono essere combinati e classificati utilizzando il ranker ReciprocalRankFusion, che unisce i set di risultati utilizzando l'algoritmo Reciprocal Rank Fusion (RRF).