PolarDB:Realizar recuperação vetorial usando o protocolo MySQL

Definir uma coluna vetorial

Utilize VECTOR(N) em uma instrução CREATE TABLE ou ALTER TABLE para definir uma coluna vetorial, onde N representa o número de dimensões (1–16.383). Cada dimensão é um número de ponto flutuante de precisão simples (4 bytes).

-- Define a 4-dimensional vector column
CREATE TABLE t1 (id INT PRIMARY KEY, v1 VECTOR(4));

Restrições:

• Uma coluna vetorial suporta comparação de igualdade apenas com outra coluna vetorial. Não é possível compará-la com outros tipos de dados.

• Colunas vetoriais não podem ser chave primária, chave estrangeira, chave única ou chave de partição.

• Caso N exceda 16.383, o seguinte erro será retornado: Data size (xxx Bytes, xxx dimensions) exceeds VECTOR max (65532 Bytes, 16383 dimensions) for column: 'xxx'

Converter entre formatos de string e binário

O PolarDB fornece duas funções para converter dados vetoriais entre formatos de texto e binário.

STRING_TO_VECTOR — converte uma string para o formato binário interno.

• Formato de entrada: números de ponto flutuante separados por vírgulas e delimitados por colchetes, por exemplo '[1.2, 3.4, 5.6]'.

• A saída utiliza ordem de bytes little-endian. Por exemplo, 1.0 (hex 0x3F800000) é armazenado como 0000803F.

• Se o formato de entrada for inválido, o erro Data cannot be converted to a valid vector: 'xxx' é retornado.

SELECT HEX(STRING_TO_VECTOR('[1,2,3,4]'));
-- Output: 0000803F000000400000404000008040

VECTOR_TO_STRING — converte dados vetoriais binários de volta para uma string legível.

• Entrada: dados binários onde cada 4 bytes representam uma dimensão em ordem de bytes little-endian.

• Se a entrada for inválida, o erro Data cannot be converted to a valid vector: '' é retornado.

SELECT VECTOR_TO_STRING(0x0000803F000000400000404000008040);
-- Output: [1.00000e+00,2.00000e+00,3.00000e+00,4.00000e+00]

Trabalhar com dados vetoriais

Adicione uma coluna vetorial a uma tabela existente:

ALTER TABLE t1 ADD COLUMN v1 VECTOR(4);

Insira um vetor:

-- As a string using STRING_TO_VECTOR
INSERT INTO t1 (id, v1) VALUES (1, STRING_TO_VECTOR('[1.0, 2.0, 3.0, 4.0]'));

-- In binary format directly
INSERT INTO t1 VALUES (2, 0x0000803F000000400000404000008040);

Faça upsert de um vetor:

INSERT INTO t1 VALUES (1, STRING_TO_VECTOR('[1.0, 2.0, 3.0, 4.0]'))
ON DUPLICATE KEY UPDATE v1 = STRING_TO_VECTOR('[1.0, 2.0, 3.0, 4.0]');

Atualize um vetor:

UPDATE t1 SET v1 = STRING_TO_VECTOR('[1.0, 2.0, 3.0, 4.0]') WHERE id = 1;

Exclua uma linha pelo valor do vetor:

DELETE FROM t1 WHERE v1 = STRING_TO_VECTOR('[1.0, 2.0, 3.0, 4.0]');

Visualize valores vetoriais como strings:

SELECT VECTOR_TO_STRING(v1) FROM t1;

Criar um índice vetorial

Defina um índice vetorial configurando o COMMENT da coluna em uma instrução CREATE TABLE ou ALTER TABLE.

Sintaxe:

COMMENT 'imci_vector_index=<algorithm>(<parameters>) [other_comments]'

• imci_vector_index= é um prefixo fixo que declara o índice vetorial.

• Sempre inclua parênteses após o nome do algoritmo, mesmo ao usar todos os padrões: HNSW().

• Separe múltiplos parâmetros com vírgulas.

• Cada parâmetro usa o formato name=value ou name:value.

Algoritmos de índice:

Parâmetros de construção do índice:

Todos os três algoritmos compartilham os seguintes parâmetros de tempo de construção:

