Hologres:Use o HGraph para busca vetorial

Crie um índice

Crie um índice vetorial ao criar uma tabela. O Hologres armazena vetores como arrays float4. A dimensão do vetor corresponde ao tamanho do array unidimensional (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>": { ... } ]
  }'
);

Parâmetros da tabela

O parâmetro vectors aceita uma string formatada em JSON. No nível superior, use apenas uma chave vector_column_name para especificar a coluna para a qual criar o índice. O valor dessa chave é um objeto JSON com os seguintes campos:

Métodos de distância e ordem de classificação obrigatória

Parâmetros de construção

Modifique um índice

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

Exclua um índice

-- Delete vector indexes for all columns in the table
ALTER TABLE <TABLE_NAME>
SET (
    vectors = '{}'
);

-- If col1 and col2 both have vector indexes and you need to delete only the index for col2,
-- use ALTER TABLE to retain only the index for col1.
ALTER TABLE <TABLE_NAME>
SET (
    vectors = '{
    "col1": { ... }
  }'
);

Visualize um índice

Consulte a tabela do sistema hologres.hg_table_properties para visualizar os índices vetoriais criados.

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

Recuperação aproximada vs. exata

O Hologres é compatível com recuperação vetorial aproximada e exata. Apenas as funções de recuperação aproximada podem usar o índice vetorial para acelerar as consultas. A função aproximada usada em uma consulta deve corresponder ao distance_method do índice e respeitar a ordem de classificação obrigatória; caso contrário, o índice não será usado.

Funções de distância vetorial

As funções de distância não suportam parâmetros de entrada totalmente constantes.

Verifique o uso do índice

Execute EXPLAIN ou EXPLAIN ANALYZE em sua consulta para verificar se o plano de execução usa o índice vetorial. Se o plano contiver Vector Filter, o índice está ativo.

Consulta de exemplo:

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

Plano de execução de exemplo (o índice é usado):

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

Quando usar um índice vetorial

Para pequenos volumes de dados (por exemplo, dezenas de milhares de registros) ou quando sua instância tem amplos recursos de computação, ignore o índice vetorial e use o cálculo por força bruta (exato). Adicione um índice vetorial apenas quando a recuperação exata não puder atender aos seus requisitos de latência, throughput ou escalabilidade.

Lembre-se de que os índices vetoriais são inerentemente aproximados:

• A taxa de recall não pode atingir 100%.

• Uma consulta com LIMIT 1000 pode retornar menos de 1.000 resultados.

Escolha um método de quantização

O base_quantization_type controla o compromisso entre uso de memória, velocidade de consulta e precisão de recall. Os valores compatíveis são: sq8, sq8_uniform, fp16, fp32 e rabitq. Tipos de quantização de maior precisão usam mais memória, mas oferecem maior precisão de recall; tipos de menor precisão usam menos memória e melhoram a velocidade da consulta ao custo de parte da precisão.

Para workloads sensíveis a latência com índices totalmente em memória, use sq8_uniform ou rabitq. Para grandes conjuntos de dados com índices híbridos de memória e disco, use rabitq. Ao usar rabitq, a ativação de use_reorder: true com precise_quantization_type: fp32 pode melhorar a precisão do recall.

Escolha uma configuração de índice para seu workload

Para um índice vetorial de tabela única, coluna única e 768 dimensões, use as configurações a seguir como ponto de partida.

Para várias colunas vetoriais na mesma tabela, reduza proporcionalmente os limites de linhas por shard. O tamanho da dimensão do vetor também afeta esses limites.

Exemplo de índice totalmente em memória

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
        }
    }
    }'
);

Exemplo de índice híbrido de memória e disco

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
        }
    }
    }'
);

Ajuste a taxa de recall

Os seguintes parâmetros de índice alcançam uma taxa de recall padrão acima de 95% no dataset VectorDBBench:

• base_quantization_type: rabitq ou sq8_uniform

• precise_quantization_type: fp32

• max_degree: 64

• ef_construction: 400

Durante a consulta, o parâmetro Grand Unified Configuration (GUC) hg_vector_ef_search controla o tamanho da lista de candidatos durante a recuperação. O valor padrão é 80, o que equilibra precisão e uso de recursos.

