管理表数据

本文档介绍如何在 BigQuery 中管理表数据。 您可以通过以下方式处理 BigQuery 表数据：

• 将数据加载到表中
• 对表数据执行附加或覆盖操作
• 浏览（或预览）表数据
• 查询表数据
• 使用数据操纵语言 (DML) 修改表数据
• 复制表数据
• 导出表数据

如需了解如何管理表架构，请参阅修改表架构。

准备工作

向需要执行本文档中每项任务的用户授予必要权限的角色。执行任务所需的权限（如果有）列在任务的“所需权限”部分中。

将数据加载到表中

您可以在创建表时加载数据，也可以先创建空表，然后再加载数据。加载数据时，您可以针对支持的数据格式使用架构自动检测功能，也可以指定架构。

如需详细了解如何加载数据，请参阅关于源数据格式和位置的文档：

• 如需详细了解如何从 Cloud Storage 加载数据，请参阅：

  • 加载 Avro 数据
  • 加载 CSV 数据
  • 加载 JSON 数据
  • 加载 Parquet 数据
  • 加载 ORC 数据
  • 从 Datastore 导出文件中加载数据
  • 从 Firestore 导出文件中加载数据

• 如需详细了解如何从本地来源加载数据，请参阅从本地文件加载数据。

对表数据执行附加和覆盖操作

您可以使用加载或查询操作覆盖表数据。您可以通过执行加载附加操作或将查询结果附加到表，将其他数据附加到现有表。

如需详细了解如何在加载数据时对表执行附加或覆盖操作，请参阅关于源数据格式的文档：

• 使用 Avro 数据覆盖或附加到表
• 使用 CSV 数据覆盖或附加到表
• 使用 JSON 数据覆盖或附加到表
• 使用 Parquet 数据覆盖或附加到表
• 使用 ORC 数据覆盖或附加到表
• 使用 Datastore 数据覆盖或附加到表

如需使用查询结果覆盖或附加到表，请指定目标表并将写入配置设置为以下某项：

• Append to table - 将查询结果附加到现有表。
• Overwrite table - 使用查询结果覆盖名称相同的现有表。

您可以使用以下查询将记录从一个表附加到另一个表：

  INSERT INTO .. (
    ,
    ) (SELECT * FROM ..)

如需详细了解如何使用查询结果执行数据附加或覆盖操作，请参阅写入查询结果。

浏览表数据

您可以通过以下方式浏览表数据：

• 使用 Google Cloud 控制台
• 使用 bq 命令行工具的 bq head 命令
• 调用 tabledata.list API 方法
• 使用客户端库

所需权限

如需浏览表和分区数据，您需要拥有 bigquery.tables.getData Identity and Access Management (IAM) 权限。

以下预定义的 IAM 角色均包含浏览表和分区数据所需的权限：

• roles/bigquery.dataViewer
• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin

如果您拥有 bigquery.datasets.create 权限，则可以浏览您创建的数据集的表和分区中的数据。

如需详细了解 BigQuery 中的 IAM 角色和权限，请参阅预定义的角色和权限。

浏览表数据

如需浏览表数据，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，打开 BigQuery 页面。

   转到 BigQuery

2. 在浏览器面板中，展开您的项目并选择数据集。

3. 点击列表中的表。

4. 点击详情并记下行数中的值。使用 bq 命令行工具或 API，您可能需要此值来控制结果的起点。

5. 点击 Preview。此时会显示一组数据示例。

   

命令行

发出带 --max_rows 标志的 bq head 命令，即可列出特定表行数对应的所有列。如果未指定 --max_rows，则默认值为 100。

如需浏览表中的列的子集（包括嵌套和重复的列），请使用 --selected_fields 标志以英文逗号分隔列表的形式输入列。

如需指定显示表数据之前要跳过的行数，请使用 --start_row=integer 标志（或 -s 快捷方式）。默认值为 0。如需检索表中的行数，您可以使用 bq show 命令检索表信息。

如果要浏览的表在非默认项目中，请按以下格式将相应项目 ID 添加到命令：project_id:dataset.table。

bq head \
--max_rows integer1 \
--start_row integer2 \
--selected_fields "columns" \
project_id:dataset.table

其中：

• integer1 是要显示的行数。
• integer2 是显示数据之前要跳过的行数。
• columns 是以英文逗号分隔的列的列表。
• project_id 是项目 ID。
• dataset 是包含该表的数据集的名称。
• table 是要浏览的表名称。