O FAISS_HNSW_PQ possui dois parâmetros adicionais para controlar a quantização de produto:

Exemplo 1: Defina um índice vetorial ao criar uma tabela.

-- Method 1: Enable columnstore for the entire table
CREATE TABLE t1 (
    id INT PRIMARY KEY,
    v1 VECTOR(4) COMMENT 'imci_vector_index=HNSW(metric=COSINE, max_degree=16)'
) COMMENT 'COLUMNAR=1';

-- Method 2: Enable columnstore only for the vector column
CREATE TABLE t1 (
    id INT PRIMARY KEY,
    description TEXT,
    v1 VECTOR(4) COMMENT 'COLUMNAR=1, imci_vector_index=HNSW(metric=COSINE)'
);

Exemplo 2: Adicione um índice vetorial a uma tabela existente.

-- Method 1: Enable table-level columnstore and define the vector index in the same statement
ALTER TABLE t1
  COMMENT "COLUMNAR=1",
  MODIFY COLUMN v1 VECTOR(4) COMMENT "imci_vector_index=HNSW(metric=COSINE,max_degree=16,ef_construction=300)";

-- Method 2: Enable columnstore only for the vector column
-- The vector index is created automatically based on the column COMMENT
ALTER TABLE t1 MODIFY COLUMN v1 VECTOR(4)
  COMMENT "COLUMNAR=1 imci_vector_index=HNSW(metric=COSINE,max_degree=16,ef_construction=300)";

Modificar um índice vetorial

Requer a versão 8.0.2.2.32 ou posterior.

Altere o algoritmo ou os parâmetros do índice modificando o COMMENT da coluna.

-- Change the algorithm from HNSW to FAISS_HNSW_FLAT
ALTER TABLE t1 MODIFY COLUMN v1 VECTOR(4)
  COMMENT "imci_vector_index=FAISS_HNSW_FLAT(metric=COSINE,max_degree=16,ef_construction=300)";

-- Change max_degree from 16 to 32
ALTER TABLE t1 MODIFY COLUMN v1 VECTOR(4)
  COMMENT "imci_vector_index=HNSW(metric=COSINE,max_degree=32,ef_construction=300)";

Excluir um índice vetorial

Exclua o índice vetorial junto com o índice columnstore:

Um índice vetorial não pode existir independentemente de um índice columnstore. Desativar o columnstore exclui o índice vetorial em cascata.

ALTER TABLE t1 COMMENT 'COLUMNAR=0';

Exclua apenas o índice vetorial (requer a versão 8.0.2.2.32 ou posterior):

Limpe o COMMENT da coluna para remover o índice vetorial mantendo o índice columnstore.

ALTER TABLE t1 MODIFY COLUMN v1 VECTOR(4) COMMENT "";

Cálculo de distância

Use a função DISTANCE para calcular a similaridade entre dois vetores.

DISTANCE(vector1, vector2, '<metric>')

SELECT DISTANCE(v1, STRING_TO_VECTOR('[1.2,2.3,3.4,4.5]'), 'COSINE') FROM t1;

Busca ANN

A busca ANN utiliza um índice vetorial para recuperar vizinhos mais próximos aproximados de forma eficiente. Todas as condições a seguir devem ser atendidas para que o otimizador use o índice vetorial:

• A consulta inclui as cláusulas ORDER BY e LIMIT.

• A primeira expressão em ORDER BY é DISTANCE(...).

• A direção de ordenação é ASC.

• A coluna vetorial em DISTANCE(...) possui um índice vetorial ativo.

• A metric em DISTANCE(...) corresponde à metric usada para construir o índice.

• Se a consulta incluir um JOIN, o plano de execução deve usar uma Right Deep Join Tree, e o campo DISTANCE(...) deve vir da tabela condutora.

• A consulta não pode conter GROUP BY. Para agregar resultados, envolva a busca vetorial em uma subconsulta.

Ative a busca ANN:

Execute estes dois comandos no nível da sessão antes de executar consultas ANN.

-- Allow the optimizer to use vector indexes
SET imci_enable_vector_search = ON;

-- Force queries to use the column store execution path
SET cost_threshold_for_imci = 0;

Execute uma consulta ANN:

