functions

Creates, updates, deletes, gets or lists a functions resource.

Overview

Name	functions
Type	Resource
Id	clickhouse.udfs.functions

Fields

The following fields are returned by SELECT queries:

get

Successful response.

Name	Datatype	Description
function_name	string	Name of the UDF. Unique within the organization. (wire: functionName)
return_name	string	Name of the returned value, or null when unnamed. (wire: returnName)
arguments	array	Arguments passed to the UDF command.
command_read_timeout	integer	Command stdout read timeout in milliseconds. (wire: commandReadTimeout)
command_write_timeout	integer	Command stdin write timeout in milliseconds. (wire: commandWriteTimeout)
created_at	string (date-time)	Creation timestamp. (wire: createdAt)
error	string	Build error, or null when no build error is present.
format	string	Input and output format used by the UDF command.
max_command_execution_time	integer	Maximum command execution time in seconds for executable_pool UDFs. (wire: maxCommandExecutionTime)
memory_limit_mib	integer	Maximum memory, in MiB, available to each UDF sandbox process. Null uses the sandbox default. (wire: memoryLimitMib)
pool_size	integer	Command pool size for executable_pool UDFs. (wire: poolSize)
return_type	string	ClickHouse data type of the returned value. (wire: returnType)
runtime	string	Runtime used to execute the UDF command. (python3.11, native)
sandbox_type	string	Sandbox isolation level. (basic, netenable) (wire: sandboxType)
sandbox_version	string	Sandbox runtime version. (v1, v2, v3) (wire: sandboxVersion)
send_chunk_header	boolean	Whether ClickHouse sends a row-count chunk header. (wire: sendChunkHeader)
status	string	Build state of this UDF version. (building, error, ready)
type	string	Executable UDF type. (executable, executable_pool)
updated_at	string (date-time)	Last-update timestamp. (wire: updatedAt)
version	integer	Version number of the UDF.

list

Successful response.