Para elevar o recall acima de 99%, aumente hg_vector_ef_search mantendo os parâmetros do índice inalterados:

SET hg_vector_ef_search = 400;

Para alcançar um recall de 99,5% a 99,7%, ajuste simultaneamente os parâmetros de construção do índice e o parâmetro de consulta. Isso aumenta a latência e o uso de recursos da consulta, além do tempo e do uso de recursos na construção do índice:

• max_degree: 96

• ef_construction: 500 ou 600

• hg_vector_ef_search: 500 ou 600

Defina uma contagem de shards adequada

Mais shards produzem mais arquivos de manifesto, o que reduz o throughput de consultas aproximadas. Siga estas diretrizes:

1. Dimensione os recursos de computação de acordo com seus dados. Para vetores de 768 dimensões: Para outras dimensões de vetor, consulte Vector search instance specs.

   • Índice totalmente em memória: até 5 milhões de vetores por worker.

   • Índice híbrido de memória e disco: até 100 milhões de vetores por worker.

2. Defina a contagem de shards igual ao número de workers. Para uma instância de 64 CU, defina shard_count como 4.

-- Create a table group with 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
        }
    }
    }'
);

Consultas híbridas de vetores e escalares

Para consultas que combinam recuperação vetorial com condições de filtro escalar, os padrões típicos são:

Filtre por uma coluna string (por exemplo, ID da organização ou do grupo)

Um caso de uso comum é recuperar vetores em um grupo específico (por exemplo, dados de reconhecimento facial de alunos de uma turma específica).

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

Otimize da seguinte forma:

• Defina uuid como chave de distribuição. Isso garante que todos os dados do mesmo valor de filtro fiquem no mesmo shard, então a consulta acessa apenas um shard.

• Defina uuid como chave de clusterização. Isso classifica os dados dentro dos arquivos por uuid, reduzindo o intervalo de varredura.

Filtre por um campo de tempo

SELECT <distance_function>(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;

Defina time_field como chave de segmento. Isso permite que o Hologres localize rapidamente os arquivos de dados relevantes por intervalo de tempo.

Estrutura de tabela recomendada para consultas híbridas

-- Remove time_field and its segment_key if you do not filter by time.
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
        }
    }
    }'
);

Reconstrua índices usando recursos serverless

Algumas alterações de propriedades acionam a compactação e a reconstrução do índice, o que pode causar picos de uso de CPU. Trate essas alterações da seguinte forma:

Alterações em bitmap_columns, dictionary_encoding_columns ou índices vetoriais

Use a sintaxe REBUILD com recursos do Serverless Computing em vez de ALTER TABLE ... SET. Para mais informações, consulte REBUILD.

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
        }
    }
    }'
);

Alterações no armazenamento colunar para dados JSON ou colunas de índice de texto completo

A sintaxe REBUILD ainda não é compatível com essas alterações. Em vez disso, use uma tabela temporária:

BEGIN;
-- Clean up any existing temporary table
DROP TABLE IF EXISTS <table_new>;
-- Create a temporary table with the same structure
SET hg_experimental_enable_create_table_like_properties = on;
CALL HG_CREATE_TABLE_LIKE ('<table_new>', 'select * from <table>');
COMMIT;

-- Apply the new column properties to the temporary table
ALTER TABLE <table_new> ALTER COLUMN <column_name> SET (enable_columnar_type = ON);
CREATE INDEX <idx_name> ON <table_new> USING FULLTEXT (column_name);

-- Insert data using Serverless resources (index building completes synchronously)
SET hg_computing_resource = 'serverless';
INSERT INTO <table_new> SELECT * FROM <table>;
ANALYZE <table_new>;

BEGIN;
-- Replace the original table with the temporary table
DROP TABLE IF EXISTS <table>;
ALTER TABLE <table_new> RENAME TO <table>;
COMMIT;

Outras alterações de propriedades (por exemplo, distribution_key, clustering_key, segment_key, formato de armazenamento)

Use a sintaxe REBUILD com recursos do Serverless Computing.