Method: projects.locations.dataStores.documents.search

Menelusuri Dokumen dari satu DataStore.

Menampilkan segmen sub-dokumen yang diberi peringkat, yang masing-masing merujuk kembali ke Dokumen asalnya dan membawa asal-usul yang diperlukan untuk mengutipnya.

Permintaan HTTP

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

Parameter jalur

Parameter
parent

string

Wajib. DataStore yang akan ditelusuri. Format: projects/{project}/locations/{location}/dataStores/{dataStore}

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi 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.
}
Kolom
topK

integer

Opsional. Jumlah hasil yang akan ditampilkan. Setelan defaultnya adalah 10. Nilai di atas 100 akan diubah menjadi 100.

documentIds[]

string

Opsional. Membatasi penelusuran ke ID Dokumen ini. Maks. 100. Jika kosong, seluruh DataStore akan ditelusuri.

rankingSpec

object (RankingSpec)

Opsional. Mengontrol cara hasil diberi peringkat.

filter

object (Struct format)

Opsional. Membatasi penelusuran ke segmen yang cocok dengan filter ini, objek JSON di jalur kolom DocumentSearchResult:

  • metadata.<property>: properti yang dideklarasikan di documentMetadataSchema DataStore, misalnya metadata.category.
  • unstructured_details.page_range.start_page dan .end_page: untuk DataStore UNSTRUCTURED. Tidak setiap segmen memiliki rentang halaman; lihat UnstructuredSegmentDetails.page_range.
  • video_details.start_offset dan .end_offset: dalam detik, untuk DataStore VIDEO.

Perbandingan: $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $all, dan $exists. Gabungkan dengan $and, $or, dan $not, yang disusun bertingkat maksimal dua level. Contoh:

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

outputFields

object (OutputFields)

Opsional. Kolom yang akan ditampilkan pada setiap hasil.

Wajib. Kueri yang akan ditelusuri. Tepatnya satu jenis kueri yang harus ditetapkan. Berikut adalah daftar kolom yang saling eksklusif. Maksimal satu kolom akan ditetapkan dalam respons:
textQuery

object (TextQuery)

Kueri teks.

Akhir kolom yang saling eksklusif.

Isi respons

Pesan respons untuk DocumentSearchService.SearchDocuments.

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi JSON
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
Kolom
results[]

object (DocumentSearchResult)

Hanya output. Segmen dokumen yang cocok dengan kriteria penelusuran, diurutkan berdasarkan relevansi.

warnings[]

object (Status)

Hanya output. Peringatan atau error tidak fatal yang terjadi selama eksekusi.

Cakupan otorisasi

Memerlukan salah satu cakupan OAuth berikut:

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

Untuk mengetahui informasi selengkapnya, lihat Authentication Overview.

TextQuery

Kueri teks.

Representasi JSON
{
  "text": string
}
Kolom
text

string

Wajib. Teks yang akan ditelusuri.

RankingSpec

Mengontrol cara hasil diberi peringkat.

Representasi JSON
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
Kolom
rerankingSpec

object (RerankingSpec)

Opsional. Mengontrol tahap pemeringkatan ulang.

RerankingSpec

Konfigurasi untuk pemeringkatan ulang semantik yang diterapkan ke hasil kandidat setelah pengambilan campuran dan Reciprocal Rank Fusion (RRF).

Representasi JSON
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
Kolom
enabled

boolean

Opsional. Apakah akan melakukan pemeringkatan ulang pada hasil gabungan. Defaultnya adalah false: hasil ditampilkan dalam urutan gabungan RRF, kecuali jika pemanggil memilih untuk mengaktifkannya.

Jika diaktifkan, pemeringkatan ulang akan menggunakan semantic-ranker-fast@latest di Vertex Ranking Service, dan mengharuskan Discovery Engine API diaktifkan di project pemanggil.

Tidak didukung untuk DataStore VIDEO: permintaan yang mengaktifkannya akan gagal dengan INVALID_ARGUMENT.

rankOversamplingFactor

integer