示例：

输入以下命令以列出 mydataset.mytable 中前 10 行的所有列。mydataset 在默认项目中。

bq head --max_rows=10 mydataset.mytable

输入以下命令以列出 mydataset.mytable 中前 100 行的所有列。mydataset 在 myotherproject 中，不在默认项目中。

bq head myotherproject:mydataset.mytable

输入以下命令，仅显示 mydataset.mytable 中的 field1 和 field2。该命令使用 --start_row 标志跳转到第 100 行。mydataset.mytable 在默认项目中。

bq head --start_row 100 --selected_fields "field1,field2" mydataset.mytable

因为 bq head 命令不会创建查询作业，所以 bq head 命令不会显示在查询历史记录中，您也无需为此付费。

API

通过调用 tabledata.list 可浏览表中的数据。在 tableId 参数中指定表的名称。

配置以下可选参数来控制输出：

• maxResults - 要返回的结果数上限
• selectedFields - 以英文逗号分隔的待返回列的列表；如果未指定此参数，则返回所有列
• startIndex - 待读取的起始行的索引（从零开始）

注意：如果您请求的 startIndex 超出最后一行，该方法仍会成功返回，但不会包含 rows 属性。您可以通过调用 tables.get 方法并查看 numRows 属性来了解表中含有的行数。

返回的值会封装在一个 JSON 对象中，您必须对此对象进行解析，具体请参阅 tabledata.list 参考文档。

C#

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 C# 设置说明进行操作。如需了解详情，请参阅 BigQuery C# API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

using Google.Api.Gax;
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;
using System.Linq;

public class BigQueryBrowseTable
{
    public void BrowseTable(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        TableReference tableReference = new TableReference()
        {
            TableId = "shakespeare",
            DatasetId = "samples",
            ProjectId = "bigquery-public-data"
        };
        // Load all rows from a table
        PagedEnumerable<TableDataList, BigQueryRow> result = client.ListRows(
            tableReference: tableReference,
            schema: null
        );
        // Print the first 10 rows
        foreach (BigQueryRow row in result.Take(10))
        {
            Console.WriteLine($"{row["corpus"]}: {row["word_count"]}");
        }
    }
}

Go

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Go 设置说明进行操作。如需了解详情，请参阅 BigQuery Go API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

默认情况下，Go 版 Cloud 客户端库会自动分页，因此您无需自行实现分页，例如：

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// browseTable demonstrates reading data from a BigQuery table directly without the use of a query.
// For large tables, we also recommend the BigQuery Storage API.
func browseTable(w io.Writer, projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	table := client.Dataset(datasetID).Table(tableID)
	it := table.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

Java

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Java 设置说明进行操作。如需了解详情，请参阅 BigQuery Java API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.TableDataListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;

// Sample to directly browse a table with optional paging
public class BrowseTable {

  public static void runBrowseTable() {
    // TODO(developer): Replace these variables before running the sample.
    String table = "MY_TABLE_NAME";
    String dataset = "MY_DATASET_NAME";
    browseTable(dataset, table);
  }

  public static void browseTable(String dataset, String table) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Identify the table itself
      TableId tableId = TableId.of(dataset, table);

      // Page over 100 records. If you don't need pagination, remove the pageSize parameter.
      TableResult result = bigquery.listTableData(tableId, TableDataListOption.pageSize(100));

      // Print the records
      result
          .iterateAll()
          .forEach(
              row -> {
                row.forEach(fieldValue -> System.out.print(fieldValue.toString() + ", "));
                System.out.println();
              });

      System.out.println("Query ran successfully");
    } catch (BigQueryException e) {
      System.out.println("Query failed to run \n" + e.toString());
    }
  }
}

Node.js

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

默认情况下，Node.js 版 Cloud 客户端库会自动分页，因此您无需自行实现分页，例如：

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function browseRows() {
  // Displays rows from "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // List rows in the table
  const [rows] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .getRows();

  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

PHP

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 PHP 设置说明进行操作。如需了解详情，请参阅 BigQuery PHP API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

PHP 版 Cloud 客户端库会通过生成器函数 rows 在迭代期间获取下一页的结果，从而实现自动分页。

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId   = 'The BigQuery table ID';
// $maxResults = 10;

$maxResults = 10;
$startIndex = 0;

$options = [
    'maxResults' => $maxResults,
    'startIndex' => $startIndex
];
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$numRows = 0;
foreach ($table->rows($options) as $row) {
    print('---');
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, $value);
    }
    $numRows++;
}

