Method: projects.locations.dataStores.documents.search

単一の DataStore のドキュメントを検索します。

ランク付けされたサブドキュメント セグメントを返します。各セグメントは、元のドキュメントを参照し、引用に必要な出所情報を含んでいます。

HTTP リクエスト

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

パスパラメータ

パラメータ
parent

string

必須。検索する DataStore。形式: projects/{project}/locations/{location}/dataStores/{dataStore}

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

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.
}
フィールド
topK

integer

省略可。返される結果の数。デフォルトは 10 です。100 を超える値は 100 に強制変換されます。

documentIds[]

string

省略可。検索をこれらのドキュメント ID に制限します。最大 100。空の場合、DataStore 全体が検索されます。

rankingSpec

object (RankingSpec)

省略可。結果のランク付け方法を制御します。

filter

object (Struct format)

省略可。検索をこのフィルタに一致するセグメントに制限します。これは、DocumentSearchResult のフィールドパスに対する JSON オブジェクトです。

  • metadata.<property>: DataStore の documentMetadataSchema で宣言されたプロパティ(例: metadata.category)。
  • unstructured_details.page_range.start_page と .end_page: UNSTRUCTURED DataStore の場合。すべてのセグメントにページ範囲があるわけではありません。UnstructuredSegmentDetails.page_range をご覧ください。
  • video_details.start_offset と .end_offset: VIDEO DataStore の場合は秒単位。

比較: $eq、$ne、$lt、$lte、$gt、$gte、$in、$nin、$all、$exists。$and、$or、$not と組み合わせ、最大 2 レベルの深さでネストします。次に例を示します。

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

outputFields

object (OutputFields)

省略可。各結果で返されるフィールド。

必須。検索するクエリ。クエリタイプは 1 つだけ設定する必要があります。相互に排他的なフィールドのリストは次のとおりです。レスポンスに設定されるフィールドは、最大 1 つです。
textQuery

object (TextQuery)

テキストクエリ。

相互に排他的なフィールドの終了。

レスポンスの本文

DocumentSearchService.SearchDocuments に対するレスポンス メッセージです。

成功した場合、レスポンスの本文には次の構造のデータが含まれます。

JSON 表現
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
フィールド
results[]

object (DocumentSearchResult)

出力専用。検索条件に一致するドキュメント セグメント。関連性の高い順に並べ替えられます。

warnings[]

object (Status)

出力専用。実行中に発生した警告または致命的でないエラー。

認可スコープ

次の OAuth スコープのいずれかが必要です。

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

詳細については、Authentication Overview をご覧ください。

TextQuery

テキストクエリ。

JSON 表現
{
  "text": string
}
フィールド
text

string

必須。検索するテキスト。

RankingSpec

結果のランク付け方法を制御します。

JSON 表現
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
フィールド
rerankingSpec

object (RerankingSpec)

省略可。再ランキング ステージを制御します。

RerankingSpec

ハイブリッド検索と Reciprocal Rank Fusion(RRF)の後に候補結果に適用されるセマンティック再ランキングの構成。

JSON 表現
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
フィールド
enabled

boolean

省略可。融合された結果を再ランク付けするかどうか。デフォルトは false です。呼び出し元がオプトインしない限り、結果は RRF 融合順で返されます。

有効にすると、再ランキングは Vertex Ranking Service で semantic-ranker-fast@latest を使用します。また、呼び出し元のプロジェクトで Discovery Engine API を有効にする必要があります。

VIDEO DataStore ではサポートされていません。有効にするリクエストは INVALID_ARGUMENT で失敗します。

rankOversamplingFactor

integer

省略可。再ランキング前に候補をオーバーサンプリングする係数。再ランキングのために取得された候補の合計数は min(rankOversamplingFactor * topK, 200) です。再ランキング後、結果は SearchDocumentsRequest.top_k にトリミングされます。

enabled が true でない場合は無視されます。有効にすると、デフォルトは 5 になります(min(5 * topK, 200) 候補を取得、最大 200)。

オーバーサンプリングなしで再ランク付けするには、このフィールドを 1 に設定します。

OutputFields

すべての結果に含まれるフィールドに加えて、各 DocumentSearchResult で返されるフィールド。

JSON 表現
{
  "metadata": [
    string
  ]
}
フィールド
metadata[]

string

省略可。DocumentSearchResult.document.metadata で返されるメタデータ プロパティ。DataStore の documentMetadataSchema で宣言されている名前が付けられます。ネストされたプロパティは、filter が使用する metadata. 接頭辞のないドット付きパス(address.city など)で名前が付けられます。"*" は、宣言されたすべてのプロパティを返します。未設定の場合は none を返します。ドキュメントに値がないプロパティは省略されます。

DocumentSearchResult

ドキュメントの一致する単一のセグメント。

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.
}
フィールド
document

object (Document)

出力専用。このセグメントの取得元であるドキュメント(リソース名と、取り込み元の Cloud Storage のロケーションを含む)。

すべての Document フィールドが入力されるわけではありません。完全なドキュメントを取得するには、返されたドキュメント名に対して documents.get を呼び出します。

ドキュメント内のセグメントの位置の詳細。設定されるフィールドは、親 DataStore の document_type に従います。相互に排他的なフィールドのリストは次のとおりです。レスポンスに設定されるフィールドは、最大 1 つです。
videoDetails

object (VideoSegmentDetails)

親 DataStore の documentType が VIDEO の場合に設定します。

unstructuredDetails

object (UnstructuredSegmentDetails)

親 DataStore の documentType が UNSTRUCTURED のときに設定されます。

相互に排他的なフィールドの終了。

VideoSegmentDetails

動画ドキュメント内のセグメントを特定します。

JSON 表現
{
  "startOffset": string,
  "endOffset": string
}
フィールド
startOffset

string (Duration format)

出力専用。このセグメントの開始位置(ソース動画の開始位置を基準とする)。

s で終わる小数 9 桁までの秒単位の期間。例: "3.5s"。

endOffset

string (Duration format)

出力専用。このセグメントの終了位置(ソース動画の開始位置を基準とする)。

s で終わる小数 9 桁までの秒単位の期間。例: "3.5s"。

UnstructuredSegmentDetails

非構造化ドキュメント内のセグメントを特定し、そのテキストを保持します。

JSON 表現
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
フィールド
contentSnippet

string

出力専用。セグメントのテキスト コンテンツ。

pageRange

object (PageRange)

出力専用。ソース ドキュメント内のセグメントの位置。PDF、PowerPoint、Excel ファイルに設定します。ページは PDF ページ、スライド、シートです。HTML、書式なしテキスト、Markdown、JSON、XML、Word ファイルの場合、ファイルがページに分割されている場合にのみ設定します(デジタル解析を使用した pageSegmentationConfig)。ページはテキストの連続したセクションであり、順番に番号が付けられます。

PageRange

ソース ドキュメント内のページ範囲。ページは 1 から始まり、範囲は包括的です。1 ページは startPage == endPage として表されます。

JSON 表現
{
  "startPage": string,
  "endPage": string
}
フィールド
startPage

string (int64 format)

出力専用。範囲の最初のページ。

endPage

string (int64 format)

出力専用。範囲の最後のページ。