-- Find the top 5 most similar records
SELECT id, v1
FROM t1
WHERE category_id = 123
ORDER BY DISTANCE(v1, STRING_TO_VECTOR('[...]'), 'COSINE') ASC
LIMIT 5;

Usando GROUP BY com busca vetorial:

GROUP BY não pode aparecer na mesma consulta que ORDER BY DISTANCE(...). Execute a busca vetorial em uma subconsulta primeiro e depois agregue.

-- Incorrect: GROUP BY conflicts with ORDER BY DISTANCE()
-- SELECT category_id, COUNT(*) FROM t1
-- GROUP BY category_id
-- ORDER BY DISTANCE(v1, STRING_TO_VECTOR('[...]'), 'COSINE') ASC
-- LIMIT 5;

-- Correct: perform ANN search in a subquery, then aggregate
SELECT category_id, COUNT(*)
FROM (
    SELECT id, category_id
    FROM t1
    ORDER BY DISTANCE(v1, STRING_TO_VECTOR('[...]'), 'COSINE') ASC
    LIMIT 100
) AS nearest_neighbors
GROUP BY category_id;

Parâmetros de busca ANN:

Busca KNN (exata)

A busca KNN percorre todos os dados para calcular distâncias, garantindo 100% de recall. Ela não requer um índice vetorial e é adequada para pequenos conjuntos de dados.

-- Find the 10 most similar records
SELECT id, VECTOR_TO_STRING(v1)
FROM t1
ORDER BY DISTANCE(v1, STRING_TO_VECTOR('[1.2,2.3,3.4,4.5]'), 'COSINE')
LIMIT 10;

Consultas vetoriais com predicados

Adicione condições WHERE para filtrar resultados juntamente com a similaridade vetorial.

SELECT * FROM t1
WHERE id < 10
ORDER BY DISTANCE(v1, STRING_TO_VECTOR('[1.2, 2.3, 3.4, 4.5]'), 'COSINE')
LIMIT 2;

O otimizador seleciona uma das três estratégias de execução com base na seletividade estimada do filtro:

Execução adaptativa: Se a estimativa de contagem de linhas do otimizador for imprecisa, o sistema pode trocar de estratégias em tempo de execução. Por exemplo, ao usar a estratégia inline filter, se o número real de linhas correspondentes for menor que imci_vector_search_prefilter_rows, o sistema muda dinamicamente para prefilter.

Otimização de partição: Para predicados baseados em IDs de locatário ou tags, use o particionamento LIST DEFAULT HASH. O otimizador usa poda de partição para selecionar a melhor estratégia por partição — postfilter para partições grandes, prefilter ou inline filter para as menores.

Parâmetros de predicado:

Deslocamento do snapshot do índice

Consulte INFORMATION_SCHEMA.IMCI_INDEX_STATS para ver quantos vetores o índice columnstore carregou em seu snapshot.

SELECT schema_name, table_name, vector_rows
FROM information_schema.imci_index_stats;

Um valor VECTOR_ROWS igual a 0 significa que nenhum snapshot de índice vetorial está disponível — ou a tabela não tem índice vetorial, ou um índice recém-criado ainda não gerou um snapshot válido.

Compare VECTOR_ROWS com ROW_ID em INFORMATION_SCHEMA.IMCI_INDEXES para estimar a latência de construção. O índice vetorial ainda funciona com alguma latência — quaisquer vetores ainda não gravados no índice são tratados automaticamente durante uma busca.

Status físico do índice vetorial

Consulte INFORMATION_SCHEMA.IMCI_VECTOR_INDEX_STATS para inspecionar o estado físico de cada índice vetorial.

SELECT schema_name, table_name, column_name, vectors, memory_usage, storage_usage
FROM information_schema.imci_vector_index_stats;

A busca ANN fica indisponível para qualquer coluna não retornada por esta visualização. Um valor VECTORS igual a 0 após uma reinicialização do cluster não significa que o índice foi perdido. O índice é persistido em disco. A primeira consulta após uma reinicialização aciona o carregamento dos dados na memória. Para informações precisas sobre snapshots, use VECTOR_ROWS em INFORMATION_SCHEMA.IMCI_INDEX_STATS .