Categorias:

Funções do sistema (Informações do sistema)

SYSTEM$CLUSTERING_INFORMATION

Retorna informações de clustering, incluindo profundidade média de clustering, para uma tabela baseada em uma ou mais colunas da tabela.

Consulte também:

SYSTEM$CLUSTERING_DEPTH

Sintaxe

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

Argumentos

table_name

Tabela para a qual você deseja retornar informações de clustering.

(expr1 [ , expr2 ... ])

Nomes de colunas ou expressões para as quais as informações de clustering são retornadas:

  • Para uma tabela sem chave de clustering, este argumento é necessário. Se este argumento for omitido, um erro é devolvido.

  • Para uma tabela com uma chave de clustering, este argumento é opcional; se o argumento for omitido, o Snowflake usará a chave de clustering definida para retornar informações de clustering.

Mesmo que apenas um nome de coluna ou expressão seja passado, ele deve estar dentro de parênteses.

Nota

Você pode usar este argumento para retornar informações de clustering para qualquer coluna na tabela, independentemente de estar definida uma chave de clustering para a tabela.

Em outras palavras, você pode usar isto para ajudá-lo a decidir que clustering usar no futuro.

number_of_errors

Número de erros de clustering retornados pela função. Se este argumento for omitido, os 10 erros mais recentes serão retornados.

Notas de uso

  • O segundo argumento da função especifica uma expressão/nome de coluna ou vários erros. Você não pode incluir ambos os argumentos em uma única chamada de função.

  • O nome da tabela, o nome da coluna e a expressão são cadeias de caracteres e devem ser colocados entre aspas simples.

Returns

A função retorna um valor do tipo VARCHAR.

A cadeia de caracteres retornada está no formato JSON e contém os seguintes pares nome/valor:

cluster_by_keys

Colunas na tabela usadas para retornar informações de clustering; pode ser qualquer coluna na tabela.

notes

Esta coluna pode conter sugestões para tornar o clustering mais eficiente. Por exemplo, este campo pode conter um aviso se a cardinalidade da coluna de clustering for extremamente alta.

Esta coluna pode estar vazia.

Para obter mais informações sobre como clusterizar de forma eficiente, consulte Estratégias para a seleção de chaves de clustering.

total_partition_count

Número total de micropartições que compõem a tabela.

total_constant_partition_count

Número total de micropartições para as quais o valor das colunas especificadas atingiu um estado constante (ou seja, as micropartições não se beneficiarão significativamente do reclustering). O número de micropartições constantes em uma tabela tem um impacto na remoção para consultas. Quanto maior o número, mais micropartições podem ser removidas a partir de consultas executadas na tabela, o que tem um impacto correspondente no desempenho.

average_overlaps

Número médio de micropartições sobrepostas para cada micropartição da tabela. Um número alto indica que a tabela não está bem clusterizada.

average_depth

Profundidade média de sobreposição de cada micropartição da tabela. Um número alto indica que a tabela não está bem clusterizada.

Este valor também é devolvido por SYSTEM$CLUSTERING_DEPTH.

partition_depth_histogram

Um histograma descrevendo a distribuição da profundidade de sobreposição para cada micropartição da tabela. O histograma contém buckets com larguras:

  • 0 a 16 com incrementos de 1.

  • Para buckets maiores que 16, incrementos de duas vezes a largura do bucket anterior (por exemplo, 32, 64, 128, …).

clustering_errors

Uma matriz de objetos JSON, cada um com um par nome/valor timestamp e error. O error descreve por que o clustering automático não conseguiu agrupar novamente os dados.

Por padrão, os 10 erros mais recentes são retornados na matriz. Para retornar mais ou menos erros, especifique um número como segundo argumento da função.

Para obter mais informações sobre a sobreposição e profundidade das micropartições e seu impacto ao reduzir a consulta, consulte Explicação das estruturas de tabela do Snowflake.

Exemplos

Retorne os 5 erros de clustering mais recentes:

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

Retornar as informações de clustering para uma tabela usando duas colunas na tabela:

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"  |
|      }                                                             |
|   ]                                                                |
| }                                                                  |
+--------------------------------------------------------------------+

Este exemplo indica que a tabela test2 não é bem clusterizada pelas seguintes razões:

  • Micropartições de constante zero (0) de 1156 micropartições totais.

  • Média elevada de micropartições sobrepostas.

  • Média elevada de profundidade de sobreposição entre micropartições.

  • A maioria das micropartições está agrupada na parte inferior do histograma, com a maioria das micropartições tendo uma profundidade de sobreposição entre 64 e 128.

  • O clustering automático foi desativado anteriormente.

Limitações

Se uma tabela tiver mais de 2 milhões de partições:

  • Os resultados da função são baseados em um subconjunto das partições da tabela.

  • O campo do valor da saída total_partition_count é de 2 milhões.

Linguagem: Português