数据集成数据工程数据分析【免费下载链接】cloudqueryData pipelines for cloud config and security data. Build cloud asset inventory, CSPM, FinOps, and vulnerability management solutions. Extract from AWS, Azure, GCP, and 70 cloud and SaaS sources.项目地址https://gitcode.com/gh_mirrors/cl/cloudquery点击查看免费下载CloudQuery ClickHouse 目标插件允许你把任意 CloudQuery 源插件同步出的数据写入 ClickHouse 数据库用于构建云资产清单、CSPM、FinOps 等分析场景。本文基于plugins/destination/clickhouse/docs/overview.md展开结合仓库内源码client/spec/spec.go、client.go、queries/tables.go、retry_helpers.go等深入剖析每个配置项的底层行为。读完本文你将掌握该插件的完整配置方法、表引擎/分区/排序键/TTL 的自定义策略以及数据迁移与写入的底层实现原理。插件概览与能力边界该目标插件用于将 CloudQuery 源插件同步的数据写入 ClickHouse 数据库。在使用前需要明确以下能力边界仅支持append写模式写入模式必须通过顶层 spec 的write_mode显式指定为append。从源码看migrate.go中实现了表创建与自动迁移逻辑但写入路径write.go中的WriteTableBatch只负责批量插入不提供 overwrite 语义。支持的数据库版本 24.8.1。该约束并非文档口号而是由 client.go 中的代码强制校验连接建立后会调用conn.ServerVersion()获取服务器版本若低于proto.Version{Major: 24, Minor: 8, Patch: 1}插件会直接报错并关闭连接。表引擎限制仅支持*MergeTree家族引擎配置其他引擎会在校验阶段直接报错。快速开始最小配置示例以下是最小可用配置完整示例见 docs/_configuration.mdkind: destination spec: name: clickhouse path: cloudquery/clickhouse registry: cloudquery version: VERSION_DESTINATION_CLICKHOUSE write_mode: append send_sync_summary: true # Learn more about the configuration options at https://cql.ink/clickhouse_destination spec: connection_string: clickhouse://${CH_USER}:${CH_PASSWORD}localhost:9000/${CH_DATABASE} # Optional parameters # cluster: # ca_cert: # engine: # name: MergeTree # parameters: [] # # batch_size: 10000 # batch_size_bytes: 5242880 # 5 MiB # batch_timeout: 20s该配置连接位于localhost:9000的 ClickHouse 实例并要求预先设置CH_USER、CH_PASSWORD、CH_DATABASE三个环境变量。注意生产环境务必使用环境变量展开如${CH_PASSWORD}来注入凭据而不是把明文密码直接写入配置文件。ClickHouse spec 参数完整参考插件的嵌套 spec即顶层spec:下的spec:定义在 client/spec/spec.go参数说明如下。connection_stringstring必填数据库连接字符串遵循 ClickHouse Go SDK 的 DSN 格式。例如clickhouse://username:passwordhost1:9000,host2:9000/database?dial_timeout200msmax_execution_time60支持逗号分隔多个 host 以实现负载均衡。该字段在 JSON Schema 中标记为required, minLength1且是唯一必填项——spec_test.go 中的测试验证了空字符串、null、非字符串类型都会校验失败。底层解析逻辑位于Spec.Options()spec.go调用clickhouse.ParseDSN解析连接字符串若 DSN 中未指定数据库名自动使用default若指定了ca_cert且 DSN 中带有 TLS 配置则把证书追加到系统证书池。clusterstring可选默认不启用用于分布式 DDL 的集群名称。若设置了该值建表/删表语句会变成CREATE TABLE IF NOT EXISTS ... ON CLUSTER cluster_name见 queries/table.go 中的tableNamePart与测试快照 create_table_cluster.sql。若为空DDL 只影响插件当前连接的服务器。ca_certstring可选默认不启用PEM 编码的 CA 证书。设置后插件会把该证书追加到系统证书池x509.SystemCertPool()用于 TLS 连接时的服务端证书校验。若追加失败证书内容非法Options()会返回failed to append ca_cert value错误spec.go。如需从文件读取证书内容可借助 CloudQuery CLI 的文件变量替换功能。batch_sizeinteger可选默认10000单个写入批次中最多合并的条目数。在 client.go 中该值通过batchwriter.WithBatchSize传给 SDK 的批处理器若配置为 0SetDefaults()会回退到10000spec.go。batch_size_bytesinteger可选默认5242880即 5 MiB单个写入批次的最大字节数通过batchwriter.WithBatchSizeBytes生效。默认值在源码中是5 205 MiB。批处理器会同时受条目数与字节数两个上限约束先达到者触发一次写入。batch_timeoutduration可选默认20s相邻两次批量写入之间的最大间隔。即使批次未达到batch_size或batch_size_bytes上限只要到达该时间窗口也会强制落盘。默认值20s由SetDefaults()中的configtype.NewDuration(20 * time.Second)设置JSON Schema 中也通过JSONSchemaExtend注入了该默认值spec.go。engine可选默认MergeTree表引擎配置详见下一节表引擎。partition可选默认不分区分区策略数组对应CREATE TABLE的PARTITION BY子句详见分区策略一节。order可选默认使用现有主键排序策略数组对应CREATE TABLE的ORDER BY子句详见排序键一节。ttl可选表 TTL 策略数组详见表 TTL一节。注意 overview 文档中 TTL 单独成节但它在 spec 结构中与partition、order平级见 spec.go 的TTL []TTLStrategy。校验逻辑Spec.Validate()spec.go会执行以下检查每个分区策略必须提供partition_by否则报partition_by is required每个排序策略必须提供order_by否则报order_by is required每个 TTL 策略必须提供ttl否则报ttl is required引擎名称必须以MergeTree结尾。相应的边界测试见 spec_test.go。自定义表引擎MergeTree 家族通过engine可以为所有由插件创建的表指定自定义引擎kind: destination spec: name: clickhouse path: cloudquery/clickhouse registry: cloudquery version: VERSION_DESTINATION_CLICKHOUSE write_mode: append send_sync_summary: true spec: connection_string: clickhouse://${CH_USER}:${CH_PASSWORD}localhost:9000/${CH_DATABASE} engine: name: ReplicatedMergeTree parameters: - /clickhouse/tables/{shard}/{database}/{table} - {replica}字段说明namestring必填表引擎名称目前只支持*MergeTree家族。JSON Schema 通过pattern^.*MergeTree$强制约束见 engine.go测试用例 engine_test.go 确认MergeTree与SomeRubbishMergeTree都能通过、而SomeEngine会被拒绝。parameters参数数组可选默认空引擎参数。目前对参数类型没有限制字符串会被单引号包裹后拼入 SQL例如ReplicatedMergeTree(/clickhouse/tables/..., {replica})整数、浮点数、布尔值等按字面量输出engine.go。不配置时默认引擎为MergeTree()。最终生成的建表语句形如见测试快照 create_table_engine.sqlCREATE TABLE IF NOT EXISTS table_name ( ... ) ENGINE ReplicatedMergeTree(a, b, 1, 2, 3, 1.2, 3.4, 327, false, true) ORDER BY (extra_col, _cq_id) SETTINGS allow_nullable_key1分区策略Partitioningpartition是一个对象数组每个对象定义一组表的PARTITION BY表达式tablesstring 数组可选默认[*]用于匹配表名的 glob 模式规则与顶层 spec 的tables选项一致。若一张表同时命中某策略的tables与skip_tables该表会被跳过若一张表同时命中两个分区策略运行时迁移阶段会报错table xxx matched multiple partition strategies。skip_tablesstring 数组可选默认空要跳过匹配的表名 glob 模式。skip_incremental_tablesboolean可选默认false若为true增量表不应用该分区策略见 queries/tables.go 中的ResolvePartitionBy对table.IsIncremental直接continue。partition_bystring必填分区表达式原样拼在PARTITION BY之后不做任何校验或引号处理例如toYYYYMM(_cq_sync_time)。留空会触发校验错误。示例partition: - tables: [*] skip_tables: [special_partition_table, non_partitioned_table] partition_by: toYYYYMM(_cq_sync_time) - tables: [special_partition_table] partition_by: toYYYYMMDD(_cq_sync_time)注意tables缺省时SetDefaults()会自动填充为[*]spec.go因此上面的两条策略分别覆盖除特殊表外的所有表按toYYYYMM(_cq_sync_time)分区和special_partition_table按toYYYYMMDD(_cq_sync_time)分区。生成的建表语句形如测试快照 create_table_partition_by.sqlCREATE TABLE IF NOT EXISTS table_name (...) ENGINE MergeTree() PARTITION BY toYYYYMM(_cq_sync_time) ORDER BY (extra_col, _cq_id) SETTINGS allow_nullable_key1排序键Orderingorder是一个对象数组用于为表或表组自定义ORDER BY子句tablesstring 数组可选默认[*]匹配表名的 glob 模式。skip_tablesstring 数组可选默认空跳过的表名 glob 模式。order_bystring 数组必填排序键表达式列表各表达式原样拼在ORDER BY之后并以逗号分隔不做校验或引号处理。注意与文档中单一字符串不同的是源码中OrderBy是字符串数组最终会被strings.Join(..., , )连接spec.go。示例order: - tables: [aws_ec2_instances] order_by: - account_id - region - toYYYYMM(_cq_sync_time) DESC - _cq_id默认行为未配置order时使用SortKeysqueries/tables.go自动推导排序键——取所有非空NotNull或主键且非复合类型Struct/Map/List的列并把_cq_id移到末尾。复合类型列之所以被排除是因为 ClickHouse 的排序键不允许数组/嵌套结构参与。表 TTLttl是一个对象数组为插件创建的表强制执行过期策略tablesstring 数组可选默认[*]匹配表名的 glob 模式。skip_tablesstring 数组可选默认空跳过的表名 glob 模式。ttlstring必填相对_cq_sync_time的 TTL 间隔例如INTERVAL 60 DAY。该字符串原样拼在TTL _cq_sync_time 之后实际上完整表达式由GetTTLString生成不做校验或引号处理。示例ttl: - tables: [*] skip_tables: [no_ttl_table] ttl: INTERVAL 60 DAYTTL 表达式的实际生成逻辑在 queries/tables.go 的GetTTLString若_cq_sync_time保证非空对应--cq-columns-not-null标志控制生成_cq_sync_time (INTERVAL 60 DAY)否则使用安全兜底toDateTime(coalesce(_cq_sync_time, makeDate(1970, 1, 1))) (INTERVAL 60 DAY)避免 TTL 列出现NULL导致 ClickHouse 报错。生成的建表语句形如测试快照 create_table_ttl.sqlCREATE TABLE IF NOT EXISTS table_name (...) ENGINE MergeTree() ORDER BY (extra_col, _cq_id) TTL toDateTime(coalesce(_cq_sync_time, makeDate(1970, 1, 1))) (INTERVAL 1 DAY INTERVAL 5415 SECOND) SETTINGS allow_nullable_key1连接 ClickHouse Cloud连接 ClickHouse Cloud 时需要在连接字符串中设置securetrue用户名固定为default端口为9440connection_string: clickhouse://default:${CH_PASSWORD}your-server-id.region.provider.clickhouse.cloud:9440/${CH_DATABASE}?securetrue其中your-server-id.region.provider.clickhouse.cloud是 ClickHouse Cloud 服务实例的主机地址。调试模式verbose logging将debugtrue加入connection_string即可启用 ClickHouse Go SDK 的调试日志kind: destination spec: name: clickhouse path: cloudquery/clickhouse registry: cloudquery version: VERSION_DESTINATION_CLICKHOUSE write_mode: append send_sync_summary: true spec: connection_string: clickhouse://${CH_USER}:${CH_PASSWORD}localhost:9000/${CH_DATABASE}?debugtrue警告debugtrue使用的是 SDK 内置日志可能会把数据内容与敏感信息如密码输出到日志中请勿在生产环境使用。另外连接失败时插件内置的连接测试器cloudquery test-connection命令使用会把错误归类为INVALID_SPEC、UNAUTHORIZED、UNREACHABLE、CONNECTION_FAILED四种码便于快速定位问题见 client/test_connection.go。Apache Arrow 类型映射插件通过 Apache Arrow 的 RecordBatch 与 ClickHouse 交互类型转换遵循 ClickHouse 的 Arrow 格式参考。下表是 Arrow 列类型到 ClickHouse 类型的映射完整版见 docs/types.mdArrow Column TypeClickHouse TypeBinaryStringBinary ViewStringBooleanBoolDate32Date32Date64DateTimeDecimal128 (Decimal)DecimalDecimal256DecimalFixed Size BinaryFixedStringFixed Size ListArrayFloat16 / Float32Float32Float64Float64Int8 / Int16 / Int32 / Int64Int8 / Int16 / Int32 / Int64Large Binary / Large StringStringLarge List / ListArrayMapMapString / String ViewStringStructTupleTime32 / Time64 / TimestampDateTime64UUID (CloudQuery 扩展)UUIDUint8 / Uint16 / Uint32 / Uint64UInt8 / UInt16 / UInt32 / UInt64两点补充不支持的类型一律映射为StringClickHouseNested类型的值按上述规则递归转换。从建表测试快照如 create_table.sql可以看到 CloudQuery 标准系统列的实际落库形态_cq_id为UUID、_cq_parent_id为Nullable(UUID)、_cq_source_name为Nullable(String)、_cq_sync_time为Nullable(DateTime64(6))。源码级实现剖析建表、迁移、写入与删除建表DDL 生成queries/tables.go 的CreateTable按固定顺序拼接CREATE TABLE IF NOT EXISTS 表名集群模式下追加ON CLUSTER ...列定义由typeconv/ch将 Arrow 字段转成 ClickHouse 列类型ENGINE engine.String()可选PARTITION BY partition_byORDER BY (...)未解析出排序键时退化为tuple()可选TTL 表达式统一追加SETTINGS allow_nullable_key1允许可空列参与排序键。迁移MigrateTablesclient/migrate.go 的MigrateTables工作流程对比期望表结构来自源插件与现有表结构查询system.columns获得表不存在则直接建表表已存在但存在安全变更如新增可空列、新增不在排序键中的非空列、删除可空列时走自动迁移ALTER TABLE ... ADD COLUMN若变更涉及分区键、排序键变化或需删除列等不安全操作则标记为需要强制迁移——普通模式下会拒绝并提示使用migrate_mode: forced强制模式下会DROP TABLE后重建注意这会删除已有数据TTL 变更通过SHOW CREATE TABLE读取现有 TTL并与期望值做等价性比对table.go 用查询SELECT ttl1 ttl2判断两种写法是否等价因为 ClickHouse 会把INTERVAL 1 DAY规范化为toIntervalDay(1)。此外client/assess.go 实现了AssessTables评估接口可对迁移行为进行预演分类无变化 / 自动可迁移 / 需手工迁移migrate_mode: safe与migrate_mode: forced下的行为分别对应拒绝变更与重建表。写入批量插入client/write.go 的WriteTableBatch使用conn.PrepareBatchbatch.Send()一次性发送一个批次的多条 RecordBatchretry_helpers.go。插入 SQL 由 queries/insert.go 生成INSERT INTO table (col1, col2, ...)。针对 ClickHouse 常见的Too many simultaneous queries并发限制所有写、读、DDL 操作都包裹了重试逻辑最多重试 5 次、初始延迟 3 秒、抖动上限 1 秒仅在命中该错误时重试retry_helpers.go。数据删除与增量清理虽然插件只支持append写模式但它仍实现了DeleteStale与DeleteRecordclient/delete.goDeleteStale用于增量同步的过期数据清理生成DELETE FROM table WHERE _cq_source_name source_name AND toTimeZone(_cq_sync_time, UTC) sync_timeDeleteRecord按谓词组生成带占位符的DELETE语句。读取Readclient/read.go 实现了Read把表中整张表读回为 Arrow RecordBatch供需要回读场景使用。小结CloudQuery ClickHouse 目标插件以append写模式 MergeTree 家族引擎 批量写入为核心配合partitionPARTITION BY、orderORDER BY、ttl数据过期三大表级策略可灵活适配从默认全量同步到按时间分区、按实例定制排序键、定期清理旧数据的多种云资产管理场景。所有配置项均有源码级校验与默认值兜底见 spec.go 与配套测试 spec_test.go建表 SQL 的可视化快照则集中在 queries/testdata 目录读者可以直接对照查看每条策略生成的最终 SQL。赞分享数据集成数据工程数据分析【免费下载链接】cloudqueryData pipelines for cloud config and security data. Build cloud asset inventory, CSPM, FinOps, and vulnerability management solutions. Extract from AWS, Azure, GCP, and 70 cloud and SaaS sources.项目地址https://gitcode.com/gh_mirrors/cl/cloudquery点击查看免费下载相关推荐CloudQuery DuckDB 目标插件类型映射指南Apache Arrow 与 DuckDB 数据类型的完整对应关系CloudQuery DuckDB 目标插件类型映射指南Apache Arrow 与 DuckDB 数据类型的完整对应关系 本指南聚焦 CloudQuery数据集成数据工程数据分析CloudQuery ClickHouse 目标插件 Apache Arrow 类型转换全指南CloudQuery ClickHouse 目标插件 Apache Arrow 类型转换全指南 本篇指南聚焦 CloudQuery ClickHouse 目标插数据集成数据工程数据分析Win11Debloat 完整教程免费精简 Windows 11 的 PowerShell 脚本Win11Debloat 完整教程免费精简 Windows 11 的 PowerShell 脚本 三十秒判断这工具是不是给你的 Win11Debloat 是桌面应用CLI上一篇3个步骤开启乐高EV3的终极编程自由ev3dev完全指南下一篇GoReplay 非 root 用户运行指南用专用组与 setcap 安全授予抓包权限创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考