Method: projects.locations.dataStores.documents.search

Durchsucht die Dokumente eines einzelnen Datenspeichers.

Gibt sortierte Unterdokumentsegmente zurück, die jeweils auf das Dokument verweisen, aus dem sie stammen, und die für die Zitierung erforderliche Herkunft enthalten.

HTTP-Anfrage

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

Pfadparameter

Parameter
parent

string

Erforderlich. Der zu durchsuchende DataStore. Format: projects/{project}/locations/{location}/dataStores/{dataStore}

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "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.
}
Felder
topK

integer

Optional. Anzahl der zurückzugebenden Ergebnisse. Der Standardwert ist 10. Werte über 100 werden implizit auf 100 umgewandelt.
documentIds[]

string

Optional. Beschränken Sie die Suche auf diese Dokument-IDs. Max. 100. Wenn das Feld leer ist, wird der gesamte Datenspeicher durchsucht.
rankingSpec

object (RankingSpec)

Optional. Steuert, wie Ergebnisse sortiert werden.
filter

object (Struct format)

Optional. Beschränkt die Suche auf Segmente, die diesem Filter entsprechen, einem JSON-Objekt über die Feldpfade eines DocumentSearchResult:

  • metadata.<property>: ein Attribut, das im documentMetadataSchema des DataStore deklariert ist, z.B. metadata.category.
  • unstructured_details.page_range.start_page und .end_page: für einen UNSTRUCTURED-Datenspeicher. Nicht jedes Segment hat einen Seitenbereich. Weitere Informationen finden Sie unter UnstructuredSegmentDetails.page_range.
  • video_details.start_offset und .end_offset: in Sekunden, für einen VIDEO-Datenspeicher.

Vergleiche: $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $all und $exists. Kombinieren Sie sie mit $and, $or und $not, verschachtelt auf maximal zwei Ebenen. Beispiel:

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

object (OutputFields)

Optional. Felder, die für jedes Ergebnis zurückgegeben werden sollen.
Erforderlich. Die Anfrage, nach der gesucht werden soll Es muss genau ein Abfragetyp festgelegt werden. Im Folgenden finden Sie eine Liste der Felder, die sich gegenseitig ausschließen. In einer Antwort wird höchstens eines der Felder festgelegt:
textQuery

object (TextQuery)

Eine Textabfrage.
Ende der sich gegenseitig ausschließenden Felder.

Antworttext

Antwortnachricht für DocumentSearchService.SearchDocuments.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung 
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
Felder
results[]

object (DocumentSearchResult)

Nur Ausgabe. Die übereinstimmenden Dokumentsegmente, die den Suchkriterien entsprechen, sortiert nach Relevanz.
warnings[]

object (Status)

Nur Ausgabe. Warnungen oder nicht schwerwiegende Fehler, die während der Ausführung aufgetreten sind.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

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

Weitere Informationen finden Sie unter Authentication Overview.

TextQuery

Eine Textabfrage.

JSON-Darstellung 
{
  "text": string
}
Felder
text

string

Erforderlich. Der Text, nach dem gesucht werden soll.

RankingSpec

Steuert, wie Ergebnisse sortiert werden.

JSON-Darstellung 
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
Felder
rerankingSpec

object (RerankingSpec)

Optional. Steuert die Phase der Neuanordnung.

RerankingSpec

Konfiguration für die semantische Neusortierung, die nach dem Hybridabruf und der Reciprocal Rank Fusion (RRF) auf die Kandidatenergebnisse angewendet wird.

JSON-Darstellung 
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
Felder
enabled

boolean

Optional. Gibt an, ob die zusammengeführten Ergebnisse neu sortiert werden sollen. Der Standardwert ist „false“: Die Ergebnisse werden in der RRF-fusionierten Reihenfolge zurückgegeben, sofern der Aufrufer nichts anderes angibt.

Wenn diese Option aktiviert ist, wird für die Neubewertung semantic-ranker-fast@latest im Vertex Ranking Service verwendet. Außerdem muss die Discovery Engine API im Projekt des Aufrufers aktiviert sein.

Nicht unterstützt für einen VIDEO-Datenspeicher: Eine Anfrage, die ihn aktiviert, schlägt mit INVALID_ARGUMENT fehl.
rankOversamplingFactor

integer

Optional. Der Faktor, um den Kandidaten vor der Neubewertung überabgetastet werden sollen. Die Gesamtzahl der für die Neubewertung abgerufenen Kandidaten beträgt min(rankOversamplingFactor * topK, 200). Nach der Neubewertung werden die Ergebnisse auf SearchDocumentsRequest.top_k gekürzt.

