ToolJet 接入 Google BigQuery 数据源全指南服务账号认证、连接配置与九大数据操作实战【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetToolJet 是开源的内部工具与低代码应用搭建平台其内置数据源插件体系允许用户以可视化方式直连各类数据库与服务。本文聚焦 BigQuery 数据源接入文档完整讲解如何在 ToolJet 中创建 Google BigQuery 数据源连接、通过服务账号私钥完成认证并系统梳理 Query、List Datasets、List Tables、Insert/Delete/Update Record、Create/Delete Table、Create View 等操作的参数含义与底层行为。读完本文你将能够独立在 ToolJet 中完成 BigQuery 的建连、查询调试以及日常的数据读写与表/视图管理。一、数据源概览与工作原理BigQuery 是 Google Cloud 的云数据仓库服务ToolJet 通过google-cloud/bigqueryNode.js 客户端与其 REST API 交互。该功能的完整实现位于仓库插件目录 plugins/packages/bigquery其中lib/index.ts实现QueryService接口的核心逻辑负责建连、鉴权与各操作分发lib/manifest.json定义数据源连接表单的字段、认证方式与默认值lib/operations.json定义查询编辑器里可选的运行模式SQL 模式 / GUI 模式及各操作所需的输入控件。从 manifest.json 可以看出BigQuery 数据源支持两种认证类型认证类型说明适用场景Service Account粘贴服务账号 JSON 私钥代码内直接解析出project_id、client_email、private_key并构造 BigQuery 客户端官方文档推荐的常规连接方式自托管与云端均可用OAuth 2.0走 Google OAuth 授权码流程换取 access/refresh token需要按用户维度的委托授权时使用其中private_key与client_secret在 manifest.json 中被标记为encrypted: true意味着这些敏感字段在入库时会以加密形式保存读取后由服务端解密使用避免明文落库。二、连接 BigQuery获取并配置服务账号私钥2.1 获取 Private key 的四个步骤ToolJet 要求用户提供 Google 服务账号的 JSON 私钥文件内容。在 ToolJet 中新增 BigQuery 数据源有两种入口点击查询面板上的 Add new Data source按钮或从 ToolJet 首页进入Data Sources页面后选择 BigQuery。拿到私钥的完整流程如下在 Google Cloud Console 中启用 BigQuery API创建服务账号Service AccountToolJet 连接本身只需读取私钥 JSON通常建议按最小权限原则给服务账号授予该数据源任务所需的 BigQuery 角色为服务账号创建新的Key格式选择 JSON 并下载到本地打开下载的 JSON 文件将文件全部内容原样复制粘贴到 ToolJet BigQuery 数据源表单的Private key字段中。2.2 私钥 JSON 的标准结构下载的服务账号私钥文件应具备如下结构字段内容由 Google Cloud 生成各账号不同{ type: service_account, project_id: long-sonar-324407, private_key_id: 63f4415e600bd7879bc14fd1157a4aabe227c204, private_key: -----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDRGgDmfwYcKp4q\n...\n-----END PRIVATE KEY-----\n, client_email: tooljettestlong-sonar-324407.iam.gserviceaccount.com, client_id: 103664451567222591066, auth_uri: https://accounts.google.com/o/oauth2/auth, token_uri: https://oauth2.googleapis.com/token, auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs, client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/tooljettest%40long-sonar-324407.iam.gserviceaccount.com, universe_domain: googleapis.com }从 index.ts 的实现可以看到该 JSON 经parseJSON解析后只会提取三个关键字段用于构造 BigQuery 客户端——project_id、client_email与private_key其余字段如token_uri、client_x509_cert_url等是 Google 服务账号的标准元数据用于 OAuth/证书发现流程ToolJet 本身并不直接依赖。因此无需手工填写 Project ID 或注册邮箱全部由私钥内容自动推导。2.3 服务账号连接的可选配置项除private_key外服务账号认证方式下还有两个可选项定义于 manifest.jsonScope作用域可选字段填写空格分隔的 Google API scope 列表。留空时使用google-cloud/bigquery的默认 scope填写后则透传给 BigQuery 客户端scopes数组。代码中按空白字符拆分后过滤空串。Region区域数据集所在地理位置用于定位存储在不同区域的数据集留空则使用默认值。表单下拉框提供了完整选项包括多区域US、EU以及全球各单区域例如us-central1Iowa、us-east1South Carolina、us-west1Oregon、europe-west1Belgium、europe-west4Netherlands、asia-east1Taiwan、asia-southeast1Singapore、australia-southeast1Sydney、southamerica-east1São Paulo等。该值最终会作为location传入 BigQuery 客户端。2.4 另一种认证方式OAuth 2.0除服务账号外ToolJet 的 BigQuery 插件还支持 OAuth 2.0 授权码认证默认认证类型即oauth2见 manifest.json 中的 defaults。连接表单在认证类型下拉中选择OAuth 2.0后需要配置Access typeRead only或Read and Write。代码 authUrl() 会据此挑选 scope——只读对应bigquery.readonly读写对应bigquery并固定追加cloud-platform.read-only。Project IDGoogle Cloud 项目 ID此时需要显式填写OAuth 模式下无法从私钥推导。Region与上述服务账号的区域选项一致。OAuth 应用凭证在client_id/client_secret字段中填入你在 Google Cloud 创建的 OAuth Client ID 与 Secret。若部署在 ToolJet Cloud 环境还可选择tooljet_app类型的托管 OAuth复用 ToolJet 自身的GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET环境变量自托管版本则必须使用custom_app自建 OAuth 应用。回调地址固定为${TOOLJET_HOST}${SUB_PATH}/oauth2/authorize。OAuth 模式下插件通过 accessDetailsFrom() 兑换令牌、refreshToken() 负责过期刷新并支持multiple_auth_enabled多用户授权可让每个终端用户用自己的 Google 身份访问 BigQuery。三、底层建连与连接测试机制3.1 连接建立与缓存插件以统一入口 getConnection() 获取 BigQuery 客户端先对数据源配置计算哈希再依据dataSourceId与配置哈希生成缓存键命中缓存则直接复用已有客户端未命中则调用buildConnection()重建后写回缓存并以dataSourceUpdatedAt作为缓存失效依据保证数据源配置更新后连接自动重建。3.2 连接测试逻辑新建数据源时 ToolJet 会触发 testConnection()其判定逻辑与认证方式强相关服务账号直接尝试调用client.getDatasets()能成功枚举数据集即认为连接有效OAuth调用 Google 的tokeninfo接口校验当前 access token 是否仍然有效。因此一个常见排查技巧是连接测试失败时先确认私钥/令牌对应服务账号是否具备 BigQuery 数据集的访问权限而不只是格式是否正确。四、查询工作流SQL 模式与 GUI 模式创建好 BigQuery 数据源后按以下步骤在应用编辑器中发起查询点击编辑器底部查询管理器的 Add按钮数据源下拉框中选择上一步添加的BigQuery数据源选择运行模式与目标操作填写所需参数点击Preview按钮预览输出或点击Run按钮真正触发查询。根据 operations.jsonBigQuery 查询支持两种运行模式SQL modeSQL 模式直接编写 BigQuery 标准 SQL适合复杂查询GUI modeGUI 模式通过下拉框选择预置操作并填表完成适合日常简单数据维护。:::tip 查询返回的结果可在 ToolJet 中使用**转换Transformations**做二次加工例如重命名字段、过滤或聚合数据具体写法参见 Transformations 使用文档。 :::五、SQL 模式详解参数与高级选项SQL 模式的输入项定义在 operations.json输入项说明界面占位示例Query要执行的 BigQuery SQL支持参数名形式的命名占位符SELECT name FROM bigquery-public-data.usa_names.usa_1910_2013 WHERE state state LIMIT 100SQL Parameters以键值对方式添加参数在 SQL 中用 parameter_name 引用state→CAQuery options提交给createQueryJob的任务级选项JSON 对象{ location: US, dryRun: true }Query results options传给getQueryResults的结果读取选项JSON 对象{ wrapIntegers: true }其底层执行逻辑位于 executeSqlMode()关键实现细节如下通过client.createQueryJob()创建查询任务queryOptions会被解析后与query合并作为任务选项可借此指定location、dryRun等若填写了查询参数会转换为命名参数对象params传入任务。由于界面参数以字符串接收插件先经 coerceParam() 尝试JSON.parse还原出数字、布尔等原始类型避免把30当字符串30传给 BigQuery 造成类型不匹配任务执行完成后用job.getQueryResults()拉取结果同样透传queryResultsOptions。此外queryOptions与queryResultsOptions两处 JSON 都经由 parseJSON() 使用JSON5解析因此允许写不带引号的键名、尾随逗号甚至注释表单书写更宽松。六、GUI 模式九大内置操作逐项说明GUI 模式下操作下拉框提供的选项覆盖原文档列出的全部操作另有部分进阶操作各操作的使用细节如下。6.1 Query查询按输入框中的 SQL 返回结果。需要填写Query、Query options与Query results options三类参数与 SQL 模式的字段含义完全一致从实现看 Query 操作与 SQL 模式的执行路径相同均经createQueryJobgetQueryResults完成见 index.ts。此类数据库操作的行为以 Google Cloud 官方的 Job 与 QueryResults 参数定义为准。6.2 List Datasets列出数据集返回账号有权访问的全部数据集列表。无需额外参数内部直接调用client.getDatasets()并对响应做裁剪仅保留metadata.datasetReference以减小体积index.ts。6.3 List Tables列出数据表返回指定数据集下的全部数据表。必需参数Dataset ID。界面中 Dataset ID 为联动下拉框可自动拉取当前数据源的数据集供选择。6.4 Create Table创建数据表用于在数据集中创建新表。必需参数Table ID新表名称Dataset ID目标数据集Options建表配置 JSON核心是schema数组。内部执行client.dataset(datasetId).createTable(tableId, options)index.ts。界面中 Options 的占位示例展示了 schema 的标准写法{ schema: [ { name: Name, type: STRING, mode: REQUIRED }, { name: Age, type: INTEGER } ], location: US }schema 中每个字段支持name、type如 STRING、INTEGER、FLOAT、BOOLEAN、TIMESTAMP、RECORD 等以及可选的modeREQUIRED / NULLABLE / REPEATED。返回结果为新建表的tableId。6.5 Delete Table删除数据表从指定数据集删除整张表。必需参数Table ID、Dataset ID。内部调用client.dataset(datasetId).table(tableId).delete()成功后返回Table tableId deleted.提示文本。该操作不可恢复请谨慎使用。6.6 Create View创建视图基于现有表创建 BigQuery 视图虚拟表。必需参数参数说明Table ID数据来源表Dataset ID表所在数据集View name新视图名称View columns视图中要包含的列逗号分隔ConditionWHERE 过滤条件例如CustomerNameAlfreds FutterkisteQuery options / Query results options任务级与结果级选项该操作并非直接调用视图 API而是在后端拼接一条CREATE VIEWSQL 执行index.tsCREATE VIEW DatasetID.View name AS SELECT View columns FROM DatasetID.TableID WHERE Condition -- 未填写 Condition 时使用 WHERE TRUE6.7 Insert Record插入记录向表中插入一行或多行记录。必需参数Table ID、Dataset ID、Rows。Rows 需为对象数组界面占位示例[ { name: Tom, age: 30 }, { name: Jane, age: 32 } ]实现上调用table.insert(rows)流式插入index.ts返回响应对象并附带records计数字段标明实际插入的行数。6.8 Delete Record删除记录按条件删除表中的记录。必需参数Table ID、Dataset ID、Condition、Query options、Query results options。底层拼接DELETE语句后以查询任务执行index.tsDELETE FROM DatasetID.TableID WHERE Condition:::warning 执行删除记录前务必小心。若 Condition 留空代码会退化为WHERE TRUE将删除整张表的全部数据。建议先在 Preview 中核对条件结果或始终显式填写带主键/唯一键的精确过滤条件。 :::6.9 Update Record更新记录按条件更新表中指定列的值。必需参数Table ID、Dataset ID、Columns、Condition、Query results options。Columns 需传入“列名 → 新值”的对象界面占位示例为{{({name:bob,age:30})}}。插件通过 columnBuilder() 将其转换为SET子句字符串值自动加单引号再拼接UPDATE语句执行index.tsUPDATE DatasetID.TableID SET namebob,age30 WHERE Condition -- 留空同样会退化为 WHERE TRUE作用到全表与 Delete Record 一致Condition 未填写时同样作用于全表更新前务必确认条件。七、进阶能力批量操作与数据集信息当前版本的插件除上述九种操作外operations.json 还注册了四个进阶操作可显著提升大批量数据维护的效率均在 index.ts 中实现操作参数底层实现Bulk insert批量插入Dataset ID、Table ID、Records接收对象数组后一次table.insert(records)返回插入数量Bulk update using primary key按主键批量更新Dataset ID、Table ID、Primary key column(s)、Records基于主键列拼接MERGE语句命中则执行UPDATE SETBulk upsert using primary key按主键批量 upsert同上基于主键列拼接 MERGE 语句命中更新、未命中则INSERTGet Dataset Info获取数据集信息Dataset ID调用dataset.getMetadata()并裁剪出 datasetReference、location、creationTime 等核心元数据其中批量更新/upsert 通过 buildMergeQuery() 动态生成 BigQuery 的MERGE ... USING UNNEST([STRUCT(...), ...]) ...语句每条记录被编码为一个STRUCT主键列作为匹配依据支持复合主键数组字符串、数字、布尔、NULL 等类型由 bqLiteral() 统一做字面量转义防止 SQL 注入。这些操作非常适合配合 ToolJet 表格组件做大批量同步。八、错误处理与排查指引从源码可以提炼几条实用的排查路径OAuth 场景下的 401/403run、SQL 模式与各 GUI 操作的 catch 分支都会检测非服务账号场景下的 401/403 状态码抛出OAuthUnauthorizedClientError见 index.tsUI 上会提示重新授权。若遇此类报错优先重新走一遍 OAuth 授权流程刷新令牌。服务账号凭据错误私钥 JSON 解析失败或缺少权限时testConnection阶段即会失败若查询阶段才暴露错误信息中会尽量携带服务端返回的reason、message与jobId可据此在 Google Cloud Console 的 BigQuery 作业历史中定位对应任务。未配置 OAuth 环境变量选用tooljet_app托管 OAuth 但服务端未设置GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET时会抛出“You need to define Google OAuth environment variables”。删除/更新类操作影响面过大返回行数与预期不符时检查是否因 Condition 留空退化为WHERE TRUE而全表生效这也是两类操作中最常见的事故来源。九、相关代码与文档索引若希望深入插件实现细节或在此基础上二次开发可按以下路径继续阅读数据源官方使用文档docs/docs/data-sources/bigquery.md、数据源总览结果转换Transformations文档docs/docs/tutorial/transformations.md插件核心实现plugins/packages/bigquery/lib/index.ts建连、鉴权、SQL/GUI 操作分发、错误处理连接表单与认证定义plugins/packages/bigquery/lib/manifest.json查询界面控件定义plugins/packages/bigquery/lib/operations.json类型定义plugins/packages/bigquery/lib/types.ts插件元数据示例可参照新增数据源插件的结构marketplace/plugins/_templates/plugin简而言之服务账号私钥认证是接入 BigQuery 成本最低的路径——在 Google Cloud 创建服务账号并下载 JSON 私钥粘贴到 Private key 字段即可完成连接日常使用中简单读写走 GUI 操作模式、复杂分析切到 SQL 模式并善用命名参数涉及大批量同步时再启用批量插入/更新/upsert 操作即可在 ToolJet 中把 BigQuery 数据完整地用起来。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考