Name	Datatype	Description
function_name	string	Name of the UDF. Unique within the organization. (wire: functionName)
return_name	string	Name of the returned value, or null when unnamed. (wire: returnName)
arguments	array	Arguments passed to the UDF command.
command_read_timeout	integer	Command stdout read timeout in milliseconds. (wire: commandReadTimeout)
command_write_timeout	integer	Command stdin write timeout in milliseconds. (wire: commandWriteTimeout)
created_at	string (date-time)	Creation timestamp. (wire: createdAt)
error	string	Build error, or null when no build error is present.
format	string	Input and output format used by the UDF command.
max_command_execution_time	integer	Maximum command execution time in seconds for executable_pool UDFs. (wire: maxCommandExecutionTime)
memory_limit_mib	integer	Maximum memory, in MiB, available to each UDF sandbox process. Null uses the sandbox default. (wire: memoryLimitMib)
pool_size	integer	Command pool size for executable_pool UDFs. (wire: poolSize)
return_type	string	ClickHouse data type of the returned value. (wire: returnType)
runtime	string	Runtime used to execute the UDF command. (python3.11, native)
sandbox_type	string	Sandbox isolation level. (basic, netenable) (wire: sandboxType)
sandbox_version	string	Sandbox runtime version. (v1, v2, v3) (wire: sandboxVersion)
send_chunk_header	boolean	Whether ClickHouse sends a row-count chunk header. (wire: sendChunkHeader)
status	string	Build state of this UDF version. (building, error, ready)
type	string	Executable UDF type. (executable, executable_pool)
updated_at	string (date-time)	Last-update timestamp. (wire: updatedAt)
version	integer	Version number of the UDF.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	function_name, organization_id		Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Returns the latest version of a UDF.
list	select	organization_id	cursor, limit	Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Returns the latest version of each UDF in the organization.
create	insert	organization_id, upload_id, runtime, arguments, return_type, type, function_name		Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Creates a new UDF. See [User-defined functions in Cloud](https:​//clickhouse.com/docs/products/cloud/features/sql-console-features/user-defined-functions).
delete	delete	function_name, organization_id		Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Deletes every version of a UDF and detaches it from all services. Removal from services completes asynchronously.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
function_name	string	Name of the UDF. (wire: functionName)
organization_id	string	ClickHouse Cloud organization ID. Resolved from the CLICKHOUSE_ORG_ID environment variable when it is set (x-stackQL-envVar); otherwise it must be supplied on every query as WHERE organization_id = <uuid>. A WHERE value always takes precedence over the environment. (x-stackQL-envVar: CLICKHOUSE_ORG_ID)
cursor	string	Cursor returned in pagination.nextCursor from the previous page.
limit	integer	Maximum number of records to return per page. Defaults to 100. Maximum is 100.

SELECT examples

get

Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Returns the latest version of a UDF.

SELECT
function_name,
return_name,
arguments,
command_read_timeout,
command_write_timeout,
created_at,
error,
format,
max_command_execution_time,
memory_limit_mib,
pool_size,
return_type,
runtime,
sandbox_type,
sandbox_version,
send_chunk_header,
status,
type,
updated_at,
version
FROM clickhouse.udfs.functions
WHERE function_name = '{{ function_name }}' -- required
AND organization_id = '{{ organization_id }}' -- required unless CLICKHOUSE_ORG_ID is set
;

list

Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Returns the latest version of each UDF in the organization.

SELECT
function_name,
return_name,
arguments,
command_read_timeout,
command_write_timeout,
created_at,
error,
format,
max_command_execution_time,
memory_limit_mib,
pool_size,
return_type,
runtime,
sandbox_type,
sandbox_version,
send_chunk_header,
status,
type,
updated_at,
version
FROM clickhouse.udfs.functions
WHERE organization_id = '{{ organization_id }}' -- required unless CLICKHOUSE_ORG_ID is set
AND cursor = '{{ cursor }}'
AND limit = '{{ limit }}'
;

INSERT examples

create

Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Creates a new UDF. See [User-defined functions in Cloud](https:​//clickhouse.com/docs/products/cloud/features/sql-console-features/user-defined-functions).

INSERT INTO clickhouse.udfs.functions (
upload_id,
runtime,
arguments,
return_type,
return_name,
command_read_timeout,
command_write_timeout,
memory_limit_mib,
send_chunk_header,
format,
sandbox_type,
sandbox_version,
type,
pool_size,
max_command_execution_time,
function_name,
organization_id
)
SELECT 
'{{ upload_id }}' /* required */,
'{{ runtime }}' /* required */,
'{{ arguments }}' /* required */,
'{{ return_type }}' /* required */,
'{{ return_name }}',
{{ command_read_timeout }},
{{ command_write_timeout }},
'{{ memory_limit_mib }}',
{{ send_chunk_header }},
'{{ format }}',
'{{ sandbox_type }}',
'{{ sandbox_version }}',
'{{ type }}' /* required */,
'{{ pool_size }}',
'{{ max_command_execution_time }}',
'{{ function_name }}' /* required */,
'{{ organization_id }}'
RETURNING
request_id,
result,
status
;

Manifest

# Description fields are for documentation purposes
- name: functions
props:
  - name: organization_id
    value: "{{ organization_id }}"
    description: Required parameter for the functions resource.
  - name: upload_id
    value: "{{ upload_id }}"
    description: |
      Identifier of the uploaded source archive.
  - name: runtime
    value: "{{ runtime }}"
    valid_values: ['python3.11', 'native']
  - name: arguments
    value:
      - name: "{{ name }}"
        type: "{{ type }}"
  - name: return_type
    value: "{{ return_type }}"
  - name: return_name
    value: "{{ return_name }}"
    default: null
  - name: command_read_timeout
    value: {{ command_read_timeout }}
    default: 10000
  - name: command_write_timeout
    value: {{ command_write_timeout }}
    default: 10000
  - name: memory_limit_mib
    value: "{{ memory_limit_mib }}"
    default: null
  - name: send_chunk_header
    value: {{ send_chunk_header }}
    default: false
  - name: format
    value: "{{ format }}"
    default: TabSeparated
  - name: sandbox_type
    value: "{{ sandbox_type }}"
    valid_values: ['basic', 'netenable']
    default: basic
  - name: sandbox_version
    value: "{{ sandbox_version }}"
    valid_values: ['v1', 'v2', 'v3']
    default: v2
  - name: type
    value: "{{ type }}"
  - name: pool_size
    value: "{{ pool_size }}"
    default: null
  - name: max_command_execution_time
    value: "{{ max_command_execution_time }}"
    default: 10
  - name: function_name
    value: "{{ function_name }}"

DELETE examples

delete

Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Deletes every version of a UDF and detaches it from all services. Removal from services completes asynchronously.

DELETE FROM clickhouse.udfs.functions
WHERE function_name = '{{ function_name }}' --required
AND organization_id = '{{ organization_id }}' --required unless CLICKHOUSE_ORG_ID is set
;