SYSTEM$CLUSTERING_INFORMATION¶

Syntaxe¶

SYSTEM$CLUSTERING_INFORMATION( '<table_name>'
    [ , { '( <expr1> [ , <expr2> ... ] )' | <number_of_errors> } ] )

Arguments¶

table_name

Table pour laquelle vous voulez renvoyer des informations de clustering.

(expr1 [ , expr2 ... ])

Noms de colonnes ou expressions pour lesquelles des informations de clustering sont retournées :

• Pour une table sans clé de clustering, cet argument est requis. Si cet argument est omis, une erreur est renvoyée.

• Pour une table avec une clé de clustering, cet argument est facultatif. Si l’argument est omis, Snowflake utilise la clé de clustering définie pour renvoyer des informations de clustering.

Même si un seul nom de colonne ou une seule expression est transmis(e), il/elle doit être entre parenthèses.

Note

Vous pouvez utiliser cet argument pour renvoyer des informations de clustering pour n’importe quelle colonne de la table, peu importe si une clé de clustering est définie pour la table.

En d’autres termes, vous pouvez l’utiliser pour vous aider à choisir le type de clustering à utiliser à l’avenir.

number_of_errors

Nombre d’erreurs de clustering renvoyées par la fonction. Si cet argument est omis, les 10 dernières erreurs sont renvoyées.

Notes sur l’utilisation¶

• Le deuxième argument de la fonction spécifie un nom de colonne/une expression ou un nombre d’erreurs. Vous ne pouvez pas inclure les deux arguments dans un seul appel de fonction.

• Le nom de la table, le nom de la colonne et l’expression sont des chaînes et doivent être placés entre guillemets simples.

Sortie¶

La fonction renvoie une valeur de type VARCHAR.

La chaîne renvoyée est au format JSON et contient les paires nom/valeur suivantes :

cluster_by_keys

Colonnes de la table utilisées pour renvoyer les informations de clustering ; il peut s’agir de n’importe quelle colonne de la table.

notes

Cette colonne peut contenir des suggestions pour rendre le clustering plus efficace. Par exemple, ce champ peut contenir un avertissement si la cardinalité de la colonne de clustering est extrêmement élevée.

Cette colonne peut être vide.

Pour plus d’informations sur la façon d’effectuer un cluster de façon efficace, voir Stratégies de sélection des clés de clustering.

total_partition_count

Nombre total de micro-partitions qui composent la table.

total_constant_partition_count

Nombre total de micro-partitions pour lesquelles la valeur des colonnes spécifiées a atteint un état constant (c’est-à-dire que les micro-partitions ne profiteront pas du reclustering de manière significative). Le nombre de micro-partitions constantes dans une table a un impact sur l’allègement des requêtes. Plus le nombre est élevé, plus le nombre de micro-partitions peut être réduit à partir des requêtes exécutées sur la table, ce qui a un impact correspondant sur les performances.

average_overlaps

Nombre moyen de micro-partitions se chevauchant pour chaque micro-partition de la table. Un chiffre élevé indique que la qualité du clustering de la table n’est pas optimale.

average_depth

Profondeur moyenne de chevauchement de chaque micro-partition de la table. Un chiffre élevé indique que la qualité du clustering de la table n’est pas optimale.

Cette valeur est également renvoyée par SYSTEM$CLUSTERING_DEPTH.

partition_depth_histogram

Histogramme illustrant la distribution de la profondeur de chevauchement pour chaque micro-partition de la table. L’histogramme contient des compartiments de largeurs différentes :

• de 0 à 16 avec des incréments de 1.

• Pour les compartiments plus grands que 16, les incréments sont égaux à deux fois la largeur du compartiment précédent (par ex. 32, 64, 128 …).

clustering_errors

Un tableau d’objets JSON, chacun avec une paire nom/valeur timestamp et error. L”error décrit pourquoi le clustering automatique n’a pas pu regrouper les données.

Par défaut, les 10 dernières erreurs sont renvoyées dans le tableau. Pour renvoyer plus ou moins d’erreurs, spécifiez un nombre comme deuxième argument de la fonction.

Pour plus d’informations sur le chevauchement et la profondeur des micropartitions et leur impact sur le raccourcissement des requêtes, voir Fonctionnement des structures de table dans Snowflake.

Exemples¶

Renvoie les 5 erreurs de clustering les plus récentes :

SELECT SYSTEM$CLUSTERING_INFORMATION('t1', 5);

Copy

Renvoyez les informations de clustering pour une table en utilisant deux colonnes dans la table :

SELECT SYSTEM$CLUSTERING_INFORMATION('test2', '(col1, col3)');

Copy

+--------------------------------------------------------------------+
| SYSTEM$CLUSTERING_INFORMATION('TEST2', '(COL1, COL3)')             |
|--------------------------------------------------------------------|
| {                                                                  |
|   "cluster_by_keys" : "LINEAR(COL1, COL3)",                        |
|   "total_partition_count" : 1156,                                  |
|   "total_constant_partition_count" : 0,                            |
|   "average_overlaps" : 117.5484,                                   |
|   "average_depth" : 64.0701,                                       |
|   "partition_depth_histogram" : {                                  |
|     "00000" : 0,                                                   |
|     "00001" : 0,                                                   |
|     "00002" : 3,                                                   |
|     "00003" : 3,                                                   |
|     "00004" : 4,                                                   |
|     "00005" : 6,                                                   |
|     "00006" : 3,                                                   |
|     "00007" : 5,                                                   |
|     "00008" : 10,                                                  |
|     "00009" : 5,                                                   |
|     "00010" : 7,                                                   |
|     "00011" : 6,                                                   |
|     "00012" : 8,                                                   |
|     "00013" : 8,                                                   |
|     "00014" : 9,                                                   |
|     "00015" : 8,                                                   |
|     "00016" : 6,                                                   |
|     "00032" : 98,                                                  |
|     "00064" : 269,                                                 |
|     "00128" : 698                                                  |
|   },                                                               |
|   "clustering_errors" : [ {                                        |
|      "timestamp" : "2023-04-03 17:50:42 +0000",                    |
|      "error" : "(003325) Clustering service has been disabled.\n"  |
|      }                                                             |
|   ]                                                                |
| }                                                                  |
+--------------------------------------------------------------------+

Cet exemple indique que la table test2 n’est pas regroupée correctement pour les raisons suivantes :

• Zéro (0) micro-partition constante sur 1156 micro-partitions au total.

• Moyenne élevée de micro-partitions qui se chevauchent.

• Profondeur moyenne de chevauchement élevée entre les micro-partitions.

• La plupart des micro-partitions sont regroupées à l’extrémité inférieure de l’histogramme et la majorité des micro-partitions ont une profondeur de chevauchement entre 64 et 128.

• Le clustering automatique était auparavant désactivé.

Limites¶

Si une table comporte plus de deux millions de partitions :

• Les résultats de la fonction sont basés sur un sous-ensemble des partitions de la table.

• La valeur du champ total_partition_count de la sortie est de deux millions.