Hologres:Panduan Pengguna Indeks HGraph (Direkomendasikan)

Create Index

Sintaks: Buat indeks vektor saat membuat tabel.

Deskripsi: Di Hologres, vektor direpresentasikan sebagai array float4. Dimensi vektor sesuai dengan panjang array satu dimensi, yang dalam dokumen ini disebut sebagai array_length.

CREATE TABLE <TABLE_NAME> (
    <VECTOR_COLUMN_NAME> float4[] CHECK (array_ndims(<VECTOR_COLUMN_NAME>) = 1 AND array_length(<VECTOR_COLUMN_NAME>, 1) = <DIM>)
)
WITH (
    vectors = '{
    "<VECTOR_COLUMN_NAME>": {
        "algorithm": "<ALGORITHM>",
        "distance_method": "<DISTANCE_METHOD>",
        "builder_params": {
            "<BUILDER_PARAMETERS_NAME>": <VALUE>
            [, ...]
        }
    }
    [ , "<VECTOR_COLUMN_NAME_2>": { ... } ]
  }'
);

Deskripsi parameter:

Parameter vectors untuk indeks vektor memiliki persyaratan berikut:

• Hanya string berformat JSON yang didukung. Pada level teratas, hanya satu kunci vector_column_name yang diperbolehkan untuk menentukan bidang vektor tempat indeks vektor akan dibuat.

• Nilai kunci vector_column_name adalah objek JSON yang mengonfigurasi parameter indeks vektor. Mendukung kunci berikut:

Parameter builder_params untuk pembuatan indeks vektor mendukung parameter berikut:

Modify Index

Sintaks:

ALTER TABLE <TABLE_NAME>
SET (
    vectors = '{
    "<VECTOR_COLUMN_NAME>": {
        "algorithm": "<ALGORITHM>",
        "distance_method": "<DISTANCE_METHOD>",
        "builder_params": {
            "<BUILDER_PARAMETERS_NAME>": <VALUE>
            [, ...]
        }
    }
  }'
);

Delete Index

-- Hapus indeks vektor untuk semua kolom dalam tabel
ALTER TABLE <TABLE_NAME>
SET (
    vectors = '{}'
);

-- Jika kolom col1 dan col2 dalam tabel memiliki indeks vektor, dan Anda perlu menghapus indeks untuk col2, gunakan pernyataan ALTER TABLE untuk hanya mempertahankan indeks untuk col1.
ALTER TABLE <TABLE_NAME>
SET (
    vectors = '{
    "col1": { ... }
  }'
);

View Index

Hologres menyediakan tabel sistem hologres.hg_table_properties untuk melihat indeks vektor yang telah dibuat.

SELECT
    *
FROM
    hologres.hg_table_properties
WHERE 
    table_name = '<TABLE_NAME>'
    AND property_key = 'vectors';

Fungsi Perhitungan Jarak Vektor

Pengambilan vektor Hologres mendukung pengambilan perkiraan dan eksak. Hanya fungsi pengambilan perkiraan yang dapat memanfaatkan indeks vektor yang ada untuk mempercepat kueri, dan fungsi tersebut harus sesuai dengan distance_method yang ditentukan dalam indeks vektor. Fungsi pengambilan eksak tidak dapat menggunakan indeks vektor.

Catatan: Fungsi perhitungan jarak vektor tidak mendukung semua parameter input konstan.

Verifikasi Penggunaan Indeks Vektor

Periksa rencana eksekusi untuk menentukan apakah SQL menggunakan indeks vektor. Jika rencana tersebut berisi 'Vector Filter', indeks berhasil digunakan. Untuk informasi selengkapnya, lihat EXPLAIN dan EXPLAIN ANALYZE.

• Contoh SQL:

  SELECT
      id,
      approx_euclidean_distance (feature, '{0.1,0.2,0.3,0.4}') AS distance
  FROM
      feature_tb
  ORDER BY
      distance
  LIMIT 40;

