All Products
Search

This Product

    Tablestore:Pencarian vektor

    Document Center

    Tablestore:Pencarian vektor

    Last Updated:Jul 28, 2026

    Pencarian vektor dengan Tablestore SDK for Java mengembalikan data terdekat dalam indeks pencarian berdasarkan kemiripan vektor, serta mendukung ambang batas skor, jumlah kandidat, dan filter non-vektor.

    Prasyarat

    • Instal Tablestore SDK for Java dan inisialisasi klien. Pencarian vektor memerlukan versi 5.17.0 atau yang lebih baru.

    • Untuk mengonfigurasi minScore atau numCandidates, gunakan versi 5.17.5 atau yang lebih baru.

    Deskripsi fitur

    Pencarian vektor melakukan pencarian tetangga terdekat aproksimasi (approximate nearest neighbor/ANN) antara vektor kueri dan vektor dalam bidang Vector. Tablestore memberi skor hasil berdasarkan metrik jarak yang dikonfigurasi saat pembuatan indeks pencarian, lalu mengembalikan data terdekat. Berbeda dengan kueri yang mencocokkan nilai bidang, pencarian vektor menentukan kemiripan berdasarkan jarak antar vektor.

    Panggil search dan atur query menjadi KnnVectorQuery.

    SearchResponse search(SearchRequest request)

    Contoh berikut mengambil tiga vektor dalam bidang embedding yang paling dekat dengan [1.0, 0.0, 0.0, 0.0]. Hasil diurutkan berdasarkan skor secara menurun.

    String tableName = "example_table";
String indexName = "example_index";
KnnVectorQuery query = new KnnVectorQuery();
query.setFieldName("embedding");
query.setTopK(3);
query.setFloat32QueryVector(new float[]{1.0f, 0.0f, 0.0f, 0.0f});

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(query);
searchQuery.setLimit(3);
searchQuery.setSort(new Sort(Collections.singletonList(new ScoreSort())));

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);

