Estatísticas do índice vetorial

Esta página descreve a tabela integrada do Spanner que armazena estatísticas sobre seus índices vetoriais. Use as estatísticas do índice de vetor para analisar a performance dele, identificar áreas de melhoria e ajustar o índice com base nas métricas.

É possível recuperar estatísticas da tabela SPANNER_SYS.VECTOR_INDEX_STATS usando instruções SQL.

O Spanner fornece as estatísticas do índice vetorial no esquema SPANNER_SYS. Você pode usar as seguintes maneiras para acessar os dados do SPANNER_SYS:

Estatísticas de índice vetorial

SPANNER_SYS.VECTOR_INDEX_STATS contém as estatísticas sobre cada índice vetorial no banco de dados, classificadas por STATISTICS_COLLECTION_TIMESTAMP. O Spanner coleta dados sobre cada índice vetorial a cada três dias. Logo após a coleta, o Spanner disponibiliza os dados na tabela VECTOR_INDEX_STATS. As informações encontradas nessa tabela fornecem insights sobre seu índice, permitindo que você ajuste e aplique recomendações para um desempenho mais rápido da pesquisa vetorial.

Nome da coluna Descrição Orientações para ajuste
START_TIME O momento em que o Spanner coletou a métrica de índice. Não relevante
VECTOR_INDEX_NAME O nome do índice vetorial, conforme informado na instrução CREATE VECTOR INDEX. Não relevante
NUM_LEAVES O número total de folhas (também conhecidas como clusters) usadas neste índice de vetor. Esse número é determinado no momento da criação do índice de vetor. Ele pode mudar com o tempo à medida que o Spanner adapta e remodela o índice de vetor. Se muitas linhas forem adicionadas à tabela indexada após a criação, é possível que alguns clusters fiquem muito grandes, o que pode afetar a latência da consulta. Recomendamos recriar o índice com mais clusters se o número de clusters no índice for igual ou maior que a raiz quadrada do número de linhas na tabela.
NUM_ZERO_SIZE_CLUSTERS_SAMPLED O número de amostras de clusters vazios no índice de vetor. Clusters vazios não têm linhas atribuídas a eles.

À medida que as linhas são adicionadas e excluídas de uma tabela ao longo do tempo, alguns clusters podem ficar vazios. Se houver muitos clusters vazios, o índice de vetor provavelmente estará desatualizado. Se 10% ou mais dos clusters estiverem vazios, considere reconstruir o índice com menos clusters. Para os índices vetoriais maiores, o Spanner usa amostragem aleatória para limitar o custo das medições. Portanto, essa métrica representa o número de clusters de tamanho zero amostrados. Para converter isso no número estimado de clusters de tamanho zero, use a seguinte consulta:

SELECT NUM_ZERO_SIZE_CLUSTERS_SAMPLED / NUM_CLUSTERS_SAMPLED AS ESTIMATED_PERCENT_OF_CLUSTERS_WITH_SIZE_ZERO
CLUSTER_SIZE_PERCENTILES Um índice vetorial divide os embeddings indexados em clusters de vetores próximos. Essa coluna de distribuição fornece alguns valores de percentil dos tamanhos desses clusters. O processo de clustering K-means, que alimenta a indexação de vetores, geralmente produz clusters de tamanhos variados. Como resultado, é esperado algum desequilíbrio. Se houver desvios graves no tamanho do cluster, o desempenho da consulta vai ficar mais lento ao pesquisar os clusters maiores. Os desvios são graves se o tamanho do cluster no percentil 99 for pelo menos 8 vezes maior que o tamanho do cluster no percentil 50. Confira a consulta de exemplo 1.
CLUSTER_AVERAGE_DISTANCE_TO_CENTROID_PERCENTILES Cada cluster tem um ponto central, ou centroide. Para alcançar um bom recall, os vetores geralmente são atribuídos a um centroide próximo, de acordo com a configuração escolhida durante a criação do índice. Para cada cluster, o Spanner calcula a distância média estimada do centroide a todos os vetores atribuídos. Devido à variância natural entre clusters, o Spanner informa essa métrica como uma distribuição, apresentada como uma lista de valores de percentil. Essa métrica não é comparável entre índices vetoriais. Em particular, os índices euclidianos e de cosseno são escalonados de maneira diferente. Acompanhe essa métrica ao longo do tempo para cada índice de vetor individualmente. Se o valor do percentil 99 dobrar em relação ao mínimo histórico, considere recriar o índice para reduzir o valor. Confira a consulta de exemplo 2.

