Statistiques sur l'index vectoriel

Cette page décrit la table Spanner intégrée qui stocke des statistiques sur vos index vectoriels. Vous pouvez utiliser les statistiques d'index vectoriel pour examiner les performances de votre index vectoriel, identifier les points à améliorer et ajuster votre index en fonction des métriques.

Vous pouvez récupérer les statistiques de la table SPANNER_SYS.VECTOR_INDEX_STATS à l'aide d'instructions SQL.

Spanner fournit les statistiques d'index vectoriel dans le schéma SPANNER_SYS. Vous pouvez accéder aux données SPANNER_SYS de différentes manières :

Statistiques sur l'index vectoriel

SPANNER_SYS.VECTOR_INDEX_STATS contient les statistiques de chaque index vectoriel de votre base de données, triées par STATISTICS_COLLECTION_TIMESTAMP. Spanner collecte des données sur chaque index vectoriel tous les trois jours. Peu de temps après la collecte des données, Spanner les met à disposition dans la table VECTOR_INDEX_STATS. Les informations de ce tableau vous donnent des insights sur votre index. Vous pouvez ainsi l'ajuster et appliquer des recommandations pour améliorer les performances de la recherche vectorielle.

Nom de la colonne Description Conseils de réglage
START_TIME Heure à laquelle Spanner a collecté la métrique d'index. Non applicable
VECTOR_INDEX_NAME Nom de l'index vectoriel, tel qu'indiqué dans l'instruction CREATE VECTOR INDEX. Non applicable
NUM_LEAVES Nombre total de feuilles (également appelées clusters) utilisées dans cet index vectoriel. Ce nombre est déterminé au moment de la création de l'index vectoriel. Il peut varier au fil du temps à mesure que Spanner remodèle de manière adaptative l'index vectoriel. Si de nombreuses lignes sont ajoutées à la table indexée après sa création, il est possible que certains clusters deviennent très volumineux, ce qui peut avoir un impact sur la latence des requêtes. Nous vous recommandons de recréer l'index avec plus de clusters si le nombre de clusters dans l'index est supérieur ou égal à la racine carrée du nombre de lignes dans la table.
NUM_ZERO_SIZE_CLUSTERS_SAMPLED Nombre échantillonné de clusters vides dans l'index vectoriel. Les clusters vides ne comportent aucune ligne.

Au fil du temps, des lignes sont ajoutées et supprimées d'un tableau, ce qui peut entraîner la suppression de certains clusters. Si de nombreux clusters sont vides, l'index vectoriel est probablement obsolète. Si 10 % ou plus des clusters sont vides, envisagez de reconstruire l'index avec moins de clusters. Pour les index vectoriels plus volumineux, Spanner utilise un échantillonnage aléatoire pour limiter le coût des mesures. Par conséquent, cette métrique représente le nombre de clusters de taille nulle échantillonnés. Pour convertir cette valeur en nombre estimé de clusters de taille zéro, vous pouvez utiliser la requête suivante :

SELECT NUM_ZERO_SIZE_CLUSTERS_SAMPLED / NUM_CLUSTERS_SAMPLED AS ESTIMATED_PERCENT_OF_CLUSTERS_WITH_SIZE_ZERO
CLUSTER_SIZE_PERCENTILES Un index vectoriel divise les embeddings indexés en clusters de vecteurs proches. Cette colonne de distribution indique certaines valeurs de centile des tailles de ces clusters. Le processus de clustering en k-moyennes, qui alimente l'indexation vectorielle, produit généralement des clusters de tailles différentes. Par conséquent, un certain déséquilibre est attendu. En cas d'écarts importants dans la taille des clusters, les performances des requêtes ralentissent lors de la recherche dans les clusters les plus volumineux. Les écarts sont considérés comme importants si la taille du cluster au 99e centile est au moins huit fois supérieure à celle du cluster au 50e centile. Consultez l'exemple de requête 1.
CLUSTER_AVERAGE_DISTANCE_TO_CENTROID_PERCENTILES Chaque cluster possède un point central, ou centroïde. Pour obtenir un bon rappel, les vecteurs sont généralement attribués à un centroïde proche, selon la configuration que vous avez choisie lors de la création de l'index. Pour chaque cluster, Spanner calcule la distance moyenne estimée entre le centroïde et tous les vecteurs attribués. En raison de la variance naturelle entre les clusters, Spanner indique cette métrique sous forme de distribution, qui se présente sous la forme d'une liste de valeurs de centiles. Cette métrique n'est pas comparable entre les index vectoriels (en particulier, les index euclidiens et les index de cosinus sont mis à l'échelle différemment). Suivez cette métrique au fil du temps pour chaque index vectoriel individuellement. Si la valeur du 99e centile double par rapport à son plus bas historique, envisagez de reconstruire l'index pour la faire redescendre. Voir l'exemple de requête 2.

Exemple de requête 1

La requête suivante indique la taille du cluster au 99e centile divisée par la taille médiane du cluster pour un index vectoriel spécifique, au fil du temps. Si la taille du cluster au 99e centile est au moins huit fois plus grande que celle du cluster au 50e centile, envisagez de reconstruire votre index."

 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;

Sortie de la requête

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 EUR

Exemple de requête 2

La requête suivante indique la distance au centroïde au 99e centile pour chaque index vectoriel, au fil du temps. Cette métrique est une indication indirecte des performances de rappel. La signification exacte des valeurs dépend de vos embeddings. Suivez chaque index de vecteur individuellement et sous forme de série temporelle. Si la valeur du 99e centile double par rapport à son niveau le plus bas pour un index donné, envisagez de reconstruire l'index.

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;

Sortie de la requête

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

Conservation des données

La table système SPANNER_SYS.VECTOR_INDEX_METRICS_HISTORY conserve les données des 30 derniers jours.

Étapes suivantes