Python

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。如需了解详情，请参阅 BigQuery Python API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to browse data rows.
# table_id = "your-project.your_dataset.your_table_name"

# Download all rows from a table.
rows_iter = client.list_rows(table_id)  # Make an API request.

# Iterate over rows to make the API requests to fetch row data.
rows = list(rows_iter)
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Download at most 10 rows.
rows_iter = client.list_rows(table_id, max_results=10)
rows = list(rows_iter)
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Specify selected fields to limit the results to certain columns.
table = client.get_table(table_id)  # Make an API request.
fields = table.schema[:2]  # First two columns.
rows_iter = client.list_rows(table_id, selected_fields=fields, max_results=10)
rows = list(rows_iter)
print("Selected {} columns from table {}.".format(len(rows_iter.schema), table_id))
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Print row data in tabular format.
rows = client.list_rows(table, max_results=10)
format_string = "{!s:<16} " * len(rows.schema)
field_names = [field.name for field in rows.schema]
print(format_string.format(*field_names))  # Prints column headers.
for row in rows:
    print(format_string.format(*row))  # Prints row data.

Ruby

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Ruby 设置说明进行操作。如需了解详情，请参阅 BigQuery Ruby API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

Ruby 版 Cloud 客户端库中会使用 Table#data 和 Data#next 自动分页。

require "google/cloud/bigquery"

def browse_table
  bigquery = Google::Cloud::Bigquery.new project_id: "bigquery-public-data"
  dataset  = bigquery.dataset "samples"
  table    = dataset.table "shakespeare"

  # Load all rows from a table
  rows = table.data

  # Load the first 10 rows
  rows = table.data max: 10

  # Print row data
  rows.each { |row| puts row }
end

查询表数据

将数据加载到 BigQuery 后，您可以使用以下查询作业类型之一查询数据：

• 交互式查询作业。默认情况下，BigQuery 会尽快运行交互式（按需）查询作业。
• 批量查询作业。使用这些作业时，BigQuery 会代表您将每个批量查询排队，然后在有空闲资源时启动查询，通常在几分钟之内。

您可以使用以下方法运行交互式查询作业或批量查询作业：

• 在 Google Cloud 控制台中编写和运行查询。
• 在 bq 命令行工具中运行 bq query 命令。
• 以编程方式调用 BigQuery REST API 中的 jobs.query 或 jobs.insert 方法。
• 使用 BigQuery 客户端库。

如需详细了解如何查询 BigQuery 表，请参阅查询 BigQuery 数据简介。

除了查询存储在 BigQuery 表中的数据外，您还可以查询存储在外部的数据。如需了解详情，请参阅外部数据源简介。

修改表数据

您可以使用 SQL 中的数据操纵语言 (DML) 语句修改表中的数据。您可以使用 DML 语句更新、合并、插入和删除表中的行。如需查看每种类型的 DML 语句的语法参考和示例，请参阅 GoogleSQL 中的数据操纵语言语句。

旧版 SQL 方言不支持 DML 语句。如需使用旧版 SQL 更新或删除数据，您必须先删除表，然后使用新数据重新创建该表。您也可以通过编写查询修改数据，并将查询结果写入新的目标表。

复制表数据

您可以通过以下方式复制表：

• 使用 Google Cloud 控制台
• 使用 bq 命令行工具的 bq cp 命令
• 调用 jobs.insert API 方法并配置复制作业
• 使用客户端库

如需详细了解如何复制表，请参阅复制表。

导出表数据

您可以采用 CSV、JSON、Avro 或 Parquet（预览版）格式将表数据导出到 Cloud Storage 存储桶。不支持导出到本地机器；但是，您可以使用 Google Cloud 控制台下载和保存查询结果。

如需了解详情，请参阅导出表数据。

表安全性

如需控制对 BigQuery 中表的访问权限，请参阅表访问权限控制简介。

后续步骤

• 如需详细了解如何加载数据，请参阅加载数据简介。
• 如需详细了解如何查询数据，请参阅查询 BigQuery 数据简介。
• 如需详细了解如何修改表架构，请参阅修改表架构。
• 如需详细了解如何创建和使用表，请参阅创建和使用表。
• 如需详细了解如何管理表，请参阅管理表。