Hologres：Panduan indeks HGraph (Direkomendasikan)

Buat indeks

Sintaks: Buat indeks vektor saat Anda membuat tabel.

Deskripsi: Di Hologres, vektor direpresentasikan oleh array float4. Dimensi vektor ditentukan oleh panjang array satu dimensi, yaitu `array_length` dalam sintaks berikut.

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:

Nilai parameter indeks vektor `vectors` harus memenuhi persyaratan berikut:

• Hanya string berformat JSON yang didukung. Pada level teratas, hanya satu kunci `vector_column_name` yang didukung. Kunci ini menentukan nama bidang vektor yang akan diindeks.

• Nilai kunci `vector_column_name` adalah objek JSON yang digunakan untuk mengonfigurasi parameter indeks vektor. Kunci berikut didukung.

Parameter `builder_params` mendukung parameter berikut:

Modifikasi indeks

Sintaks:

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

Hapus indeks

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

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

Lihat indeks

Hologres menyediakan tabel sistem `hologres.hg_table_properties`. Anda dapat menggunakan tabel ini 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 di Hologres mendukung pengambilan perkiraan dan pengambilan eksak. Hanya fungsi pengambilan perkiraan yang dapat menggunakan indeks vektor yang telah dibuat untuk mempercepat kueri. Fungsi tersebut harus sesuai dengan `distance_method` indeks vektor. Fungsi pengambilan eksak tidak dapat menggunakan indeks vektor.

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

Verifikasi penggunaan indeks vektor

Anda dapat melihat rencana eksekusi untuk memeriksa apakah pernyataan 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 efisien

Ketika volume data kecil (misalnya, puluhan ribu baris) atau instans memiliki sumber daya komputasi yang cukup, hindari penggunaan indeks vektor. Gunakan perhitungan brute-force sebagai gantinya. Gunakan indeks vektor hanya ketika perhitungan brute-force tidak memenuhi kebutuhan Anda terkait latensi, throughput, atau metrik lainnya. Hal ini karena:

• Indeks vektor bersifat lossy, sehingga akurasi (tingkat recall) tidak dapat mencapai 100%.

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

Jika Anda memutuskan untuk menggunakan indeks vektor, konfigurasikan sebagai berikut (menggunakan tabel non-partisi dengan satu bidang vektor berdimensi 768 sebagai contoh):

• Skema sensitif latensi: Gunakan indeks hanya di memori. Untuk metode kuantisasi indeks, kami merekomendasikan `sq8_uniform` atau `rabitq`. Volume data yang direkomendasikan tidak lebih dari 5 juta baris per shard.

• Skema tidak sensitif latensi atau volume data besar: Gunakan indeks hibrid memori-disk. Untuk metode kuantisasi indeks, kami merekomendasikan `rabitq`. Volume data yang direkomendasikan tidak lebih dari 30 juta hingga 50 juta baris per shard.

• Catatan: Untuk mengatur indeks vektor pada beberapa kolom, volume data yang direkomendasikan per shard harus dikurangi secara proporsional. Dimensi vektor juga memengaruhi rekomendasi ini.

Contoh:

-- Contoh lengkap indeks hibrid
CREATE TABLE feature_tb (
    id bigint,
  	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 indeks hanya di memori
CREATE TABLE feature_tb (
    id bigint,
  	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.

Beberapa faktor dapat memengaruhi tingkat recall. Dengan pengaturan parameter indeks berikut, tingkat recall default sistem biasanya dapat mencapai lebih dari 95%:

• Parameter indeks:

  • `base_quantization_type` adalah `rabitq` atau `sq8_uniform`

  • `precise_quantization_type` adalah `fp32`

  • `max_degree` adalah `64`

  • `ef_construction` adalah `400`

• Parameter kueri (GUC):

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

Untuk lebih meningkatkan tingkat recall hingga lebih dari 99%, Anda dapat menjalankan SET hg_vector_ef_search = 400; sambil mempertahankan parameter lainnya. Namun, peningkatan tingkat recall meningkatkan latensi kueri dan penggunaan sumber daya komputasi.

Untuk lebih meningkatkan tingkat recall hingga 99,5%–99,7%, Anda dapat menyesuaikan parameter `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.

Atur jumlah shard yang sesuai

Jumlah shard yang lebih tinggi menghasilkan lebih banyak file indeks yang dibuat, yang mengurangi throughput kueri vektor perkiraan. Oleh karena itu, atur jumlah shard yang sesuai untuk aplikasi Anda. Anda biasanya dapat mengikuti langkah-langkah berikut:

1. Pilih spesifikasi instans yang sesuai berdasarkan volume data vektor. Contoh berikut untuk vektor berdimensi 768. Untuk informasi tentang dimensi lainnya, lihat Tipe instans yang direkomendasikan untuk komputasi vektor.

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

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

2. Tentukan jumlah shard berdasarkan spesifikasi instans. Biasanya, Anda dapat mengatur jumlah shard sama dengan jumlah worker. Misalnya, untuk instans 64 CU, Anda dapat mengatur `shard_count` menjadi 4.

   Berikut adalah contoh SQL:

   -- Buat tabel vektor dan tempatkan dalam kelompok tabel dengan jumlah shard 4.
   CALL HG_CREATE_TABLE_GROUP ('test_tg_shard_4', 4);
   
   CREATE TABLE feature_tb (
       id bigint,
     	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
           }
       }
       }'
   );

Skema kueri hibrid vektor dan skalar

Untuk pengambilan vektor dengan kondisi filter, berikut adalah skenario penyaringan umum:

Skema kueri 1: Kolom string digunakan sebagai kondisi filter

Berikut adalah contoh kueri. Skema umum adalah menemukan data vektor yang sesuai dalam suatu organisasi, seperti menemukan data wajah dalam suatu kelas.

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

Kami merekomendasikan optimasi berikut:

• Atur `uuid` sebagai kunci distribusi. Hal ini memastikan bahwa data dengan kondisi filter yang sama disimpan dalam shard yang sama. Kueri kemudian hanya mengakses satu shard.

• Atur `uuid` sebagai kunci pengelompokan untuk tabel. Data diurutkan dalam file berdasarkan kunci pengelompokan.

Skema kueri 2: Bidang waktu digunakan sebagai kondisi filter

Berikut adalah contoh kueri. Ini biasanya digunakan untuk menyaring data vektor berdasarkan bidang waktu. Kami merekomendasikan agar Anda mengatur bidang waktu `time_field` sebagai kunci segmen untuk tabel. Hal ini memungkinkan Anda dengan cepat menemukan file tempat data berada.

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 `CREATE TABLE` biasanya sebagai berikut:

-- Catatan: Jika Anda tidak menyaring 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 pada kolom yang sesuai.
CREATE INDEX <idx_name> ON <table_new> USING FULLTEXT (column_name);

-- Masukkan data ke tabel sementara, gunakan resource serverless untuk menjalankan pekerjaan, 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 ;