Wird ignoriert, sofern enabled nicht „true“ ist. Wenn diese Option aktiviert ist, wird standardmäßig der Wert 5 verwendet (min(5 * topK, 200) Kandidaten werden abgerufen, maximal 200).

Wenn Sie die Rangfolge ohne Oversampling neu festlegen möchten, setzen Sie dieses Feld auf 1.

OutputFields

Felder, die für jedes DocumentSearchResult zurückgegeben werden sollen, zusätzlich zu den Feldern, die jedes Ergebnis enthält.

JSON-Darstellung 
{
  "metadata": [
    string
  ]
}
Felder
metadata[]

string

Optional. Metadatenattribute, die in DocumentSearchResult.document.metadata zurückgegeben werden sollen, benannt wie im documentMetadataSchema des DataStore deklariert. Eine verschachtelte Property wird durch ihren Pfad mit Punkten benannt, z.B. address.city, ohne das Präfix metadata., das filter verwendet. "*" gibt alle deklarierten Properties zurück. Wenn die Option nicht festgelegt ist, wird „none“ zurückgegeben. Eine Eigenschaft, für die das Dokument keinen Wert hat, wird weggelassen.

DocumentSearchResult

Ein einzelnes übereinstimmendes Segment eines Dokuments.

JSON-Darstellung 
{
  "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.
}
Felder
document

object (Document)

Nur Ausgabe. Das Dokument, aus dem dieses Segment stammt, einschließlich des Ressourcennamens und des Cloud Storage-Speicherorts, aus dem es aufgenommen wurde.

Beachten Sie, dass nicht alle Dokumentfelder ausgefüllt sind. Wenn Sie das vollständige Dokument abrufen möchten, rufen Sie „documents.get“ für den zurückgegebenen Dokumentnamen auf.
Details dazu, wo sich das Segment im Dokument befindet. Welches Feld festgelegt wird, richtet sich nach dem document_type des übergeordneten DataStore. Im Folgenden finden Sie eine Liste der Felder, die sich gegenseitig ausschließen. In einer Antwort wird höchstens eines der Felder festgelegt:
videoDetails

object (VideoSegmentDetails)

Wird festgelegt, wenn der documentType des übergeordneten DataStore VIDEO ist.
unstructuredDetails

object (UnstructuredSegmentDetails)

Wird festgelegt, wenn der documentType des übergeordneten DataStore UNSTRUCTURED ist.
Ende der sich gegenseitig ausschließenden Felder.

VideoSegmentDetails

Sucht ein Segment in einem Videodokument.

JSON-Darstellung 
{
  "startOffset": string,
  "endOffset": string
}
Felder
startOffset

string (Duration format)

Nur Ausgabe. Wo dieses Segment beginnt, relativ zum Anfang des Quellvideos.

Die Dauer in Sekunden mit bis zu neun Nachkommastellen und am Ende mit „s“. Beispiel: "3.5s".
endOffset

string (Duration format)

Nur Ausgabe. Wo dieses Segment endet, relativ zum Beginn des Quellvideos.

Die Dauer in Sekunden mit bis zu neun Nachkommastellen und am Ende mit „s“. Beispiel: "3.5s".

UnstructuredSegmentDetails

Sucht ein Segment in einem unstrukturierten Dokument und enthält den Text.

JSON-Darstellung 
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
Felder
contentSnippet

string

Nur Ausgabe. Textinhalt des Segments.
pageRange

object (PageRange)

Nur Ausgabe. Wo sich das Segment im Quelldokument befindet. Wird für PDF-, PowerPoint- und Excel-Dateien festgelegt, wobei eine Seite eine PDF-Seite, eine Folie oder ein Tabellenblatt ist. Legen Sie dies für Nur-Text- und Word-Dateien nur fest, wenn die Datei in Seiten aufgeteilt ist (pageSegmentationConfig mit digitalem Parsen). Die Seiten sind dann aufeinanderfolgende Abschnitte des Texts, die der Reihe nach nummeriert sind.

PageRange

Ein Seitenbereich im Quelldokument. Seiten sind 1-basiert und der Bereich ist inklusiv. Eine einzelne Seite wird als startPage == endPage dargestellt.

JSON-Darstellung 
{
  "startPage": string,
  "endPage": string
}
Felder
startPage

string (int64 format)

Nur Ausgabe. Erste Seite des Bereichs.
endPage

string (int64 format)

Nur Ausgabe. Letzte Seite des Bereichs.