BigQuery 客户端库连接实战skills 仓库 bigquery-basics 技能中 client-library-usage 参考文档全解【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文以 skills 仓库Agent Skills for Google products and technologies中bigquery-basics技能的参考文档 client-library-usage.md 为主体系统讲解如何通过 Google Cloud 官方客户端库用 Python、Java、Node.jsTypeScript、Go 四种语言连接 BigQuery 并执行 SQL 查询并结合仓库内的 SKILL.md、iam-security.md 与姊妹技能 bigquery-bigframes/SKILL.md补充资源准备、鉴权上下文与 BigQuery DataFramesBigFrames的进阶用法。读完本文你可以为任意主流语言项目接入 BigQuery并知道何时应改用 BigFrames 或 CLI。客户端库在 BigQuery 访问方式中的定位bigquery-basics技能将访问 BigQuery 的方式分为多条路径参考目录中明确列出了各自适用的文档见 SKILL.md 的 Reference Directory 一节CLIbq命令见 cli-usage.md适合交互式管理数据集、表、作业例如bq mk --dataset --locationus my_dataset或bq query --use_legacy_sqlfalse ...客户端库本文主题见 client-library-usage.md提供以惯用idiomatic方式与你首选编程语言交互的 BigQuery 途径适合把 BigQuery 查询嵌入应用代码、ETL 作业与后台服务MCP 远程服务器见 mcp-usage.md面向 Agent 自动执行execute_sql仅允许SELECT是客户端库之外供 LLM/Agent 使用的访问面。选择客户端库的典型场景你的程序需要在运行时执行 SQL、处理返回的行数据并跟随代码库做版本管理。文档给出的四个语言示例都围绕同一件事——发起一条SELECT查询并读取结果——这正是所有客户端库用法的公共骨架。前提安装并登录 Google Cloud SDK原文档 Getting Started 一节的要求非常明确To use the client libraries, ensure you have the Google Cloud SDK installed and authenticated.即使用任何语言的客户端库之前先安装 Google Cloud SDK安装方式参见 Google Cloud SDK 官方安装文档并完成身份认证。客户端库会依赖当前登录身份或环境变量中提供的凭据来发起请求。这一点与仓库中 iam-security.md 的鉴权描述一致该文档指出 BigQuery 内部由托管服务账号bq-PROJECT_NUMBERbigquery-encryption.iam.gserviceaccount.com或通用 BigQuery Service Agentservice-PROJECT_NUMBERgcp-sa-bigquery.iam.gserviceaccount.com承担内部操作而应用侧则应遵循最小权限原则——只授予执行特定操作所需的权限在尽可能细如表/视图级的粒度上使用权限最少的 IAM 角色。需要临时切换凭据时该文档给出的做法是使用gcloud config set auth/impersonate_service_account做服务账号模拟。写代码前先备好资源启用 API 与创建数据集/表bigquery-basics技能的 SKILL.md 在 Setup and Basic Usage 一节给出了客户端库示例真正能跑起来所需的前置资源建议按顺序执行启用 BigQuery APIgcloud services enable bigquery.googleapis.com --quiet创建数据集bq mk --dataset --locationUS my_dataset创建表先准备schema.json列定义含name/type/modemode可取REQUIRED、NULLABLE[ { name: name, type: STRING, mode: REQUIRED }, { name: post_abbr, type: STRING, mode: NULLABLE } ]再用bq建表bq mk --table my_dataset.mytable schema.json验证连通性CLI 侧bq query --use_legacy_sqlfalse \ SELECT name FROM bigquery-public-data.usa_names.usa_1910_2013 \ WHERE state TX LIMIT 10其中--use_legacy_sqlfalse表示使用标准 SQLGoogleSQL方言这一点在后续各语言的客户端库查询中同样适用。完成以上准备后各语言示例中的project.dataset.table引用才有真实对象可查。Pythongoogle-cloud-bigquery原文档给出的 Python 部分包含安装命令与最小查询示例完整继承如下。安装pip install --upgrade google-cloud-bigquery使用示例from google.cloud import bigquery client bigquery.Client() query_job client.query(SELECT * FROM project.dataset.table LIMIT 10) results query_job.result()逐行解读这段代码的语义依据文档示例本身bigquery.Client()无参构造客户端从当前环境的默认凭据解析项目与鉴权信息client.query(...)提交 SQL 并立即返回一个query job 对象query_job说明查询是以异步作业方式提交的query_job.result()阻塞等待作业完成并返回可迭代的行集合results。注意示例中表引用使用了反引号包裹的全限定名project.dataset.table——这是 GoogleSQL 的标准写法与 cli-usage.md 中bq query示例的my_project.my_dataset.my_table保持一致。跨项目查询公共数据集时project位置填目标项目 ID如bigquery-public-data。此外iam-security.md 提醒BigQuery 支持列级安全policy tags、行级安全行访问策略、数据脱敏与审计日志等治理能力。若你的客户端库代码运行在服务账号下请确保该账号只被授予查询目标表所需的最小角色。JavaMaven 依赖与 BigQueryOptions原文档的 Java 部分如下。Maven 依赖dependency groupIdcom.google.cloud/groupId artifactIdgoogle-cloud-bigquery/artifactId /dependency使用示例BigQuery bigquery BigQueryOptions.getDefaultInstance().getService(); QueryJobConfiguration queryConfig QueryJobConfiguration.newBuilder( SELECT * FROM dataset.table).build(); TableResult results bigquery.query(queryConfig);从示例结构可以看出 Java 客户端库的调用链BigQueryOptions.getDefaultInstance()从默认配置解析出连接选项.getService()取得BigQuery服务句柄SQL 被封装进不可变的QueryJobConfiguration随后bigquery.query(queryConfig)同步执行并返回TableResult可直接遍历其中的行。与 Python 版本先拿 job、再取 result的两段式不同这个示例呈现的是同步一次性获取结果的用法。Node.jsTypeScriptgoogle-cloud/bigquery原文档的 Node.js 部分如下。安装npm install google-cloud/bigquery使用示例import {BigQuery} from google-cloud/bigquery; const bigquery new BigQuery(); const [rows] await bigquery.query(SELECT * FROM dataset.table);要点构造new BigQuery()同样无需显式传项目参数依赖环境默认凭据bigquery.query(...)返回 Promiseawait之后的结果是一个数组第一个元素即行数组rows示例用解构const [rows] ...直接取出行数据该示例面向 TypeScript/ES 模块写法import语句可直接用于.ts工程。Gocloud.google.com/go/bigquery原文档的 Go 部分如下。安装go get cloud.google.com/go/bigquery使用示例ctx : context.Background() client, _ : bigquery.NewClient(ctx, project-id) q : client.Query(SELECT * FROM dataset.table) it, _ : q.Read(ctx)要点与注意事项Go 版本是四个语言中唯一要求显式传入项目 ID的bigquery.NewClient(ctx, project-id)并且所有操作都以context.Context作为第一个参数贯穿创建客户端、读取结果均是如此这符合 Go 标准库对取消/超时的通行约定client.Query(...)返回查询对象q再经q.Read(ctx)拿到行迭代器it同样是提交—迭代两段式示例中的两个_是教学性简化真实代码不应忽略NewClient与Read返回的错误建议在封装层对这两处做显式错误处理后再使用迭代器。四种语言速查对比语言包 / 依赖安装方式项目参数结果获取方式Pythongoogle-cloud-bigquerypip install --upgrade google-cloud-bigquery默认凭据解析client.query()返回 jobjob.result()取行Javacom.google.cloud:google-cloud-bigqueryMaven添加dependencyBigQueryOptions.getDefaultInstance()bigquery.query(config)同步返回TableResultNode.js (TS)google-cloud/bigquerynpm install google-cloud/bigquery默认凭据解析await bigquery.query()解构首元素为rowsGocloud.google.com/go/bigquerygo get cloud.google.com/go/bigquery构造时显式传project-idclient.Query()q.Read(ctx)迭代器四种示例的 SQL 均为最简单的SELECT * FROM ...实际使用时请替换为带反引号全限定表引用的 GoogleSQL 语句如SELECT * FROM project.dataset.table LIMIT 10并可参考 cli-usage.md 中的--dry_run思路用先估成本再执行的习惯控制按扫描字节计费的开销计费模型见 core-concepts.md按字节计费的 On-demand 或按预留槽位的 Capacity/Reservations 两类。Agent 场景下的一条约束如果你的客户端库代码是由 Agent 依据本技能生成的SKILL.md 的 Attribution 一节有一条明确的Constraint for Generated Code终端里直接执行的gcloud命令需带CLOUDSDK_METRICS_REQUEST_ATTRIBUTIONagent-skills/1.0 (skill:bigquery-basics)前缀以便用量归因但这段跟踪前缀只属于 Agent 自己执行的终端命令不得写入生成给用户的脚本、Terraform 模板或代码仓库。同理上节各语言示例应原样交付不带任何归因标记。BigQuery DataFramesBigFramesPython 用户的 pandas 风格替代原文档在末尾单独给出了 BigFrames 段落For Python users,bigframesprovides a pandas-like API that executes directly in BigQuery.pip install --upgrade bigframes即对 Python 用户而言bigframes提供 pandas 风格 API且计算直接在 BigQuery 内执行而不是把数据拉到本地。仓库中专门有一个姊妹技能 bigquery-bigframes其 SKILL.md 明确说明BigFrames 用于基于熟悉的 Python API 做 pandas 风格 DataFrame/ML 工作SQL 优先或google-cloud-bigquery客户端库的工作流应使用bigquery-basics可以据此对 BigFrames 的实战要点做如下扩充保持在云端计算用 BigFrames 方法做清洗、转换与分析利用 BigQuery 的规模优势而非下载数据开启 partial ordering 模式导入后立即设置bpd.options.bigquery.ordering_mode partial放宽行序约束以显著提速用peek(n)代替head(n)预览peek(n)随机抽样n行、速度更快head(n)要求严格行序在partial模式下未显式排序前会失败避免本地物化to_pandas()会把全部数据下载到客户端内存绕过分布式计算并可能触发 OOM仅在数据足够小或报错明确要求时才使用优先 DataFrame API 而非原始 SQL能用 DataFrame/Series 方法就不要用read_gbq()写裸 SQL否则会打断 pandas 抽象、失去惰性执行用内置访问器代替 UDF/lambda例如字符串操作用df.col.str.*、时间操作用df.col.dt.*Series.map()/DataFrame.apply()不接受未加udf/remote_function装饰器的函数ML 训练走bigframes.bigquery.ml标准 Scikit-learn 需要把数据拉回本地而bigframes.bigquery.ml把训练直接委托给 BigQuery 的可扩展 ML 引擎线性回归、逻辑回归的参考实现见 linear_regression.md 与 logistic_regression.md。选型建议依据两个技能文档的分工描述以 SQL 查询为中心、需要精细控制作业参数时用google-cloud-bigquery客户端库以 pandas 工作流为中心、数据量大到不宜落盘时用 BigFrames。相关文档与延伸阅读围绕本文主题skills 仓库中以下文件可直接对照阅读client-library-usage.md本文主体四种语言客户端库与 BigFrames 入门SKILL.mdbigquery-basics技能入口含 API 启用、数据集/表创建等前置操作与参考目录索引cli-usage.mdbq命令的数据集/表/作业管理与查询含--dry_run成本预估core-concepts.mdBigQuery 架构计算与存储分离、资源层级与分析工作流是理解客户端库查表对象模型的基础iam-security.md最小权限原则、服务账号模拟与数据治理手段列/行级安全、脱敏、审计日志mcp-usage.md面向 Agent 的远程 MCP 工具list_dataset_ids、execute_sql等bigquery-bigframes/SKILL.mdBigFrames 的 DataFrame API 最佳实践与 ML 用法。以上文档共同构成了从装 SDK、建资源、写代码、控权限到Agent 接入的完整链路本文聚焦其中的客户端库一环其余环节可按对应文档深入。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 BigQuery 客户端库连接实战：skills 仓库 bigquery-basics 技能中 client-library-usage 参考文档全解
BigQuery 客户端库连接实战skills 仓库 bigquery-basics 技能中 client-library-usage 参考文档全解【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文以 skills 仓库Agent Skills for Google products and technologies中bigquery-basics技能的参考文档 client-library-usage.md 为主体系统讲解如何通过 Google Cloud 官方客户端库用 Python、Java、Node.jsTypeScript、Go 四种语言连接 BigQuery 并执行 SQL 查询并结合仓库内的 SKILL.md、iam-security.md 与姊妹技能 bigquery-bigframes/SKILL.md补充资源准备、鉴权上下文与 BigQuery DataFramesBigFrames的进阶用法。读完本文你可以为任意主流语言项目接入 BigQuery并知道何时应改用 BigFrames 或 CLI。客户端库在 BigQuery 访问方式中的定位bigquery-basics技能将访问 BigQuery 的方式分为多条路径参考目录中明确列出了各自适用的文档见 SKILL.md 的 Reference Directory 一节CLIbq命令见 cli-usage.md适合交互式管理数据集、表、作业例如bq mk --dataset --locationus my_dataset或bq query --use_legacy_sqlfalse ...客户端库本文主题见 client-library-usage.md提供以惯用idiomatic方式与你首选编程语言交互的 BigQuery 途径适合把 BigQuery 查询嵌入应用代码、ETL 作业与后台服务MCP 远程服务器见 mcp-usage.md面向 Agent 自动执行execute_sql仅允许SELECT是客户端库之外供 LLM/Agent 使用的访问面。选择客户端库的典型场景你的程序需要在运行时执行 SQL、处理返回的行数据并跟随代码库做版本管理。文档给出的四个语言示例都围绕同一件事——发起一条SELECT查询并读取结果——这正是所有客户端库用法的公共骨架。前提安装并登录 Google Cloud SDK原文档 Getting Started 一节的要求非常明确To use the client libraries, ensure you have the Google Cloud SDK installed and authenticated.即使用任何语言的客户端库之前先安装 Google Cloud SDK安装方式参见 Google Cloud SDK 官方安装文档并完成身份认证。客户端库会依赖当前登录身份或环境变量中提供的凭据来发起请求。这一点与仓库中 iam-security.md 的鉴权描述一致该文档指出 BigQuery 内部由托管服务账号bq-PROJECT_NUMBERbigquery-encryption.iam.gserviceaccount.com或通用 BigQuery Service Agentservice-PROJECT_NUMBERgcp-sa-bigquery.iam.gserviceaccount.com承担内部操作而应用侧则应遵循最小权限原则——只授予执行特定操作所需的权限在尽可能细如表/视图级的粒度上使用权限最少的 IAM 角色。需要临时切换凭据时该文档给出的做法是使用gcloud config set auth/impersonate_service_account做服务账号模拟。写代码前先备好资源启用 API 与创建数据集/表bigquery-basics技能的 SKILL.md 在 Setup and Basic Usage 一节给出了客户端库示例真正能跑起来所需的前置资源建议按顺序执行启用 BigQuery APIgcloud services enable bigquery.googleapis.com --quiet创建数据集bq mk --dataset --locationUS my_dataset创建表先准备schema.json列定义含name/type/modemode可取REQUIRED、NULLABLE[ { name: name, type: STRING, mode: REQUIRED }, { name: post_abbr, type: STRING, mode: NULLABLE } ]再用bq建表bq mk --table my_dataset.mytable schema.json验证连通性CLI 侧bq query --use_legacy_sqlfalse \ SELECT name FROM bigquery-public-data.usa_names.usa_1910_2013 \ WHERE state TX LIMIT 10其中--use_legacy_sqlfalse表示使用标准 SQLGoogleSQL方言这一点在后续各语言的客户端库查询中同样适用。完成以上准备后各语言示例中的project.dataset.table引用才有真实对象可查。Pythongoogle-cloud-bigquery原文档给出的 Python 部分包含安装命令与最小查询示例完整继承如下。安装pip install --upgrade google-cloud-bigquery使用示例from google.cloud import bigquery client bigquery.Client() query_job client.query(SELECT * FROM project.dataset.table LIMIT 10) results query_job.result()逐行解读这段代码的语义依据文档示例本身bigquery.Client()无参构造客户端从当前环境的默认凭据解析项目与鉴权信息client.query(...)提交 SQL 并立即返回一个query job 对象query_job说明查询是以异步作业方式提交的query_job.result()阻塞等待作业完成并返回可迭代的行集合results。注意示例中表引用使用了反引号包裹的全限定名project.dataset.table——这是 GoogleSQL 的标准写法与 cli-usage.md 中bq query示例的my_project.my_dataset.my_table保持一致。跨项目查询公共数据集时project位置填目标项目 ID如bigquery-public-data。此外iam-security.md 提醒BigQuery 支持列级安全policy tags、行级安全行访问策略、数据脱敏与审计日志等治理能力。若你的客户端库代码运行在服务账号下请确保该账号只被授予查询目标表所需的最小角色。JavaMaven 依赖与 BigQueryOptions原文档的 Java 部分如下。Maven 依赖dependency groupIdcom.google.cloud/groupId artifactIdgoogle-cloud-bigquery/artifactId /dependency使用示例BigQuery bigquery BigQueryOptions.getDefaultInstance().getService(); QueryJobConfiguration queryConfig QueryJobConfiguration.newBuilder( SELECT * FROM dataset.table).build(); TableResult results bigquery.query(queryConfig);从示例结构可以看出 Java 客户端库的调用链BigQueryOptions.getDefaultInstance()从默认配置解析出连接选项.getService()取得BigQuery服务句柄SQL 被封装进不可变的QueryJobConfiguration随后bigquery.query(queryConfig)同步执行并返回TableResult可直接遍历其中的行。与 Python 版本先拿 job、再取 result的两段式不同这个示例呈现的是同步一次性获取结果的用法。Node.jsTypeScriptgoogle-cloud/bigquery原文档的 Node.js 部分如下。安装npm install google-cloud/bigquery使用示例import {BigQuery} from google-cloud/bigquery; const bigquery new BigQuery(); const [rows] await bigquery.query(SELECT * FROM dataset.table);要点构造new BigQuery()同样无需显式传项目参数依赖环境默认凭据bigquery.query(...)返回 Promiseawait之后的结果是一个数组第一个元素即行数组rows示例用解构const [rows] ...直接取出行数据该示例面向 TypeScript/ES 模块写法import语句可直接用于.ts工程。Gocloud.google.com/go/bigquery原文档的 Go 部分如下。安装go get cloud.google.com/go/bigquery使用示例ctx : context.Background() client, _ : bigquery.NewClient(ctx, project-id) q : client.Query(SELECT * FROM dataset.table) it, _ : q.Read(ctx)要点与注意事项Go 版本是四个语言中唯一要求显式传入项目 ID的bigquery.NewClient(ctx, project-id)并且所有操作都以context.Context作为第一个参数贯穿创建客户端、读取结果均是如此这符合 Go 标准库对取消/超时的通行约定client.Query(...)返回查询对象q再经q.Read(ctx)拿到行迭代器it同样是提交—迭代两段式示例中的两个_是教学性简化真实代码不应忽略NewClient与Read返回的错误建议在封装层对这两处做显式错误处理后再使用迭代器。四种语言速查对比语言包 / 依赖安装方式项目参数结果获取方式Pythongoogle-cloud-bigquerypip install --upgrade google-cloud-bigquery默认凭据解析client.query()返回 jobjob.result()取行Javacom.google.cloud:google-cloud-bigqueryMaven添加dependencyBigQueryOptions.getDefaultInstance()bigquery.query(config)同步返回TableResultNode.js (TS)google-cloud/bigquerynpm install google-cloud/bigquery默认凭据解析await bigquery.query()解构首元素为rowsGocloud.google.com/go/bigquerygo get cloud.google.com/go/bigquery构造时显式传project-idclient.Query()q.Read(ctx)迭代器四种示例的 SQL 均为最简单的SELECT * FROM ...实际使用时请替换为带反引号全限定表引用的 GoogleSQL 语句如SELECT * FROM project.dataset.table LIMIT 10并可参考 cli-usage.md 中的--dry_run思路用先估成本再执行的习惯控制按扫描字节计费的开销计费模型见 core-concepts.md按字节计费的 On-demand 或按预留槽位的 Capacity/Reservations 两类。Agent 场景下的一条约束如果你的客户端库代码是由 Agent 依据本技能生成的SKILL.md 的 Attribution 一节有一条明确的Constraint for Generated Code终端里直接执行的gcloud命令需带CLOUDSDK_METRICS_REQUEST_ATTRIBUTIONagent-skills/1.0 (skill:bigquery-basics)前缀以便用量归因但这段跟踪前缀只属于 Agent 自己执行的终端命令不得写入生成给用户的脚本、Terraform 模板或代码仓库。同理上节各语言示例应原样交付不带任何归因标记。BigQuery DataFramesBigFramesPython 用户的 pandas 风格替代原文档在末尾单独给出了 BigFrames 段落For Python users,bigframesprovides a pandas-like API that executes directly in BigQuery.pip install --upgrade bigframes即对 Python 用户而言bigframes提供 pandas 风格 API且计算直接在 BigQuery 内执行而不是把数据拉到本地。仓库中专门有一个姊妹技能 bigquery-bigframes其 SKILL.md 明确说明BigFrames 用于基于熟悉的 Python API 做 pandas 风格 DataFrame/ML 工作SQL 优先或google-cloud-bigquery客户端库的工作流应使用bigquery-basics可以据此对 BigFrames 的实战要点做如下扩充保持在云端计算用 BigFrames 方法做清洗、转换与分析利用 BigQuery 的规模优势而非下载数据开启 partial ordering 模式导入后立即设置bpd.options.bigquery.ordering_mode partial放宽行序约束以显著提速用peek(n)代替head(n)预览peek(n)随机抽样n行、速度更快head(n)要求严格行序在partial模式下未显式排序前会失败避免本地物化to_pandas()会把全部数据下载到客户端内存绕过分布式计算并可能触发 OOM仅在数据足够小或报错明确要求时才使用优先 DataFrame API 而非原始 SQL能用 DataFrame/Series 方法就不要用read_gbq()写裸 SQL否则会打断 pandas 抽象、失去惰性执行用内置访问器代替 UDF/lambda例如字符串操作用df.col.str.*、时间操作用df.col.dt.*Series.map()/DataFrame.apply()不接受未加udf/remote_function装饰器的函数ML 训练走bigframes.bigquery.ml标准 Scikit-learn 需要把数据拉回本地而bigframes.bigquery.ml把训练直接委托给 BigQuery 的可扩展 ML 引擎线性回归、逻辑回归的参考实现见 linear_regression.md 与 logistic_regression.md。选型建议依据两个技能文档的分工描述以 SQL 查询为中心、需要精细控制作业参数时用google-cloud-bigquery客户端库以 pandas 工作流为中心、数据量大到不宜落盘时用 BigFrames。相关文档与延伸阅读围绕本文主题skills 仓库中以下文件可直接对照阅读client-library-usage.md本文主体四种语言客户端库与 BigFrames 入门SKILL.mdbigquery-basics技能入口含 API 启用、数据集/表创建等前置操作与参考目录索引cli-usage.mdbq命令的数据集/表/作业管理与查询含--dry_run成本预估core-concepts.mdBigQuery 架构计算与存储分离、资源层级与分析工作流是理解客户端库查表对象模型的基础iam-security.md最小权限原则、服务账号模拟与数据治理手段列/行级安全、脱敏、审计日志mcp-usage.md面向 Agent 的远程 MCP 工具list_dataset_ids、execute_sql等bigquery-bigframes/SKILL.mdBigFrames 的 DataFrame API 最佳实践与 ML 用法。以上文档共同构成了从装 SDK、建资源、写代码、控权限到Agent 接入的完整链路本文聚焦其中的客户端库一环其余环节可按对应文档深入。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考