Como gerenciar dados de tabela

Neste documento, você aprende a gerenciar dados de tabela no BigQuery. É possível trabalhar com eles das seguintes formas:

  • carregar dados em uma tabela
  • procurar ou visualizar dados da tabela
  • consultar dados da tabela
  • anexar ou substituir dados da tabela
  • modificar dados da tabela usando a linguagem de manipulação de dados
  • copiar dados da tabela
  • exportar dados da tabela

Para informações sobre como gerenciar esquemas de tabelas, consulte Como modificar esquemas de tabelas.

Como carregar dados em uma tabela

Você pode carregar dados ao criar uma tabela ou pode criar uma tabela vazia e carregar os dados depois. Ao carregá-los, use a detecção automática de esquema em formatos de dados compatíveis ou especifique o esquema.

Para mais informações sobre o carregamento de dados, consulte a documentação para o formato e o local dos dados de origem:

Como navegar pelos dados da tabela

Para procurar dados da tabela:

  • Use o Console do GCP ou a IU da Web clássica do BigQuery.
  • Use o comando bq head da ferramenta de linha de comando.
  • chame o método de API tabledata.list.

Permissões exigidas

No nível do conjunto de dados, você precisa ter acesso de READER ao conjunto de dados da tabela para navegar pelos dados contidos nela.

Em vez de usar as permissões do conjunto de dados, utilize um papel do IAM no nível do projeto que inclua as permissões bigquery.tables.getData. Todos os papéis de IAM predefinidos para envolvidos no projeto incluem permissões bigquery.tables.getData, exceto bigquery.user, bigquery.jobUser e bigquery.metadataViewer.

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário atribuído ao papel bigquery.user lê os dados em qualquer tabela de qualquer conjunto de dados criado pelo usuário. Quando um usuário atribuído ao papel bigquery.user cria um conjunto de dados, esse usuário recebe acesso de OWNER para esse conjunto. Com o acesso OWNER, o usuário tem controle total sobre o conjunto de dados e todas as tabelas nele.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso. Para mais informações sobre os papéis para conjuntos de dados, consulte Papéis primários para conjuntos de dados.

Como navegar pelos dados da tabela

Para procurar dados de tabela:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, na seção Recursos, expanda seu projeto e selecione um conjunto de dados. Isso exibe as tabelas e visualizações no conjunto de dados.

  3. Clique em uma tabela na lista.

  4. Clique em Detalhes e anote o valor em Número de linhas. Talvez esse valor seja necessário para controlar o ponto de partida de seus resultados usando CLI ou API.

  5. Clique em Visualizar. Um conjunto de dados de amostra é exibido.

    Visualização da tabela

IU clássica

  1. No painel de navegação da IU da Web clássica do BigQuery, clique na seta azul à esquerda do conjunto de dados para expandi-lo ou clique duas vezes no nome dele. Isso exibe as tabelas e visualizações no conjunto de dados.

  2. Clique em uma tabela na lista.

  3. Clique em Detalhes e anote o valor em Número de linhas. Talvez esse valor seja necessário para controlar o ponto de partida de seus resultados usando CLI ou API.

  4. Clique em Visualizar. Um conjunto de dados de amostra é exibido.

    Visualização da tabela

Linha de comando

Emita o comando bq head com a sinalização --max_rows para listar todos os campos em um determinado número de linhas da tabela. Caso --max_rows não seja especificado, o padrão será 100.

Para procurar um subconjunto de campos na tabela, incluindo campos aninhados e repetidos, use a sinalização --selected_fields e insira os campos como uma lista separada por vírgulas.

Para especificar o número de linhas a serem ignoradas antes de exibir os dados da tabela, use o --start_row=[INTEGER] ou o atalho -s. O valor padrão é 0. Se quiser ver o número de linhas em uma tabela, use o comando bq show para recuperar informações da tabela.

Caso a tabela que você procura conste em um projeto diferente do projeto padrão, adicione o código do projeto ao comando no seguinte formato: [PROJECT_ID]:[DATASET].[TABLE].

bq head --max_rows [INTEGER1] --start_row [INTEGER2] --selected_fields "[FIELDS]" [PROJECT_ID]:[DATASET].[TABLE]

em que:

  • [INTEGER1] é o número de linhas a ser exibido;
  • [INTEGER2] é o número de linhas a ser ignorado antes da exibição dos dados;
  • [FIELDS] é uma lista de campos separada por vírgulas;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é o nome do conjunto de dados que contém a tabela;
  • [TABLE] é o nome da tabela a ser navegada.

Exemplos:

Digite o seguinte comando para listar todos os campos nas 10 primeiras linhas no mydataset.mytable. O mydataset está no projeto padrão.

bq head --max_rows=10 mydataset.mytable

Digite o seguinte comando para listar todos os campos nas primeiras 100 linhas no mydataset.mytable. O mydataset está em myotherproject, que não é o projeto padrão.

bq head myotherproject:mydataset.mytable

Digite o seguinte comando para exibir apenas field1 e field2 em mydataset.mytable. O comando usa a sinalização --start_row para pular para a linha 100. O mydataset.mytable está no seu projeto padrão.

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

Como o comando bq head não cria um job de consulta, os comandos bq head não aparecem no histórico da consulta e você não será cobrado por eles.

API

Chame tabledata.list para navegar pelos dados de uma tabela. Especifique o nome da tabela no parâmetro tableId.

Configure esses parâmetros opcionais para controlar a saída:

  • maxResults: número máximo de resultados que serão retornados
  • selectedFields: lista de campos separados por vírgulas a ser retornada (se não especificado, todos os campos serão retornados)
  • startIndex: índice baseado em zero da primeira linha a ser lida