SearchResponse response = client.search(request);
for (SearchHit hit : response.getSearchHits()) {
    System.out.println(hit.getScore() + ": " + hit.getRow());
}
    Catatan

    Batas berlaku untuk jumlah dan dimensi bidang vektor serta nilai topK. Untuk detailnya, lihat Batas indeks pencarian.

    Parameter

    Permintaan pencarian

    request adalah objek SearchRequest yang berisi parameter berikut.

    Name

    Type

    Description

    tableName (required)

    String

    Nama tabel.

    indexName (required)

    String

    Nama indeks pencarian.

    searchQuery (required)

    SearchQuery

    Kondisi kueri dan konfigurasi kueri umum.

    columnsToGet (optional)

    SearchRequest.ColumnsToGet

    Konfigurasi kolom yang dikembalikan. Jika parameter ini tidak dikonfigurasi, hanya kolom kunci primer yang dikembalikan.

    timeoutInMillisecond (optional)

    int

    Timeout kueri tingkat permintaan dalam milidetik. Nilai default: -1, yang berarti tidak mengatur timeout kueri terpisah.

    routingValues (optional)

    List<PrimaryKey>

    Nilai kunci primer dari bidang routing kustom. Biarkan parameter ini tidak diatur jika routing kustom tidak dikonfigurasi.

    Konfigurasi kueri

    request.searchQuery adalah objek SearchQuery yang berisi parameter berikut.

    Name

    Type

    Description

    query (required)

    Query

    Kondisi kueri. Atur parameter ini ke KnnVectorQuery untuk pencarian vektor.

    offset (optional)

    Integer

    Posisi awal kueri.

    limit (optional)

    Integer

    Jumlah maksimum baris yang dikembalikan. Jika parameter ini diatur ke 0, tidak ada baris yang dikembalikan.

    highlight (optional)

    Highlight

    Konfigurasi ringkasan dan penyorotan. Bidang vektor tidak mendukung ringkasan dan penyorotan.

    collapse (optional)

    Collapse

    Konfigurasi collapse untuk menghilangkan duplikasi hasil berdasarkan kolom tertentu.

    sort (optional)

    Sort

    Urutan pengurutan hasil. Gunakan ScoreSort untuk mengurutkan berdasarkan skor.

    trackTotalCount (optional)

    int

    Jumlah maksimum baris yang cocok untuk dihitung. Nilai default: TRACK_TOTAL_COUNT_DISABLED, yang menonaktifkan penghitungan. Atur parameter ini ke TRACK_TOTAL_COUNT untuk menghitung semua baris yang cocok. Nilai yang lebih kecil meningkatkan performa kueri.

    filter (optional)

    SearchFilter

    Filter yang diterapkan pada hasil query.

    aggregationList (optional)

    List<Aggregation>

    Konfigurasi agregasi.

    groupByList (optional)

    List<GroupBy>

    Konfigurasi pengelompokan.

    token (optional)

    byte[]

    Token paginasi. Atur parameter ini ke nextToken dari respons sebelumnya untuk mengambil lebih banyak data. Setiap partisi indeks sisi server mengembalikan nilai topK terdekatnya sendiri, yang kemudian digabungkan di node koordinasi. Oleh karena itu, saat Anda melakukan paginasi dengan token, jumlah kumulatif baris yang dikembalikan bergantung pada jumlah partisi indeks sisi server.

    Kondisi kueri vektor

    request.searchQuery.query adalah objek KnnVectorQuery yang berisi parameter berikut.

    Name

    Type

    Description

    fieldName (required)

    String

    Nama bidang vektor. Bidang harus bertipe Vector, dan dimensi vektor kueri harus sesuai dengan dimensi yang dikonfigurasi saat Anda membuat indeks pencarian.

    topK (required)

    Integer

    Jumlah vektor terdekat yang diambil. Maksimum: 1000. Nilai yang lebih besar mengembalikan lebih banyak kandidat dan dapat meningkatkan Recall, tetapi juga dapat meningkatkan latensi dan biaya kueri.

    float32QueryVector (required)

    float[]

    Vektor kueri Float32 yang digunakan untuk menghitung kemiripan. Panjang array harus sesuai dengan dimensi bidang vektor.

    filter (optional)

    Query

    Kondisi kueri non-vektor yang juga harus dipenuhi oleh hasil pencarian vektor. Anda dapat menggabungkan beberapa objek Query non-vektor.

    weight (optional)

    Float

    Bobot relevansi kueri vektor. Nilainya harus lebih besar atau sama dengan 0. Nilai default: 1.0. Nilai yang lebih besar memberikan pengaruh lebih besar pada skor kueri vektor terhadap skor relevansi akhir tanpa mengubah baris mana yang cocok.

    minScore (optional)

    Float

    Ambang batas skor minimum. Nilainya harus lebih besar atau sama dengan 0. Nilai default: 0. Hanya data dengan skor yang secara ketat lebih besar dari nilai ini yang dikembalikan.

    numCandidates (optional)

    Integer

    Jumlah kandidat yang diakses di setiap partisi indeks saat menghitung tetangga terdekat. Nilai valid: [topK, 1000]. Nilai yang lebih besar dapat meningkatkan Recall tetapi juga dapat meningkatkan waktu kueri.

    Kolom yang dikembalikan

    request.columnsToGet adalah objek SearchRequest.ColumnsToGet yang berisi parameter berikut.

    Name

    Type

    Description

    columns (optional)

    List<String>

    Kolom atribut yang dikembalikan. Konfigurasikan parameter ini hanya jika returnAll dan returnAllFromIndex keduanya bernilai false. Jika parameter ini tidak dikonfigurasi, hanya kolom kunci primer yang dikembalikan.

    returnAll (optional)

    boolean

    Menentukan apakah semua kolom atribut dalam tabel akan dikembalikan. Nilai default: false.

    returnAllFromIndex (optional)

    boolean

    Menentukan apakah semua kolom atribut yang diindeks akan dikembalikan. Nilai default: false. Parameter ini dan returnAll tidak boleh diatur ke true secara bersamaan.

    Respons

    Respons pencarian

    search mengembalikan objek SearchResponse. Tabel berikut menjelaskan bidang intinya.

    Name

    Type

    Description

    totalCount

    long

    Jumlah baris yang cocok. Panggil getTotalCount() untuk mendapatkan nilainya. Nilai yang dikembalikan bergantung pada trackTotalCount.

    rows

    List<Row>

    Baris yang dikembalikan oleh kueri ini. Panggil getRows() untuk mendapatkan nilainya. Jumlah baris yang dikembalikan tidak melebihi limit.

    searchHits

    List<SearchHit>

    Hasil pencarian. Panggil getSearchHits() untuk mendapatkan baris dan skornya.

    nextToken

    byte[]

    Token untuk halaman berikutnya. Panggil getNextToken() untuk mendapatkan nilainya. Jika nilainya bukan null, teruskan sebagai token dalam permintaan berikutnya untuk mengambil lebih banyak data.

    isAllSuccess

    boolean

    Menunjukkan apakah semua partisi indeks telah dikueri. Panggil isAllSuccess() untuk mendapatkan nilainya. Jika bidang ini bernilai false, respons berisi hasil parsial dan totalCount mungkin kurang dari jumlah sebenarnya dari baris yang cocok.

    Hasil pencarian

    Setiap elemen dalam response.searchHits[] adalah objek SearchHit yang berisi bidang inti berikut.

    Name

    Type

    Description

    row

    Row

    Baris yang cocok. Panggil getRow() untuk mendapatkan nilainya.

    score

    Double

    Skor kueri vektor. Panggil getScore() untuk mendapatkan nilainya. Metrik jarak dan weight memengaruhi nilai ini.

    Contoh

    Filter berdasarkan kondisi non-vektor dan skor minimum

    Gunakan filter untuk mewajibkan tetangga terdekat memenuhi kondisi kueri non-vektor, dan gunakan minScore untuk mengecualikan data yang skornya tidak melebihi ambang batas. Contoh berikut hanya mengembalikan data di mana category bernilai book, price kurang dari 4, dan skor vektornya lebih besar dari 0.6.

    KnnVectorQuery filteredQuery = new KnnVectorQuery();
filteredQuery.setFieldName("embedding");
filteredQuery.setTopK(10);
filteredQuery.setFloat32QueryVector(
        new float[]{1.0f, 0.0f, 0.0f, 0.0f});
filteredQuery.setMinScore(0.6f);
filteredQuery.setFilter(QueryBuilders.bool()
        .must(QueryBuilders.term("category", "book"))
        .must(QueryBuilders.range("price").lessThan(4)));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(filteredQuery);
searchQuery.setLimit(10);

    Menyesuaikan jumlah kandidat

    Atur numCandidates untuk memperluas set kandidat yang diakses di setiap partisi indeks saat menghitung tetangga terdekat. Contoh berikut mengambil tiga vektor terdekat dari empat kandidat.

    KnnVectorQuery candidateQuery = new KnnVectorQuery();
candidateQuery.setFieldName("embedding");
candidateQuery.setTopK(3);
candidateQuery.setFloat32QueryVector(
        new float[]{1.0f, 0.0f, 0.0f, 0.0f});
candidateQuery.setNumCandidates(4);

SearchQuery candidateSearchQuery = new SearchQuery();
candidateSearchQuery.setQuery(candidateQuery);
candidateSearchQuery.setLimit(3);

    Topik terkait