Como gerenciar dados de tabela

Neste documento, você aprenderá como 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 (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:

Como procurar dados em tabelas

Para procurar dados de tabela:

  • use o console do Cloud;
  • Use o comando bq head da ferramenta de linha de comando bq.
  • chame o tabledata.list método de API;
  • usar 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

  1. No console do Cloud, abra a página do BigQuery.

    Ir para o BigQuery

  2. No painel Explorer, expanda o projeto e selecione um 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 ferramenta de linha de comando bq ou a API.

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

    Visualização da tabela

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

Onde:

  • 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#. 


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 do BigQuery para Go.

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. 

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 Node.js.

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 PHP.

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 para 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. 


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 para 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 Ruby.

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

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 como usar 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:

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

Próximas etapas