数据集成数据工程数据分析【免费下载链接】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 仓库中 SQLite 目标插件plugins/destination/sqlite的官方类型说明文档types.md展开系统讲解 Apache Arrow 列类型与 SQLite 存储类型之间的映射规则、SQLite 简化的类型系统原理并结合插件源码验证每一类映射的底层实现。读完本文你将掌握哪些 Arrow 类型被 SQLite 插件支持、它们分别落到 SQLite 的哪个存储类型、为什么不支持的复杂类型统一退化为text以及建表、写入、读取时这套映射如何闭环工作。一、背景CloudQuery 的列类型为什么需要转换CloudQuery 从 AWS、Azure、GCP 以及 70 云与 SaaS 数据源抽取数据时以 Apache Arrow 的内存列式格式承载数据。当数据落地到 SQLite 目标时插件必须把 Arrow 的列类型翻译成 SQLite 能理解的类型。SQLite 与大多数数据库不同它采用动态类型系统只有 5 种存储类storage classSQLite 存储类说明NULL空值INTEGER有符号整数按值大小自动使用 1/2/3/4/6/8 字节存储REAL8 字节 IEEE 浮点数TEXT文本字符串采用数据库编码UTF-8/UTF-16BLOB按输入原样存储的二进制数据因此CloudQuery 的 SQLite 插件需要在 Arrow 的丰富类型体系与 SQLite 的 5 类存储之间做一次收敛映射。这一映射的官方定义就在 types.md 中而它的代码实现位于 client/types.go 的arrowTypeToSqliteStr函数。二、官方类型映射总表以下是 types.md 中给出的完整映射表原文 33 种 Arrow 列类型全部继承于此并保留“不支持的列类型一律映射为text”这条核心规则Arrow 列类型是否支持SQLite 类型Binary✅ 支持blobBoolean✅ 支持booleanDate32✅ 支持textDate64✅ 支持textDecimal✅ 支持textDense Union✅ 支持textDictionary✅ 支持textDuration✅ 支持textFixed Size List✅ 支持textFloat16✅ 支持realFloat32✅ 支持realFloat64✅ 支持realInet✅ 支持textInt8✅ 支持integerInt16✅ 支持integerInt32✅ 支持integerInt64✅ 支持integerInterval[DayTime]✅ 支持textInterval[MonthDayNano]✅ 支持textInterval[Month]✅ 支持textJSON✅ 支持textLarge Binary✅ 支持blobLarge List✅ 支持textLarge String✅ 支持textList✅ 支持textMAC✅ 支持textMap✅ 支持textString✅ 支持textStruct✅ 支持textTime32✅ 支持textTime64✅ 支持textTimestamp✅ 支持timestampUUID✅ 支持textUint8✅ 支持integerUint16✅ 支持integerUint32✅ 支持integerUint64✅ 支持integerUnion✅ 支持text注意表中列出的 33 种 Arrow 类型中32 种被明确标记为「✅ 支持」仅在前言声明“Unsupported types are always mapped totext”不支持的列类型总是映射为text作为兜底策略存在。从实现上看凡未进入arrowTypeToSqliteStr显式分支的类型都会落入default分支返回text见下文源码解析。三、官方 NotesSQLite 类型系统的五个要点types.md 在映射表之后给出了五条关键说明这些是理解整张映射表的理论基础SQLite 的类型系统极其简化只有NULL、INTEGER、REAL、TEXT、BLOB五种存储类所有整数类型有符号与无符号8 位到 64 位统一存储为 SQLiteinteger所有浮点类型Float16、Float32、Float64统一存储为 SQLitereal复杂数据类型如 JSON、List、Struct会被序列化后以text形式存储二进制数据使用 SQLite 的blob存储类SQLite 的动态类型系统允许数据在声明列类型之外灵活存储因此即使列的声明类型与实际写入的值类型不一致也不会造成写入失败。第 5 点需要特别展开SQLite 采用**动态类型type affinity**机制——建表时声明的类型只是“亲和性建议”实际写入时每个值按自身情况独立选择存储类。这意味着即使某列被声明为integer写入一个TEXT值也不会报错。这也正是 CloudQuery SQLite 插件可以放心地把大量复杂类型全部映射为text的底层原因读取时再通过字符串反序列化还原成 Arrow 类型即可见第六节。四、源码级验证映射函数arrowTypeToSqliteStr映射表的实现核心是 client/types.go 中的arrowTypeToSqliteStr函数。它按 Arrow 类型的 IDarrow.DataType.ID()做 switch 分发与文档映射表一一对应func (*Client) arrowTypeToSqliteStr(t arrow.DataType) string { switch t.ID() { case arrow.BINARY, arrow.LARGE_BINARY: return blob case arrow.INT8, arrow.INT16, arrow.INT32, arrow.INT64, arrow.UINT8, arrow.UINT16, arrow.UINT32, arrow.UINT64: return integer case arrow.FLOAT16, arrow.FLOAT32, arrow.FLOAT64: return real case arrow.BOOL: return boolean case arrow.TIMESTAMP: return timestamp default: return text } }这份实现可以逐一印证文档的映射规则blob分支只有BINARY与LARGE_BINARY两类落入与文档表中 Binary/Large Binary →blob完全一致integer分支8 种整数类型Int8/16/32/64 与 Uint8/16/32/64全部收敛到integer印证了「所有整数类型统一存为 integer」real分支Float16/32/64 三种浮点类型全部收敛到realboolean与timestamp仅 Boolean 与 Timestamp 两个 Arrow 类型独享这两个 SQLite 类型名default分支text包括 String、Date、JSON、List、Struct、Map、UUID、Decimal、所有 Interval/Union/Dictionary 等在内的其余全部类型都落到这里印证了「复杂类型一律序列化为 text」以及「不支持的未知类型兜底为 text」。配套的逆向映射arrowTypeToSqlite与sqliteTypeToArrowType同一文件中还有两个重要函数共同构成完整的双向往返arrowTypeToSqlite(t arrow.DataType) arrow.DataTypetypes.go在建表前把 Arrow 字段“归一化”将各类整数统一为arrow.PrimitiveTypes.Int64、浮点统一为Float64、时间戳统一为Timestamp_us、其余一律归一为LargeString。这样从源头保证了写入 SQLite 的值类型与建表声明的类型一致规避动态类型系统下的值/声明不一致问题。sqliteTypeToArrowType(t string) arrow.DataTypetypes.go读取表结构PRAGMA table_info时把 SQLite 的integer/real/text/blob/boolean/timestamp还原回对应的 Arrow 类型用于把本地 SQLite 表映射回schema.Table。五、建表时如何应用映射createTableIfNotExist映射最终落地在 client/migrate.go 的createTableIfNotExist中。该函数遍历表的每一列用arrowTypeToSqliteStr(col.Type)取得 SQLite 列类型然后拼装CREATE TABLE IF NOT EXISTS语句for i, col : range table.Columns { sqlType : c.arrowTypeToSqliteStr(col.Type) if sqlType { c.logger.Warn().Str(table, table.Name).Str(column, col.Name).Msg(Column type is not supported, skipping) continue } fieldDef : identifier(col.Name) sqlType if col.NotNull { fieldDef NOT NULL } sb.WriteString(fieldDef) ... }这里有两个值得注意的工程细节NOT NULL约束如果源列定义了NotNull建表语句会追加NOT NULL这会影响后续迁移见canAutoMigrate对主键/非空列的保守处理复合主键当表存在主键列时函数末尾会追加形如CONSTRAINT table_cqpk PRIMARY KEY (col1,col2)的复合主键约束migrate.go这一约束又决定了写入时走INSERT OR REPLACE的 upsert 路径见下文。六、写入与读取映射如何闭环类型映射不只是“建表时定个列类型”还贯穿写入与读取两个方向。写入方向Arrow Record → SQLite 值写入路径的核心是 typeconv/values.go 的FromArray函数。它对不同 Arrow 数组做差异化取值整数/布尔/字符串/浮点通过泛型辅助函数primitiveValuetypeconv/primitive.go直接取出底层值Float16通过float16Valuetypeconv/special.go把半精度浮点转成float32再落库Binary/FixedSizeBinary/LargeBinary通过byteArrValuetypeconv/special.go把字节数组转为字符串存储注意二进制列在写库时转成了字符串读回时再还原见下文其余所有类型JSON、List、Struct、Map、UUID、时间、Decimal 等统一走valueStrDatatypeconv/special.go调用arr.ValueStr(i)获取该值的字符串表示后写入text列——这正是文档「复杂类型序列化存为 text」的实现细节。写入 SQL 的生成在 client/write.go表没有主键时生成普通INSERT INTOinsert函数write.go表有主键时生成INSERT OR REPLACE INTOupsert函数write.go实现基于主键的幂等覆盖写入避免cloudquery sync重复同步时产生重复行。读取方向SQLite 值 → Arrow Record读取路径在 client/read.gocreateResultsArrayread.go按列类型选择sql.NullBool/[]byte/sql.NullInt64/sql.NullFloat64/sql.NullString作为扫描目标reverseTransformread.go把扫描到的值按列类型还原为对应的 Arrow Builder 值整数还原为 Int8/Int16/…/Uint64 各自的 Builder浮点还原为 Float32/Float64字符串还原为 String二进制还原为BinaryBuilder.Append([]byte)对于以text存储的复杂类型reverseTransform的default分支调用appendFromString实现见 client/append_from_string.go把文本反序列化回原始 Arrow 类型从而保证从 SQLite 读出的数据与源端 Arrow 类型一致。七、实战建议与注意事项结合 types.md 与源码实现给出几条可直接落地的实践建议查询复杂字段注意序列化格式JSON、List、Struct、Map、UUID、Date、Decimal 等字段在 SQLite 中都以text存储。用sqlite3CLI 直接查看时看到的是序列化字符串若需要以原生类型消费建议仍通过 CloudQuery 的读取链路或读回后反序列化而不要假设某种固定的文本格式。具体以valueStrData调用 ArrowValueStr的语义为准typeconv/special.go。二进制与 BlobBinary/Large Binary列在建表时声明为blob但写入时byteArrValue会先转为字符串、读回时再[]byte还原typeconv/special.go。若需要在库外直接用 SQL 处理这些二进制内容请先验证其实际存储形态。无主键表是追加语义有主键表是覆盖语义cloudquery sync重复运行同一任务时带主键的表通过INSERT OR REPLACE覆盖更新write.go而无主键表会持续追加可能出现重复行。迁移模式选择主键或NOT NULL列的新增/删除无法自动迁移此时cloudquery sync会报错提示改用migrate_mode: forced相关逻辑见 migrate.go 的canAutoMigrate。快速上手完整的最小配置示例见 configuration.mdconnection_string: ./db.sql同步完成后即可用sqlite ./db.sql本地探索数据插件整体能力概览可参考 overview.md。八、小结CloudQuery 的 SQLite 目标插件在「Arrow 的丰富类型体系」与「SQLite 的 5 种存储类」之间建立了一套清晰且保守的映射能用原生存储类表达的整数→integer、浮点→real、布尔→boolean、时间戳→timestamp、二进制→blob尽量原生表达其余复杂类型统一序列化为text兜底。这套规则在 types.md 中有权威定义在 client/types.go、client/migrate.go、typeconv/values.go、client/read.go 等源码中得到了完整闭环的印证。理解这张映射表是正确使用、查询与运维 CloudQuery SQLite 落地数据的前提。赞分享数据集成数据工程数据分析【免费下载链接】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 Gremlin 目标插件类型映射指南Apache Arrow 与 Gremlin/Neptune 数据类型全解析CloudQuery Gremlin 目标插件类型映射指南Apache Arrow 与 Gremlin/Neptune 数据类型全解析 Gremlin 目标插数据集成数据工程数据分析CloudQuery MySQL 目标插件类型映射全解析Apache Arrow 类型到 MySQL 数据类型的对照与源码实现CloudQuery MySQL 目标插件类型映射全解析Apache Arrow 类型到 MySQL 数据类型的对照与源码实现 导读 CloudQuery 的数据集成数据工程数据分析上一篇微信自动化新工具WeChatFerry如何让你的社交管理效率翻倍下一篇LLaMA-Factory MoE微调实战指南3种配置跑通Qwen3-30B-A3B创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考