Hologres：Gunakan indeks HGraph (Direkomendasikan)

Catatan

• Hologres V4.0 dan versi yang lebih baru mendukung algoritma pengambilan vektor HGraph.

• Indeks vektor hanya didukung untuk tabel berorientasi kolom dan tabel hibrida baris-kolom. Indeks ini tidak didukung untuk tabel berorientasi baris.

• Jika Anda menghapus atau membangun ulang tabel yang memiliki indeks vektor—misalnya dengan menggunakan Insert Overwrite—jangan aktifkan fitur recycle bin karena tabel dalam recycle bin tetap mengonsumsi memori.

• Setelah membuat indeks vektor, manifes dibuat selama proses compaction yang mengikuti impor data.

• Data dalam tabel memori (Mem Table) tidak memiliki indeks vektor. Saat menjalankan permintaan pengambilan vektor, data ini diproses menggunakan komputasi brute-force.

• Anda dapat menggunakan resource Serverless Computing untuk melakukan impor data batch. Resource serverless secara sinkron menyelesaikan compaction dan pembuatan indeks selama impor data. Untuk informasi selengkapnya, lihat Gunakan Serverless Computing untuk menjalankan tugas baca dan tulis dan Gunakan Serverless Computing untuk menjalankan tugas compaction.

• Jika tidak menggunakan resource serverless, Anda harus menjalankan perintah berikut secara manual untuk memicu compaction setelah mengimpor data secara batch atau memodifikasi indeks. Untuk informasi selengkapnya, lihat Compaction (Beta).

• SELECT hologres.hg_full_compact_table('<schema_name>.<table_name>', 'max_file_size_mb=4096');

• Anda juga dapat menggunakan resource Serverless Computing untuk menjalankan kueri pengambilan vektor.

Kelola indeks vektor

Buat indeks

Anda dapat membuat indeks vektor saat membuat tabel. Sintaksnya adalah sebagai berikut:

