Como criar conjuntos de dados

Neste documento, descrevemos como criar conjuntos de dados no BigQuery.

É possível criar conjuntos de dados das seguintes maneiras:

  • Use o Console do Cloud ou a IU da Web clássica do BigQuery
  • Como usar o comando bq mk na ferramenta de linha de comando bq
  • Chamando o método datasets.insert da API.
  • Como usar as bibliotecas de cliente
  • Copiando um conjunto de dados existente.

Para ver as etapas para essa ação, inclusive entre regiões, consulte Como copiar conjuntos de dados.

Limitações do conjunto de dados

Os conjuntos de dados do BigQuery estão sujeitos às seguintes limitações:

  • A definição do local geográfico é possível apenas no momento da criação. Após a criação de um conjunto de dados, a localização se torna imutável e não pode ser alterada no Console do Cloud, na versão clássica da IU da Web do BigQuery ou na ferramenta de linha de comando bq e nem mesmo ao chamar os métodos patch ou update da API.

  • Todas as tabelas referenciadas em uma consulta precisam ser armazenadas em conjuntos de dados no mesmo local.

  • Ao copiar uma tabela, os conjuntos de dados que contêm as tabelas de origem e de destino precisam estar no mesmo local.

  • Os nomes dos conjuntos de dados precisam ser exclusivos por projeto.

  • À medida que o número de conjuntos de dados em um projeto se aproxima dos milhares, o desempenho da IU clássica começa a se degradar e a listagem de conjuntos de dados fica mais lenta.

Como nomear conjuntos de dados

Quando você cria um conjunto de dados no BigQuery, ele precisa ter um nome exclusivo por projeto. O nome do conjunto de dados:

  • pode conter até 1.024 caracteres;

  • letras (maiúsculas e minúsculas), números e sublinhados;

  • Quando há diferenciação de maiúsculas e minúsculas: mydataset e MyDataset podem coexistir no mesmo projeto

Os nomes dos conjuntos de dados não podem:

  • conter espaços ou caracteres especiais, como -, &, @ ou %.

Permissões necessárias

É preciso, pelo menos, ter as permissões bigquery.datasets.create para criar um conjunto de dados. Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.datasets.create:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.user
  • bigquery.admin

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

Como criar um conjunto de dados

Para criar um conjunto de dados:

Console

  1. Abra a página do BigQuery no Console do Cloud.

    Acessar a página do BigQuery

  2. No painel de navegação, na seção Recursos, selecione seu projeto.

  3. No lado direito da janela, no painel de detalhes, clique em Criar conjunto de dados.

  4. Na página Criar conjunto de dados, faça o seguinte:

    • Em Código do conjunto de dados, insira um nome exclusivo para o conjunto de dados.

    • Opcional: em Local dos dados, escolha uma localização geográfica para o conjunto de dados. Se o valor permanecer definido como Padrão, o local será definido como US. Após a criação de um conjunto de dados, o local não pode ser alterado.

    • Em Validade da tabela padrão, escolha uma das seguintes opções:

      • Nunca: (padrão) as tabelas criadas no conjunto de dados nunca são excluídas automaticamente. Você precisa excluí-las manualmente.
      • Número de dias após a criação da tabela: esse valor determina quando uma tabela recém-criada no conjunto de dados é excluída. Esse valor será aplicado caso a expiração da tabela não seja definida quando ela for criada.

    • Clique em Criar conjunto de dados.

IU clássica

  1. Clique no ícone de seta para baixo ícone de seta para baixo ao lado do nome do seu projeto na navegação e depois clique em Criar novo conjunto de dados.

  2. Na caixa de diálogo Criar conjunto de dados, siga estas instruções:

    • Em Código do conjunto de dados, digite um nome exclusivo.

    • Em Local de dados, escolha uma localização para o conjunto de dados. O valor padrão se encontra não especificado, o que define a localização do conjunto de dados nos US. Após a criação de um conjunto de dados, o local não pode ser alterado.

    • Em Validade de dados, escolha uma das seguintes opções:

      • Nunca: (padrão) as tabelas criadas no conjunto de dados nunca são excluídas automaticamente. Você precisa excluí-las manualmente.

      • Em integer dias: qualquer tabela criada no conjunto será excluída depois de integer dias a partir do momento da criação. Esse valor será aplicado caso a expiração da tabela não seja definida quando ela for criada.

        Validade dos dados refere-se à expiração padrão da tabela para novas tabelas criadas no conjunto de dados. No momento, não é possível definir uma expiração da partição padrão na IU da Web do BigQuery ao criar um conjunto de dados. É possível definir uma expiração de partição padrão após a criação do conjunto de dados usando a ferramenta de linha de comando bq ou a API.

    • Clique em OK.

bq

Use o comando bq mk com a sinalização --location para criar um novo conjunto de dados. Os parâmetros opcionais incluem --default_table_expiration, --default_partition_expiration e --description.

Para criar um conjunto de dados em um projeto diferente do projeto padrão, adicione a ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.

bq --location=location mk \
--dataset \
--default_table_expiration integer1 \
--default_partition_expiration integer2 \
--description description \
project_id:dataset

