跳到主要内容
跳到主要内容

连接 dlt 到 ClickHouse

dlt 是一个开源库，您可以将其添加到您的 Python 脚本中，以将来自各种且常常杂乱的数据源的数据加载到结构良好、实时的数据集中。

使用 ClickHouse 安装 dlt​

安装带有 ClickHouse 依赖项的 dlt 库:​

设置指南​

1. 初始化 dlt 项目​

首先，按如下方式初始化一个新的 dlt 项目：

备注

此命令将以 chess 作为源，以 ClickHouse 作为目标初始化您的管道。

上述命令会生成多个文件和目录，包括 .dlt/secrets.toml 以及用于 ClickHouse 的 requirements 文件。您可以通过以下命令执行 requirements 文件以安装所需的依赖项：

或使用 pip install dlt[clickhouse]，这将安装 dlt 库及其与 ClickHouse 作为目标工作所需的依赖项。

2. 设置 ClickHouse 数据库​

要将数据加载到 ClickHouse，您需要创建一个 ClickHouse 数据库。以下是您应执行的大致步骤：

  1. 您可以使用现有的 ClickHouse 数据库或创建一个新的。

  2. 要创建新数据库，请使用 clickhouse-client 命令行工具或您选择的 SQL 客户端连接到您的 ClickHouse 服务器。

  3. 运行以下 SQL 命令以创建新数据库、用户并授予必要的权限：

3. 添加凭据​

接下来，在 .dlt/secrets.toml 文件中设置 ClickHouse 凭据，如下所示：

备注

HTTP_PORT http_port 参数指定连接到 ClickHouse 服务器的 HTTP 接口时使用的端口号。此端口与默认的 9000 端口不同，后者用于原生 TCP 协议。

如果您不使用外部暂存（即在管道中没有设置暂存参数），则必须设置 http_port。这是因为内置的 ClickHouse 本地存储暂存使用 clickhouse content 库，该库通过 HTTP 与 ClickHouse 通信。

确保您的 ClickHouse 服务器已配置为接受在 http_port 指定的端口上的 HTTP 连接。例如，如果您设置 http_port = 8443，则 ClickHouse 应在 8443 端口上监听 HTTP 请求。如果您使用外部暂存，则可以省略 http_port 参数，因为在这种情况下不会使用 clickhouse-connect。

您可以传递类似于 clickhouse-driver 库使用的数据库连接字符串。上述凭据看起来将是这样的：

写入处置​

所有 写入处置 都是支持的。

dlt 库中的写入处置定义了数据应如何写入目标。有三种类型的写入处置：

替换：此处置将资源中的数据替换目标中的数据。它会先删除所有类和对象，然后在加载数据之前重新创建模式。您可以在 这里 了解更多。

合并：此写入处置将资源中的数据与目标中的数据合并。对于 merge 处置，您需要为资源指定 primary_key。您可以在 这里 了解更多。

附加：这是默认的处置。它将数据附加到目标中现有的数据，忽略 primary_key 字段。

数据加载​

数据是根据数据源使用最有效的方法加载到 ClickHouse 中：

  • 对于本地文件，使用 clickhouse-connect 库直接将文件加载到 ClickHouse 表中，使用 INSERT 命令。
  • 对于 S3，Google Cloud Storage 或 Azure Blob Storage 中的远程存储文件，使用 ClickHouse 表函数，如 s3、gcs 和 azureBlobStorage 读取文件并将数据插入表中。

数据集​

Clickhouse 不支持一个数据库中的多个数据集，而 dlt 则因多种原因依赖数据集。为了使 Clickhouse 能够与 dlt 一起工作，dlt 在您的 Clickhouse 数据库中生成的表将以数据集名称为前缀，使用可配置的 dataset_table_separator 分隔。此外，将创建一个特殊的哨兵表，该表不包含任何数据，以便 dlt 识别在 Clickhouse 目标中已存在的虚拟数据集。

支持的文件格式​

  • jsonl 是直接加载和暂存的首选格式。
  • parquet 同样支持直接加载和暂存。

clickhouse 目标有一些特定于默认 sql 目标的偏差：

  1. Clickhouse 有一个实验性的 object 数据类型，但我们发现它有点不可预测，因此 dlt clickhouse 目标将复杂数据类型加载到文本列中。如果您需要此功能，请与我们的 Slack 社区联系，我们将考虑添加它。
  2. Clickhouse 不支持 time 数据类型。时间将加载到 text 列中。
  3. Clickhouse 不支持 binary 数据类型。相反，二进制数据将加载到 text 列中。当从 jsonl 加载时，二进制数据将是一个 base64 字符串，而从 parquet 加载时，binary 对象将转换为 text。
  4. Clickhouse 允许在已填充的表中添加不可为 null 的列。
  5. Clickhouse 在某些条件下使用 float 或 double 数据类型时可能会产生舍入错误。如果您无法承受舍入错误，请确保使用 decimal 数据类型。例如，将值 12.7001 加载到设置为 jsonl 的 double 列中将可预测地产生舍入错误。

支持的列提示​

ClickHouse 支持以下 列提示：

  • primary_key - 将列标记为主键的一部分。多个列可以具有此提示以创建复合主键。

表引擎​

默认情况下，表使用 ClickHouse 中的 ReplicatedMergeTree 表引擎创建。您可以使用 table_engine_type 与 clickhouse 适配器指定一种替代表引擎：

支持的值为：

  • merge_tree - 使用 MergeTree 引擎创建表
  • replicated_merge_tree（默认） - 使用 ReplicatedMergeTree 引擎创建表

暂存支持​

ClickHouse 支持 Amazon S3、Google Cloud Storage 和 Azure Blob Storage 作为文件暂存目标。

dlt 将上传 Parquet 或 jsonl 文件到暂存位置，并使用 ClickHouse 表函数直接从暂存文件加载数据。

请参考文件系统文档以了解如何配置暂存目标的凭据：

要运行启用暂存的管道：

使用 Google Cloud Storage 作为暂存区域​

dlt 支持使用 Google Cloud Storage (GCS) 作为将数据加载到 ClickHouse 时的暂存区域。ClickHouse 的 GCS 表函数 会自动处理此事，dlt 在底层使用它。

clickhouse GCS 表函数仅支持使用基于哈希的消息认证码（HMAC）密钥进行身份验证。为此，GCS 提供了一种 S3 兼容模式，以模拟 Amazon S3 API。ClickHouse 利用这一点允许通过其 S3 集成访问 GCS 存储桶。

要在 dlt 中使用 HMAC 身份验证设置 GCS 暂存：

  1. 按照 Google Cloud 指南 为您的 GCS 服务帐户创建 HMAC 密钥。

  2. 在 dlt 项目的 ClickHouse 目标设置的 config.toml 中配置 HMAC 密钥以及 client_email、project_id 和 private_key：

注意：除了 HMAC 密钥 gcp_access_key_id 和 gcp_secret_access_key 之外，您现在还需要在 [destination.filesystem.credentials] 下提供服务帐户的 client_email、project_id 和 private_key。这是因为 GCS 暂存支持现在作为一种临时解决方案实现，仍在优化中。

dlt 将把这些凭证传递给 ClickHouse，后者将处理身份验证和 GCS 访问。

目前正在进行积极的工作，以简化和改进 ClickHouse dlt 目标的 GCS 暂存设置。适当的 GCS 暂存支持正在这些 GitHub 问题中跟踪：

dbt 支持​

通过 dbt-clickhouse 与 dbt 的集成通常是支持的。

dlt 状态同步​

该目标完全支持 dlt 状态同步。