Opsional. Faktor untuk melakukan oversampling kandidat sebelum pemeringkatan ulang. Jumlah total kandidat yang diambil untuk pemeringkatan ulang adalah min(rankOversamplingFactor * topK, 200). Setelah pemeringkatan ulang, hasil akan dipangkas menjadi SearchDocumentsRequest.top_k.

Diabaikan kecuali jika enabled bernilai benar (true). Jika diaktifkan, setelan defaultnya adalah 5 (mengambil min(5 * topK, 200) kandidat, dengan maksimum 200).

Untuk memberi peringkat ulang tanpa oversampling, tetapkan kolom ini ke 1.

OutputFields

Kolom yang akan ditampilkan pada setiap DocumentSearchResult, selain yang dibawa oleh setiap hasil.

Representasi JSON
{
  "metadata": [
    string
  ]
}
Kolom
metadata[]

string

Opsional. Properti metadata yang akan ditampilkan di DocumentSearchResult.document.metadata, diberi nama seperti yang dideklarasikan di documentMetadataSchema DataStore. Properti bertingkat diberi nama berdasarkan jalur bertitiknya, misalnya address.city, tanpa awalan metadata. yang digunakan filter. "*" menampilkan setiap properti yang dideklarasikan. Jika tidak ditetapkan, akan menampilkan none. Properti yang tidak memiliki nilai untuk Dokumen akan dihilangkan.

DocumentSearchResult

Satu segmen Dokumen yang cocok.

Representasi 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.
}
Kolom
document

object (Document)

Hanya output. Dokumen asal segmen ini, termasuk nama resource-nya dan lokasi Cloud Storage tempat segmen tersebut diserap.

Perhatikan bahwa tidak semua kolom Dokumen diisi. Untuk Dokumen lengkap, panggil documents.get pada nama dokumen yang ditampilkan.

Detail tempat segmen berada dalam Dokumennya. Kolom yang ditetapkan mengikuti document_type DataStore induk. Berikut adalah daftar kolom yang saling eksklusif. Maksimal satu kolom akan ditetapkan dalam respons:
videoDetails

object (VideoSegmentDetails)

Ditetapkan saat documentType DataStore induk adalah VIDEO.

unstructuredDetails

object (UnstructuredSegmentDetails)

Ditetapkan saat documentType DataStore induk adalah UNSTRUCTURED.

Akhir kolom yang saling eksklusif.

VideoSegmentDetails

Menemukan segmen dalam Dokumen video.

Representasi JSON
{
  "startOffset": string,
  "endOffset": string
}
Kolom
startOffset

string (Duration format)

Hanya output. Tempat segmen ini dimulai, relatif terhadap awal video sumber.

Durasi dalam detik dengan maksimal sembilan digit pecahan, diakhiri dengan 's'. Contoh: "3.5s".

endOffset

string (Duration format)

Hanya output. Tempat segmen ini berakhir, relatif terhadap awal video sumber.

Durasi dalam detik dengan maksimal sembilan digit pecahan, diakhiri dengan 's'. Contoh: "3.5s".

UnstructuredSegmentDetails

Menemukan segmen dalam Dokumen tidak terstruktur, dan membawa teksnya.

Representasi JSON
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
Kolom
contentSnippet

string

Hanya output. Konten teks segmen.

pageRange

object (PageRange)

Hanya output. Tempat segmen berada dalam dokumen sumber. Ditetapkan untuk file PDF, PowerPoint, dan Excel, dengan halaman berupa halaman PDF, slide, atau sheet. Untuk file HTML, teks biasa, Markdown, JSON, XML, dan Word, tetapkan hanya jika file dibagi menjadi beberapa halaman (pageSegmentationConfig dengan penguraian digital); halaman tersebut kemudian menjadi bagian teks yang berurutan, diberi nomor secara berurutan.

PageRange

Rentang halaman dalam dokumen sumber. Halaman berbasis 1 dan rentangnya inklusif; satu halaman direpresentasikan sebagai startPage == endPage.

Representasi JSON
{
  "startPage": string,
  "endPage": string
}
Kolom
startPage

string (int64 format)

Hanya output. Halaman pertama rentang.

endPage

string (int64 format)

Hanya output. Halaman terakhir rentang.