Service

Create new service

Creates a new service in the organization, and returns the current service state and a password to access the service. The service is started asynchronously.

post/v1/organizations/{organizationId}/services

Request

  • Base URL: https://api.clickhouse.cloud
  • URL: https://api.clickhouse.cloud/v1/organizations/{organizationId}/services
  • Auth: HTTP basic

Path parameters

organizationIdstring uuid required

ID of the organization that will own the service.

Request body

namestring required

Name of the service. Alphanumerical string with whitespaces up to 50 characters.

provider'aws' | 'gcp' | 'azure' required

Cloud provider

region'ap-northeast-1' | 'ap-northeast-2' | 'ap-south-1' | 'ap-southeast-1' | 'ap-southeast-2' | 'ca-central-1' | 'eu-central-1' | 'eu-west-1' | 'eu-west-2' | 'il-central-1' | 'us-east-1' | 'us-east-2' | 'us-west-2' | 'us-east1' | 'us-central1' | 'europe-west2' | 'europe-west4' | 'asia-southeast1' | 'asia-northeast1' | 'eastus' | 'eastus2' | 'westus3' | 'germanywestcentral' | 'centralus' required

Service region.

tier'development' | 'production'

DEPRECATED for BASIC, SCALE and ENTERPRISE organization tiers. Use minReplicaMemoryGb, maxReplicaMemoryGb, and numReplicas instead. Tier of the service: 'development', 'production'. Production services scale, Development are fixed size. Azure services don't support Development tier

minTotalMemoryGbnumber

DEPRECATED - inaccurate for services with non-default numbers of replicas. Use minReplicaMemoryGb instead. Minimum memory of three workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and greater than or equal to 24. Always absent for horizontal-autoscaling services (replica count is variable).

maxTotalMemoryGbnumber

DEPRECATED - inaccurate for services with non-default numbers of replicas. Use maxReplicaMemoryGb instead. Maximum memory of three workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and lower than or equal to 360 for non paid services or 1068 for paid services. Always absent for horizontal-autoscaling services (replica count is variable).

autoscalingMode'vertical' | 'horizontal'

Autoscaling mode. "vertical" (the default when omitted) runs a fixed replica count while memory scales between minReplicaMemoryGb and maxReplicaMemoryGb; "horizontal" scales the replica count between minReplicas and maxReplicas at a fixed per-replica memory (minReplicaMemoryGb equal to maxReplicaMemoryGb). Horizontal requires the feature to be enabled for the organization.

minReplicaMemoryGbnumber

Minimum total memory of each replica during auto-scaling in Gb. A range in vertical autoscaling; equal to maxReplicaMemoryGb in horizontal (memory is fixed while the replica count scales). Must be a multiple of 4 and greater than or equal to 8.

maxReplicaMemoryGbnumber

Maximum total memory of each replica during auto-scaling in Gb. A range in vertical autoscaling; equal to minReplicaMemoryGb in horizontal (memory is fixed while the replica count scales). Must be a multiple of 4 and lower than or equal to 120* for non paid services or 356* for paid services.* - maximum replica size subject to cloud provider hardware availability in your selected region.

numReplicasinteger

Fixed replica count for vertical autoscaling (autoscalingMode "vertical" or omitted). Mutually exclusive with minReplicas/maxReplicas.

minReplicasinteger

Minimum number of replicas. A minReplicas/maxReplicas band scales the replica count in horizontal autoscaling (autoscalingMode "horizontal"). Must be provided together with maxReplicas. Mutually exclusive with numReplicas. Requires horizontal autoscaling to be enabled for the organization, unless autoscalingMode is omitted or "vertical" and minReplicas equals maxReplicas (an equal band is then an accepted vertical fixed count and needs no horizontal entitlement).

maxReplicasinteger

Maximum number of replicas. A minReplicas/maxReplicas band scales the replica count in horizontal autoscaling (autoscalingMode "horizontal"). Must be provided together with minReplicas. Mutually exclusive with numReplicas. Requires horizontal autoscaling to be enabled for the organization, unless autoscalingMode is omitted or "vertical" and minReplicas equals maxReplicas (an equal band is then an accepted vertical fixed count and needs no horizontal entitlement).

idleScalingboolean

When set to true the service is allowed to scale down to zero when idle. True by default.

idleTimeoutMinutesnumber

