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 ステートメントを使用します。