Get started with Aiven for ClickHouse®
Start using Aiven for ClickHouse® by creating and configuring a service, connecting to it, and loading sample data.
Prerequisites
Depending on a dev tool to use for working with Aiven for ClickHouse:
- Access to the Aiven Console
- ClickHouse CLI client
- Aiven Provider for Terraform
- Aiven Operator for Kubernetes®
- Docker
Create an Aiven for ClickHouse® service
- Console
- Terraform
- Kubernetes
-
From your project, in the Services page, click Create service.
-
From the Select service page, click ClickHouse®.
-
Select the cloud provider and region to host your service on.
noteThe pricing for the same service can vary between different providers and regions. The service summary shows you the pricing for your selected options.
-
Select a service plan.
noteThis determines the number of servers and the memory, CPU, and disk resources allocated to your service. See Plans & Pricing.
-
Optional: Add disk storage.
-
Enter a name for your service.
importantYou cannot change the name after you create the service.
You can fork the service with a new name instead.
-
Optional: Add tags.
-
Click Create service.
The Overview page of the service opens. It shows the connection parameters for your service, its current status, and the configuration options.
The status of the service is Rebuilding during its creation. When the status becomes Running, you can start using the service. This typically takes couple of minutes and can vary between cloud providers and regions.
-
Create the
sample.tffile for theaivenprovider configuration and theaiven_clickhouseresource.variable "aiven_token" {
type = string
}
variable "aiven_project_name" {
type = string
}
terraform {
required_providers {
aiven = {
source = "aiven/aiven"
version = ">=4.0.0, <5.0.0"
}
}
}
provider "aiven" {
api_token = var.aiven_token
}
resource "aiven_clickhouse" "clickhouse" {
project = var.aiven_project_name
cloud_name = "google-europe-west1"
plan = "startup-16"
service_name = "my-clickhouse"
maintenance_window_dow = "friday"
maintenance_window_time = "23:00:00"
clickhouse_user_config {
service_log = false
}
}
output "clickhouse_service_host" {
value = aiven_clickhouse.clickhouse.service_host
}
output "clickhouse_service_port" {
value = aiven_clickhouse.clickhouse.service_port
}
output "clickhouse_service_username" {
value = aiven_clickhouse.clickhouse.service_username
}
output "clickhouse_service_password" {
value = aiven_clickhouse.clickhouse.service_password
sensitive = true
} -
Create the
terraform.tfvarsfile for assigning actual values to your previously declared variables.aiven_token = "AIVEN_TOKEN"
aiven_project_name = "PROJECT_NAME" -
Run
terraform init>terraform plan>terraform apply --auto-approve. -
Store Terraform outputs in environment variables so that they can be used for connecting:
CLICKHOUSE_HOST="$(terraform output -raw clickhouse_service_host)"
CLICKHOUSE_PORT="$(terraform output -raw clickhouse_service_port)"
CLICKHOUSE_USER="$(terraform output -raw clickhouse_service_username)"
CLICKHOUSE_PASSWORD="$(terraform output -raw clickhouse_service_password)"
Create an Aiven for ClickHouse service using the Aiven Operator for Kubernetes.
-
Create file
example.yamlwith the following content:apiVersion: aiven.io/v1alpha1
kind: Clickhouse
metadata:
name: my-clickhouse
spec:
authSecretRef:
name: aiven-token
key: token
connInfoSecretTarget:
name: my-clickhouse-connection
userConfig:
service_log: false
project: my-aiven-project
cloudName: google-europe-west1
plan: startup-16
maintenanceWindowDow: friday
maintenanceWindowTime: 23:00:00 -
Create the service by applying the configuration:
kubectl apply -f example.yaml -
Review the resource you created with the following command:
kubectl get clickhouses my-clickhouse
The output is similar to the following:
Name Project Region Plan State
my-clickhouse my-aiven-project google-europe-west1 startup-16 RUNNING
The resource can stay in the REBUILDING state for a couple of minutes. Once the state
changes to RUNNING, you are ready to access it.
Configure the service
You can change your service settings by updating the service configuration.
- Console
- Terraform
- Kubernetes
- Select the new service from the list of services on the Services page.
- On the Overview page, select Service settings from the sidebar.
- In the Advanced configuration section, make changes to the service configuration.
Your changes can force the recreation of the aiven_clickhouse resource.
For all the attributes available for the aiven_clickhouse resource, see
the Aiven Provider for Terraform® documentation.
-
Updating the
aiven_clickhouseresource in thesample.tffile:- Add
service_log = trueandtermination_protection = true. - Update
maintenance_window_dow = "sunday"andmaintenance_window_time = "22:00:00".
variable "aiven_token" {
type = string
}
variable "aiven_project_name" {
type = string
}
terraform {
required_providers {
aiven = {
source = "aiven/aiven"
version = ">=4.0.0, <5.0.0"
}
}
}
provider "aiven" {
api_token = var.aiven_token
}
resource "aiven_clickhouse" "clickhouse" {
project = var.aiven_project_name
cloud_name = "google-europe-west1"
plan = "startup-16"
service_name = "my-clickhouse"
maintenance_window_dow = "sunday"
maintenance_window_time = "22:00:00"
termination_protection = true
clickhouse_user_config {
service_log = true
}
}
output "clickhouse_service_host" {
value = aiven_clickhouse.clickhouse.service_host
}
output "clickhouse_service_port" {
value = aiven_clickhouse.clickhouse.service_port
}
output "clickhouse_service_username" {
value = aiven_clickhouse.clickhouse.service_username
}
output "clickhouse_service_password" {
value = aiven_clickhouse.clickhouse.service_password
sensitive = true
} - Add
-
Run
terraform plan>terraform apply --auto-approve.
-
Update file
example.yaml:- Add
service_log: trueandterminationProtection: true. - Update
maintenanceWindowDow: sundayandmaintenanceWindowTime: 22:00:00.
apiVersion: aiven.io/v1alpha1
kind: Clickhouse
metadata:
name: my-clickhouse
spec:
authSecretRef:
name: aiven-token
key: token
connInfoSecretTarget:
name: my-clickhouse-connection
userConfig:
service_log: true
project: my-aiven-project
cloudName: google-europe-west1
plan: startup-16
maintenanceWindowDow: sunday
maintenanceWindowTime: 22:00:00
terminationProtection: true - Add
-
Update the service by applying the configuration:
kubectl apply -f example.yaml -
Review the resource you updated with the following command:
kubectl get clickhouses my-clickhouse
The resource can stay in the REBUILDING state for a couple of minutes. Once the state
changes to RUNNING, you are ready to access it.
See the available configuration options in:
Connect to the service
- Console
- Terraform
- ClickHouse client
-
Log in to the Aiven Console, and go to your organization > project > Aiven for ClickHouse service.
-
On the Overview page of your service, click Quick connect.
-
In the Connect window, select a tool or language to connect to your service, follow the connection instructions, and click Done.
docker run -it \
--rm clickhouse/clickhouse-server clickhouse-client \
--user avnadmin \
--password admin_password \
--host clickhouse-service-name-project-name.e.aivencloud.com \
--port 12691 \
--secure
Access your new service with the ClickHouse client using the environment variables assigned to Terraform outputs:
docker run -it \
--rm clickhouse/clickhouse-client \
--user=$CLICKHOUSE_USER \
--password=$CLICKHOUSE_PASSWORD \
--host=$CLICKHOUSE_HOST \
--port=$CLICKHOUSE_PORT \
--secure
Discover more tools for connecting to Aiven for ClickHouse in Connect to Aiven for ClickHouse®.
Load a dataset
-
Download a dataset from Example Datasets using cURL:
curl https://datasets.clickhouse.com/hits/tsv/hits_v1.tsv.xz | unxz --threads=`nproc` > hits_v1.tsv
curl https://datasets.clickhouse.com/visits/tsv/visits_v1.tsv.xz | unxz --threads=`nproc` > visits_v1.tsvnoteThe
nprocLinux command, which prints the number of processing units, is not available on macOS. To use the command, add an alias fornprocinto your~/.zshrcfile:alias nproc="sysctl -n hw.logicalcpu".Once done, you should have two files:
hits_v1.tsvandvisits_v1.tsv. -
Create tables
hits_v1andvisits_v1in thedefaultdatabase, which has been created automatically upon the creation of your Aiven for ClickHouse service.Expand for the
CREATE TABLE default.hits_v1sampleExpand for the
CREATE TABLE default.visits_v1sample -
Load data into tables
hits_v1andvisits_v1.-
Go to the folder where you stored the downloaded files for
hits_v1.tsvandvisits_v1.tsv. -
Run the following commands:
cat hits_v1.tsv | docker run \
--interactive \
--rm clickhouse/clickhouse-server clickhouse-client \
--user USERNAME \
--password PASSWORD \
--host HOST \
--port PORT \
--secure \
--max_insert_block_size=100000 \
--query="INSERT INTO default.hits_v1 FORMAT TSV"cat visits_v1.tsv | docker run \
--interactive \
--rm clickhouse/clickhouse-server clickhouse-client \
--user USERNAME \
--password PASSWORD \
--host HOST \
--port PORT \
--secure \
--max_insert_block_size=100000 \
--query="INSERT INTO default.visits_v1 FORMAT TSV"
-
Query data
Once the data is loaded, you can run queries against the sample data you imported.
-
Query the number of items in the
hits_v1table:SELECT COUNT(*) FROM default.hits_v1 -
Find the longest lasting sessions:
SELECT StartURL AS URL,
MAX(Duration) AS MaxDuration
FROM default.visits_v1
GROUP BY URL
ORDER BY MaxDuration DESC
LIMIT 10