Estadísticas del índice vectorial

En esta página, se describe la tabla integrada de Spanner que almacena estadísticas sobre tus índices vectoriales. Puedes usar las estadísticas del índice de vectores para revisar el rendimiento de tu índice, identificar áreas de mejora y ajustarlo según las métricas.

Puedes recuperar estadísticas de la tabla SPANNER_SYS.VECTOR_INDEX_STATS con instrucciones de SQL.

Spanner proporciona las estadísticas del índice vectorial en el esquema SPANNER_SYS. Puedes acceder a los datos de SPANNER_SYS de las siguientes maneras:

Estadísticas del índice vectorial

SPANNER_SYS.VECTOR_INDEX_STATS contiene las estadísticas sobre cada índice vectorial de tu base de datos, ordenadas por STATISTICS_COLLECTION_TIMESTAMP. Spanner recopila datos sobre cada índice de vector cada tres días. Poco después de que se recopilan los datos, Spanner los pone a disposición en la tabla VECTOR_INDEX_STATS. La información que se encuentra en esta tabla proporciona estadísticas sobre tu índice, lo que te permite ajustar y aplicar recomendaciones para mejorar el rendimiento de la búsqueda de vectores.

Nombre de la columna Descripción Orientación para el ajuste
START_TIME Es la fecha y hora en la que Spanner recopiló la métrica del índice. No aplicable
VECTOR_INDEX_NAME Es el nombre del índice de vectores, tal como se indica en la declaración CREATE VECTOR INDEX. No aplicable
NUM_LEAVES Es la cantidad total de hojas (también conocidas como clústeres) que se usan en este índice de vectores. Este número se determina en el momento de la creación del índice de vectores. Puede cambiar con el tiempo a medida que Spanner remodela de forma adaptativa el índice de vectores. Si se agregan muchas filas a la tabla indexada después de la creación, es posible que algunos clústeres se vuelvan bastante grandes, lo que puede afectar la latencia de las consultas. Recomendamos volver a compilar el índice con más clústeres si la cantidad de clústeres en el índice es igual o superior a la raíz cuadrada de la cantidad de filas en la tabla.
NUM_ZERO_SIZE_CLUSTERS_SAMPLED Es la cantidad de clústeres vacíos muestreados en el índice de vectores. Los clústeres vacíos no tienen filas asignadas.

A medida que se agregan y borran filas de una tabla con el tiempo, es posible que algunos clústeres queden vacíos. Si hay muchos clústeres vacíos, es probable que el índice de vectores esté desactualizado. Si el 10% o más de los clústeres están vacíos, considera volver a compilar el índice con menos clústeres. En el caso de los índices de vectores más grandes, Spanner usa el muestreo aleatorio para limitar el costo de las mediciones. Por lo tanto, esta métrica representa la cantidad de clústeres de tamaño cero muestreados. Para convertir este valor en la cantidad estimada de clústeres de tamaño cero, puedes usar la siguiente consulta:

SELECT NUM_ZERO_SIZE_CLUSTERS_SAMPLED / NUM_CLUSTERS_SAMPLED AS ESTIMATED_PERCENT_OF_CLUSTERS_WITH_SIZE_ZERO
CLUSTER_SIZE_PERCENTILES Un índice de vectores divide los embeddings indexados en clústeres de vectores cercanos. Esta columna de distribución proporciona algunos valores de percentiles de los tamaños de estos clústeres. El proceso de agrupamiento en clústeres de K-means, que impulsa la indexación de vectores, suele producir clústeres de tamaño variable. Como resultado, se espera cierto desequilibrio. Si hay desviaciones graves en el tamaño del clúster, el rendimiento de las consultas se vuelve más lento cuando se buscan los clústeres más grandes. Las desviaciones son graves si el tamaño del clúster del percentil 99 es al menos 8 veces mayor que el tamaño del clúster del percentil 50. Consulta el ejemplo de consulta 1.
CLUSTER_AVERAGE_DISTANCE_TO_CENTROID_PERCENTILES Cada clúster tiene un punto central, o centroide. Para lograr una buena recuperación, los vectores suelen asignarse a un centroide cercano, según la configuración que elegiste durante la creación del índice. Para cada clúster, Spanner calcula la distancia promedio estimada desde el centroide hasta todos los vectores asignados. Debido a la variación natural entre los clústeres, Spanner informa esta métrica como una distribución, que se proporciona como una lista de valores de percentiles. Esta métrica no se puede comparar entre los índices de vectores (en particular, los índices euclidianos y los índices de coseno se ajustan de manera diferente). Haz un seguimiento de esta métrica a lo largo del tiempo para cada índice de vector de forma individual. Si el valor del percentil 99 se duplica con respecto a su mínimo histórico, considera volver a compilar el índice para reducirlo. Consulta el ejemplo de consulta 2.

Consulta de ejemplo 1

La siguiente consulta informa el tamaño del clúster del percentil 99 dividido por el tamaño del clúster de la mediana para un índice de vectores específico, a lo largo del tiempo. Si el tamaño del clúster del percentil 99 es al menos 8 veces mayor que el tamaño del clúster del percentil 50, considera volver a compilar tu í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;

Resultado de la 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

Consulta de ejemplo 2

La siguiente consulta informa el percentil 99 de la distancia al centroide para cada índice de vector a lo largo del tiempo. Esta métrica es un indicador indirecto del rendimiento de la recuperación. El significado exacto de los valores depende de tus incorporaciones. Hacer un seguimiento de cada índice de vector de forma individual y como una serie temporal Si el valor del percentil 99 se duplica con respecto a su mínimo histórico para un índice determinado, considera recompilar el índice.

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;

Resultado de la 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

Retención de datos

La tabla del sistema SPANNER_SYS.VECTOR_INDEX_METRICS_HISTORY retiene los datos de los últimos 30 días.

¿Qué sigue?