Exemplo de consulta 1

A consulta a seguir informa o tamanho do cluster do 99º percentil dividido pelo tamanho mediano do cluster para um índice vetorial específico ao longo do tempo. Se o tamanho do cluster do 99º percentil for pelo menos oito vezes maior que o tamanho do cluster do 50º percentil, considere reconstruir o índice."

 SELECT VECTOR_INDEX_NAME,
        START_TIME,
        SUM(CASE WHEN percentile = 99 THEN value_at_percentile ELSE 0 END)
        / SUM(CASE WHEN percentile = 50 THEN value_at_percentile ELSE 0 END) as cluster_size_imbalance
FROM (
  SELECT v.VECTOR_INDEX_NAME,
         v.START_TIME, d.percentile,
         d.value_at_percentile
  FROM SPANNER_SYS.VECTOR_INDEX_METRICS_HISTORY AS v,
  UNNEST(v.CLUSTER_AVERAGE_DISTANCE_TO_CENTROID_PERCENTILES)
AS d)
WHERE VECTOR_INDEX_NAME = "VecIndex2"
GROUP BY 1, 2;

Saída da consulta

VECTOR_INDEX_NAME START_TIME cluster_size_imbalance
VecIndex2 2025-12-10 10:09:55.322415+00:00 3.288
VecIndex2 2025-12-07 10:10:02.362223+00:00 3.11
VecIndex2 2025-12-04 10:09:55.180895+00:00 2,98
VecIndex2 2025-12-01 10:10:01.680543+00:00 3,01
VecIndex2 2025-11-28 10:10:02.130079+00:00 2,99

Exemplo de consulta 2

A consulta a seguir informa a distância do percentil 99 até o centroide de cada índice de vetor ao longo do tempo. Essa métrica é uma indicação indireta da performance de recall. O significado exato dos valores depende dos seus embeddings. Acompanhe cada índice de vetor individualmente e como uma série temporal. Se o valor do percentil 99 dobrar em relação ao mínimo histórico de um determinado índice, considere recriá-lo.

SELECT v.VECTOR_INDEX_NAME,
       v.START_TIME,
       d.value_at_percentile AS distance_to_centroid_99p
FROM SPANNER_SYS.VECTOR_INDEX_METRICS_HISTORY AS v,
UNNEST(v.CLUSTER_AVERAGE_DISTANCE_TO_CENTROID_PERCENTILES) AS d
WHERE d.percentile=99
ORDER BY VECTOR_INDEX_NAME, START_TIME DESC;

Saída da consulta

VECTOR_INDEX_NAME START_TIME distance_to_centroid_99p
ANNVectorBase_VI 2025-12-10 10:09:55.322415+00:00 1.109
ANNVectorBase_VI 2025-12-07 10:10:02.362223+00:00 1.11
ANNVectorBase_VI 2025-12-04 10:09:55.180895+00:00 1.18
ANNVectorBase_VI 2025-12-01 10:10:01.680543+00:00 1.11
ANNVectorBase_VI 2025-11-28 10:10:02.130079+00:00 1,04

Retenção de dados

A tabela de sistema SPANNER_SYS.VECTOR_INDEX_METRICS_HISTORY retém dados dos últimos 30 dias.

A seguir