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 clássica do BigQuery na Web.
  • Use o comando bq head da ferramenta de linha de comando.
  • Chame o método de API tabledata.list.
  • Use bibliotecas de cliente.

Permissões exigidas

Para navegar por dados de tabelas e partições, é necessário ter, no mínimo, as permissões bigquery.tables.getData. Os papéis predefinidos do Cloud IAM a seguir incluem as permissões bigquery.tables.getData:

  • bigquery.dataViewer
  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Além disso, quando um usuário com permissões bigquery.datasets.create cria um conjunto de dados, recebe o acesso bigquery.dataOwner a ele. Com o acesso bigquery.dataOwner, o usuário consegue navegar pelos dados das tabelas e partições no conjunto de dados.

Para mais informações sobre os papéis e as permissões do Cloud IAM no BigQuery, consulte Papéis e permissões predefinidos.

Como navegar pelos dados da tabela

Para procurar dados de tabela:

Console

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

  2. Na seção Recursos do painel de navegação, abra o 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 a CLI ou a 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 clássica do BigQuery na Web, 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 a CLI ou a 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 todas as colunas em um determinado número de linhas da tabela. Se --max_rows não for especificada, o padrão será 100.

Para navegar por um subconjunto de colunas da tabela, incluindo colunas aninhadas e repetidas, use a sinalização --selected_fields e insira as colunas 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 a sinalização --start_row=integer ou o atalho -s. O valor padrão é 0. Recupere o número de linhas em uma tabela usando o comando bq show para recuperar as informações de uma tabela.

Se a tabela em que você está navegando estiver em um projeto diferente do padrão, adicione o ID do projeto ao comando no seguinte formato: project_id:dataset.table.

bq head \
--max_rows integer1 \
--start_row integer2 \
--selected_fields "columns" \
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;
  • columns é uma lista de colunas separadas 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:

Insira o comando a seguir para listar todas as tabelas nas dez primeiras linhas em mydataset.mytable. mydataset é seu projeto padrão.

bq head --max_rows=10 mydataset.mytable

Insira o comando a seguir para listar todas as colunas nas 100 primeiras linhas em mydataset.mytable. mydataset está em myotherproject, não em seu projeto padrão.

bq head myotherproject:mydataset.mytable

Insira o comando a seguir 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 o resultado:

  • maxResults: número máximo de resultados a serem retornados.
  • selectedFields: lista de colunas separadas por vírgulas a ser retornada (se não especificado, todas as colunas serão retornadas).
  • startIndex: índice baseado em zero da primeira linha a ser lida.

Os valores são retornados encapsulados em um objeto JSON que precisa ser analisado, 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 saber mais informações, consulte a documentação de referência da API BigQuery 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 este exemplo, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API BigQuery Go.

Na biblioteca de cliente do Google Cloud para Go, a paginação dos resultados é feita automaticamente por padrão, por isso, não é necessário implementá-la, 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 este exemplo, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para saber 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 no guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API BigQuery Node.js.

Na biblioteca de cliente do Google Cloud para Node.js, a paginação dos resultados é feita automaticamente por padrão, por isso, não é necessário implementá-la. Por exemplo:


// 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

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

A paginação ocorre automaticamente na biblioteca de cliente do Google Cloud para PHP com o uso da função geradora rows. A função 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 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 Python.

# 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 este exemplo, siga as instruções de configuração do Ruby 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 Ruby.

A paginação é feita automaticamente na biblioteca de cliente do Google Cloud para Ruby com o uso do 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.

Execute 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 fontes 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. Para anexar mais dados a uma tabela atual, execute uma operação de anexação de carga ou anexe resultados de consulta à tabela.

Para mais informações sobre como anexar ou substituir uma tabela durante o carregamento de dados, consulte a documentação referente ao formato dos 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 de uso da DML, consulte Como atualizar dados de 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 clássica do BigQuery na Web.
  • 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.
  • Use bibliotecas de cliente.

Para mais informações sobre a cópia de 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á como exportar para sua máquina local, porém, é possível fazer o download de resultados de consulta e salvá-los usando o Console do GCP ou a IU clássica do BigQuery na Web.

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.