Query ClickHouse clusters using the Python SDK - ApsaraDB for ClickHouse

Use the Alibaba Cloud SDK for Python to call the DescribeDBClusters operation and list your ApsaraDB for ClickHouse clusters programmatically.

Prerequisites

Before you begin, ensure that you have:

Python 3 installed. Run python --version to check your version.
An Alibaba Cloud account with at least one ApsaraDB for ClickHouse cluster

Set up a RAM user

Skip this section if you already have a RAM user with the required permissions.

Go to the Users page and click Create User.
Set Logon Name to clickhouse-openapi-operator and Access Mode to Using permanent AccessKey to access.
Click OK. Save the AccessKey ID and AccessKey secret that are displayed — you won't be able to retrieve the secret again.
On the Users page, click Add Permissions in the Actions column for the user you created.
In the Policy section, search for AliyunClickHouse and select AliyunClickHouseReadOnlyAccess.
AliyunClickHouseReadOnlyAccess grants read-only access to ApsaraDB for ClickHouse. To also allow modifications, select AliyunClickHouseFullAccess instead. To define a custom scope, see Create custom policies.
Click Grant permissions.

Call the DescribeDBClusters operation

Configure environment variables

Store your credentials as environment variables to avoid hardcoding them in source code.

Linux or macOS — replace the placeholder values and run:

export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>

Windows — add ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET as system environment variables set to your AccessKey ID and AccessKey secret, then restart your machine.

Install the SDK

pip install alibabacloud_clickhouse20191111

Download the sample code

The fastest way to get runnable code is from OpenAPI Explorer:

Open the DescribeDBClusters page in OpenAPI Explorer.
On the Parameters tab, set RegionId to the region where your cluster is located (for example, cn-hangzhou).
On the SDK Sample Code tab, select Python and click Download Project.
Extract the downloaded package and navigate to the alibabacloud_sample directory.

Run the code

python sample.py

A successful response looks like:

[
    LOG
]{
    "headers": {
        "date": "Thu, 27 Jul 2023 10:03:39 GMT",
        "content-type": "application/json;charset=utf-8",
        "content-length": "1665",
        "connection": "keep-alive",
        "keep-alive": "timeout=25",
        "vary": "Accept-Encoding",
        "access-control-allow-origin": "*",
        "access-control-expose-headers": "*",
        "x-acs-request-id": "F2F4B6CB-3C03-51A0-9300-F78BC94E****",
        "x-acs-trace-id": "4d9ceb1f6cb98086cd8333f0bb30****",
        "etag": "1YlaXvHZ3H5CjZic1Oeo****"
    },
    "statusCode": 200,
    "body": {
        "DBClusters": {
            "DBCluster": [
                {
                    "Category": "Basic",
                    "ResourceGroupId": "rg-acfmz7u4zzr****",
                    "ControlVersion": "v2",
                    "Port": "8123",
                    "DBClusterId": "cc-bp1084nnobip9****",
                    "DBClusterNetworkType": "vpc",
                    "DBNodeCount": 1,
                    "CommodityCode": "clickhouse_go_public_cn",
                    "Bid": "26842",
                    "LockReason": "",
                    "Tags": {
                        "Tag": [
                            {
                                "Value": "01",
                                "Key": "test"
                            }
                        ]
                    },
                    "DBNodeStorage": 100,
                    "IsExpired": false,
                    "StorageType": "CloudESSD",
                    "ZoneId": "cn-hangzhou-h",
                    "DBClusterStatus": "Running",
                    "CreateTime": "2023-07-27T07:47:19Z",
                    "VSwitchId": "vsw-bp11dxnc500olkyyf****",
                    "DBClusterDescription": "cc-bp1084nnobip9****",
                    "PayType": "Postpaid",
                    "LockMode": "Unlock",
                    "DBNodeClass": "S8",
                    "ScaleOutStatus": {},
                    "VpcId": "vpc-bp1pf7eciga85yo53****",
                    "VpcCloudInstanceId": "cc-bp1084nnobip9****",
                    "RegionId": "cn-hangzhou",
                    "ConnectionString": "cc-bp1084nnobip9****.clickhouse.ads.aliyuncs.com",
                    "ExpireTime": "",
                    "AliUid": 164882191396****
                },
                {
                    "Category": "Basic",
                    "ResourceGroupId": "rg-acfmz7u4zzr****",
                    "ControlVersion": "v2",
                    "Port": "8123",
                    "DBClusterId": "cc-bp166xfnay4rw****",
                    "DBClusterNetworkType": "vpc",
                    "DBNodeCount": 1,
                    "CommodityCode": "clickhouse_go_public_cn",
                    "Bid": "26842",
                    "LockReason": "",
                    "Tags": {
                        "Tag": [
                            {
                                "Value": "01",
                                "Key": "test"
                            }
                        ]
                    },
                    "DBNodeStorage": 100,
                    "IsExpired": false,
                    "StorageType": "CloudESSD",
                    "ZoneId": "cn-hangzhou-h",
                    "DBClusterStatus": "Running",
                    "CreateTime": "2023-07-27T06:53:54Z",
                    "VSwitchId": "vsw-bp1mbnyrjtf3ihga1****",
                    "DBClusterDescription": "cc-bp166xfnay4rw****",
                    "PayType": "Postpaid",
                    "LockMode": "Unlock",
                    "DBNodeClass": "S8",
                    "ScaleOutStatus": {},
                    "VpcId": "vpc-bp1ov7as4yvz4kxei****",
                    "VpcCloudInstanceId": "cc-bp166xfnay4rw****",
                    "RegionId": "cn-hangzhou",
                    "ConnectionString": "cc-bp166xfnay4rw****.clickhouse.ads.aliyuncs.com",
                    "ExpireTime": "",
                    "AliUid": 164882191396****
                }
            ]
        }
    }
}

Each object in the DBCluster array represents one cluster. Key fields:

Field	Description
`DBClusterId`	Unique cluster ID
`DBClusterStatus`	Current status, for example `Running`
`ConnectionString`	Endpoint for connecting to the cluster
`Port`	HTTP port (`8123`)
`RegionId`	Region where the cluster is deployed
`PayType`	Billing method (`Postpaid` = pay-as-you-go)

Tip: In production code, create the SDK client once and reuse it across requests. Creating a new client per request adds unnecessary overhead.

What's next

Browse the full list of available API operations: ApsaraDB for ClickHouse API reference
Use SDKs for other languages: ApsaraDB for ClickHouse SDK