• Rencana eksekusi:

  Limit  (cost=0.00..182.75 rows=40 width=12)
    ->  Sort  (cost=0.00..182.75 rows=160 width=12)
          Sort Key: (VectorDistanceRef)
          ->  Gather  (cost=0.00..181.95 rows=160 width=12)
                ->  Limit  (cost=0.00..181.94 rows=160 width=12)
                      ->  Sort  (cost=0.00..181.94 rows=40000 width=12)
                            Sort Key: (VectorDistanceRef)
                            ->  Local Gather  (cost=0.00..91.53 rows=40000 width=12)
                                  ->  Limit  (cost=0.00..91.53 rows=40000 width=12)
                                        ->  Sort  (cost=0.00..91.53 rows=40000 width=12)
                                              Sort Key: (VectorDistanceRef)
                                              ->  Project  (cost=0.00..1.12 rows=40000 width=12)
                                                    ->  Index Scan using Clustering_index on feature_tb  (cost=0.00..1.00 rows=40000 width=8)
                                                          Vector Filter: VectorCond => KNN: '40'::bigint distance_method: approx_euclidean_distance search_params: {NULL} args: {feature'{0.100000001,0.200000003,0.300000012,0.400000006}'::real[]}
  Query Queue: init_warehouse.default_queue
  Optimizer: HQO version 4.0.0

Gunakan Indeks Vektor Secara Tepat

Jika volume data Anda kecil—misalnya, puluhan ribu catatan—atau instans Anda memiliki sumber daya komputasi yang cukup, hindari pembuatan indeks vektor dan gunakan komputasi brute-force. Gunakan indeks vektor hanya ketika komputasi brute-force gagal memenuhi persyaratan latensi, throughput, atau performa lainnya, karena:

• Indeks vektor bersifat lossy, dan tingkat recall hasil tidak dapat mencapai 100%.

• Indeks vektor mungkin mengembalikan lebih sedikit hasil daripada yang diminta. Misalnya, kueri dengan LIMIT 1000 mungkin hanya mengembalikan 500 catatan.

Saat memutuskan untuk menggunakan indeks vektor, konfigurasikan sebagai berikut (menggunakan contoh satu tabel, satu kolom, vektor 768-dimensi):

• Untuk beban kerja sensitif latensi: Gunakan indeks murni di memori. Untuk kuantisasi indeks, gunakan sq8_uniform atau rabitq. Untuk satu shard, pertahankan volume data di bawah 5 juta baris.

• Untuk beban kerja tidak sensitif latensi atau volume data besar: Gunakan indeks hibrida memori-disk. Untuk kuantisasi indeks, gunakan rabitq. Untuk satu shard, pertahankan volume data di bawah 30 juta hingga 50 juta baris.

• Catatan: Untuk mengonfigurasi indeks vektor untuk beberapa kolom, kurangi proporsional volume data per shard yang direkomendasikan. Ukuran dimensi vektor juga memengaruhi rekomendasi ini.

Contoh:

-- Contoh lengkap untuk indeks hibrida
CREATE TABLE feature_tb (
    id bigint not null,
    feature float4[] CHECK(array_ndims(feature) = 1 AND array_length(feature, 1) = 4)
)
WITH (
    table_group = 'test_tg_shard_4',
    vectors = '{
    "feature": {
        "algorithm": "HGraph",
        "distance_method": "Cosine",
        "builder_params": {
            "base_quantization_type": "rabitq",
            "graph_storage_type": "compressed",
            "max_degree": 64,
            "ef_construction": 400,
            "precise_quantization_type": "fp32",
            "precise_io_type": "reader_io",
            "use_reorder": true,
            "max_total_size_to_merge_mb" : 4096
        }
    }
    }'
);


-- Contoh lengkap untuk indeks penuh di memori
CREATE TABLE feature_tb (
    id bigint not null,
    feature float4[] CHECK(array_ndims(feature) = 1 AND array_length(feature, 1) = 4)
)
WITH (
    table_group = 'test_tg_shard_4',
    vectors = '{
    "feature": {
        "algorithm": "HGraph",
        "distance_method": "Cosine",
        "builder_params": {
            "base_quantization_type": "sq8_uniform",
            "graph_storage_type": "compressed",
            "max_degree": 64,
            "ef_construction": 400,
            "precise_quantization_type": "fp32",
            "use_reorder": true,
            "max_total_size_to_merge_mb" : 4096
        }
    }
    }'
);

