Criar conjuntos de dados
Este documento descreve como criar conjuntos de dados no BigQuery.
Pode criar conjuntos de dados das seguintes formas:
- Usar a Google Cloud consola.
- Usando uma consulta SQL.
- Usando o comando
bq mk
na ferramenta de linhas de comando bq. - Chamar o método da API
datasets.insert
. - Usando as bibliotecas cliente.
- Copiar um conjunto de dados existente.
Para ver os passos para copiar um conjunto de dados, inclusive entre regiões, consulte o artigo Copiar conjuntos de dados.
Este documento descreve como trabalhar com conjuntos de dados normais que armazenam dados no BigQuery. Para saber como trabalhar com conjuntos de dados externos do Spanner, consulte o artigo Criar conjuntos de dados externos do Spanner. Para saber como trabalhar com conjuntos de dados federados do AWS Glue, consulte o artigo Crie conjuntos de dados federados do AWS Glue.
Para saber como consultar tabelas num conjunto de dados público, consulte o artigo Consulte um conjunto de dados público com a consola. Google Cloud
Limitações do conjunto de dados
Os conjuntos de dados do BigQuery estão sujeitos às seguintes limitações:
- A localização do conjunto de dados só pode ser definida no momento da criação. Depois de criar um conjunto de dados, não é possível alterar a respetiva localização.
- Todas as tabelas referenciadas numa consulta têm de ser armazenadas em conjuntos de dados na mesma localização.
Os conjuntos de dados externos não suportam a expiração de tabelas, as réplicas, a viagem no tempo, a ordenação predefinida, o modo de arredondamento predefinido nem a opção para ativar ou desativar nomes de tabelas não sensíveis a maiúsculas e minúsculas.
Quando copia uma tabela, os conjuntos de dados que contêm a tabela de origem e a tabela de destino têm de estar na mesma localização.
Os nomes dos conjuntos de dados têm de ser exclusivos para cada projeto.
Se alterar o modelo de faturação de armazenamento de um conjunto de dados, tem de aguardar 14 dias antes de poder alterar novamente o modelo de faturação de armazenamento.
Não pode inscrever um conjunto de dados na faturação de armazenamento físico se tiver quaisquer compromissos de slots de taxa fixaantigos existentes na mesma região que o conjunto de dados.
Antes de começar
Conceda funções de gestão de identidade e acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento.
Autorizações necessárias
Para criar um conjunto de dados, precisa da autorização da IAM.bigquery.datasets.create
Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para criar um conjunto de dados:
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.user
roles/bigquery.admin
Para mais informações sobre as funções de IAM no BigQuery, consulte o artigo Funções predefinidas e autorizações.
Criar conjuntos de dados
Para criar um conjunto de dados:
Consola
- Abra a página do BigQuery na Google Cloud consola. Aceda à página do BigQuery
- No painel Explorador, selecione o projeto onde quer criar o conjunto de dados.
- Expanda a opção Ver ações e clique em Criar conjunto de dados.
- Na página Criar conjunto de dados:
- Para ID do conjunto de dados, introduza um nome exclusivo do conjunto de dados.
- Para Tipo de localização, escolha uma localização geográfica para o conjunto de dados. Após a criação de um conjunto de dados, não é possível alterar a localização.
- Opcional: selecione Associar a um conjunto de dados externo se estiver a criar um conjunto de dados externo.
- Se não precisar de configurar opções adicionais, como etiquetas e expirações de tabelas, clique em Criar conjunto de dados. Caso contrário, expanda a secção seguinte para configurar as opções adicionais do conjunto de dados.
- Opcional: expanda a secção Etiquetas para adicionar etiquetas ao seu conjunto de dados.
- Para aplicar uma etiqueta existente, faça o seguinte:
- Clique na seta de menu pendente junto a Selecionar âmbito e escolha Âmbito atual: Selecionar organização atual ou Selecionar projeto atual.
- Para Chave 1 e Valor 1, escolha os valores adequados nas listas.
- Para introduzir manualmente uma nova etiqueta, faça o seguinte:
- Clique na seta de menu pendente junto a Selecionar um âmbito e escolha Introduzir IDs manualmente > Organização, Projeto ou Etiquetas.
- Se estiver a criar uma etiqueta para o seu projeto ou organização,
na caixa de diálogo, introduza o
PROJECT_ID
ou oORGANIZATION_ID
e, de seguida, clique em Guardar. - Para Chave 1 e Valor 1, escolha os valores adequados nas listas.
- Para adicionar mais etiquetas à tabela, clique em Adicionar etiqueta e siga os passos anteriores.
- Opcional: expanda a secção Opções avançadas para configurar uma ou mais das seguintes opções.
- Para alterar a opção Encriptação de modo a usar a sua própria chave criptográfica com o Cloud Key Management Service, selecione Chave do Cloud KMS.
- Para usar nomes de tabelas que não sejam sensíveis a maiúsculas e minúsculas, selecione Ativar nomes de tabelas que não sejam sensíveis a maiúsculas e minúsculas.
- Para alterar a especificação de ordenação predefinida , escolha o tipo de ordenação na lista.
- Para definir uma validade para tabelas no conjunto de dados, selecione Ativar validade da tabela e, de seguida, especifique a Idade máxima predefinida da tabela em dias.
- Para definir um Modo de arredondamento predefinido, escolha o modo de arredondamento na lista.
- Para ativar o modelo de faturação de armazenamento, escolha o modelo de faturação na lista.
- Para definir o período de viagem no tempo do conjunto de dados, escolha o tamanho do período na lista.
- Clique em Criar conjunto de dados.

