メインコンテンツまでスキップ
メインコンテンツまでスキップ

UDFs User Defined Functions

クエリ:

結果:

Pythonスクリプト

STDIN から値を読み取り、それを文字列として返します:

XML 設定を使用して test_function を作成します。ファイル test_function.xml (デフォルトパス設定の /etc/clickhouse-server/test_function.xml)。

user_scripts フォルダ内のスクリプトファイル test_function.py (デフォルトパス設定の /var/lib/clickhouse/user_scripts/test_function.py)。

クエリ:

結果:

STDIN から 2 つの値を読み取り、それらの合計を JSON オブジェクトとして返します:

XML 設定を使用して名付け引数およびフォーマット JSONEachRow を持つ test_function_sum_json を作成します。ファイル test_function.xml (デフォルトパス設定の /etc/clickhouse-server/test_function.xml)。

user_scripts フォルダ内のスクリプトファイル test_function_sum_json.py (デフォルトパス設定の /var/lib/clickhouse/user_scripts/test_function_sum_json.py)。

クエリ:

結果:

command 設定でパラメータを使用:

実行可能なユーザー定義関数は、command 設定で構成された定数パラメータを受け取ることができます(executable タイプのユーザー定義関数にのみ有効)。これには、execute_direct オプションが必要です(シェル引数展開の脆弱性を回避するため)。 ファイル test_function_parameter_python.xml (デフォルトパス設定の /etc/clickhouse-server/test_function_parameter_python.xml)。

user_scripts フォルダ内のスクリプトファイル test_function_parameter_python.py (デフォルトパス設定の /var/lib/clickhouse/user_scripts/test_function_parameter_python.py)。

クエリ:

結果:

シェルスクリプト

各値を 2 倍にするシェルスクリプト:

実行可能なユーザー定義関数はシェルスクリプトとともに使用できます。 ファイル test_function_shell.xml (デフォルトパス設定の /etc/clickhouse-server/test_function_shell.xml)。

user_scripts フォルダ内のスクリプトファイル test_shell.sh (デフォルトパス設定の /var/lib/clickhouse/user_scripts/test_shell.sh)。

クエリ:

結果:

エラーハンドリング

一部の関数は、データが無効な場合に例外をスローすることがあります。この場合、クエリはキャンセルされ、エラーテキストがクライアントに返されます。分散処理の場合、サーバーの一つで例外が発生したとき、他のサーバーもクエリを中止しようとします。

引数式の評価

ほとんどすべてのプログラミング言語では、特定の演算子に対して引数の1つが評価されないことがあります。これは通常、演算子 &&||、 および ?: に当てはまります。しかし、ClickHouse では、関数(演算子)の引数は常に評価されます。これは、カラムの全体の部分が一度に評価され、各行を別々に計算するのではないからです。

分散クエリ処理のための関数の実行

分散クエリ処理のために、可能な限り多くのクエリ処理のステージはリモートサーバーで実行され、残りのステージ(中間結果の統合やそれ以降の全て)はリクエスターサーバーで実行されます。

これは、関数が異なるサーバーで実行される可能性があることを意味します。 例えば、クエリ SELECT f(sum(g(x))) FROM distributed_table GROUP BY h(y), の場合、

  • distributed_table に少なくとも 2 つのシャードがある場合、関数 'g' と 'h' はリモートサーバーで実行され、関数 'f' はリクエスターサーバーで実行されます。
  • distributed_table にひとつのシャードしかない場合、すべての 'f'、 'g'、および 'h' の関数はこのシャードのサーバーで実行されます。

関数の結果は、通常、実行されるサーバーに依存しません。ただし、時には重要なこともあります。 例えば、辞書を扱う関数は、実行されているサーバーに存在する辞書を使用します。 もう一つの例は、hostName 関数で、実行されているサーバーの名前を返し、SELECT クエリでサーバーごとに GROUP BY を行います。

クエリで関数がリクエスターサーバーで実行される場合でも、リモートサーバーで実行する必要がある場合は、'any' 集約関数でラップするか、GROUP BY のキーに追加することができます。

SQL ユーザー定義関数

カスタム関数は、CREATE FUNCTION ステートメントを使用して lambda 式から作成できます。これらの関数を削除するには、DROP FUNCTION ステートメントを使用します。

ClickHouse Cloud におけるユーザー定義関数