Catatan: Di Hologres, vektor direpresentasikan sebagai array float4. Dimensi vektor adalah panjang array satu dimensi, yang ditentukan oleh `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>": { ... } ]
  }'
);

Parameter:

Parameter `vectors` untuk indeks vektor memiliki persyaratan berikut:

• Nilainya harus berupa string JSON. Tingkat teratas hanya mendukung satu kunci `vector_column_name`, yang menentukan nama kolom vektor tempat indeks akan dibuat.

• 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

Sintaksnya adalah sebagai berikut:

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 untuk semua kolom dalam tabel
ALTER TABLE <table_name>
SET (
    vectors = '{}'
);

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

Lihat indeks

Anda dapat mengkueri 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';

Gunakan indeks vektor untuk pengambilan vektor

Fungsi jarak vektor

Pengambilan vektor 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 jarak vektor tidak mendukung parameter permintaan yang seluruhnya konstan.

Verifikasi penggunaan indeks vektor

Anda dapat memeriksa rencana eksekusi untuk menentukan apakah pernyataan SQL menggunakan indeks vektor. Jika rencana tersebut berisi "Vector Filter", berarti indeks berhasil digunakan. Untuk informasi selengkapnya, lihat EXPLAIN dan EXPLAIN ANALYZE.

• Contoh:

  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

Contoh

• Buat tabel.

  -- Buat kelompok tabel dengan jumlah shard 4.
  CALL HG_CREATE_TABLE_GROUP ('test_tg_shard_4', 4);
  
  -- Buat tabel.
  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",
              "max_degree": 64,
              "ef_construction": 400,
              "precise_quantization_type": "fp32",
              "use_reorder": true,
              "max_total_size_to_merge_mb" : 4096
          }
      }
      }'
  );

• Impor data.

  -- (Opsional) Gunakan Serverless Computing untuk menjalankan impor data offline volume besar dan pekerjaan ekstrak, transformasi, dan muat (ETL). Compaction dan pembuatan indeks diselesaikan secara sinkron selama impor.
  SET hg_computing_resource = 'serverless';
  SET hg_serverless_computing_run_compaction_before_commit_bulk_load = on;
  
  INSERT INTO feature_tb SELECT i, array[random(), random(), random(), random()]::float4[] FROM generate_series(1, 100000) i;
  
  -- Setel ulang konfigurasi untuk memastikan bahwa pernyataan SQL yang tidak perlu tidak menggunakan resource serverless.
  RESET hg_computing_resource;

• Lakukan pengambilan vektor perkiraan.

  -- Hitung 40 hasil teratas berdasarkan jarak cosine.
  SELECT
      id,
      approx_cosine_distance (feature, '{0.1,0.2,0.3,0.4}') AS distance
  FROM
      feature_tb
  ORDER BY
      distance DESC
  LIMIT 40;

• Lakukan pengambilan vektor eksak.

  -- Pengambilan eksak tidak menggunakan indeks vektor. Oleh karena itu, fungsi jarak tidak perlu sama dengan distance_method indeks vektor.
  SELECT
      id,
      cosine_distance (feature, '{0.1,0.2,0.3,0.4}') AS distance
  FROM
      feature_tb
  ORDER BY
      distance DESC
  LIMIT 40;

Penyetelan performa

Gunakan indeks vektor secara tepat

Jika volume data kecil—misalnya puluhan ribu baris—atau jika instans memiliki sumber daya komputasi yang cukup, jangan atur indeks vektor. Gunakan komputasi brute-force sebagai gantinya. Anda sebaiknya hanya menggunakan indeks vektor ketika komputasi brute-force tidak dapat memenuhi kebutuhan Anda terhadap latensi atau throughput. Alasannya sebagai berikut:

• Indeks vektor bersifat lossy. Akurasi hasil, atau 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.

Saat menggunakan indeks vektor, konfigurasikan sebagai berikut. Contoh berikut menggunakan tabel non-partisi yang memiliki satu kolom vektor berdimensi 768.

• Skenario sensitif latensi: Gunakan indeks hanya di memori. Atur metode kuantisasi indeks ke `sq8_uniform` atau `rabitq`. Volume data dalam satu shard sebaiknya tidak melebihi 5 juta baris.

• Skenario non-sensitif latensi atau volume data besar: Gunakan indeks hibrida memori-disk. Atur metode kuantisasi indeks ke `rabitq`. Volume data dalam satu shard sebaiknya tidak melebihi 30 juta hingga 50 juta baris.

• Catatan: Jika Anda mengatur indeks vektor pada beberapa kolom, Anda harus mengurangi volume data yang direkomendasikan untuk satu shard secara proporsional. Dimensi vektor juga memengaruhi rekomendasi ini.

Contoh:

-- Contoh lengkap indeks hibrida
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",
            "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",
            "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 sistem default biasanya dapat melebihi 95%:

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

• `precise_quantization_type` adalah `fp32`.

• `max_degree` adalah `64`.

• `ef_construction` adalah `400`.

• `hg_vector_ef_search` diatur ke nilai default sistem yaitu 80.

Untuk lebih meningkatkan tingkat recall hingga lebih dari 99%, Anda dapat mengatur `hg_vector_ef_search` ke 400 sambil mempertahankan parameter lainnya. Namun, peningkatan tingkat recall akan meningkatkan latensi kueri dan penggunaan sumber daya komputasi.

Untuk meningkatkan tingkat recall ke kisaran 99,5% hingga 99,7%, Anda dapat lebih lanjut menyesuaikan parameter `max_degree`, `ef_construction`, dan `hg_vector_ef_search`. Penyesuaian 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 manifes dan throughput kueri yang lebih rendah. Dalam praktiknya, Anda harus mengatur jumlah shard yang sesuai berdasarkan sumber daya instans Anda. Biasanya, jumlah shard dapat disetarakan dengan jumlah worker. Misalnya, untuk instans 64-core, Anda dapat mengatur jumlah shard ke 4. Untuk mengurangi latensi kueri tunggal, Anda dapat mengurangi jumlah shard, tetapi hal ini juga mengurangi performa penulisan.

-- 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",
            "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, terdapat beberapa skenario pemfilteran umum, seperti yang dijelaskan dalam bagian ini.

Skenario kueri 1: Kolom string digunakan sebagai kondisi filter

Kueri berikut adalah contohnya. Skenario 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;

Anda dapat melakukan optimasi berikut:

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

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

Skenario kueri 2: Bidang waktu digunakan sebagai kondisi filter

Kueri berikut adalah contohnya. Biasanya, bidang waktu digunakan untuk memfilter data vektor. Anda dapat mengatur bidang waktu `time_field` sebagai kunci segmen untuk tabel. Hal ini memungkinkan lokasi cepat file yang berisi data.

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 memfilter berdasarkan waktu, Anda dapat menghapus indeks yang terkait dengan 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",
            "max_degree": 64,
            "ef_construction": 400,
            "precise_quantization_type": "fp32",
            "use_reorder": true,
            "max_total_size_to_merge_mb" : 4096
        }
    }
    }'
);

FAQ

• T: Terjadi error: "Writting column: feature with array size: 5 violates fixed size list (4) constraint declared in schema".

  J: Error ini terjadi karena dimensi data yang ditulis ke kolom vektor fitur tidak sesuai dengan dimensi yang didefinisikan dalam tabel. Periksa adanya data kotor.

• T: Terjadi error: "The size of two array must be the same in DistanceFunction, size of left array: 4, size of right array: x".

  J: Error ini terjadi karena dimensi `left` tidak sesuai dengan dimensi `right` dalam `xx_distance(left, right)`.

• T: Bagaimana cara menulis data vektor menggunakan Java?

  J: Anda dapat menggunakan kode Java contoh berikut:

  private static void insertIntoVector(Connection conn) throws Exception {
      try (PreparedStatement stmt = conn.prepareStatement("INSERT INTO feature_tb VALUES(?,?);")) {
          for (int i = 0; i < 100; ++i) {
             stmt.setInt(1, i);
             Float[] featureVector = {0.1f,0.2f,0.3f,0.4f};
             Array array = conn.createArrayOf("FLOAT4", featureVector);
             stmt.setArray(2, array);
             stmt.execute();
          }
      }
  }

• T: Bagaimana cara mengubah indeks Proxima Graph menjadi indeks HGraph?

  J: Untuk mengubah indeks Proxima Graph menjadi indeks HGraph, Anda harus melakukan dua langkah berikut secara berurutan:

  • Langkah 1: Hapus indeks Proxima Graph yang ada dari tabel. Perintah SQL-nya adalah sebagai berikut:

  CALL set_table_property ('<TABLE_NAME>', 'proxima_vectors', '{}');

  Ganti `<TABLE_NAME>` dengan nama tabel yang sebenarnya.

  • Langkah 2: Setelah indeks Proxima Graph asli dihapus, Anda dapat membuat indeks HGraph. Untuk informasi selengkapnya, lihat Buat indeks.