Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Create UDF version

Beta
View as MarkdownEdit this pageReport an issueSet up docs MCP
POST/v1/organizations/{organizationId}/udfs/{functionName}/versions

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.

Authorizations

Path parameters

  • organizationIdstringrequired

    ID of the requested organization.

    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)$
  • functionNamestringrequired

    Name of the UDF.

    pattern: ^[A-Za-z][A-Za-z0-9_]*$

Request bodyJSON

One of the following:

  • object
  • object

Response

JSON

201

UDF version created and building.

JSON
  • statusintegerrequired

    HTTP status code.

    Example: 201
  • requestIdstringrequired

    Unique id assigned to every request. UUIDv4

    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)$
  • resultobjectrequired
    21 properties
    • functionNamestringrequired

      Name of the UDF. Unique within the organization.

    • versionintegerrequired

      Version number of the UDF.

      Example: 1
    • statusbuildingorerrororreadyrequired

      Build state of this UDF version.

    • runtimepython3.11ornativerequired

      Runtime used to execute the UDF command.

    • typeexecutableorexecutable_poolrequired

      Executable UDF type.

    • argumentsarray ofobjectrequired

      Arguments passed to the UDF command.

      2 properties
      • namestringrequired

        Name of the argument. Required for Native and JSONEachRow formats.

        pattern: ^[A-Za-z][A-Za-z0-9_]*$
      • typestringrequired

        ClickHouse data type of the argument.

    • returnTypestringrequired

      ClickHouse data type of the returned value.

    • returnNamestringornullrequired

      Name of the returned value, or null when unnamed.

      2 variants

      One of the following:

      • string
      • null
    • poolSizeintegerornullrequired

      Command pool size for executable_pool UDFs.

      2 variants

      One of the following:

      • integer
      • null
    • commandReadTimeoutintegerrequired

      Command stdout read timeout in milliseconds.

    • commandWriteTimeoutintegerrequired

      Command stdin write timeout in milliseconds.

    • maxCommandExecutionTimeintegerornullrequired

      Maximum command execution time in seconds for executable_pool UDFs.

      2 variants

      One of the following:

      • integer
      • null
    • memoryLimitMibintegerornullrequired

      Maximum memory, in MiB, available to each UDF sandbox process. Null uses the sandbox default.

      Default: null
      2 variants

      One of the following:

      • integer
      • null
    • sendChunkHeaderbooleanrequired

      Whether ClickHouse sends a row-count chunk header.

    • deterministicbooleanrequired

      Whether ClickHouse may reuse cached query results for this UDF.

    • formatstringrequired

      Input and output format used by the UDF command.

    • sandboxTypebasicornetenablerequired

      Sandbox isolation level.

    • sandboxVersionv1orv2orv3required

      Sandbox runtime version.

    • errorstringornullrequired

      Build error, or null when no build error is present.

      2 variants

      One of the following:

      • string
      • null
    • createdAtstringrequired

      Creation timestamp.

      format: date-time
    • updatedAtstringrequired

      Last-update timestamp.

      format: date-time
Navigation