Opções adicionais para conjuntos de dados
Em alternativa, clique em Selecionar âmbito para pesquisar um recurso ou ver uma lista de recursos atuais.
Quando altera o modelo de faturação de um conjunto de dados, a alteração demora 24 horas a entrar em vigor.
Depois de alterar o modelo de faturação de armazenamento de um conjunto de dados, tem de aguardar 14 dias antes de poder alterar novamente o modelo de faturação de armazenamento.
SQL
Use a declaração CREATE SCHEMA
.
Para criar um conjunto de dados num projeto que não seja o projeto predefinido, adicione o ID do projeto ao ID do conjunto de dados no seguinte formato:
PROJECT_ID.DATASET_ID
.
Na Google Cloud consola, aceda à página BigQuery.
No editor de consultas, introduza a seguinte declaração:
CREATE SCHEMA PROJECT_ID.DATASET_ID OPTIONS ( default_kms_key_name = 'KMS_KEY_NAME', default_partition_expiration_days = PARTITION_EXPIRATION, default_table_expiration_days = TABLE_EXPIRATION, description = 'DESCRIPTION', labels = [('KEY_1','VALUE_1'),('KEY_2','VALUE_2')], location = 'LOCATION', max_time_travel_hours = HOURS, storage_billing_model = BILLING_MODEL);
Substitua o seguinte:
PROJECT_ID
: o ID do seu projetoDATASET_ID
: o ID do conjunto de dados que está a criarKMS_KEY_NAME
: o nome da chave do Cloud Key Management Service predefinida usada para proteger as tabelas criadas recentemente neste conjunto de dados, a menos que seja fornecida uma chave diferente no momento da criação. Não pode criar uma tabela encriptada pela Google num conjunto de dados com este parâmetro definido.PARTITION_EXPIRATION
: o tempo de vida predefinido (em dias) para partições em tabelas particionadas recém-criadas. A validade da partição predefinida não tem um valor mínimo. O tempo de expiração é avaliado como a data da partição mais o valor inteiro. Qualquer partição criada numa tabela particionada no conjunto de dados é eliminadaPARTITION_EXPIRATION
dias após a data da partição. Se fornecer a opçãotime_partitioning_expiration
quando criar ou atualizar uma tabela particionada, a validade da partição ao nível da tabela tem precedência sobre a validade da partição predefinida ao nível do conjunto de dados.TABLE_EXPIRATION
: o tempo de vida predefinido (em dias) para tabelas recém-criadas. O valor mínimo é de 0,042 dias (uma hora). O tempo de expiração é avaliado como a hora atual mais o valor inteiro. Qualquer tabela criada no conjunto de dados é eliminadaTABLE_EXPIRATION
dias após a hora da criação. Este valor é aplicado se não definir uma data de validade da tabela quando criar a tabela.DESCRIPTION
: uma descrição do conjunto de dadosKEY_1:VALUE_1
: o par de chave-valor que quer definir como a primeira etiqueta neste conjunto de dadosKEY_2:VALUE_2
: o par de chave-valor que quer definir como a segunda etiquetaLOCATION
: a localização do conjunto de dados. Após a criação de um conjunto de dados, não é possível alterar a localização.HOURS
: a duração em horas do período de deslocação no tempo para o novo conjunto de dados. O valorHOURS
tem de ser um número inteiro expresso em múltiplos de 24 (48, 72, 96, 120, 144, 168) entre 48 (2 dias) e 168 (7 dias). 168 horas é a predefinição se esta opção não estiver especificada.BILLING_MODEL
: define o modelo de faturação de armazenamento para o conjunto de dados. Defina o valorBILLING_MODEL
comoPHYSICAL
para usar bytes físicos ao calcular os custos de armazenamento ou comoLOGICAL
para usar bytes lógicos.LOGICAL
é a predefinição.Quando altera o modelo de faturação de um conjunto de dados, a alteração demora 24 horas a entrar em vigor.
Depois de alterar o modelo de faturação de armazenamento de um conjunto de dados, tem de aguardar 14 dias antes de poder alterar novamente o modelo de faturação de armazenamento.
Clique em
Executar.
Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.
bq
Para criar um novo conjunto de dados, use o comando
bq mk
com a flag --location
. Para uma lista completa de parâmetros possíveis, consulte a referência do comando bq mk --dataset
.
Para criar um conjunto de dados num projeto que não seja o projeto predefinido, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato:
PROJECT_ID:DATASET_ID
.
bq --location=LOCATION mk \ --dataset \ --default_kms_key=KMS_KEY_NAME \ --default_partition_expiration=PARTITION_EXPIRATION \ --default_table_expiration=TABLE_EXPIRATION \ --description="DESCRIPTION" \ --label=KEY_1:VALUE_1 \ --label=KEY_2:VALUE_2 \ --add_tags=KEY_3:VALUE_3[,...] \ --max_time_travel_hours=HOURS \ --storage_billing_model=BILLING_MODEL \ PROJECT_ID:DATASET_ID
Substitua o seguinte:
LOCATION
: a localização do conjunto de dados. Após a criação de um conjunto de dados, não é possível alterar a localização. Pode definir um valor predefinido para a localização através do ficheiro.bigqueryrc
.KMS_KEY_NAME
: o nome da chave do Cloud Key Management Service predefinida usada para proteger as tabelas criadas recentemente neste conjunto de dados, a menos que seja fornecida uma chave diferente no momento da criação. Não pode criar uma tabela encriptada pela Google num conjunto de dados com este parâmetro definido.PARTITION_EXPIRATION
: o tempo de vida predefinido (em segundos) para partições em tabelas particionadas recém-criadas. A expiração da partição predefinida não tem um valor mínimo. O tempo de expiração é avaliado como a data da partição mais o valor inteiro. Qualquer partição criada numa tabela particionada no conjunto de dados é eliminadaPARTITION_EXPIRATION
segundos após a data da partição. Se fornecer a flag--time_partitioning_expiration
quando criar ou atualizar uma tabela particionada, a data de validade da partição ao nível da tabela tem precedência sobre a data de validade da partição predefinida ao nível do conjunto de dados.TABLE_EXPIRATION
: o tempo de vida predefinido (em segundos) para tabelas criadas recentemente. O valor mínimo é de 3600 segundos (uma hora). O tempo de expiração é avaliado como a hora atual mais o valor inteiro. Qualquer tabela criada no conjunto de dados é eliminadaTABLE_EXPIRATION
segundos após a hora de criação. Este valor é aplicado se não definir uma data de validade da tabela quando criar a tabela.DESCRIPTION
: uma descrição do conjunto de dadosKEY_1:VALUE_1
: o par chave-valor que quer definir como a primeira etiqueta neste conjunto de dados eKEY_2:VALUE_2
é o par chave-valor que quer definir como a segunda etiqueta.KEY_3:VALUE_3
: o par chave-valor que quer definir como uma etiqueta no conjunto de dados. Adicione várias etiquetas com a mesma flag, separadas por vírgulas entre os pares chave:valor.HOURS
: a duração em horas do período de deslocação no tempo para o novo conjunto de dados. O valorHOURS
tem de ser um número inteiro expresso em múltiplos de 24 (48, 72, 96, 120, 144, 168) entre 48 (2 dias) e 168 (7 dias). 168 horas é a predefinição se esta opção não estiver especificada.BILLING_MODEL
: define o modelo de faturação de armazenamento para o conjunto de dados. Defina o valorBILLING_MODEL
comoPHYSICAL
para usar bytes físicos ao calcular os custos de armazenamento ou comoLOGICAL
para usar bytes lógicos.LOGICAL
é a predefinição.Quando altera o modelo de faturação de um conjunto de dados, a alteração demora 24 horas a entrar em vigor.
Depois de alterar o modelo de faturação de armazenamento de um conjunto de dados, tem de aguardar 14 dias antes de poder alterar novamente o modelo de faturação de armazenamento.
PROJECT_ID
: o ID do seu projeto.DATASET_ID
é o ID do conjunto de dados que está a criar.
Por exemplo, o comando seguinte cria um conjunto de dados denominado mydataset
com a localização dos dados definida como US
, um prazo de validade da tabela predefinido de 3600 segundos (1 hora) e uma descrição de This is my dataset
. Em vez de usar a flag --dataset
, o comando usa o atalho -d
. Se omitir -d
e --dataset
, o comando
cria um conjunto de dados por predefinição.
bq --location=US mk -d \ --default_table_expiration 3600 \ --description "This is my dataset." \ mydataset
Para confirmar que o conjunto de dados foi criado, introduza o comando bq ls
. Além disso, pode criar uma tabela quando cria um novo conjunto de dados com o seguinte formato: bq mk -t dataset.table
.
Para mais informações sobre como criar tabelas, consulte o artigo
Criar uma tabela.
Terraform
Use o recurso
google_bigquery_dataset
.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Crie um conjunto de dados
O exemplo seguinte cria um conjunto de dados denominado mydataset
:
Quando cria um conjunto de dados através do recurso google_bigquery_dataset
, concede automaticamente acesso ao conjunto de dados a todas as contas que são funções básicas ao nível do projeto.
Se executar o comando
terraform show
depois de criar o conjunto de dados, o
blocoaccess
para o conjunto de dados é semelhante ao seguinte:
Para conceder acesso ao conjunto de dados, recomendamos que use um dos
google_bigquery_iam
recursos, conforme mostrado no exemplo seguinte, a menos que planeie
criar objetos autorizados, como
vistas autorizadas, no conjunto de dados.
Nesse caso, use o recurso google_bigquery_dataset_access
. Consulte essa documentação para ver exemplos.
Crie um conjunto de dados e conceda-lhe acesso
O exemplo seguinte cria um conjunto de dados denominado mydataset
e, em seguida, usa o recurso google_bigquery_dataset_iam_policy
para conceder-lhe acesso.
Crie um conjunto de dados com uma chave de encriptação gerida pelo cliente
O exemplo seguinte cria um conjunto de dados denominado mydataset
e também usa os recursos
google_kms_crypto_key
e
google_kms_key_ring
para especificar uma chave do Cloud Key Management Service para o conjunto de dados. Tem de
ativar a API Cloud Key Management Service antes de executar este exemplo.
Para aplicar a configuração do Terraform num Google Cloud projeto, conclua os passos nas secções seguintes.
Prepare o Cloud Shell
- Inicie o Cloud Shell.
-
Defina o Google Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.
Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.
Prepare o diretório
Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).
-
No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão
.tf
, por exemplo,main.tf
. Neste tutorial, o ficheiro é denominadomain.tf
.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.
Copie o exemplo de código para o ficheiro
main.tf
criado recentemente.Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.
- Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
- Guarde as alterações.
-
Inicialize o Terraform. Só tem de fazer isto uma vez por diretório.
terraform init
Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção
-upgrade
:terraform init -upgrade
Aplique as alterações
-
Reveja a configuração e verifique se os recursos que o Terraform vai criar ou
atualizar correspondem às suas expetativas:
terraform plan
Faça as correções necessárias à configuração.
-
Aplique a configuração do Terraform executando o seguinte comando e introduzindo
yes
no comando:terraform apply
Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).
- Abra o seu Google Cloud projeto para ver os resultados. Na Google Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.
API
Chame o método datasets.insert
com um recurso de conjunto de dados definido.
C#
Antes de experimentar este exemplo, siga as C#instruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API C# BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Go
Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Java
Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Node.js
Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
PHP
Antes de experimentar este exemplo, siga as PHPinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API PHP BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Python
Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Ruby
Antes de experimentar este exemplo, siga as Rubyinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Ruby BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Atribua nomes aos conjuntos de dados
Quando cria um conjunto de dados no BigQuery, o nome do conjunto de dados tem de ser único para cada projeto. O nome do conjunto de dados pode conter o seguinte:
- Até 1024 carateres.
- Letras (maiúsculas ou minúsculas), números e sublinhados.
Os nomes dos conjuntos de dados são sensíveis a maiúsculas e minúsculas por predefinição. mydataset
e MyDataset
podem coexistir no mesmo projeto, a menos que um deles tenha a sensibilidade a maiúsculas e minúsculas desativada. Para ver exemplos, consulte Criar um conjunto de dados não sensível a maiúsculas e minúsculas e Recurso: conjunto de dados.
Os nomes dos conjuntos de dados não podem conter espaços nem carateres especiais, como -
, &
, @
ou %
.
Conjuntos de dados ocultos
Um conjunto de dados oculto é um conjunto de dados cujo nome começa com um sublinhado. Pode consultar tabelas e vistas em conjuntos de dados ocultos da mesma forma que o faria em qualquer outro conjunto de dados. Os conjuntos de dados ocultos têm as seguintes restrições:
- Estão ocultos no painel Explorador na Google Cloud consola.
- Não aparecem em nenhuma vista
INFORMATION_SCHEMA
. - Não podem ser usados com conjuntos de dados associados.
- Não podem ser usados como um conjunto de dados de origem com os seguintes recursos autorizados:
- Não aparecem no catálogo de dados (descontinuado) nem no catálogo universal do Dataplex.
Segurança do conjunto de dados
Para controlar o acesso a conjuntos de dados no BigQuery, consulte o artigo Controlar o acesso a conjuntos de dados. Para obter informações sobre a encriptação de dados, consulte o artigo Encriptação em repouso.
O que se segue?
- Para mais informações sobre como listar conjuntos de dados num projeto, consulte o artigo Listar conjuntos de dados.
- Para mais informações sobre os metadados dos conjuntos de dados, consulte o artigo Obter informações sobre conjuntos de dados.
- Para mais informações sobre como alterar as propriedades do conjunto de dados, consulte o artigo Atualizar conjuntos de dados.
- Para mais informações sobre a criação e gestão de etiquetas, consulte o artigo Criar e gerir etiquetas.
Experimente
Se está a usar o Google Cloud pela primeira vez, crie uma conta para avaliar o desempenho do BigQuery em cenários reais. Os novos clientes também recebem 300 USD em créditos gratuitos para executar, testar e implementar cargas de trabalho.
Experimentar o BigQuery gratuitamente