Em que:

  • location é o local do conjunto de dados. Após a criação de um conjunto de dados, o local não pode ser alterado. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.

  • integer1 é a vida útil padrão (em segundos) das tabelas recém-criadas. O valor mínimo é de 3.600 segundos (uma hora). O prazo de validade é avaliado como a hora atual mais o valor inteiro. Qualquer tabela criada no conjunto de dados é excluída após [INTEGER] segundos a partir do momento da criação. Esse valor será aplicado caso a expiração da tabela não seja definida quando ela for criada.

  • integer2 é a vida útil padrão (em segundos) das partições nas tabelas particionadas recém-criadas. Não há um valor mínimo de expiração de partição padrão. O prazo de validade é avaliado como a data da partição mais o valor inteiro. Qualquer partição criada em uma tabela particionada no conjunto de dados é excluída após [INTEGER2] segundos a partir da data da partição. Ao fornecer a sinalização --time_partitioning_expiration ao criar ou atualizar uma tabela particionada, a expiração de partição no nível da tabela terá precedência sobre a expiração da partição padrão no nível do conjunto de dados.

  • description é uma descrição do conjunto de dados entre aspas.

  • project_id é o ID do projeto.

  • dataset é o nome do conjunto de dados que você está criando.

Por exemplo: o comando a seguir cria um conjunto de dados chamado mydataset com o local do conjunto de dados definido nos US, uma expiração de tabela padrão de 3.600 segundos (1 hora) e uma descrição de This is my dataset. Em vez de usar a sinalização --dataset, o comando usa o atalho -d. Se você omitir -d e --dataset, o comando retorna ao padrão para criar um conjunto de dados.

bq --location=US mk -d \
--default_table_expiration 3600 \
--description "This is my dataset." \
mydataset

API

Chame o método datasets.insert com um recurso de conjunto de dados definido.

C#

Antes de testar essa amostra, siga as instruções de configuração para 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 C# (em inglês). 


using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryCreateDataset
{
    public BigQueryDataset CreateDataset(
        string projectId = "your-project-id",
        string location = "US"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var createDatasetOptions = new CreateDatasetOptions()
        {
            // Specify the geographic location where the dataset should reside.
            Location = location
        };
        // Create the dataset
        return client.CreateDataset(
            datasetId: "your_new_dataset_id", options: createDatasetOptions);
    }
}

Go

Antes de testar essa amostra, siga as instruções de configuração para 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 Go. 

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// createDataset demonstrates creation of a new dataset using an explicit destination location.
func createDataset(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	meta := &bigquery.DatasetMetadata{
		Location: "US", // See https://cloud.google.com/bigquery/docs/locations
	}
	if err := client.Dataset(datasetID).Create(ctx, meta); err != nil {
		return err
	}
	return nil
}

Java

Antes de testar essa amostra, siga as instruções de configuração para 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.

Ver no GitHub (em inglês) Feedback 
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetInfo;

public class CreateDataset {

  public static void runCreateDataset() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    createDataset(datasetName);
  }

  public static void createDataset(String datasetName) {
    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();

      DatasetInfo datasetInfo = DatasetInfo.newBuilder(datasetName).build();

      Dataset newDataset = bigquery.create(datasetInfo);
      String newDatasetName = newDataset.getDatasetId().getDataset();
      System.out.println(newDatasetName + " created successfully");
    } catch (BigQueryException e) {
      System.out.println("Dataset was not created. \n" + e.toString());
    }
  }
}

Node.js

Antes de testar essa amostra, siga as instruções de configuração para 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 do BigQuery para Node.js.

Ver no GitHub (em inglês) Feedback 
// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function createDataset() {
  // Creates a new dataset named "my_dataset".

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

  // Specify the geographic location where the dataset should reside
  const options = {
    location: 'US',
  };

  // Create a new dataset
  const [dataset] = await bigquery.createDataset(datasetId, options);
  console.log(`Dataset ${dataset.id} created.`);
}
createDataset();

PHP

Antes de testar esta amostra, siga as instruções de configuração para 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. 

use Google\Cloud\BigQuery\BigQueryClient;

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

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->createDataset($datasetId);
printf('Created dataset %s' . PHP_EOL, $datasetId);

Python

Antes de testar essa 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.

Ver no GitHub (em inglês) Feedback 
from google.cloud import bigquery

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

# TODO(developer): Set dataset_id to the ID of the dataset to create.
# dataset_id = "{}.your_dataset".format(client.project)

# Construct a full Dataset object to send to the API.
dataset = bigquery.Dataset(dataset_id)

# TODO(developer): Specify the geographic location where the dataset should reside.
dataset.location = "US"

# Send the dataset to the API for creation, with an explicit timeout.
# Raises google.api_core.exceptions.Conflict if the Dataset already
# exists within the project.
dataset = client.create_dataset(dataset, timeout=30)  # Make an API request.
print("Created dataset {}.{}".format(client.project, dataset.dataset_id))

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.

Ver no GitHub (em inglês) Feedback 
require "google/cloud/bigquery"

def create_dataset dataset_id = "my_dataset", location = "US"
  bigquery = Google::Cloud::Bigquery.new

  # Create the dataset in a specified geographic location
  bigquery.create_dataset dataset_id, location: location

  puts "Created dataset: #{dataset_id}"
end

A seguir