类别：

:doc:`/sql-reference/functions-system`（系统信息）

SYSTEM$CLUSTERING_INFORMATION

根据表中的一列或多列，返回表的群集信息（包括平均群集深度）。

另请参阅：

SYSTEM$CLUSTERING_DEPTH

语法

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

实参

table_name

要返回群集信息的表。

(expr1 [ , expr2 ... ])

返回群集信息的列名或表达式：

  • 对于没有群集密钥的表，必须使用此实参。如果省略此实参，将返回错误信息。

  • 对于具有群集密钥的表，此实参是可选的；如果省略此实参，Snowflake 将使用定义的群集密钥返回群集信息。

即使只传递一个列名或表达式，也必须包含在括号内。

备注

无论是否为表定义了群集密钥，都可以使用此实参返回表中任何列的群集信息。

换言之，可以使用它来帮助您确定将来要使用的群集。

number_of_errors

函数返回的群集错误数。如果省略此实参，则返回最近的 10 个错误。

使用说明

  • 该函数的第二个实参指定列名/表达式 或 错误数。不能在单个函数调用中同时包含这两个实参。

  • 表名、列名和表达式均为字符串，应放在单引号内。

输出

该函数返回 VARCHAR 类型的值。

返回的字符串采用 JSON 格式，并包含以下名称/值对：

cluster_by_keys

表中用于返回群集信息的列；可以是表中的任何列。

notes

此列可以包含使群集更有效的建议。例如，如果群集列的基数非常高，则此字段可能包含警告。

此列可以为空。

有关如何使群集更有效的更多信息，请参阅 选择群集密钥的策略。

total_partition_count

构成表的微分区总数。

total_constant_partition_count

指定列的值已达到恒定状态（即微分区不会从重聚类中明显受益）的微分区总数。表中恒定微分区的数量会影响查询的修剪。数量越多，在表上执行的查询中可修剪的微分区就越多，从而对性能产生相应的影响。

average_overlaps

表中每个微分区的平均重叠微分区数。数字越高，说明表的聚类越差。

average_depth

表中每个微分区的平均重叠深度。数字越高，说明表的聚类越差。

SYSTEM$CLUSTERING_DEPTH 也会返回此值。

partition_depth_histogram

描述表中每个微分区重叠深度分布的直方图。直方图包含以下宽度的桶：

  • 0 至 16，增量为 1。

  • 对于大于 16 的桶，增量为前一桶宽度的两倍（如 32、64、128...）。

clustering_errors

一个 JSON 对象数组，每个对象都有一个 timestamp 和 error 名称/值对。error 描述了自动聚类无法重聚类数据的原因。

默认情况下，在数组中返回 10 个最新的错误。若要增加或减少返回的错误数量，请指定一个数字作为函数的第二个实参。

有关微分区重叠和深度及其对查询修剪的影响的更多信息，请参阅 了解 Snowflake 表结构。

示例

返回 5 个最新的群集错误：

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

使用表中的两列返回表的群集信息：

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

此示例指示 test2 表 没有 很好地聚类，原因如下：

  • 在总共 1156 个微分区中，恒定微分区数量为零 (0)。

  • 重叠微分区的平均值较高。

  • 跨微分区的重叠深度平均值较高。

  • 大多数微分区分组在直方图的下端，大多数微分区的重叠深度介于 64 和 128 之间。

  • 以前禁用了自动聚类。

限制

如果表的分区超过 200 万个：

  • 函数结果基于表分区的子集。

  • 输出的 total_partition_count 字段的值为 200 万。

语言: 中文