Method: projects.locations.dataStores.documents.search

Pesquisa os documentos de um único DataStore.

Retorna segmentos de subdocumentos classificados, cada um se referindo ao documento de origem e com a procedência necessária para citá-lo.

Solicitação HTTP

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

Parâmetros de caminho

Parâmetros
parent

string

Obrigatório. O DataStore a ser pesquisado. Formato: projects/{project}/locations/{location}/dataStores/{dataStore}

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação 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.
}
Campos
topK

integer

Opcional. Número de resultados que serão retornados. O valor padrão é 10. Valores acima de 100 são convertidos para 100.

documentIds[]

string

Opcional. Restrinja a pesquisa a esses IDs de documento. Máximo de 100. Se estiver vazio, todo o DataStore será pesquisado.

rankingSpec

object (RankingSpec)

Opcional. Controla como os resultados são classificados.

filter

object (Struct format)

Opcional. Restringe a pesquisa a segmentos que correspondem a esse filtro, um objeto JSON nos caminhos de campo de um DocumentSearchResult:

  • metadata.<property>: uma propriedade declarada no documentMetadataSchema do DataStore, por exemplo, metadata.category.
  • unstructured_details.page_range.start_page e .end_page: para um DataStore UNSTRUCTURED. Nem todos os segmentos têm um intervalo de páginas. Consulte UnstructuredSegmentDetails.page_range.
  • video_details.start_offset e .end_offset: em segundos, para um DataStore VIDEO.

Comparações: $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $all e $exists. Combine-os com $and, $or e $not, aninhados em no máximo dois níveis de profundidade. Exemplo:

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

outputFields

object (OutputFields)

Opcional. Campos a serem retornados em cada resultado.

Obrigatório. A consulta a ser pesquisada. É necessário definir exatamente um tipo de consulta. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
textQuery

object (TextQuery)

Uma consulta de texto.

Fim dos campos mutuamente exclusivos.

Corpo da resposta

Mensagem de resposta para DocumentSearchService.SearchDocuments.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
Campos
results[]

object (DocumentSearchResult)

Apenas saída. Os segmentos de documentos que correspondem aos critérios de pesquisa, ordenados por relevância.

warnings[]

object (Status)

Apenas saída. Avisos ou erros não fatais que ocorreram durante a execução.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

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

Para mais informações, consulte Authentication Overview.

TextQuery

Uma consulta de texto.

Representação JSON
{
  "text": string
}
Campos
text

string

Obrigatório. O texto a ser pesquisado.

RankingSpec

Controla como os resultados são classificados.

Representação JSON
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
Campos
rerankingSpec

object (RerankingSpec)

Opcional. Controla o estágio de reclassificação.

RerankingSpec

Configuração para reclassificação semântica aplicada aos resultados candidatos após a recuperação híbrida e a Reciprocal Rank Fusion (RRF).

Representação JSON
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
Campos
enabled

boolean

Opcional. Se os resultados combinados devem ser reclassificados. O padrão é falso: os resultados são retornados na ordem de fusão da RRF, a menos que o autor da chamada opte por não fazer isso.

Quando ativada, a reclassificação usa semantic-ranker-fast@latest no serviço de classificação da Vertex e exige que a API Discovery Engine esteja ativada no projeto do autor da chamada.

Não há suporte para um DataStore VIDEO: uma solicitação que o ativa falha com INVALID_ARGUMENT.

rankOversamplingFactor

integer

Opcional. O fator pelo qual os candidatos são superamostrados antes de serem reclassificados. O número total de candidatos recuperados para reclassificação é min(rankOversamplingFactor * topK, 200). Após a reclassificação, os resultados são reduzidos para SearchDocumentsRequest.top_k.

Ignorado, a menos que enabled seja verdadeiro. Quando ativado, o padrão é 5 (recuperando min(5 * topK, 200) candidatos, com um máximo de 200).

Para reclassificar sem oversampling, defina esse campo como 1.

OutputFields

Campos a serem retornados em cada DocumentSearchResult, além daqueles que todos os resultados carregam.

Representação JSON
{
  "metadata": [
    string
  ]
}
Campos
metadata[]

string

Opcional. Propriedades de metadados a serem retornadas em DocumentSearchResult.document.metadata, nomeadas conforme declarado no documentMetadataSchema do DataStore. Uma propriedade aninhada é nomeada pelo caminho pontilhado, por exemplo, address.city, sem o prefixo metadata. que filter usa. "*" retorna todas as propriedades declaradas. Não definido não retorna nada. Uma propriedade para a qual o documento não tem valor é omitida.

DocumentSearchResult

Um único segmento correspondente de um documento.

Representação 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.
}
Campos
document

object (Document)

Apenas saída. O documento de origem desse segmento, incluindo o nome do recurso e o local do Cloud Storage de onde ele foi ingerido.

Nem todos os campos do documento são preenchidos. Para o documento completo, chame documents.get no nome do documento retornado.

Detalhes de onde o segmento está no documento. O campo definido segue o document_type do DataStore pai. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
videoDetails

object (VideoSegmentDetails)

Definido quando o documentType do DataStore pai é VIDEO.

unstructuredDetails

object (UnstructuredSegmentDetails)

Definido quando o documentType do DataStore pai é UNSTRUCTURED.

Fim dos campos mutuamente exclusivos.

VideoSegmentDetails

Localiza um segmento em um documento de vídeo.

Representação JSON
{
  "startOffset": string,
  "endOffset": string
}
Campos
startOffset

string (Duration format)

Apenas saída. Onde esse segmento começa, em relação ao início do vídeo de origem.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

endOffset

string (Duration format)

Apenas saída. Onde esse segmento termina, em relação ao início do vídeo de origem.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

UnstructuredSegmentDetails

Localiza um segmento em um documento não estruturado e carrega o texto dele.

Representação JSON
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
Campos
contentSnippet

string

Apenas saída. Conteúdo de texto do segmento.

pageRange

object (PageRange)

Apenas saída. Onde o segmento está no documento de origem. Defina para arquivos PDF, PowerPoint e Excel, em que uma página é uma página PDF, um slide ou uma planilha. Para arquivos HTML, de texto simples, Markdown, JSON, XML e Word, defina apenas quando o arquivo for dividido em páginas (pageSegmentationConfig com análise digital). As páginas são seções consecutivas do texto, numeradas em ordem.

PageRange

Um intervalo de páginas no documento de origem. As páginas são baseadas em 1, e o intervalo é inclusivo. Uma única página é representada como startPage == endPage.

Representação JSON
{
  "startPage": string,
  "endPage": string
}
Campos
startPage

string (int64 format)

Apenas saída. Primeira página do intervalo.

endPage

string (int64 format)

Apenas saída. Última página do intervalo.