Como gerenciar dados de tabelas

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

Carregar dados em uma tabela
anexar ou substituir dados da tabela;
procurar ou visualizar dados da tabela;
Consultar os dados da tabela
Modificar dados da tabela usando a linguagem de manipulação de dados (DML)
copiar dados da tabela;
exportar dados da tabela

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

Antes de começar

Conceda papéis que concedam as permissões necessárias aos usuários que precisam executar cada tarefa neste documento. As permissões necessárias (se houver) para executar uma tarefa estão listadas na seção "Permissões necessárias" da tarefa.

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:

Para mais informações sobre o carregamento de dados do Cloud Storage, consulte estes tópicos:
Para mais informações sobre como carregar dados de uma fonte local, consulte Como carregar dados de arquivos locais.

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.

A consulta a seguir pode ser usada para anexar registros de uma tabela a outra:

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

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

Como procurar dados da tabela

Para procurar dados de tabela:

Use o console do Google Cloud
use o comando bq head da ferramenta de linha de comando bq;
chame o tabledata.list método de API;
use as bibliotecas de cliente.

Permissões necessárias

Para procurar dados em tabelas e partições, você precisa da permissão bigquery.tables.getData de gerenciamento de identidade e acesso (IAM, na sigla em inglês).

Cada um dos seguintes papéis predefinidos do IAM inclui as permissões necessárias para procurar dados em tabelas e partições:

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

Se você tiver a permissão bigquery.datasets.create, poderá procurar dados nas tabelas e partições dos conjuntos de dados criados.

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

Como procurar dados em tabelas

Para procurar dados de tabela:

Console

No Console do Google Cloud, abra a página do BigQuery.

Ir para o BigQuery
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Clique em uma tabela na lista.
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 ferramenta de linha de comando bq ou a API.
Clique em Visualizar. Um conjunto de dados de amostra é exibido.

Linha de comando

Use 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 especificado, o padrão será 100.

Para procurar 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 separada por vírgulas;
project_id é o ID 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 comando a seguir para listar todas as colunas nas primeiras 10 linhas em mydataset.mytable. mydataset está no projeto padrão.

bq head --max_rows=10 mydataset.mytable

Digite o comando a seguir para listar todas as colunas nas primeiras 100 linhas em mydataset.mytable. mydataset está em myotherproject, não no 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. mydataset.mytable está no 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 seu histórico de consultas, e você não é cobrado por eles.

API

Procure dados em uma tabela chamando tabledata.list. 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 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 incorporados em um objeto JSON para análise, 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 BigQuery em C#.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.


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

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 em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Nas bibliotecas de cliente do Cloud para Go a paginação dos resultados é feita automaticamente por padrão. Portanto, não é necessário implementá-la. Por exemplo:

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

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 em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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 mais informações, consulte a documentação de referência da API BigQuery em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Nas bibliotecas de cliente do Cloud para Node.js a paginação dos resultados é feita automaticamente por padrão. Portanto, 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 mais informações, consulte a documentação de referência da API BigQuery em PHP.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Nas bibliotecas de cliente do Cloud para PHP, a paginação é automática 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 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 em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.


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

Antes de testar esta amostra, 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 em Ruby.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Nas bibliotecas de cliente do Cloud para Rubya paginação é automática com o uso de 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

Você pode consultar dados do BigQuery usando um dos seguintes tipos de job de consulta:

Jobs de consulta interativos. Por padrão, o BigQuery executa jobs de consulta interativos (sob demanda) o mais rápido possível.
Jobs de consulta contínua (Prévia). Com esses jobs, a consulta é executada continuamente, para que você analise os dados de entrada no BigQuery em tempo real e gravar resultados para uma tabela do BigQuery ou exportar os resultados para Bigtable ou Pub/Sub. Use esse recurso para realizar tarefas urgentes, como criar e agir imediatamente insights, aplicando inferências de machine learning (ML) em tempo real e criar pipelines de dados orientados por eventos.
Jobs de consulta em lote. Com esses jobs, o BigQuery coloca em fila cada consulta em lote em seu nome e inicia a consulta quando os recursos inativos estão disponíveis, geralmente em alguns minutos.

É possível executar jobs de consulta usando os seguintes métodos:

Escreva e execute uma consulta no Console do Google Cloud.
Execute o comando bq query na ferramenta de linha de comando bq.
Chame o método jobs.query ou jobs.insert de maneira programática na API REST do BigQuery.
Use as bibliotecas de cliente do BigQuery.

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 modificar dados da tabela

É possível modificar os dados em uma tabela usando instruções da linguagem de manipulação de dados (DML, na sigla em inglês) no SQL. Com as instruções da DML, é possível atualizar, mesclar, inserir e excluir linhas em tabelas. Para ver referências de sintaxe e exemplos de cada tipo de instrução DML, consulte Instruções da linguagem de manipulação de dados no GoogleSQL.

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 o console do Google Cloud
use o comando bq cp da ferramenta de linha de comando bq;
Chame o método da API jobs.insert e configure um job de cópia.
Como usar bibliotecas de cliente

Para mais informações sobre a cópia de tabelas, consulte Como copiar uma tabela.

Como exportar dados de tabelas

É possível exportar dados de tabela para um bucket do Cloud Storage nos formatos CSV, JSON, Avro ou Parquet (Visualização). Não há como exportá-los para sua máquina local. Porém, é possível fazer o download e salvar os resultados da consulta usando o console do Google Cloud.

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

Segurança de tabelas

Para controlar o acesso a tabelas no BigQuery, consulte Introdução aos controles de acesso a tabelas.

A seguir

Para mais informações sobre o carregamento de dados, consulte Introdução ao carregamento de dados.
Para mais informações sobre consulta de dados, consulte Introdução à consulta de dados do BigQuery.
Para mais informações sobre modificação de esquemas de tabelas, consulte Como modificar esquemas de tabelas.
Para mais informações sobre criação e uso de tabelas, consulte Como criar e usar tabelas.
Para saber mais sobre gerenciamento de tabelas, consulte esta página.