Tingkatkan Tingkat Recall

Bagian ini menggunakan dataset VectorDBBench sebagai contoh untuk menjelaskan cara meningkatkan tingkat recall.

Banyak faktor yang memengaruhi tingkat recall. Dengan konfigurasi parameter indeks berikut, tingkat recall default sistem biasanya melebihi 95%:

• Parameter indeks:

  • base_quantization_type: rabitq, sq8_uniform

  • precise_quantization_type: fp32

  • max_degree: 64

  • ef_construction: 400

• Parameter kueri (GUC):

  • hg_vector_ef_search: Gunakan nilai default 80. Parameter ini mengontrol ukuran daftar kandidat selama pengambilan untuk menyeimbangkan akurasi dan kecepatan. Nilai yang lebih besar meningkatkan akurasi tetapi juga meningkatkan overhead sumber daya.

Untuk meningkatkan tingkat recall lebih dari 99%, jalankan SET hg_vector_ef_search = 400; sambil mempertahankan parameter lainnya. Namun, peningkatan tingkat recall juga meningkatkan latensi kueri dan pemanfaatan sumber daya komputasi.

Untuk mencapai tingkat recall 99,5% hingga 99,7%, sesuaikan nilai max_degree, ef_construction, dan hg_vector_ef_search. Hal ini meningkatkan latensi kueri, konsumsi sumber daya kueri, waktu pembuatan indeks, dan konsumsi sumber daya pembuatan indeks. Contohnya:

• max_degree = 96.

• ef_construction = 500 atau 600.

• hg_vector_ef_search = 500 atau 600.

Tetapkan Jumlah Shard yang Sesuai

Jumlah shard yang lebih tinggi meningkatkan jumlah file manifes, yang mengurangi throughput kueri vektor perkiraan. Oleh karena itu, pilih jumlah shard yang sesuai untuk aplikasi Anda. Umumnya, ikuti panduan berikut:

1. Pilih spesifikasi resource komputasi yang sesuai berdasarkan volume data vektor Anda. Sebagai contoh, untuk vektor 768-dimensi, ikuti panduan di bawah. Untuk rekomendasi spesifik dimensi lainnya, lihat Tipe instans yang direkomendasikan untuk komputasi vektor.

   1. Indeks penuh di memori: 5 juta vektor per worker.

   2. Indeks hibrida memori-disk: 100 juta vektor per worker.

2. Tentukan jumlah shard berdasarkan spesifikasi resource komputasi Anda. Umumnya, atur jumlah shard sama dengan jumlah worker. Misalnya, untuk instans 64 CU, atur shard_count menjadi 4.

   Pengaturan SQL contoh:

   -- Buat tabel vektor dan tempatkan dalam kelompok tabel dengan Shard Count = 4
   CALL HG_CREATE_TABLE_GROUP ('test_tg_shard_4', 4);
   
   CREATE TABLE feature_tb (
       id bigint not null,
       feature float4[] CHECK(array_ndims(feature) = 1 AND array_length(feature, 1) = 4)
   )
   WITH (
       table_group = 'test_tg_shard_4',
       vectors = '{
       "feature": {
           "algorithm": "HGraph",
           "distance_method": "Cosine",
           "builder_params": {
               "base_quantization_type": "sq8_uniform",
               "graph_storage_type": "compressed",
               "max_degree": 64,
               "ef_construction": 400,
               "precise_quantization_type": "fp32",
               "use_reorder": true,
               "max_total_size_to_merge_mb" : 4096
           }
       }
       }'
   );

Skenario Kueri Hibrida Vektor dan Skalar

Untuk pengambilan vektor dengan kondisi filter, skenario dibagi menjadi kategori berikut:

Skenario Kueri 1: Kolom string sebagai kondisi filter

