SYSTEM$CLUSTERING_INFORMATION¶

構文¶

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

引数¶

table_name

クラスタリング情報を返すテーブルです。

(expr1 [ , expr2 ... ])

クラスタリング情報が返される列名または式。

• クラスタリングキーのないテーブルの場合、この引数は必須です。この引数を省略すると、エラーが返されます。

• クラスタリングキーを持つテーブルの場合、この引数はオプションです。引数を省略すると、Snowflakeは定義されたクラスタリングキーを使用して、クラスタリング情報を返します。

列名または式が1つだけ渡される場合でも、括弧内に含める必要があります。

注釈

この引数を使用して、テーブルにクラスタリングキーが定義されているかどうかに関係なく、テーブル内にある任意の列のクラスタリング情報を返すことができます。

つまり、これを使用して、将来使用するクラスタリングを決定できます。

number_of_errors

関数が返したクラスタリングエラーの数。この引数が省略された場合は、最新の10件のエラーが返されます。

使用上の注意¶

• 関数の第2引数は、列名/式 または エラー数を指定します。1つの関数呼び出しに両方の引数を含めることはできません。

• テーブル名、列名、式は文字列であり、一重引用符で囲む必要があります。

Returns¶

この関数は、 VARCHAR 型の値を返します。

返される文字列は JSON 形式で、次の名前と値のペアが含まれています。

cluster_by_keys

クラスタリング情報を返すために使用されるテーブルの列です。テーブル内の任意の列を使用できます。

notes

この列には、クラスタリングをより効率的にするための提案を含めることができます。例えば、クラスタリング列のカーディナリティが非常に高い場合、このフィールドには警告が含まれる場合があります。

この列は空にすることができます。

効率的にクラスター化する方法の詳細については、 クラスタリングキーを選択するための戦略 をご参照ください。

total_partition_count

テーブルを構成するマイクロパーティションの総数。

total_constant_partition_count

指定された列の値が一定の状態に達したマイクロパーティションの合計数（つまり、マイクロパーティションは再クラスタリングの恩恵を受けない）。テーブル内の一定のマイクロパーティションの数は、クエリのプルーニングに影響を与えます。数値が大きいほど、テーブルで実行されるクエリからより多くのマイクロパーティションをプルーニングできます。これは、パフォーマンスに相応の影響があります。

average_overlaps

テーブル内にある各マイクロパーティションの重複するマイクロパーティションの平均数です。数値が大きい場合は、テーブルが適切にクラスター化されていないことを示します。

average_depth

テーブル内にある各マイクロパーティションの平均重複深度です。数値が大きい場合は、テーブルが適切にクラスター化されていないことを示します。

この値は、 SYSTEM$CLUSTERING_DEPTH によっても返されます。

partition_depth_histogram

テーブル内にある各マイクロパーティションの重複深度の分布を示すヒストグラムです。ヒストグラムには幅のあるバケットが含まれます。

• 1 の増分で 0 から 16。

• 16 より大きいバケットの場合、前のバケットの幅の2倍の増分（例： 32、 64、 128、...）。

clustering_errors

timestamp と error の名前/値のペアを持つ JSON オブジェクトの配列。 error は、自動クラスタリングがデータを再クラスタリングできなかった理由を説明します。

デフォルトでは、最新の10件のエラーが配列に返されます。より多く、またはより少なくエラーを返すには、関数の第2引数に数値を指定します。

マイクロパーティションの重複と深度、およびクエリプルーニングへの影響の詳細については、 Snowflakeテーブル構造について をご参照ください。

例¶

最新のクラスタリングエラー5件を返します。

CopyExpand

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

Show lessSee more

Scroll to top

テーブルの2つの列を使用して、テーブルのクラスタリング情報を返します。

CopyExpand

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

Show lessSee more

Scroll to top

Expand

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

Show lessSee more

Scroll to top

この例は、次の理由により、 test2 テーブルがクラスター化されて いない ことを示しています。

• 合計 1156 個のマイクロパーティションのうち、ゼロ（0）の一定のマイクロパーティション。

• 重複するマイクロパーティションの平均が高い。

• マイクロパーティション全体の重複深度の平均が高い。

• ほとんどのマイクロパーティションはヒストグラムの下端でグループ化されており、大半のマイクロパーティションが 64 と 128 の間の重複深度である。

• 以前に自動クラスタリングが無効になっていた。

制限事項¶

テーブルのパーティションが200万個を超える場合、

• この関数の結果は、テーブルのパーティションのサブセットに基づいています。

• 出力の total_partition_count フィールドの値は200万です。