Set minimum idling timeout (in minutes). Must be >= 5 minutes.

isReadonlyboolean

True if this service is read-only. It can only be read-only if a dataWarehouseId is provided.

dataWarehouseIdstring

Data warehouse containing this service

backupIdstring uuid

Optional backup ID used as an initial state for the new service. When used the region and the tier of the new instance must be the same as the values of the original instance. If the backup is stored in your organization's own bucket, backupEncryptionConfig is required; it must be omitted otherwise.

backupEncryptionConfigBackupEncryptionConfig

The encryption_config.json stored alongside this backup in your bucket, passed through unchanged. Supply the file contents verbatim rather than constructing this object — its shape is versioned and depends on your cloud provider. See Export backups to your own cloud account for what it contains.

Accepted only for organizations enrolled in the private preview, and only when the backup is of a service that has transparent data encryption enabled. Such a restore always produces a service with transparent data encryption enabled, inherited from the source service.

encryptionKeystring

Optional customer provided disk encryption key

encryptionAssumedRoleIdentifierstring

Optional role to use for disk encryption

privateEndpointIdsstring[]

DEPRECATED. To associate the service with private endpoints, first create the service, then use the Update Service Basic Details endpoint with the privateEndpointIds field to modify private endpoints.

privatePreviewTermsCheckedboolean

Accept the private preview terms and conditions. It is only needed when creating the first service in the organization in case of a private preview

releaseChannel'slow' | 'default' | 'fast'

Select fast if you want to get new ClickHouse releases as soon as they are available. You'll get new features faster, but with a higher risk of bugs. Select slow if you would like to defer releases to give yourself more time to test. This feature is only available for production services. default is the regular release channel.

byocIdstring

This is the ID returned after setting up a region for Bring Your Own Cloud (BYOC). When the byocId parameter is specified, the minReplicaMemoryGb and the maxReplicaGb parameters are required too, with values included among the following sizes: 48, 116, 172, 232.

hasTransparentDataEncryptionboolean

True if the service should have the Transparent Data Encryption (TDE) enabled. TDE is only available for ENTERPRISE organizations tiers and can only be enabled at service creation.

profilestring

Custom instance profile. Only available for ENTERPRISE and BYOC organization tiers. Standard values: 'v1-default', 'v1-highmem-xs', 'v1-highmem-s', 'v1-highmem-m', 'v1-highmem-l', 'v1-highmem-xl'. BYOC services may instead use a dynamic BYOC profile configured for their infrastructure (e.g. 'v1-standard-byoc-4'); it requires byocId, and minReplicaMemoryGb and maxReplicaMemoryGb must both equal the profile's memory size. Use the serviceProfiles endpoint to list the profiles available to the organization.

complianceType'hipaa' | 'pci'

Type of regulatory compliance for service.

enableCoreDumpsboolean

Enables the underlying infra for collecting core dumps. Default is enabled.

Example request

{
  "minTotalMemoryGb": 48,
  "maxTotalMemoryGb": 360,
  "autoscalingMode": "vertical",
  "minReplicaMemoryGb": 16,
  "maxReplicaMemoryGb": 120,
  "numReplicas": 3,
  "minReplicas": 1,
  "maxReplicas": 5,
  "backupEncryptionConfig": {
    "schema_version": 1,
    "restore_key_pairs": [
      {
        "customer_managed_encryption_key": {
          "aws_kms_key_arn": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        },
        "encrypted_dek": "<base64 wrapped data encryption key>"
      }
    ]
  },
  "endpoints": [
    {
      "protocol": "mysql"
    }
  ],
  "tags": [
    {
      "key": "Environment",
      "value": "staging"
    }
  ]
}

Response

Successful response

statusnumber

HTTP status code.

requestIdstring uuid

Unique id assigned to every request. UUIDv4

Example response

{
  "status": 200,
  "result": {
    "service": {
      "endpoints": [
        {
          "protocol": "mysql"
        }
      ],
      "minTotalMemoryGb": 48,
      "maxTotalMemoryGb": 360,
      "minReplicaMemoryGb": 16,
      "maxReplicaMemoryGb": 120,
      "numReplicas": 3,
      "minReplicas": 1,
      "maxReplicas": 5,
      "autoscalingMode": "vertical",
      "replicaMemoryGb": 32,
      "tags": [
        {
          "key": "Environment",
          "value": "staging"
        }
      ]
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.