Berikut adalah contoh kueri. Skenario umum adalah mengambil data vektor dalam organisasi tertentu—misalnya, data wajah siswa dalam kelas tertentu.

SELECT(feature, '{1,2,3,4}') AS d FROM feature_tb WHERE uuid = 'x' ORDER BY d LIMIT 10;

Optimalkan sebagai berikut:

• Tetapkan UUID sebagai kunci distribusi. Ini memastikan data yang difilter identik berada dalam shard yang sama, sehingga satu kueri hanya mengakses satu shard.

• Tetapkan UUID sebagai kunci pengelompokan. Data diurutkan dalam file sesuai kunci pengelompokan.

Skenario Kueri 2: Bidang waktu sebagai kondisi filter

Berikut adalah contoh kueri. Anda sering memfilter data vektor berdasarkan waktu. Tetapkan time_field sebagai kunci segmen untuk cepat menemukan file data yang relevan.

SELECT xx_distance(feature, '{1,2,3,4}') AS d FROM feature_tb WHERE time_field BETWEEN '2020-08-30 00:00:00' AND '2020-08-30 12:00:00' ORDER BY d LIMIT 10;

Oleh karena itu, untuk pengambilan vektor dengan kondisi filter apa pun, pernyataan pembuatan tabel khas adalah sebagai berikut:

-- Catatan: Jika Anda tidak memfilter berdasarkan waktu, Anda dapat menghapus indeks terkait time_field.
CREATE TABLE feature_tb (
    time_field timestamptz NOT NULL,
    uuid text NOT NULL,
    feature float4[] CHECK(array_ndims(feature) = 1 AND array_length(feature, 1) = 4)
)
WITH (
    distribution_key = 'uuid',
    segment_key = 'time_field',
    clustering_key = 'uuid',
    vectors = '{
    "feature": {
        "algorithm": "HGraph",
        "distance_method": "Cosine",
        "builder_params": {
            "base_quantization_type": "sq8_uniform",
            "graph_storage_type": "compressed",
            "max_degree": 64,
            "ef_construction": 400,
            "precise_quantization_type": "fp32",
            "use_reorder": true,
            "max_total_size_to_merge_mb" : 4096
        }
    }
    }'
);

ASYNC REBUILD TABLE <table_name> 
WITH (
    rebuild_guc_hg_computing_resource = 'serverless'
)
SET (
    bitmap_columns = '<col1>,<col2>',
    dictionary_encoding_columns = '<col1>:on,<col2>:off',
    vectors = '{
    "<col_vector>": {
        "algorithm": "HGraph",
        "distance_method": "Cosine",
        "builder_params": {
            "base_quantization_type": "rabitq",
            "graph_storage_type": "compressed",
            "max_degree": 64,
            "ef_construction": 400,
            "precise_quantization_type": "fp32",
            "use_reorder": true,
            "max_total_size_to_merge_mb" : 4096
        }
    }
    }'
);

BEGIN ;
-- Bersihkan tabel sementara yang mungkin ada
DROP TABLE IF EXISTS <table_new>;
-- Buat tabel sementara
SET hg_experimental_enable_create_table_like_properties=on;
CALL HG_CREATE_TABLE_LIKE ('<table_new>', 'select * from <table>');
COMMIT ;

-- Aktifkan penyimpanan berorientasi kolom untuk data berformat JSON pada kolom yang sesuai
ALTER TABLE <table_new> ALTER COLUMN <column_name> SET (enable_columnar_type = ON);
-- Buat indeks teks penuh untuk kolom yang sesuai
CREATE INDEX <idx_name> ON <table_new> USING FULLTEXT (column_name);

-- Masukkan data ke tabel sementara, jalankan menggunakan resource Serverless, dan selesaikan pembuatan indeks secara sinkron
SET hg_computing_resource = 'serverless';
INSERT INTO <table_new> SELECT * FROM <table>;
ANALYZE <table_new>;

BEGIN ;
-- Hapus tabel lama
DROP TABLE IF EXISTS  <table>;
-- Ubah nama tabel sementara
ALTER TABLE <table_new> RENAME TO <table>;
COMMIT ;