Method: projects.locations.dataStores.documents.search

Recherche dans les documents d'un seul datastore.

Renvoie des segments de sous-documents classés, chacun renvoyant au document d'origine et contenant la provenance nécessaire pour le citer.

Requête HTTP

POST https://vectorsearch.googleapis.com/v1beta/{parent}/documents:search

Paramètres de chemin d'accès

Paramètres
parent

string

Obligatoire. Le datastore dans lequel effectuer la recherche. Format : projects/{project}/locations/{location}/dataStores/{dataStore}

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON
{
  "topK": integer,
  "documentIds": [
    string
  ],
  "rankingSpec": {
    object (RankingSpec)
  },
  "filter": {
    object
  },
  "outputFields": {
    object (OutputFields)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "textQuery": {
    object (TextQuery)
  }
  // End of mutually exclusive fields.
}
Champs
topK

integer

Facultatif. Nombre de résultats à renvoyer. Valeur par défaut : 10 Les valeurs supérieures à 100 sont réduites à 100.

documentIds[]

string

Facultatif. Limitez la recherche à ces ID de document. 100 max. Si ce champ est vide, l'intégralité du datastore est recherchée.

rankingSpec

object (RankingSpec)

Facultatif. Contrôle le classement des résultats.

filter

object (Struct format)

Facultatif. Limite la recherche aux segments correspondant à ce filtre, un objet JSON sur les chemins d'accès aux champs d'un DocumentSearchResult :

  • metadata.<property> : propriété déclarée dans le documentMetadataSchema du DataStore, par exemple metadata.category.
  • unstructured_details.page_range.start_page et .end_page : pour un DataStore UNSTRUCTURED. Tous les segments n'ont pas de plage de pages. Voir UnstructuredSegmentDetails.page_range.
  • video_details.start_offset et .end_offset : en secondes, pour un DataStore VIDEO.

Comparaisons : $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $all et $exists. Combinez-les avec $and, $or et $not, imbriqués sur deux niveaux au maximum. Exemple :

{"$and": [{"metadata.year": {"$gte": 2025}}, {"unstructured_details.page_range.start_page": {"$lte": 20}}]}

outputFields

object (OutputFields)

Facultatif. Champs à renvoyer pour chaque résultat.

Obligatoire. Requête à rechercher. Vous devez définir un seul type de requête. Voici une liste de champs mutuellement exclusifs. Au maximum, un des champs sera défini dans une réponse :
textQuery

object (TextQuery)

Une requête textuelle.

Fin des champs mutuellement exclusifs.

Corps de la réponse

Message de réponse pour DocumentSearchService.SearchDocuments.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation JSON
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
Champs
results[]

object (DocumentSearchResult)

Uniquement en sortie. Segments de document correspondant aux critères de recherche, classés par pertinence.

warnings[]

object (Status)

Uniquement en sortie. Avertissements ou erreurs non fatales survenus lors de l'exécution.

Niveaux d'accès des autorisations

Nécessite l'un des niveaux d'accès OAuth suivants :

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/vectorsearch
  • https://www.googleapis.com/auth/vectorsearch.readonly

Pour plus d'informations, consultez la Authentication Overview.

TextQuery

Une requête textuelle.

Représentation JSON
{
  "text": string
}
Champs
text

string

Obligatoire. Texte à rechercher.

RankingSpec

Contrôle le classement des résultats.

Représentation JSON
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
Champs
rerankingSpec

object (RerankingSpec)

Facultatif. Contrôle l'étape de reclassement.

RerankingSpec

Configuration du reclassement sémantique appliqué aux résultats candidats après la récupération hybride et la fusion de classement réciproque (RRF).

Représentation JSON
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
Champs
enabled

boolean

Facultatif. Indique si les résultats fusionnés doivent être reclassés. La valeur par défaut est "false" : les résultats sont renvoyés dans l'ordre de fusion RRF, sauf si l'appelant active l'option.

Lorsqu'il est activé, le reclassement utilise semantic-ranker-fast@latest sur le service de classement Vertex et nécessite l'activation de l'API Discovery Engine sur le projet de l'appelant.

Non compatible avec un datastore VIDEO : une requête qui l'active échoue avec INVALID_ARGUMENT.

rankOversamplingFactor

integer

Facultatif. Facteur de suréchantillonnage des candidats avant le reclassement. Le nombre total de candidats récupérés pour le reclassement est de min(rankOversamplingFactor * topK, 200). Après le reclassement, les résultats sont limités à SearchDocumentsRequest.top_k.

Ignoré, sauf si enabled est défini sur "true". Lorsqu'il est activé, la valeur par défaut est de 5 (récupération de min(5 * topK, 200) candidats, avec un maximum de 200).

Pour reclasser sans suréchantillonnage, définissez ce champ sur 1.

OutputFields

Champs à renvoyer pour chaque DocumentSearchResult, en plus de ceux que chaque résultat comporte.

Représentation JSON
{
  "metadata": [
    string
  ]
}
Champs
metadata[]

string

Facultatif. Propriétés de métadonnées à renvoyer dans DocumentSearchResult.document.metadata, nommées comme déclaré dans le documentMetadataSchema du DataStore. Une propriété imbriquée est nommée par son chemin d'accès séparé par des points, par exemple address.city, sans le préfixe metadata. utilisé par filter. "*" renvoie toutes les propriétés déclarées. "Unset" ne renvoie rien. Une propriété pour laquelle le document n'a pas de valeur est omise.

DocumentSearchResult

Un seul segment correspondant d'un document.

Représentation JSON
{
  "document": {
    object (Document)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "videoDetails": {
    object (VideoSegmentDetails)
  },
  "unstructuredDetails": {
    object (UnstructuredSegmentDetails)
  }
  // End of mutually exclusive fields.
}
Champs
document

object (Document)

Uniquement en sortie. Le document d'où provient ce segment, y compris son nom de ressource et l'emplacement Cloud Storage d'où il a été ingéré.

Notez que tous les champs du document ne sont pas renseignés. Pour obtenir le document complet, appelez documents.get sur le nom du document renvoyé.

Détails de l'emplacement du segment dans son document. Le champ défini suit le document_type du DataStore parent. Voici une liste de champs mutuellement exclusifs. Au maximum, un des champs sera défini dans une réponse :
videoDetails

object (VideoSegmentDetails)

Définissez ce paramètre lorsque le documentType du datastore parent est VIDEO.

unstructuredDetails

object (UnstructuredSegmentDetails)

Définissez ce paramètre lorsque le documentType du datastore parent est UNSTRUCTURED.

Fin des champs mutuellement exclusifs.

VideoSegmentDetails

Localise un segment dans un document vidéo.

Représentation JSON
{
  "startOffset": string,
  "endOffset": string
}
Champs
startOffset

string (Duration format)

Uniquement en sortie. Début de ce segment par rapport au début de la vidéo source.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

endOffset

string (Duration format)

Uniquement en sortie. Fin de ce segment, par rapport au début de la vidéo source.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

UnstructuredSegmentDetails

Localise un segment dans un document non structuré et contient son texte.

Représentation JSON
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
Champs
contentSnippet

string

Uniquement en sortie. Contenu textuel du segment.

pageRange

object (PageRange)

Uniquement en sortie. Emplacement du segment dans le document source. Définissez cette option pour les fichiers PDF, PowerPoint et Excel, où une page correspond à une page PDF, une diapositive ou une feuille. Pour les fichiers HTML, en texte brut, Markdown, JSON, XML et Word, définissez cette option uniquement lorsque le fichier est divisé en pages (pageSegmentationConfig avec analyse numérique). Les pages sont alors des sections consécutives du texte, numérotées dans l'ordre.

PageRange

Une plage de pages dans le document source. Les pages sont basées sur 1 et la plage est inclusive. Une seule page est représentée par startPage == endPage.

Représentation JSON
{
  "startPage": string,
  "endPage": string
}
Champs
startPage

string (int64 format)

Uniquement en sortie. Première page de la plage.

endPage

string (int64 format)

Uniquement en sortie. Dernière page de la plage.