versions

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

Overview

Name	versions
Type	Resource
Id	clickhouse.udfs.versions

Fields

The following fields are returned by SELECT queries:

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
list	select	function_name, organization_id	cursor, limit	Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Returns all versions of a UDF.
create	insert	function_name, organization_id, upload_id, runtime, arguments, return_type, type		Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Consumes a source archive, assigns a version, and starts the UDF build. Optional configuration fields omitted from the request use the defaults documented in the request schema; values are not inherited from the previous version. Retry by requesting a new upload URL and re-uploading.
delete	delete	function_name, version, organization_id		Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Deletes a UDF version. The UDF must not be attached to any services.

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)
version	integer	Version number of the UDF.
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

list

Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Returns all versions 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.versions
WHERE function_name = '{{ function_name }}' -- required
AND 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 /> Consumes a source archive, assigns a version, and starts the UDF build. Optional configuration fields omitted from the request use the defaults documented in the request schema; values are not inherited from the previous version. Retry by requesting a new upload URL and re-uploading.

INSERT INTO clickhouse.udfs.versions (
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 }}',
'{{ organization_id }}'
RETURNING
request_id,
result,
status
;

Manifest

# Description fields are for documentation purposes
- name: versions
props:
  - name: function_name
    value: "{{ function_name }}"
    description: Required parameter for the versions resource.
  - name: organization_id
    value: "{{ organization_id }}"
    description: Required parameter for the versions 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

DELETE examples

delete

Disclaimer: This beta endpoint is evolving; the API contract may change. <br /><br /> Deletes a UDF version. The UDF must not be attached to any services.

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