Os valores são retornados encapsulados em um objeto JSON que é preciso analisar, conforme descrito na documentação de referência de tabledata.list.

C#

Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para C#.

using Google.Api.Gax;
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
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

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery para Go.

Na biblioteca de cliente do Google Cloud para Go, os resultados são percorridos automaticamente por padrão, então não é necessário implementar a paginação. Por exemplo:

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.Println(row)
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Java.

TableId tableIdObject = TableId.of(datasetName, tableName);
// This example reads the result 100 rows per RPC call. If there's no need to limit the number,
// simply omit the option.
TableResult tableData =
    bigquery.listTableData(tableIdObject, TableDataListOption.pageSize(100));
for (FieldValueList row : tableData.iterateAll()) {
  // do something with the row
}

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js em Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery para Node.js.

Na biblioteca de cliente do Google Cloud para Node.js, os resultados são percorridos automaticamente por padrão, então não é necessário implementar a paginação. Por exemplo:

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

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

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

  // Create a client
  const bigqueryClient = new BigQuery();

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

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

browseRows();

PHP

Antes de testar esta amostra, siga as instruções de configuração do PHP em Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery para PHP.

A paginação ocorre automaticamente na biblioteca de cliente do Google Cloud para PHP com o uso da função geradora rows, que busca a próxima página de resultados durante a iteração.

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

Antes de testar esta amostra, siga as instruções de configuração do Python em Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Python (em inglês).

# from google.cloud import bigquery
# client = bigquery.Client()

dataset_ref = client.dataset("samples", project="bigquery-public-data")
table_ref = dataset_ref.table("shakespeare")
table = client.get_table(table_ref)  # API call

# Load all rows from a table
rows = client.list_rows(table)
assert len(list(rows)) == table.num_rows

# Load the first 10 rows
rows = client.list_rows(table, max_results=10)
assert len(list(rows)) == 10

# Specify selected fields to limit the results to certain columns
fields = table.schema[:2]  # first two columns
rows = client.list_rows(table, selected_fields=fields, max_results=10)
assert len(rows.schema) == 2
assert len(list(rows)) == 10

# Use the start index to load an arbitrary portion of the table
rows = client.list_rows(table, start_index=10, max_results=10)

# Print row data in tabular format
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

Antes de testar esta amostra, siga as instruções de configuração do Ruby em Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Ruby.

A paginação ocorre automaticamente na biblioteca de cliente do Google Cloud para Ruby Table#data e 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

Como consultar dados da tabela

Depois de carregar dados no BigQuery, você pode consultar os dados nas tabelas. O BigQuery aceita dois tipos de consultas:

Por padrão, o BigQuery executa consultas interativas, o que significa que elas são executadas assim que possível.

O BigQuery também oferece consultas em lote. O BigQuery coloca em fila cada consulta em lote em seu nome e inicia a consulta assim que os recursos inativos tornam-se disponíveis, normalmente em alguns minutos.

É possível executar consultas interativas e em lote usando:

Para mais informações sobre como consultar as tabelas do BigQuery, consulte Introdução à consulta de dados do BigQuery.

Além de consultar dados armazenados em tabelas do BigQuery, é possível consultar dados armazenados externamente. Para mais informações, consulte Introdução às origens de dados externas.

Como anexar e substituir dados da tabela

É possível substituir os dados da tabela usando uma operação de carga ou consulta, além de anexar dados adicionais a uma tabela existente, executando uma operação de anexação de carga ou anexando à tabela resultados de consulta.

Para mais informações sobre como anexar ou substituir uma tabela durante o carregamento de dados, consulte a documentação para o formato dos seus dados de origem:

Para anexar ou substituir uma tabela usando os resultados da consulta, especifique uma tabela de destino e configure a disposição de gravação como:

  • Anexar à tabela: anexa os resultados da consulta a uma tabela atual.
  • Substituir tabela: usa os resultados da consulta para substituir uma tabela atual com o mesmo nome.

Para mais informações sobre como usar os resultados da consulta para anexar ou substituir dados, consulte Como gravar resultados da consulta.

Como modificar os dados da tabela

Com o dialeto SQL padrão, é possível modificar os dados de uma tabela usando as instruções DML. Com elas, é possível executar atualizações, inserções e exclusões de linhas em massa. Para exemplos sobre como utilizar a DML, consulte Como atualizar dados da tabela usando a linguagem de manipulação de dados.

O dialeto SQL legado não é compatível com as instruções DML. Para atualizar ou excluir dados usando o SQL legado, é preciso excluir a tabela e recriá-la com novos dados. Como alternativa, escreva uma consulta que modifique os dados e grave os resultados em uma nova tabela de destino.

Como copiar dados da tabela

Para copiar uma tabela, use estes métodos:

  • Use o Console do GCP ou a IU da Web clássica do BigQuery.
  • use o comando bq cp da ferramenta de linha de comando;
  • Chame o método de API jobs.insert e configure um job de cópia.

Para mais informações sobre como copiar tabelas, consulte Como copiar uma tabela.

Como exportar dados de tabela

É possível exportar dados de tabela nos formatos CSV, JSON ou Avro. Atualmente, é preciso exportar os dados para um intervalo do Cloud Storage. Não há suporte para exportar para sua máquina local. No entanto, é possível fazer o download e salvar os resultados da consulta usando o Console do GCP ou a IU da Web clássica do BigQuery.

Para mais informações, consulte Como exportar dados de tabelas.

A seguir

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.