数据集成数据工程数据分析【免费下载链接】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 的 BigQuery 目标插件destination plugin负责把任意 CloudQuery 源插件采集到的云资产与安全数据同步到 Google Cloud Platform 的 BigQuery 数据库中是构建云资产清单、CSPM 与安全分析链路的关键一环。本文将围绕 BigQuery 目标插件官方文档 展开完整讲解前置准备、鉴权方式、全部 Spec 配置参数、流式写入与批处理机制、自动建表与时间分区以及基于 Vertex AI 的文本嵌入扩展并结合当前仓库的源码实现spec.go、client.go、write.go、migrate.go 等给出可直接落地与排查问题的实战方案。插件定位与能力边界BigQuery 目标插件将来自任何 CloudQuery 源插件AWS、Azure、GCP 等 70 云与 SaaS 源的数据同步进 BigQuery 数据库。当前版本存在两条明确的能力边界配置前必须先了解仅支持流式写入模式插件目前只通过 BigQuery 的 legacy streaming APItabledata.insertAll语义写入数据适合中小规模数据集数据会直接流入 BigQuery 表。仅支持append写入模式官方文档明确说明 BigQuery 插件只支持append写模式在源码层面client.go 中batchwriter.UnimplementedDeleteStale与batchwriter.UnimplementedDeleteRecord两个未实现标记也印证了删除类操作如增量覆盖所需的 stale 清理暂不支持。批处理模式仍在开发中官方文档指出面向更大数据集的 batch 模式正在开发当前尚未支持。免费层限制Google Cloud 免费层free tier不提供流式写入能力使用该插件需要付费层项目。开始前的准备工作官方文档要求在使用前完成三步准备确保项目已启用结算billingBigQuery 需要有效的结算账户可先在 GCP 控制台确认项目 billing 状态。预先创建 BigQuery 数据集dataset需要手动创建用于存放 CloudQuery 同步表的 dataset。CloudQuery 不会创建 dataset 本身但会在首次sync触发的 migration 阶段自动创建 dataset 内部的表。确保拥有数据集的写入权限流式写入要求具备对应的数据权限详见 GCP 的 streaming data into BigQuery 权限说明。上述第 2 点可以在源码中得到进一步印证client.go 中的validateCreds在插件初始化时就会通过DatasetInProject(projectID, datasetID).Metadata(ctx)检查 dataset 是否存在若返回 404 会直接报错invalid dataset. dataset must be created before sync or migration。因此dataset 必须预先创建这是插件启动校验的一部分而不是可选项。最小配置示例完整的可运行配置见 _configuration.md其标准 YAML 如下kind: destination spec: name: bigquery path: cloudquery/bigquery registry: cloudquery version: VERSION_DESTINATION_BIGQUERY write_mode: append send_sync_summary: true # Learn more about the configuration options at https://cql.ink/bigquery_destination spec: project_id: ${PROJECT_ID} dataset_id: ${DATASET_ID} # Optional parameters # service_account_key_json: ${file:./path-to-your-file.json} # GCP service account key, can be placed in a file and referenced with this syntax. # dataset_location: # time_partitioning: none # options: none, hour, day, month, year # time_partitioning_expiration: 0h # duration, e.g. 24h or 720h (30 days) # service_account_key_json: # endpoint: # batch_size: 10000 # batch_size_bytes: 5242880 # 5 MiB # batch_timeout: 10s # client_project_id: *detect-project-id*该示例依赖两个环境变量PROJECT_ID—— Google Cloud 项目 IDDATASET_ID—— BigQuery 数据集 ID。配置中write_mode: append与插件仅支持 append 的约束一致。send_sync_summary: true表示同步完成后向目标发送同步摘要。除了环境变量CloudQuery 还支持文件变量替换语法如${file:./path-to-your-file.json}适合把服务账号密钥这类敏感内容放到单独文件中引用。认证方式插件默认通过 GCP 的Application Default CredentialsADC应用默认凭据完成鉴权完整选项见 _authentication.md。按部署环境可分为五类运行环境推荐认证方式本地开发gcloud auth application-default login官方推荐Google Cloud 云开发环境Cloud Shell / Cloud Code 已自带凭据无需额外配置Google Cloud 容器环境GKE使用 workload identity支持附加服务账号的 GCP 服务Compute Engine、App Engine、Cloud Functions 等附加用户管理的服务账号CloudQuery 可直接使用本地机房或其他云厂商首选 Workload identity federation不可用时再使用服务账号密钥并通过GOOGLE_APPLICATION_CREDENTIALS环境变量指向密钥文件官方标注不推荐长期有效密钥存在安全风险此外插件 Spec 还提供service_account_key_json字段允许直接内嵌 GCP 服务账号密钥内容从而实现GCP 源插件与 BigQuery 目标插件使用不同的服务账号。从 client.go 的源码可见当该字段非空时客户端会以option.WithAuthCredentialsJSON方式显式注入密钥校验逻辑spec.go会先用json.Unmarshal验证其是合法 JSON否则报invalid json for service_account_key_json。BigQuery Spec 完整参数详解以下是 BigQuery 目标插件的顶层 Specspec:下的全部字段与 overview.md 一致并补充了源码中可确认的默认值与校验规则必填参数project_idstring必填目标 BigQuery 数据库所在的项目 ID。在 spec.go 中标记为jsonschema:required,minLength1校验时为空会直接报project_id is required。dataset_idstring必填项目内 BigQuery 数据集的名称例如my_dataset。该 dataset 必须在运行 sync 或 migration 之前创建前面已说明插件启动校验会强制这一点。可选参数dataset_locationstring可选数据集的数据位置region设置后作为所有 job 操作的默认位置。官方 Pro-tip对刚创建的数据集这可以解决 dataset not found 类问题。源码中该值会直接赋给 BigQuery 客户端的client.Locationclient.go。time_partitioningstring可选默认none建表时使用的时间分区策略。文档列出的选项为none、hour、day从源码结构看spec.go 的TimePartitioningOptions与 schema.json 的枚举实际还支持month、year共五种取值。分区时间列固定使用_cq_sync_time因此一次 sync 运行产生的所有行都会按 sync 开始的小时/天/月/年进行分区。实现细节见 migrate.go 的timePartitioning()它将配置映射为 BigQuery 的HourPartitioningType/DayPartitioningType/MonthPartitioningType/YearPartitioningType并指定Field: schema.CqSyncTimeColumn.Name配置为none时返回 nil不分区。time_partitioning_expirationduration可选分区自动删除的时间。时长以秒、分钟或小时为单位书写例如3600s、60m、24h、720h。仅在time_partitioning设置为非none时才有效——spec.go 会在none 非零过期时间时校验报错。值为 0 表示不过期。service_account_key_jsonstring可选默认空GCP 服务账号密钥内容用于源与目标使用不同服务账号的场景见上文认证部分。endpointstring可选BigQuery API 端点主要用于对接本地模拟器emulator进行测试。源码中以option.WithEndpoint注入client.go。batch_sizeinteger可选默认10000写入多少条记录后开始新一批写入。源码常量与默认值一致spec.gobatchSize 10000schema 约束minimum1。batch_size_bytesinteger可选默认5242880即 5 MiB按 Arrow 缓冲区字节数计算的批大小阈值。源码注释给出了设计动机BigQuery 官方单次流式插入限制为 10 MB而字节估计并不精确且请求大小本身也有限制因此保守地取 5 MiBspec.go。batch_timeoutduration可选默认10s批写入的最大时间间隔即达到该时长后无论是否凑满一批都会触发写入。源码默认值同样为 10 秒spec.go。client_project_idstring可选标识 BigQuery 客户端在哪个项目上下文中执行查询默认等于project_id可设为*detect-project-id*以从环境变量或应用默认凭据自动探测项目 ID。该字段虽未出现在 overview.md 的参数列表中但已被 spec.go 与 _configuration.md 支持可用于让查询如文本嵌入生成的 SQL运行在与目标表所在项目不同的项目中。其中batch_size、batch_size_bytes、batch_timeout三个参数会通过batchwriter.New传给插件 SDK 的批处理写入器client.go共同控制“记录数 字节数 时间”三种触发条件的批处理行为。流式写入与批处理机制写入路径的入口是 write.go 的WriteTableBatch其核心链路为通过DatasetInProject(...).Table(name).Inserter()获取目标表的流式插入器并设置IgnoreUnknownValues true、SkipInvalidRows false将每条 Arrow 记录按行拆解为item{Cols: map[string]bigquery.Value}其中nil 值会被直接跳过不发送源码注释为节省带宽不发送 null 值调用inserter.Put进行流式写入并带有 5 分钟超时writeTimeout写入失败时针对两类错误做特殊处理404表尚未创建说明表还在创建过程中每秒重试一次直到表可见配合 migration 后的等待逻辑避免“写得太早”数据过大entity too large将批数据序列化为错误信息的一部分返回提示开发者检查 BigQuery 流式插入配额限制。从类型转换逻辑write.go可以看到Arrow 的 Struct 会映射为 BigQuery 的RECORDmapMap 与 JSON 序列化为字符串List 类列映射为 repeated 列Timestamp 转为对应时间。同时源码明确标注了一个已知限制BigQuery 的 repeated 列不支持 null 值所以列表中的 null 元素会被剔除这也是 types.md 中“列表不支持嵌套列表”等注意事项的底层原因。值得强调的是虽然插件通过 SDK 的 BatchWriter 做了“批”的聚合但最终落库仍然是 BigQuery legacy streaming API 的逐批插入与普通批处理写入文件装载等有本质区别这也是“适合中小规模数据集”说法的来源。表迁移自动建表与 Schema 演进首次sync时的 migration 阶段会自动创建目标表相关实现集中在 migrate.go。其行为特征如下并发迁移最多 10 个表并发迁移concurrentMigrations 10。表不存在则创建createTable使用bigquery.TableMetadata创建表带上表描述、完整 Schema 以及根据time_partitioning生成的分区配置。表已存在则自动迁移autoMigrateTable会获取现有表的 Schema并与期望 Schema 做mergemergeSchemas保留已有字段除非类型变更或必填列被删除并追加新字段从而避免丢失已有数据若某列类型发生变化会明确报错提示“Try dropping the column and re-running”。一致性等待建表或 Schema 更新后会以 6 秒为间隔轮询最多 20 次确认表已可见/Schema 已匹配其中 Schema 匹配检查要求连续 3 次结果一致以规避 BigQuery 不同后端节点响应不一致的问题确保后续写入不会因表尚未就绪而失败。表描述长度截断描述超过 16384 字符时会被截断maxDescriptionLength。文本嵌入Text Embeddings扩展BigQuery 插件支持通过 Vertex AI 模型为指定表生成文本嵌入配置结构见 overview.md 的text_embeddings对象源码定义位于 spec.go完整 JSON Schema 见 schema.json。启用该功能前必须先在 dataset 上挂载一个远程模型remote model并在配置中提供其名称。spec: project_id: ${PROJECT_ID} dataset_id: ${DATASET_ID} text_embeddings: remote_model_name: your_remote_model_name tables: - source_table_name: source_table target_table_name: embeddings_table embed_columns: [content_column_1, content_column_2] metadata_columns: [id, created_at] text_splitter: recursive_text: chunk_size: 1000 # 默认 1000字符数 chunk_overlap: 100 # 默认 100字符数顶层字段remote_model_namestring必填用于生成嵌入的远程模型名称。校验时为空会报错。tablesarray必填需要生成嵌入的表列表每个表有独立配置source_table_namestring必填要生成嵌入的源表名target_table_namestring必填存放嵌入结果的目标表名embed_columnsarray必填作为嵌入生成函数输入内容的列会按提供顺序拼接源码中用|| \n ||以换行符连接见 embeddings_write.gometadata_columnsarray可选从源表原样复制到目标表的列_cq_id始终会被自动加入——spec.go 的SetDefaults会为每个表的 metadata 列补上_cq_id。text_splitterobject可选文本切分配置目前仅支持recursive_textrecursive_text.chunk_sizeinteger必填默认1000文本块的字符大小按字符而非 token 计recursive_text.chunk_overlapinteger必填默认100相邻块之间的字符重叠量。校验要求chunk_overlap chunk_sizespec.go。底层实现原理嵌入功能的实际执行位于 embeddings_write.go 与 embeddings_migrate.go首次写入时ConcreteEmbeddingsClient.MigrateTables会为每个target_table_name创建目标表表结构为chunk_idINT64、chunk_textSTRING、embeddingFLOAT64 repeated加上所选 metadata 列并复用主客户端的时间分区配置每次写入源表批次后从 Arrow 记录中提取该批次的_cq_id列表动态拼装一条 SQL先用GENERATE_ARRAY与SUBSTR按chunk_size/chunk_overlap把文本切成块再调用ML.GENERATE_EMBEDDING(MODEL ...)生成嵌入最后INSERT INTO目标表若配置中未设置text_embeddingsembeddings_client.go 会返回NoOpEmbeddingsClient写入路径零开销。类型映射BigQuery 目标插件v3.0.0 及以后支持大多数 Apache Arrow 类型完整映射关系见 types.md。核心对应关系包括Arrow 类型是否支持BigQuery 类型Binary / Large Binary✅BYTESBoolean✅BOOLDate32 / Date64✅DATEDecimal✅BIGNUMERICDuration✅INT64Float16 / Float32 / Float64✅FLOAT64Int8~Int64 / Uint8~Uint32✅INT64Uint64✅NUMERICJSON✅JSONList / Large List / Fixed Size List✅repeated 列见下方注意事项 †Map / Dictionary / Union / Dense Union❌不支持String / Large String / Inet / MAC / UUID✅STRINGStruct✅RECORDTimestamp✅TIMESTAMPInterval[DayTime] / MonthDayNano / Month✅对应的RECORD...复合结构注意事项†BigQuery 的 repeated 列不支持 null 值因此数组中的 null 元素在写入时会被丢弃同时由于使用REPEATED列表示列表列表嵌套列表lists of lists目前不支持。底层依赖库插件使用 Google 官方 Go 客户端cloud.google.com/go/bigquery包建立数据库连接client.go。连接建立时会附加自定义 User-AgentCloudQuery_BigQuery_Destination/version (GPN:CloudQuery)与请求原因标记并按需注入服务账号密钥、自定义 endpoint 与 dataset location。整体流程为解析 Spec →SetDefaults()填充默认值 →Validate()校验 → 创建批处理写入器 → 建立 BigQuery 客户端 → 校验 dataset 存在性与凭据 → 按需初始化嵌入客户端。TestConnectionclient.go则提供了不建客户端即可验证配置连通性的路径可用于cloudquery test-connection命令的配置预检。小结BigQuery 目标插件以流式写入 append 模式为核心配合 SDK 级批处理、自动建表迁移、时间分区与 Vertex AI 文本嵌入能力适合把 CloudQuery 各源插件的数据持续汇入 BigQuery 进行安全与云资产管理分析。配置的关键要点可归纳为预先创建 dataset、正确配置 ADC 或服务账号密钥、按数据规模调整batch_size/batch_size_bytes/batch_timeout三项批参数并在需要成本治理或增量查询时使用time_partitioning与time_partitioning_expiration。更多细节可直接参考仓库内的 overview.md、_configuration.md、_authentication.md 与 types.md以及 spec.go、client.go、write.go、migrate.go 等实现文件。赞分享数据集成数据工程数据分析【免费下载链接】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点击查看免费下载相关推荐国家中小学智慧教育平台电子课本怎么免费下载成 PDFtchMaterial-parser 三分钟上手国家中小学智慧教育平台电子课本怎么免费下载成 PDFtchMaterial parser 三分钟上手 如果你需要把国家中小学智慧教育平台上的电子课本拿到离线用网页爬虫教育CloudQuery BigQuery 目标插件认证指南基于 ADC 的多环境凭据配置CloudQuery BigQuery 目标插件认证指南基于 ADC 的多环境凭据配置 本指南以 CloudQuery 仓库中 BigQuery 目标插件数据集成数据工程数据分析Tabby备份和同步配置文件和插件迁移指南Tabby备份和同步配置文件和插件迁移指南 你是否曾遇到更换设备后需要重新配置Tabby终端的烦恼本文将详细介绍如何备份、迁移和同步Tabby的配置文件与插桌面应用网络通信上一篇SBEMU与DOSBox对比谁才是复古游戏音频模拟之王下一篇XManager如何用Google DeepMind的机器学习实验管理框架提升研究效率创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考