thevar1able/ClickHouse
1
0
Fork 0
mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-11-22 15:42:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix documentation for executable user defined functions configuration

Browse Source
This commit is contained in:
Maksim Kita 2022-04-28 18:01:10 +02:00
parent ab389e2cbb
commit fc4f241f01
5 changed files with 84 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/en/operations/server-configuration-parameters/settings.md
View File

@ -23,7 +23,7 @@ Default value: 3600.
Data compression settings for [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md)-engine tables. Data compression settings for [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md)-engine tables.
:::warning :::warning
Don’t use it if you have just started using ClickHouse. Don’t use it if you have just started using ClickHouse.
::: :::
@ -253,6 +253,23 @@ See also “[External dictionaries](../../sql-reference/dictionaries/external-di
<dictionaries_config>*_dictionary.xml</dictionaries_config> <dictionaries_config>*_dictionary.xml</dictionaries_config>
``` ```
## user_defined_executable_functions_config {#server_configuration_parameters-user_defined_executable_functions_config}
The path to the config file for executable user defined functions.
Path:
- Specify the absolute path or the path relative to the server config file.
- The path can contain wildcards \* and ?.
See also “[Executable User Defined Functions](../../sql-reference/functions/index.md#executable-user-defined-functions).”.
**Example**
``` xml
<user_defined_executable_functions_config>*_dictionary.xml</user_defined_executable_functions_config>
```
## dictionaries_lazy_load {#server_configuration_parameters-dictionaries_lazy_load} ## dictionaries_lazy_load {#server_configuration_parameters-dictionaries_lazy_load}
Lazy loading of dictionaries. Lazy loading of dictionaries.
@ -1357,6 +1374,16 @@ The directory with user files. Used in the table function [file()](../../sql-ref
<user_files_path>/var/lib/clickhouse/user_files/</user_files_path> <user_files_path>/var/lib/clickhouse/user_files/</user_files_path>
``` ```
## user_scripts_path {#server_configuration_parameters-user_scripts_path}
The directory with user scripts files. Used for Executable user defined functions [Executable User Defined Functions](../../sql-reference/functions/index.md#executable-user-defined-functions).
**Example**
``` xml
<user_scripts_path>/var/lib/clickhouse/user_scripts/</user_scripts_path>
```
## users_config {#users-config} ## users_config {#users-config}
Path to the file that contains: Path to the file that contains:

18
docs/en/sql-reference/dictionaries/external-dictionaries/external-dicts-dict-sources.md
View File

@ -3,7 +3,7 @@ sidebar_position: 43
sidebar_label: Sources of External Dictionaries sidebar_label: Sources of External Dictionaries
--- ---
# Sources of External Dictionaries # Sources of External Dictionaries
An external dictionary can be connected from many different sources. An external dictionary can be connected from many different sources.
@ -126,7 +126,7 @@ Setting fields:
- `command_read_timeout` - timeout for reading data from command stdout in milliseconds. Default value 10000. Optional parameter. - `command_read_timeout` - timeout for reading data from command stdout in milliseconds. Default value 10000. Optional parameter.
- `command_write_timeout` - timeout for writing data to command stdin in milliseconds. Default value 10000. Optional parameter. - `command_write_timeout` - timeout for writing data to command stdin in milliseconds. Default value 10000. Optional parameter.
- `implicit_key` — The executable source file can return only values, and the correspondence to the requested keys is determined implicitly — by the order of rows in the result. Default value is false. - `implicit_key` — The executable source file can return only values, and the correspondence to the requested keys is determined implicitly — by the order of rows in the result. Default value is false.
- `execute_direct` - If `execute_direct` = `1`, then `command` will be searched inside user_scripts folder. Additional script arguments can be specified using whitespace separator. Example: `script_name arg1 arg2`. If `execute_direct` = `0`, `command` is passed as argument for `bin/sh -c`. Default value is `0`. Optional parameter. - `execute_direct` - If `execute_direct` = `1`, then `command` will be searched inside user_scripts folder specified by [user_scripts_path](../../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-user_scripts_path). Additional script arguments can be specified using whitespace separator. Example: `script_name arg1 arg2`. If `execute_direct` = `0`, `command` is passed as argument for `bin/sh -c`. Default value is `0`. Optional parameter.
- `send_chunk_header` - controls whether to send row count before sending a chunk of data to process. Optional. Default value is `false`. - `send_chunk_header` - controls whether to send row count before sending a chunk of data to process. Optional. Default value is `false`.
That dictionary source can be configured only via XML configuration. Creating dictionaries with executable source via DDL is disabled, otherwise, the DB user would be able to execute arbitrary binary on ClickHouse node. That dictionary source can be configured only via XML configuration. Creating dictionaries with executable source via DDL is disabled, otherwise, the DB user would be able to execute arbitrary binary on ClickHouse node.
@ -161,7 +161,7 @@ Setting fields:
- `command_read_timeout` - timeout for reading data from command stdout in milliseconds. Default value 10000. Optional parameter. - `command_read_timeout` - timeout for reading data from command stdout in milliseconds. Default value 10000. Optional parameter.
- `command_write_timeout` - timeout for writing data to command stdin in milliseconds. Default value 10000. Optional parameter. - `command_write_timeout` - timeout for writing data to command stdin in milliseconds. Default value 10000. Optional parameter.
- `implicit_key` — The executable source file can return only values, and the correspondence to the requested keys is determined implicitly — by the order of rows in the result. Default value is false. Optional parameter. - `implicit_key` — The executable source file can return only values, and the correspondence to the requested keys is determined implicitly — by the order of rows in the result. Default value is false. Optional parameter.
- `execute_direct` - If `execute_direct` = `1`, then `command` will be searched inside user_scripts folder. Additional script arguments can be specified using whitespace separator. Example: `script_name arg1 arg2`. If `execute_direct` = `0`, `command` is passed as argument for `bin/sh -c`. Default value is `1`. Optional parameter. - `execute_direct` - If `execute_direct` = `1`, then `command` will be searched inside user_scripts folder specified by [user_scripts_path](../../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-user_scripts_path). Additional script arguments can be specified using whitespace separator. Example: `script_name arg1 arg2`. If `execute_direct` = `0`, `command` is passed as argument for `bin/sh -c`. Default value is `1`. Optional parameter.
- `send_chunk_header` - controls whether to send row count before sending a chunk of data to process. Optional. Default value is `false`. - `send_chunk_header` - controls whether to send row count before sending a chunk of data to process. Optional. Default value is `false`.
That dictionary source can be configured only via XML configuration. Creating dictionaries with executable source via DDL is disabled, otherwise, the DB user would be able to execute arbitrary binary on ClickHouse node. That dictionary source can be configured only via XML configuration. Creating dictionaries with executable source via DDL is disabled, otherwise, the DB user would be able to execute arbitrary binary on ClickHouse node.
@ -220,7 +220,7 @@ When creating a dictionary using the DDL command (`CREATE DICTIONARY ...`) remot
### Known Vulnerability of the ODBC Dictionary Functionality {#known-vulnerability-of-the-odbc-dictionary-functionality} ### Known Vulnerability of the ODBC Dictionary Functionality {#known-vulnerability-of-the-odbc-dictionary-functionality}
:::note :::note
When connecting to the database through the ODBC driver connection parameter `Servername` can be substituted. In this case values of `USERNAME` and `PASSWORD` from `odbc.ini` are sent to the remote server and can be compromised. When connecting to the database through the ODBC driver connection parameter `Servername` can be substituted. In this case values of `USERNAME` and `PASSWORD` from `odbc.ini` are sent to the remote server and can be compromised.
::: :::
@ -472,7 +472,7 @@ Setting fields:
- `invalidate_query` – Query for checking the dictionary status. Optional parameter. Read more in the section [Updating dictionaries](../../../sql-reference/dictionaries/external-dictionaries/external-dicts-dict-lifetime.md). - `invalidate_query` – Query for checking the dictionary status. Optional parameter. Read more in the section [Updating dictionaries](../../../sql-reference/dictionaries/external-dictionaries/external-dicts-dict-lifetime.md).
- `query` – The custom query. Optional parameter. - `query` – The custom query. Optional parameter.
:::note :::note
The `table` and `query` fields cannot be used together. And either one of the `table` or `query` fields must be declared. The `table` and `query` fields cannot be used together. And either one of the `table` or `query` fields must be declared.
::: :::
@ -551,7 +551,7 @@ Setting fields:
- `query` – The custom query. Optional parameter. - `query` – The custom query. Optional parameter.
:::note :::note
The `table` or `where` fields cannot be used together with the `query` field. And either one of the `table` or `query` fields must be declared. The `table` or `where` fields cannot be used together with the `query` field. And either one of the `table` or `query` fields must be declared.
::: :::
@ -642,7 +642,7 @@ Setting fields:
- `secure` - Use ssl for connection. - `secure` - Use ssl for connection.
- `query` – The custom query. Optional parameter. - `query` – The custom query. Optional parameter.
:::note :::note
The `table` or `where` fields cannot be used together with the `query` field. And either one of the `table` or `query` fields must be declared. The `table` or `where` fields cannot be used together with the `query` field. And either one of the `table` or `query` fields must be declared.
::: :::
@ -756,7 +756,7 @@ Setting fields:
- `max_threads` – The maximum number of threads to use for loading data from multiple partitions in compose key dictionaries. - `max_threads` – The maximum number of threads to use for loading data from multiple partitions in compose key dictionaries.
- `query` – The custom query. Optional parameter. - `query` – The custom query. Optional parameter.
:::note :::note
The `column_family` or `where` fields cannot be used together with the `query` field. And either one of the `column_family` or `query` fields must be declared. The `column_family` or `where` fields cannot be used together with the `query` field. And either one of the `column_family` or `query` fields must be declared.
::: :::
@ -813,6 +813,6 @@ Setting fields:
- `invalidate_query` – Query for checking the dictionary status. Optional parameter. Read more in the section [Updating dictionaries](../../../sql-reference/dictionaries/external-dictionaries/external-dicts-dict-lifetime.md). - `invalidate_query` – Query for checking the dictionary status. Optional parameter. Read more in the section [Updating dictionaries](../../../sql-reference/dictionaries/external-dictionaries/external-dicts-dict-lifetime.md).
- `query` – The custom query. Optional parameter. - `query` – The custom query. Optional parameter.
:::note :::note
The `table` or `where` fields cannot be used together with the `query` field. And either one of the `table` or `query` fields must be declared. The `table` or `where` fields cannot be used together with the `query` field. And either one of the `table` or `query` fields must be declared.
::: :::

13
docs/en/sql-reference/functions/index.md
View File

@ -3,7 +3,7 @@ sidebar_position: 32
sidebar_label: Functions sidebar_label: Functions
--- ---
# Functions # Functions
There are at least\* two types of functions - regular functions (they are just called “functions”) and aggregate functions. These are completely different concepts. Regular functions work as if they are applied to each row separately (for each row, the result of the function does not depend on the other rows). Aggregate functions accumulate a set of values from various rows (i.e. they depend on the entire set of rows). There are at least\* two types of functions - regular functions (they are just called “functions”) and aggregate functions. These are completely different concepts. Regular functions work as if they are applied to each row separately (for each row, the result of the function does not depend on the other rows). Aggregate functions accumulate a set of values from various rows (i.e. they depend on the entire set of rows).
@ -63,11 +63,9 @@ For some functions the first argument (the lambda function) can be omitted. In t
Custom functions from lambda expressions can be created using the [CREATE FUNCTION](../statements/create/function.md) statement. To delete these functions use the [DROP FUNCTION](../statements/drop.md#drop-function) statement. Custom functions from lambda expressions can be created using the [CREATE FUNCTION](../statements/create/function.md) statement. To delete these functions use the [DROP FUNCTION](../statements/drop.md#drop-function) statement.
## Executable User Defined Functions {#executable-user-defined-functions} ## Executable User Defined Functions {#executable-user-defined-functions}
ClickHouse can call any external executable program or script to process data. Describe such functions in a [configuration file](../../operations/configuration-files.md) and add the path of that file to the main configuration in `user_defined_executable_functions_config` setting. If a wildcard symbol `*` is used in the path, then all files matching the pattern are loaded. Example: ClickHouse can call any external executable program or script to process data.
``` xml
<user_defined_executable_functions_config>*_function.xml</user_defined_executable_functions_config> The configuration of executable user defined functions can be located in one or more xml-files. The path to the configuration is specified in the [user_defined_executable_functions_config](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-user_defined_executable_functions_config) parameter.
```
User defined function configurations are searched relative to the path specified in the `user_files_path` setting.
A function configuration contains the following settings: A function configuration contains the following settings:
@ -84,12 +82,13 @@ A function configuration contains the following settings:
- `command_write_timeout` - timeout for writing data to command stdin in milliseconds. Default value 10000. Optional parameter. - `command_write_timeout` - timeout for writing data to command stdin in milliseconds. Default value 10000. Optional parameter.
- `pool_size` - the size of a command pool. Optional. Default value is `16`. - `pool_size` - the size of a command pool. Optional. Default value is `16`.
- `send_chunk_header` - controls whether to send row count before sending a chunk of data to process. Optional. Default value is `false`. - `send_chunk_header` - controls whether to send row count before sending a chunk of data to process. Optional. Default value is `false`.
- `execute_direct` - If `execute_direct` = `1`, then `command` will be searched inside user_scripts folder. Additional script arguments can be specified using whitespace separator. Example: `script_name arg1 arg2`. If `execute_direct` = `0`, `command` is passed as argument for `bin/sh -c`. Default value is `1`. Optional parameter. - `execute_direct` - If `execute_direct` = `1`, then `command` will be searched inside user_scripts folder specified by [user_scripts_path](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-user_scripts_path). Additional script arguments can be specified using whitespace separator. Example: `script_name arg1 arg2`. If `execute_direct` = `0`, `command` is passed as argument for `bin/sh -c`. Default value is `1`. Optional parameter.
- `lifetime` - the reload interval of a function in seconds. If it is set to `0` then the function is not reloaded. Default value is `0`. Optional parameter. - `lifetime` - the reload interval of a function in seconds. If it is set to `0` then the function is not reloaded. Default value is `0`. Optional parameter.
The command must read arguments from `STDIN` and must output the result to `STDOUT`. The command must process arguments iteratively. That is after processing a chunk of arguments it must wait for the next chunk. The command must read arguments from `STDIN` and must output the result to `STDOUT`. The command must process arguments iteratively. That is after processing a chunk of arguments it must wait for the next chunk.
**Example** **Example**
Creating `test_function` using XML configuration. Creating `test_function` using XML configuration.
File test_function.xml. File test_function.xml.
```xml ```xml

45
docs/ru/operations/server-configuration-parameters/settings.md
View File

@ -249,6 +249,23 @@ ClickHouse проверяет условия для `min_part_size` и `min_part
<dictionaries_config>*_dictionary.xml</dictionaries_config> <dictionaries_config>*_dictionary.xml</dictionaries_config>
``` ```
## user_defined_executable_functions_config {#server_configuration_parameters-user_defined_executable_functions_config}
Путь к файлу конфигурации для исполняемых пользовательских функций.
Путь:
- Указывается абсолютным или относительно конфигурационного файла сервера.
- Может содержать wildcard-ы \* и ?.
Смотрите также “[Исполняемые пользовательские функции](../../sql-reference/functions/index.md#executable-user-defined-functions).”.
**Пример**
``` xml
<user_defined_executable_functions_config>*_dictionary.xml</user_defined_executable_functions_config>
```
## dictionaries_lazy_load {#server_configuration_parameters-dictionaries_lazy_load} ## dictionaries_lazy_load {#server_configuration_parameters-dictionaries_lazy_load}
Отложенная загрузка словарей. Отложенная загрузка словарей.
@ -369,10 +386,10 @@ ClickHouse проверяет условия для `min_part_size` и `min_part
``` ```
## hsts_max_age {#hsts-max-age} ## hsts_max_age {#hsts-max-age}
Срок действия HSTS в секундах. Значение по умолчанию `0` (HSTS выключен). Для включения HSTS задайте положительное число. Срок действия HSTS будет равен введенному числу. Срок действия HSTS в секундах. Значение по умолчанию `0` (HSTS выключен). Для включения HSTS задайте положительное число. Срок действия HSTS будет равен введенному числу.
**Пример** **Пример**
```xml ```xml
<hsts_max_age>600000</hsts_max_age> <hsts_max_age>600000</hsts_max_age>
@ -697,7 +714,7 @@ ClickHouse поддерживает динамическое изменение
:::info "Примечание" :::info "Примечание"
Параметры этих настроек могут быть изменены во время выполнения запросов и вступят в силу немедленно. Запросы, которые уже запущены, выполнятся без изменений. Параметры этих настроек могут быть изменены во время выполнения запросов и вступят в силу немедленно. Запросы, которые уже запущены, выполнятся без изменений.
Возможные значения: Возможные значения:
- Положительное целое число. - Положительное целое число.
@ -717,7 +734,7 @@ ClickHouse поддерживает динамическое изменение
:::info "Примечание" :::info "Примечание"
Параметры этих настроек могут быть изменены во время выполнения запросов и вступят в силу немедленно. Запросы, которые уже запущены, выполнятся без изменений. Параметры этих настроек могут быть изменены во время выполнения запросов и вступят в силу немедленно. Запросы, которые уже запущены, выполнятся без изменений.
Возможные значения: Возможные значения:
- Положительное целое число. - Положительное целое число.
@ -834,7 +851,7 @@ ClickHouse поддерживает динамическое изменение
ClickHouse использует потоки из глобального пула потоков для обработки запросов. Если в пуле нет свободных потоков, то в нем создается еще один. Параметр `max_thread_pool_size` ограничивает максимальное количество потоков в пуле. ClickHouse использует потоки из глобального пула потоков для обработки запросов. Если в пуле нет свободных потоков, то в нем создается еще один. Параметр `max_thread_pool_size` ограничивает максимальное количество потоков в пуле.
Возможные значения: Возможные значения:
- Положительное целое число. - Положительное целое число.
@ -850,7 +867,7 @@ ClickHouse использует потоки из глобального пул
Если в глобальном пуле потоков количество **свободных** потоков больше, чем задано параметром `max_thread_pool_free_size`, то ClickHouse освобождает ресурсы, занятые некоторыми потоками. В таком случае размер пула уменьшается. При необходимости потоки будут созданы заново. Если в глобальном пуле потоков количество **свободных** потоков больше, чем задано параметром `max_thread_pool_free_size`, то ClickHouse освобождает ресурсы, занятые некоторыми потоками. В таком случае размер пула уменьшается. При необходимости потоки будут созданы заново.
Возможные значения: Возможные значения:
- Положительное целое число. - Положительное целое число.
@ -866,7 +883,7 @@ ClickHouse использует потоки из глобального пул
Максимальное количество задач, которые запланированы для выполнения в глобальном пуле потоков. При увеличении этого параметра возрастает использование памяти. Рекомендуется, чтобы значение этого параметра совпадало со значением параметра [max_thread_pool_size](#max-thread-pool-size). Максимальное количество задач, которые запланированы для выполнения в глобальном пуле потоков. При увеличении этого параметра возрастает использование памяти. Рекомендуется, чтобы значение этого параметра совпадало со значением параметра [max_thread_pool_size](#max-thread-pool-size).
Возможные значения: Возможные значения:
- Положительное целое число. - Положительное целое число.
@ -1336,6 +1353,16 @@ TCP порт для защищённого обмена данными с кли
<user_files_path>/var/lib/clickhouse/user_files/</user_files_path> <user_files_path>/var/lib/clickhouse/user_files/</user_files_path>
``` ```
## user_scripts_path {#server_configuration_parameters-user_scripts_path}
Каталог с файлами пользовательских скриптов. Используется для исполняемых пользовательских функций [Executable User Defined Functions](../../sql-reference/functions/index.md#executable-user-defined-functions).
**Пример**
``` xml
<user_scripts_path>/var/lib/clickhouse/user_scripts/</user_scripts_path>
```
## users_config {#users-config} ## users_config {#users-config}
Путь к файлу, который содержит: Путь к файлу, который содержит:

11
docs/ru/sql-reference/functions/index.md
View File

@ -62,11 +62,10 @@ str -> str != Referer
Функции можно создавать из лямбда выражений с помощью [CREATE FUNCTION](../statements/create/function.md). Для удаления таких функций используется выражение [DROP FUNCTION](../statements/drop.md#drop-function). Функции можно создавать из лямбда выражений с помощью [CREATE FUNCTION](../statements/create/function.md). Для удаления таких функций используется выражение [DROP FUNCTION](../statements/drop.md#drop-function).
## Исполняемые пользовательские функции {#executable-user-defined-functions} ## Исполняемые пользовательские функции {#executable-user-defined-functions}
ClickHouse может вызывать внешнюю программу или скрипт для обработки данных. Такие функции описываются в [конфигурационном файле](../../operations/configuration-files.md). Путь к нему должен быть указан в настройке `user_defined_executable_functions_config` в основной конфигурации. В пути можно использовать символ подстановки `*`, тогда будут загружены все файлы, соответствующие шаблону. Пример:
``` xml ClickHouse может вызывать любую внешнюю исполняемую программу или скрипт для обработки данных.
<user_defined_executable_functions_config>*_function.xml</user_defined_executable_functions_config>
``` Конфигурация исполняемых пользовательских функций может находиться в одном или нескольких xml-файлах. Путь к конфигурации указывается в параметре [user_defined_executable_functions_config](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-user_defined_executable_functions_config).
Файлы с описанием функций ищутся относительно каталога, заданного в настройке `user_files_path`.
Конфигурация функции содержит следующие настройки: Конфигурация функции содержит следующие настройки:
@ -83,7 +82,7 @@ ClickHouse может вызывать внешнюю программу или
- `command_write_timeout` - время ожидания записи данных в команду stdin в миллисекундах. Значение по умолчанию 10000. Необязательная настройка. - `command_write_timeout` - время ожидания записи данных в команду stdin в миллисекундах. Значение по умолчанию 10000. Необязательная настройка.
- `pool_size` - размер пула команд. Необязательная настройка. Значение по умолчанию `16`. - `pool_size` - размер пула команд. Необязательная настройка. Значение по умолчанию `16`.
- `send_chunk_header` - управляет отправкой количества строк перед отправкой блока данных для обработки. Необязательная настройка. Значение по умолчанию `false`. - `send_chunk_header` - управляет отправкой количества строк перед отправкой блока данных для обработки. Необязательная настройка. Значение по умолчанию `false`.
- `execute_direct` - Если `execute_direct` = `1`, то будет произведен поиск `command` в папке user_scripts. Дополнительные аргументы скрипта можно указать с помощью разделителя пробелов. Пример: `script_name arg1 arg2`. Если `execute_direct` = `0`, `command` передается как аргумент для `bin/sh -c`. Значение по умолчанию `1`. Необязательный параметр. - `execute_direct` - Если `execute_direct` = `1`, то будет произведен поиск `command` в папке user_scripts, указанной в [user_scripts_path](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-user_scripts_path). Дополнительные аргументы скрипта можно указать с помощью разделителя пробелов. Пример: `script_name arg1 arg2`. Если `execute_direct` = `0`, `command` передается как аргумент для `bin/sh -c`. Значение по умолчанию `1`. Необязательный параметр.
- `lifetime` - интервал перезагрузки функций в секундах. Если задан `0`, то функция не перезагружается. - `lifetime` - интервал перезагрузки функций в секундах. Если задан `0`, то функция не перезагружается.
Команда должна читать аргументы из `STDIN` и выводить результат в `STDOUT`. Обработка должна выполняться в цикле. То есть после обработки группы аргументов команда должна ожидать следующую группу. Команда должна читать аргументы из `STDIN` и выводить результат в `STDOUT`. Обработка должна выполняться в цикле. То есть после обработки группы аргументов команда должна ожидать следующую группу.