Loading data from Yandex Direct to a Yandex Managed Service for ClickHouse® data mart using Yandex Cloud Functions, Yandex Object Storage, and Yandex Data Transfer
To transfer data from Yandex Direct to Managed Service for ClickHouse®, you can use Cloud Functions, Object Storage, and Data Transfer. To do this:
- Transfer your data from Yandex Direct to Object Storage using Cloud Functions.
- Transfer your data from Object Storage to Managed Service for ClickHouse® using Data Transfer.
If you no longer need the resources you created, delete them.
Getting started
-
Prepare the test data to load from Yandex Direct:
-
Register the test application in Yandex.OAuth
.Select Web services as the platform. In the Redirect URI field, paste the URL for debugging:
https://oauth.yandex.ru/verification_code
. -
Get a debug token
for the application. -
Request
test access to Yandex Direct for the application and wait for approval. -
Set up the sandbox
in Yandex Direct with the Client role. -
(Optional) Check your setup by sending a request to the sandbox API from the application:
Sample request
curl \ -H 'Authorization: Bearer <debug_token>' \ -H 'Accept-Language: en' \ -d ' { "method":"get", "params": { "SelectionCriteria": {}, "FieldNames": [ "Id", "Name" ] } }' \ "https://api-sandbox.direct.yandex.com/json/v5/campaigns" | jq
Sample response
{ "result": { "Campaigns": [ { "Id": 463476, "Name": "Test API Sandbox campaign 1" }, { "Id": 463477, "Name": "Test API Sandbox campaign 2" }, { "Id": 463478, "Name": "Test API Sandbox campaign 3" } ] } }
-
-
Prepare your Yandex Cloud infrastructure:
ManuallyTerraform-
Create a service account named
storage-lockbox-sa
and assign it thestorage.uploader
andlockbox.payloadViewer
roles. -
Create a static access key for the
storage-lockbox-sa
service account. -
Create a secret in Yandex Lockbox with three
key:value
pairs:access_key:<public_key>
secret_key:<private_key>
app_token:<application_debug_token>
-
Create a bucket in Object Storage.
-
Create a Managed Service for ClickHouse® cluster in any suitable configuration with publicly available hosts.
-
If using security groups in your Managed Service for ClickHouse® cluster, make sure they are configured correctly and allow connecting to it.
-
If you do not have Terraform yet, install it.
-
Get the authentication credentials. You can add them to environment variables or specify them later in the provider configuration file.
-
Configure and initialize a provider. There is no need to create a provider configuration file manually, you can download it
. -
Place the configuration file in a separate working directory and specify the parameter values. If you did not add the authentication credentials to environment variables, specify them in the configuration file.
-
Download the ya-direct-to-mch.tf
configuration file to the same working directory.This file describes:
- Network.
- Subnet.
- Security group and rules required to connect to a Managed Service for ClickHouse® cluster.
- Service account with the
storage.uploader
andlockbox.payloadViewer
roles. - Static key for the service account.
- Yandex Lockbox secret.
- Object Storage bucket.
- Cloud Functions serverless function.
- Managed Service for ClickHouse® target cluster.
- Managed Service for ClickHouse® target endpoint.
- Transfer.
-
In the
ya-direct-to-mch.tf
file, specify the following variables:folder_id
: Cloud folder ID, same as in the provider settings.app_token
: Application debug token.bucket_name
: Object Storage bucket name. The name must be unique within the service.ch_password
: Managed Service for ClickHouse® cluster admin user password.
-
Make sure the Terraform configuration files are correct using this command:
terraform validate
If there are any errors in the configuration files, Terraform will point them out.
-
Create the required infrastructure:
-
Run the command to view planned changes:
terraform plan
If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
-
If you are happy with the planned changes, apply them:
-
Run the command:
terraform apply
-
Confirm the update of resources.
-
Wait for the operation to complete.
-
All the required resources will be created in the specified folder. You can check resource availability and their settings in the management console
. -
-
Transfer your data from Yandex Direct to Object Storage using Cloud Functions
-
Download the
example-py.zip
archive file with a Python function.The function uses an application token to read marketing campaign IDs and names from the sandbox, then writes this data to an Object Storage bucket in Parquet format.
The function accepts the following input:
- Service account key
- Application token
- Bucket name
Tip
You can use this function to obtain real campaign data or make requests on behalf of the agency. To do this, extract the archive file and comment out all the required parameters in
example.py
. See the code comments for details. -
Create and configure a function in the Cloud Functions service:
ManuallyTerraform-
In the editor that opens, select Python as the runtime environment and click Continue.
-
Specify the required settings:
-
ZIP archive:
ZIP archive
. -
File: Select the
example-py.zip
file you downloaded earlier. -
Entry point:
example.foo
. -
Service account: Select
storage-lockbox-sa
from the list. -
Environment variables: Enter the bucket name in the
key=value
format:- Key:
BUCKET
. - Value: Name of the previously created bucket after
s3://
.
- Key:
-
Lockbox secrets: Specify the path to the three previously created Yandex Lockbox secrets as environment variables:
AWS_ACCESS_KEY_ID
:access_key
AWS_SECRET_ACCESS_KEY
:secret_key
TOKEN
:app_token
You may leave default values for the other settings.
-
-
Click Save changes and wait for the function to compile.
-
In the
ya-direct-to-mch.tf
file, specify the following variables:path_to_zip_cf
: Path to the ZIP archive file with the function code.create_function
: Set to1
for creating a function.
-
Make sure the Terraform configuration files are correct using this command:
terraform validate
If there are any errors in the configuration files, Terraform will point them out.
-
Create the required infrastructure:
-
Run the command to view planned changes:
terraform plan
If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
-
If you are happy with the planned changes, apply them:
-
Run the command:
terraform apply
-
Confirm the update of resources.
-
Wait for the operation to complete.
-
-
-
Open the function you created in the management console. Select Functions in the left-hand panel.
-
Click Run test and wait for the function to complete.
You will see a Parquet file in the bucket.
Transfer your data from Object Storage to Managed Service for ClickHouse® using Data Transfer
-
Create a source endpoint with the following parameters:
-
Database type:
Object Storage
. -
Bucket: Bucket name in Object Storage.
-
Access Key ID: Public part of the service account static key. You may copy it from the Yandex Lockbox secret.
-
Secret Access Key: Private part of the service account static key. You may copy it from the Yandex Lockbox secret.
-
Endpoint:
https://storage.yandexcloud.net
. -
Region:
ru-central1
. -
Data format:
Parquet
. -
Schema:
{"Id": "int64", "Name": "string"}
. -
Table: Name of the Parquet file in the bucket, e.g.,
ac05e4fe818e463f88a8a299d290734d.snappy.parquet
. -
Result table schema: Select
Manual
and specify field names and data types:Id
:Int64
Name
:String
Leave the default values for the other parameters.
-
-
Create an endpoint for the target and the transfer:
ManuallyTerraform-
Create a Managed Service for ClickHouse® target endpoint using the parameters of the cluster you created earlier.
-
Create a transfer that will use the created endpoints.
-
In the
ya-direct-to-mch.tf
file, specify the following variables:source_endpoint_id
: Source endpoint ID.transfer_enabled
: Set to1
to enable transfer creation.
-
Make sure the Terraform configuration files are correct using this command:
terraform validate
If there are any errors in the configuration files, Terraform will point them out.
-
Create the required infrastructure:
-
Run the command to view planned changes:
terraform plan
If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
-
If you are happy with the planned changes, apply them:
-
Run the command:
terraform apply
-
Confirm the update of resources.
-
Wait for the operation to complete.
-
-
-
-
Activate the transfer and wait for its status to change to Completed.
-
Make sure the Object Storage source data was transferred to the Managed Service for ClickHouse® database:
-
Connect to the cluster using
clickhouse-client
: -
Run the following query:
SELECT * FROM ac05e4fe818e463f88a8a299d290734d_snappy_parquet;
Where
ac05e4fe818e463f88a8a299d290734d
is the Parquet file name.Response example
┌─────Id─┬─Name────────────────────────┬─__file_name─────────────────────────────────────┬─__row_index─┐ │ 463476 │ Test API Sandbox campaign 1 │ ac05e4fe818e463f88a8a299d290734d.snappy.parquet │ 1 │ │ 463477 │ Test API Sandbox campaign 2 │ ac05e4fe818e463f88a8a299d290734d.snappy.parquet │ 2 │ │ 463478 │ Test API Sandbox campaign 3 │ ac05e4fe818e463f88a8a299d290734d.snappy.parquet │ 3 │ └────────┴─────────────────────────────┴─────────────────────────────────────────────────┴─────────────┘
-
Delete the resources you created
Some resources are not free of charge. To avoid paying for them, delete the resources you no longer need:
Delete the other resources depending on how they were created:
-
In the terminal window, go to the directory containing the infrastructure plan.
-
Delete the
ya-direct-to-mch.tf
configuration file. -
Make sure the Terraform configuration files are correct using this command:
terraform validate
If there are any errors in the configuration files, Terraform will point them out.
-
Confirm updating the resources.
-
Run the command to view planned changes:
terraform plan
If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
-
If you are happy with the planned changes, apply them:
-
Run the command:
terraform apply
-
Confirm the update of resources.
-
Wait for the operation to complete.
-
This will delete all the resources described in the
ya-direct-to-mch.tf
configuration file. -
ClickHouse® is a registered trademark of ClickHouse, Inc