ContextQMD
Back to Clickhouse

system.user_defined_functions

docs/en/operations/system-tables/user_defined_functions.md

26.4.1.1-new3.7 KB
Original Source

system.user_defined_functions

Contains loading status, error information, and configuration metadata for User-Defined Functions (UDFs).

Columns:

Loading Status

  • name (String) — UDF name.
  • load_status (Enum8) — Loading status: Success (UDF loaded and ready), Failed (UDF failed to load).
  • loading_error_message (String) — Detailed error message when loading failed. Empty if loaded successfully.
  • last_successful_update_time (Nullable(DateTime)) — Timestamp of the last successful load. NULL if never succeeded.
  • loading_duration_ms (UInt64) — Time spent loading the UDF, in milliseconds.

UDF Configuration

  • type (Enum8) — UDF type: executable (single process per block) or executable_pool (persistent process pool).
  • command (String) — Script or command to execute, including arguments.
  • format (String) — Data format for I/O (e.g., TabSeparated, JSONEachRow).
  • return_type (String) — Function return type (e.g., String, UInt64).
  • return_name (String) — Optional return value identifier. Empty if not configured.
  • argument_types (Array(String)) — Array of argument types.
  • argument_names (Array(String)) — Array of argument names. Empty strings for unnamed arguments.

Execution Parameters

  • max_command_execution_time (UInt64) — Maximum seconds to process a data block. Only for executable_pool type.
  • command_termination_timeout (UInt64) — Seconds before sending SIGTERM to command process.
  • command_read_timeout (UInt64) — Milliseconds for reading from command stdout.
  • command_write_timeout (UInt64) — Milliseconds for writing to command stdin.
  • pool_size (UInt64) — Number of process instances in pool. Only for executable_pool type.
  • send_chunk_header (UInt8) — Whether to send row count before each data chunk (1 = true, 0 = false).
  • execute_direct (UInt8) — Whether to execute command directly (1) or via /bin/bash (0).
  • lifetime (UInt64) — Reload interval in seconds. 0 means reload is disabled.
  • deterministic (UInt8) — Whether function returns the same result for same arguments (1 = true, 0 = false).

Example

View all UDFs and their loading status:

sql
SELECT
    name,
    load_status,
    type,
    command,
    return_type,
    argument_types
FROM system.user_defined_functions
FORMAT Vertical;
response
Row 1:
──────
name:           my_sum_udf
load_status:    Success
type:           executable
command:        /var/lib/clickhouse/user_scripts/sum.py
return_type:    UInt64
argument_types: ['UInt64','UInt64']

Find failed UDFs:

sql
SELECT
    name,
    loading_error_message
FROM system.user_defined_functions
WHERE load_status = 'Failed';

See Also