> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create UDF version
> **Disclaimer:** This beta endpoint is evolving; the API contract may change.
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.
Beta
**Disclaimer:** This beta endpoint is evolving; the API contract may change.
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.
## OpenAPI
````yaml _specs/cloud-openapi.json POST /v1/organizations/{organizationId}/udfs/{functionName}/versions
openapi: 3.1.2
info:
title: OpenAPI spec for ClickHouse Cloud
version: '1.0'
contact:
name: ClickHouse Support
url: >-
https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1037333
email: support@clickhouse.com
servers:
- url: https://api.clickhouse.cloud
security:
- basicAuth: []
tags:
- name: Organization
- name: User management
- name: Billing
- name: Role Management
- name: Service
- name: Backup
- name: OpenAPI
- name: Prometheus
- name: ClickPipes
- name: ClickStack
- name: Postgres
- name: UDF
paths:
/v1/organizations/{organizationId}/udfs/{functionName}/versions:
post:
tags:
- UDF
summary: Create UDF version
description: >-
**Disclaimer:** This beta endpoint is evolving; the API contract may
change.
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.
operationId: udfVersionCreate
parameters:
- in: path
name: organizationId
schema:
description: ID of the requested organization.
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required: true
description: ID of the requested organization.
- in: path
name: functionName
schema:
description: Name of the UDF.
type: string
pattern: ^[A-Za-z][A-Za-z0-9_]*$
required: true
description: Name of the UDF.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UdfVersionCreateRequest'
responses:
'201':
description: UDF version created and building.
content:
application/json:
schema:
type: object
properties:
status:
description: HTTP status code.
example: 201
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
result:
$ref: '#/components/schemas/Udf'
required:
- status
- requestId
- result
additionalProperties: false
'400':
description: >-
The request cannot be processed due to a client error. Please verify
your request parameters and try again.
content:
application/json:
schema:
type: object
properties:
error:
description: Error message.
type: string
issues:
description: Validation issues that caused the request to be rejected.
type: array
items:
type: object
properties:
path:
description: Path to the invalid field.
type: array
items:
anyOf:
- type: string
- type: number
code:
description: Validation issue code.
type: string
message:
description: Human-readable description of the issue.
type: string
required:
- path
- code
- message
additionalProperties: false
status:
description: HTTP status code.
example: 400
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: false
'403':
description: Requested UDF features are not enabled.
content:
application/json:
schema:
type: object
properties:
error:
description: Human-readable error message.
type: string
status:
description: HTTP status code.
example: 403
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: false
'404':
description: UDF not found.
content:
application/json:
schema:
type: object
properties:
error:
description: Human-readable error message.
type: string
status:
description: HTTP status code.
example: 404
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: false
'409':
description: A concurrent request conflicted with this request.
content:
application/json:
schema:
type: object
properties:
error:
description: Human-readable error message.
type: string
status:
description: HTTP status code.
example: 409
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: false
'410':
description: The source archive is unavailable.
content:
application/json:
schema:
type: object
properties:
error:
description: Human-readable error message.
type: string
status:
description: HTTP status code.
example: 410
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: false
'500':
description: >-
An internal server error has occurred. If this issue persists,
please contact ClickHouse Cloud support for assistance.
content:
application/json:
schema:
type: object
properties:
error:
description: Error message.
type: string
status:
type: integer
description: HTTP status code.
example: 500
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: {}
components:
schemas:
UdfVersionCreateRequest:
oneOf:
- type: object
properties:
uploadId:
description: Identifier of the uploaded source archive.
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
runtime:
type: string
enum:
- python3.11
- native
arguments:
type: array
items:
type: object
properties:
name:
description: >-
Name of the argument. Required for Native and JSONEachRow
formats.
type: string
pattern: ^[A-Za-z][A-Za-z0-9_]*$
type:
description: ClickHouse data type of the argument.
type: string
required:
- name
- type
returnType:
type: string
returnName:
default: null
anyOf:
- type: string
pattern: ^[A-Za-z][A-Za-z0-9_]*$
- type: 'null'
commandReadTimeout:
default: 10000
type: integer
exclusiveMinimum: 0
commandWriteTimeout:
default: 10000
type: integer
exclusiveMinimum: 0
sendChunkHeader:
default: false
type: boolean
format:
default: TabSeparated
type: string
sandboxType:
default: basic
type: string
enum:
- basic
- netenable
sandboxVersion:
default: v2
type: string
enum:
- v1
- v2
- v3
type:
type: string
const: executable
poolSize:
default: null
type: 'null'
maxCommandExecutionTime:
default: 10
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
required:
- uploadId
- runtime
- arguments
- returnType
- type
- type: object
properties:
uploadId:
description: Identifier of the uploaded source archive.
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
runtime:
type: string
enum:
- python3.11
- native
arguments:
type: array
items:
type: object
properties:
name:
description: >-
Name of the argument. Required for Native and JSONEachRow
formats.
type: string
pattern: ^[A-Za-z][A-Za-z0-9_]*$
type:
description: ClickHouse data type of the argument.
type: string
required:
- name
- type
returnType:
type: string
returnName:
default: null
anyOf:
- type: string
pattern: ^[A-Za-z][A-Za-z0-9_]*$
- type: 'null'
commandReadTimeout:
default: 10000
type: integer
exclusiveMinimum: 0
commandWriteTimeout:
default: 10000
type: integer
exclusiveMinimum: 0
sendChunkHeader:
default: false
type: boolean
format:
default: TabSeparated
type: string
sandboxType:
default: basic
type: string
enum:
- basic
- netenable
sandboxVersion:
default: v2
type: string
enum:
- v1
- v2
- v3
type:
type: string
const: executable_pool
poolSize:
default: 3
type: integer
exclusiveMinimum: 0
maxCommandExecutionTime:
default: 10
type: integer
exclusiveMinimum: 0
required:
- uploadId
- runtime
- arguments
- returnType
- type
type: object
Udf:
type: object
properties:
functionName:
description: Name of the UDF. Unique within the organization.
type: string
version:
description: Version number of the UDF.
example: 1
type: integer
exclusiveMinimum: 0
status:
description: Build state of this UDF version.
type: string
enum:
- building
- error
- ready
runtime:
description: Runtime used to execute the UDF command.
type: string
enum:
- python3.11
- native
type:
description: Executable UDF type.
type: string
enum:
- executable
- executable_pool
arguments:
description: Arguments passed to the UDF command.
type: array
items:
type: object
properties:
name:
description: >-
Name of the argument. Required for Native and JSONEachRow
formats.
type: string
pattern: ^[A-Za-z][A-Za-z0-9_]*$
type:
description: ClickHouse data type of the argument.
type: string
required:
- name
- type
additionalProperties: false
returnType:
description: ClickHouse data type of the returned value.
type: string
returnName:
description: Name of the returned value, or null when unnamed.
anyOf:
- type: string
- type: 'null'
poolSize:
description: Command pool size for executable_pool UDFs.
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
commandReadTimeout:
description: Command stdout read timeout in milliseconds.
type: integer
exclusiveMinimum: 0
commandWriteTimeout:
description: Command stdin write timeout in milliseconds.
type: integer
exclusiveMinimum: 0
maxCommandExecutionTime:
description: Maximum command execution time in seconds for executable_pool UDFs.
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
sendChunkHeader:
description: Whether ClickHouse sends a row-count chunk header.
type: boolean
format:
description: Input and output format used by the UDF command.
type: string
sandboxType:
description: Sandbox isolation level.
type: string
enum:
- basic
- netenable
sandboxVersion:
description: Sandbox runtime version.
type: string
enum:
- v1
- v2
- v3
error:
description: Build error, or null when no build error is present.
anyOf:
- type: string
- type: 'null'
createdAt:
description: Creation timestamp.
type: string
format: date-time
updatedAt:
description: Last-update timestamp.
type: string
format: date-time
required:
- functionName
- version
- status
- runtime
- type
- arguments
- returnType
- returnName
- poolSize
- commandReadTimeout
- commandWriteTimeout
- maxCommandExecutionTime
- sendChunkHeader
- format
- sandboxType
- sandboxVersion
- error
- createdAt
- updatedAt
additionalProperties: false
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Use key ID and key secret obtained in ClickHouse Cloud console:
https://clickhouse.com/docs/cloud/manage/openapi
````