Atualizar propriedades do conjunto de dados

Neste documento, você verá como atualizar propriedades de conjuntos de dados no BigQuery. Depois de criar um conjunto de dados, é possível atualizar as seguintes propriedades:

Controles de acesso
Modelo de faturamento
Prazo de validade padrão das tabelas novas
Validade da partição padrão das tabelas particionadas novas
Modo de arredondamento padrão para novas tabelas
Descrição
Marcadores
Janelas de viagem no tempo

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento.

Permissões necessárias

Para atualizar as propriedades do conjunto de dados, você precisa das seguintes permissões do IAM:

bigquery.datasets.update
bigquery.datasets.setIamPolicy (obrigatório apenas ao atualizar os controles de acesso do conjunto de dados no console do Google Cloud)

O papel predefinido do IAM roles/bigquery.dataOwner inclui as permissões necessárias para atualizar as propriedades do conjunto de dados.

Além disso, se você tiver a permissão bigquery.datasets.create, será possível atualizar as propriedades dos conjuntos de dados que criar.

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

Atualizar descrições dos conjuntos de dados

É possível atualizar a descrição de um conjunto de dados das seguintes maneiras:

Usando o Console do Google Cloud.
usando o comando bq update da ferramenta de linha de comando bq;
chamando o método de API datasets.patch;
usando bibliotecas de cliente.

Para atualizar a descrição de um conjunto de dados:

Console

No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Expanda a opção Ações e clique em Abrir.
No painel Detalhes, clique em Editar detalhes para editar o texto da descrição.

Na caixa de diálogo Editar detalhe exibida, faça o seguinte:
1. No campo Descrição, insira uma descrição ou edite a atual.
2. Para salvar o novo texto da descrição, clique em Salvar.

SQL

Para atualizar a descrição de um conjunto de dados, use a instrução ALTER SCHEMA SET OPTIONS para definir a opção description.

No exemplo a seguir, definimos a descrição em um conjunto de dados chamado mydataset:

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

Ir para o BigQuery

No editor de consultas, digite a seguinte instrução:

 ALTER SCHEMA mydataset
 SET OPTIONS (
     description = 'Description of mydataset');

Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq update com a sinalização --description. Caso esteja atualizando um conjunto de dados em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.

bq update \
--description "string" \
project_id:dataset

Substitua:

string: o texto que descreve o conjunto de dados entre aspas.
project_id: ID do projeto
dataset: o nome do conjunto de dados que você está atualizando.

Exemplos:

Use o comando a seguir para alterar a descrição de mydataset para "Descrição de mydataset". mydataset está no projeto padrão.

bq update --description "Description of mydataset" mydataset

Use o comando a seguir para alterar a descrição de mydataset para "Descrição de mydataset". O conjunto de dados está em myotherproject, e não no projeto padrão.

bq update \
--description "Description of mydataset" \
myotherproject:mydataset

API

Chame datasets.patch e atualize a propriedade description no recurso de conjunto de dados. Como o método datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.patch.

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.

import (
	"context"
	"fmt"

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

// updateDatasetDescription demonstrates how the Description metadata of a dataset can
// be read and modified.
func updateDatasetDescription(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()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}
	update := bigquery.DatasetMetadataToUpdate{
		Description: "Updated Description.",
	}
	if _, err = ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	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.

Crie uma instância Dataset.Builder a partir de uma instância Dataset atual com o método Dataset.toBuilder(). Configure o objeto de builder do conjunto de dados. Crie o conjunto de dados atualizado com o método Dataset.Builder.build() e chame o método Dataset.update() para enviar a atualização para a API.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

public class UpdateDatasetDescription {

  public static void runUpdateDatasetDescription() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String newDescription = "this is the new dataset description";
    updateDatasetDescription(datasetName, newDescription);
  }

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

      Dataset dataset = bigquery.getDataset(datasetName);
      bigquery.update(dataset.toBuilder().setDescription(newDescription).build());
      System.out.println("Dataset description updated successfully to " + newDescription);
    } catch (BigQueryException e) {
      System.out.println("Dataset description was not updated \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.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateDatasetDescription() {
  // Updates a dataset's description.

  // Retreive current dataset metadata
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Set new dataset description
  const description = 'New dataset description.';
  metadata.description = description;

  const [apiResponse] = await dataset.setMetadata(metadata);
  const newDescription = apiResponse.description;

  console.log(`${datasetId} description: ${newDescription}`);
}

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.

Configure a propriedade Dataset.description e chame Client.update_dataset() para enviar a atualização para a API.


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 fetch.
# dataset_id = 'your-project.your_dataset'

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.description = "Updated description."
dataset = client.update_dataset(dataset, ["description"])  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with description '{}'.".format(
        full_dataset_id, dataset.description
    )
)

Atualizar os prazos de validade padrão da tabela

É possível atualizar o prazo de validade padrão da tabela de um conjunto de dados das seguintes maneiras:

Usando o Console do Google Cloud.
usando o comando bq update da ferramenta de linha de comando bq;
chamando o método de API datasets.patch;
usando bibliotecas de cliente.

É possível configurar o prazo de validade padrão da tabela no nível do conjunto de dados ou defini-lo quando a tabela é criada. Ao fazer isso durante a criação da tabela, a expiração padrão da tabela do conjunto de dados será ignorada. Se você não configurar uma expiração de tabela padrão no nível do conjunto de dados e não defini-la quando a tabela for criada, a tabela nunca vai expirar, e você precisará excluí-la manualmente. Quando uma tabela expira, ela é excluída com todos os dados que ela contém.

Ao atualizar a configuração da validade padrão da tabela de um conjunto de dados:

Se você alterar o valor de Never para um prazo de validade definido, todas as tabelas no conjunto de dados só expirarão caso esse prazo tenha sido definido na tabela quando ela foi criada.
Se você estiver alterando o valor da validade padrão de tabelas, todas as tabelas atuais expirarão de acordo com a configuração de validade original. A nova configuração de expiração será aplicada a todas as novas tabelas criadas no conjunto de dados, a menos que você especifique uma expiração diferente na tabela quando ela for criada.

O valor da expiração padrão da tabela é expresso de diferentes formas, dependendo do local em que você o define. Use o método que garanta o nível apropriado de granularidade:

No console do Google Cloud, a validade é expressa em dias.
Na ferramenta de linha de comando bq, a validade é expressa em segundos.
Na API, em milissegundos.

Para atualizar o prazo de validade padrão de um conjunto de dados:

Console

No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Expanda a opção Ações e clique em Abrir.
No painel de detalhes, clique no ícone de lápis ao lado de Informações do conjunto de dados para editar a validade.
Na caixa de diálogo Informações do conjunto de dados, na seção Expiração da tabela padrão, insira um valor para Número de dias após a criação da tabela.
Clique em Salvar.

SQL

Para atualizar o prazo de validade da tabela padrão, use a instrução ALTER SCHEMA SET OPTIONS para definir a opção default_table_expiration_days.

O exemplo a seguir atualiza a validade padrão de tabelas de um conjunto de dados chamado mydataset.

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

Ir para o BigQuery

No editor de consultas, digite a seguinte instrução:

 ALTER SCHEMA mydataset
 SET OPTIONS(
     default_table_expiration_days = 3.75);

Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Para atualizar o prazo de validade padrão de tabelas recém-criadas em um conjunto de dados, digite o comando bq update com a sinalização --default_table_expiration. Caso esteja atualizando um conjunto de dados em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.

bq update \
--default_table_expiration integer \
project_id:dataset

Substitua:

integer: 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 é a soma do horário UTC atual com o valor inteiro. Especifique 0 para remover o prazo de validade atual. Qualquer tabela criada no conjunto de dados será excluída integer segundos após a hora de criação. Esse valor será aplicado caso a validade da tabela não seja definida quando ela for criada.
project_id: o ID do projeto.
dataset: o nome do conjunto de dados que você está atualizando.

Exemplos:

Digite o comando a seguir para definir a validade padrão de tabelas para novas tabelas criadas em mydataset como duas horas (7.200 segundos) a partir do horário atual. O conjunto de dados está no projeto padrão.

bq update --default_table_expiration 7200 mydataset

bq update --default_table_expiration 7200 myotherproject:mydataset

API

Chame datasets.patch e atualize a propriedade defaultTableExpirationMs no recurso de conjunto de dados. A expiração é expressa em milissegundos na API. Como o método datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.patch.

Go

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

import (
	"context"
	"fmt"
	"time"

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

// updateDatasetDefaultExpiration demonstrats setting the default expiration of a dataset
// to a specific retention period.
func updateDatasetDefaultExpiration(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()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}
	update := bigquery.DatasetMetadataToUpdate{
		DefaultTableExpiration: 24 * time.Hour,
	}
	if _, err := client.Dataset(datasetID).Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

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

Configure o prazo de validade padrão com o método Dataset.Builder.setDefaultTableLifetime() (link em inglês).

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 java.util.concurrent.TimeUnit;

public class UpdateDatasetExpiration {

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

  public static void updateDatasetExpiration(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();

      // Update dataset expiration to one day
      Long newExpiration = TimeUnit.MILLISECONDS.convert(1, TimeUnit.DAYS);

      Dataset dataset = bigquery.getDataset(datasetName);
      bigquery.update(dataset.toBuilder().setDefaultTableLifetime(newExpiration).build());
      System.out.println("Dataset description updated successfully to " + newExpiration);
    } catch (BigQueryException e) {
      System.out.println("Dataset expiration was not updated \n" + e.toString());
    }
  }
}

Node.js

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateDatasetExpiration() {
  // Updates the lifetime of all tables in the dataset, in milliseconds.

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

  // Retreive current dataset metadata
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Set new dataset metadata
  const expirationTime = 24 * 60 * 60 * 1000;
  metadata.defaultTableExpirationMs = expirationTime.toString();

  const [apiResponse] = await dataset.setMetadata(metadata);
  const newExpirationTime = apiResponse.defaultTableExpirationMs;

  console.log(`${datasetId} expiration: ${newExpirationTime}`);
}

Python

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

Configure a propriedade Dataset.default_table_expiration_ms e chame Client.update_dataset() para enviar a atualização para a API.


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 fetch.
# dataset_id = 'your-project.your_dataset'

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.default_table_expiration_ms = 24 * 60 * 60 * 1000  # In milliseconds.

dataset = client.update_dataset(
    dataset, ["default_table_expiration_ms"]
)  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset {} with new expiration {}".format(
        full_dataset_id, dataset.default_table_expiration_ms
    )
)

Atualizar os prazos de validade padrão de partições

É possível atualizar a validade padrão de partições de um conjunto de dados das seguintes maneiras:

usando o comando bq update da ferramenta de linha de comando bq;
chamando o método de API datasets.patch;
usando bibliotecas de cliente.

A configuração ou atualização da validade da partição padrão de um conjunto de dados não é compatível com o console do Google Cloud.

É possível definir um prazo de validade padrão de partições no nível do conjunto de dados que afete todas as tabelas particionadas recém-criadas. Se preferir, defina um prazo de validade de partições individualmente durante a criação das tabelas particionadas. Se você definir os prazos de validade padrão de partições e tabelas no nível do conjunto de dados, as novas tabelas particionadas terão apenas uma validade de partições. Quando ambas as opções são definidas, a validade padrão de partições modifica a validade padrão de tabelas.

Se você definir o prazo de validade da partição no momento da criação da tabela, esse valor modificará a validade padrão definida no nível do conjunto de dados.

Se você não definir uma validade padrão de partição no nível do conjunto de dados nem a validade de partição durante a criação da tabela, as partições nunca expirarão e será necessário excluí-las manualmente.

Quando definimos uma validade padrão de partições em um conjunto de dados, esse prazo é aplicado a todas as partições nas tabelas particionadas criadas no conjunto de dados. Quando definimos a validade de partições em uma tabela, esse prazo é aplicado a todas as partições criadas na tabela especificada. Atualmente, não é possível aplicar prazos de validade distintos a diferentes partições na mesma tabela.

Ao atualizar a validade padrão de partição de um conjunto de dados:

altere o valor de never para um prazo de validade definido. Assim, todas as partições atuais das tabelas particionadas no conjunto de dados não expirarão, a menos que tal prazo tenha sido definido nas tabelas quando elas foram criadas;
altere o valor de validade padrão de partição. Assim, todas as partições nas tabelas particionadas atuais expirarão de acordo com o prazo original. A nova validade padrão de partição será aplicada a todas as novas tabelas particionadas criadas no conjunto de dados, a menos que você especifique um prazo diferente durante a criação das tabelas.

O valor da validade padrão da tabela é expresso de formas diferentes, dependendo do local em que é definido. Use o método que garanta o nível apropriado de granularidade:

Na ferramenta de linha de comando bq, a validade é expressa em segundos.
Na API, em milissegundos.

Para atualizar o prazo de validade da partição padrão de um conjunto de dados:

Console

A atualização da validade padrão de partições de um conjunto de dados não é compatível com o console do Google Cloud.

SQL

Para atualizar o prazo de validade padrão da partição, use a instrução ALTER SCHEMA SET OPTIONS para definir a opção default_partition_expiration_days.

O exemplo a seguir atualiza a validade padrão de partições de um conjunto de dados chamado mydataset:

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

Ir para o BigQuery

No editor de consultas, digite a seguinte instrução:

 ALTER SCHEMA mydataset
 SET OPTIONS(
     default_partition_expiration_days = 3.75);

Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Para atualizar o prazo de validade padrão de um conjunto de dados, insira o comando bq update com a sinalização --default_partition_expiration. Caso esteja atualizando um conjunto de dados em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.

bq update \
--default_partition_expiration integer \
project_id:dataset

Substitua:

integer: a vida útil padrão, em segundos, das partições nas tabelas particionadas recém-criadas. Esta sinalização não tem valor mínimo. Especifique 0 para remover o prazo de validade atual. Todas as partições nas tabelas particionadas recém-criadas serão excluídas integer segundos após a data UTC da partição. Esse valor será aplicado se você não definir uma validade de partição na tabela quando ela for criada.
project_id: o ID do projeto.
dataset: o nome do conjunto de dados que você está atualizando.

Exemplos:

Digite o comando a seguir para definir a validade padrão de partições para tabelas particionadas novas criadas em mydataset como 26 horas (93.600 segundos). O conjunto de dados está no projeto padrão.

bq update --default_partition_expiration 93600 mydataset

bq update --default_partition_expiration 93600 myotherproject:mydataset

API

Chame datasets.patch e atualize a propriedade defaultPartitionExpirationMs no recurso de conjunto de dados. A validade é expressa em milissegundos. Como o método datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.patch.

Atualizar modo de arredondamento

É possível atualizar o modo de arredondamento padrão de um conjunto de dados usando a instrução DDL ALTER SCHEMA SET OPTIONS. O exemplo a seguir atualiza o modo de arredondamento padrão de mydataset para ROUND_HALF_EVEN.

ALTER SCHEMA mydataset
SET OPTIONS (
  default_rounding_mode = "ROUND_HALF_EVEN");

Isso define o modo de arredondamento padrão para novas tabelas criadas no conjunto de dados. Ela não afeta as novas colunas adicionadas às tabelas atuais. Definir o modo de arredondamento padrão em uma tabela no conjunto de dados modifica essa opção.

Atualizar controles de acesso ao conjunto de dados

O processo de atualização dos controles de acesso do conjunto de dados é muito semelhante ao de atribuição. Não é possível aplicar controles de acesso durante a criação do conjunto de dados usando o console do Google Cloud ou a ferramenta de linha de comando bq. Você precisa primeiro criar o conjunto e atualizar os controles de acesso dele. Com a API, é possível atualizar os controles de acesso ao conjunto de dados chamando o método datasets.patch.

Ao atualizar os controles de acesso em um conjunto de dados, é possível modificar o acesso das seguintes entidades:

Principais do IAM:
- E-mail da Conta do Google: concede acesso ao conjunto de dados a uma conta individual do Google.
- Grupo do Google: concede acesso ao conjunto de dados a todos os membros de um grupo do Google.
- Domínio do Google Apps: concede acesso ao conjunto de dados a todos os usuários e grupos em um domínio do Google.
- Conta de serviço: concede a uma conta de serviço o acesso ao conjunto de dados.
- Qualquer pessoa: insira allUsers para conceder acesso ao público em geral.
- Todas as Contas do Google: insira allAuthenticatedUsers para conceder acesso a qualquer usuário conectado a uma Conta do Google.
Tipos de recurso
- Conjuntos de dados autorizados: concede acesso a um conjunto de dados autorizado ao conjunto.
- Visualização autorizada: fornece acesso de visualização ao conjunto de dados.
- Funções autorizadas: concede acesso a uma função de tabela ou UDF autorizada ao conjunto de dados.

Para atualizar os controles de acesso em um conjunto de dados:

Console

No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Expanda a opção Ações e clique em Abrir.
Clique em Compartilhar conjunto de dados.
Para excluir as entradas existentes, na caixa de diálogo Compartilhar conjunto de dados, expanda a entrada e clique no ícone de excluir (lixeira).
Na caixa de diálogo Compartilhar conjunto de dados, para adicionar novas entradas:
1. Insira a entidade na caixa Adicionar participantes.
2. Em Selecionar um papel, escolha um papel adequado do IAM na lista. Para mais informações sobre as permissões atribuídas a cada papel predefinido do BigQuery, consulte a página Papéis e permissões predefinidas.
3. Clique em Adicionar.
Para adicionar uma visualização autorizada, clique na guia Visualização autorizada e insira o projeto, o conjunto de dados e a visualização. Depois clique em Adicionar.
Quando terminar de adicionar ou excluir os controles de acesso, clique em Concluído.

bq

Use o comando show para gravar as informações atuais do conjunto de dados, incluindo controles de acesso, em um arquivo JSON. Se o conjunto de dados estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.
```
bq show \
--format=prettyjson \
project_id:dataset > path_to_file
```
Substitua:
- project_id: o ID do projeto.
- dataset: o nome do conjunto de dados.
- path_to_file: o caminho para o arquivo JSON em sua máquina local.
Exemplos:

Digite o comando a seguir para gravar os controles de acesso para mydataset em um arquivo JSON. mydataset está no projeto padrão.
```
bq show --format=prettyjson mydataset > /tmp/mydataset.json
```
Digite o comando a seguir para gravar os controles de acesso para mydataset em um arquivo JSON. mydataset está em myotherproject.
```
bq show --format=prettyjson \
myotherproject:mydataset > /tmp/mydataset.json
```

Faça suas alterações na seção "access" do arquivo JSON. É possível adicionar ou remover qualquer uma das entradas specialGroup: projectOwners, projectWriters, projectReaders e allAuthenticatedUsers. É possível adicionar, remover ou modificar qualquer uma destas opções: userByEmail, groupByEmail e domain.

Por exemplo, a seção "access" do arquivo JSON de um conjunto de dados tem esta aparência:

{
 "access": [
  {
   "role": "READER",
   "specialGroup": "projectReaders"
  },
  {
   "role": "WRITER",
   "specialGroup": "projectWriters"
  },
  {
   "role": "OWNER",
   "specialGroup": "projectOwners"
  }
  {
   "role": "READER",
   "specialGroup": "allAuthenticatedUsers"
  }
  {
   "role": "READER",
   "domain": "[DOMAIN_NAME]"
  }
  {
   "role": "WRITER",
   "userByEmail": "[USER_EMAIL]"
  }
  {
   "role": "READER",
   "groupByEmail": "[GROUP_EMAIL]"
  }
 ],
}

Quando as edições estiverem concluídas, use o comando update e inclua o arquivo JSON usando a sinalização --source. Se o conjunto de dados estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.

Cuidado: quando você aplica o arquivo JSON que contém os controles de acesso, os controles de acesso atuais são substituídos.
```
bq update --source path_to_file project_id:dataset
```
Substitua:
- path_to_file: o caminho para o arquivo JSON em sua máquina local.
- project_id: o ID do projeto.
- dataset: o nome do conjunto de dados.
Exemplos:

Digite o comando a seguir para atualizar os controles de acesso para mydataset. mydataset está no projeto padrão.
```
bq update --source /tmp/mydataset.json mydataset
```
Digite o comando a seguir para atualizar os controles de acesso para mydataset. mydataset está em myotherproject.
```
bq update --source /tmp/mydataset.json myotherproject:mydataset
```
Para verificar as alterações no controle de acesso, insira o comando show novamente sem gravar as informações em um arquivo.
```
bq show --format=prettyjson dataset
```
ou
```
bq show --format=prettyjson project_id:dataset
```

API

Chame datasets.patch e atualize a propriedade access no recurso de conjunto de dados.

Como datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.patch para atualizar os controles de acesso.

Go

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

import (
	"context"
	"fmt"

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

// updateDatasetAccessControl demonstrates how the access control policy of a dataset
// can be amended by adding an additional entry corresponding to a specific user identity.
func updateDatasetAccessControl(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()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}
	// Append a new access control entry to the existing access list.
	update := bigquery.DatasetMetadataToUpdate{
		Access: append(meta.Access, &bigquery.AccessEntry{
			Role:       bigquery.ReaderRole,
			EntityType: bigquery.UserEmailEntity,
			Entity:     "sample.bigquery.dev@gmail.com"},
		),
	}

	// Leverage the ETag for the update to assert there's been no modifications to the
	// dataset since the metadata was originally read.
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

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

Configure os controles de acesso com o método Dataset.Builder.setAcl() (link em inglês).

import com.google.cloud.bigquery.Acl;
import com.google.cloud.bigquery.Acl.Role;
import com.google.cloud.bigquery.Acl.User;
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 java.util.ArrayList;

public class UpdateDatasetAccess {

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

  public static void updateDatasetAccess(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();

      Dataset dataset = bigquery.getDataset(datasetName);

      // Create a new ACL granting the READER role to "sample.bigquery.dev@gmail.com"
      // For more information on the types of ACLs available see:
      // https://cloud.google.com/storage/docs/access-control/lists
      Acl newEntry = Acl.of(new User("sample.bigquery.dev@gmail.com"), Role.READER);

      // Get a copy of the ACLs list from the dataset and append the new entry
      ArrayList<Acl> acls = new ArrayList<>(dataset.getAcl());
      acls.add(newEntry);

      bigquery.update(dataset.toBuilder().setAcl(acls).build());
      System.out.println("Dataset Access Control updated successfully");
    } catch (BigQueryException e) {
      System.out.println("Dataset Access control was not updated \n" + e.toString());
    }
  }
}

Node.js

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateDatasetAccess() {
  // Updates a datasets's access controls.

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

  // Create new role metadata
  const newRole = {
    role: 'READER',
    entity_type: 'userByEmail',
    userByEmail: 'sample.bigquery.dev@gmail.com',
  };

  // Retreive current dataset metadata
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add new role to role acess array
  metadata.access.push(newRole);
  const [apiResponse] = await dataset.setMetadata(metadata);
  const newAccessRoles = apiResponse.access;
  newAccessRoles.forEach(role => console.log(role));
}

Python

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

Defina a propriedade dataset.access_entries com os controles de acesso de um conjunto de dados. Em seguida, chame a função client.update_dataset() para atualizar a propriedade.


# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
dataset_id = "your-project.your_dataset"

# TODO(developer): Set entity_id to the ID of the email or group from whom
# you are adding access. Alternatively, to the JSON REST API representation
# of the entity, such as a view's table reference.
entity_id = "user-or-group-to-add@example.com"

from google.cloud.bigquery.enums import EntityTypes

# TODO(developer): Set entity_type to the type of entity you are granting access to.
# Common types include:
#
# * "userByEmail" -- A single user or service account. For example "fred@example.com"
# * "groupByEmail" -- A group of users. For example "example@googlegroups.com"
# * "view" -- An authorized view. For example
#       {"projectId": "p", "datasetId": "d", "tableId": "v"}
#
# For a complete reference, see the REST API reference documentation:
# https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets#Dataset.FIELDS.access
entity_type = EntityTypes.GROUP_BY_EMAIL

# TODO(developer): Set role to a one of the "Basic roles for datasets"
# described here:
# https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
role = "READER"

from google.cloud import bigquery

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

dataset = client.get_dataset(dataset_id)  # Make an API request.

entries = list(dataset.access_entries)
entries.append(
    bigquery.AccessEntry(
        role=role,
        entity_type=entity_type,
        entity_id=entity_id,
    )
)
dataset.access_entries = entries

dataset = client.update_dataset(dataset, ["access_entries"])  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with modified user permissions.".format(full_dataset_id)
)

Atualizar janelas de viagem no tempo

É possível atualizar a janela de viagem no tempo de um conjunto de dados das seguintes maneiras:

Usando o Console do Google Cloud.
usando a instrução ALTER SCHEMA SET OPTIONS.
Use o comando bq update da ferramenta de linha de comando bq.
chamando o método da API datasets.patch ou datasets.update; O método update substitui todo o recurso do conjunto de dados, enquanto o método patch substitui apenas os campos fornecidos no recurso do conjunto de dados enviado.

Para mais informações sobre a janela de viagem no tempo, consulte Configurar a janela de viagem no tempo.

Para atualizar a janela de tempo de viagem de um conjunto de dados:

Console

No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Expanda a opção Ações e clique em Abrir.
No painel Detalhes, clique em Editar detalhes.
Expanda Opções avançadas e selecione a janela de viagem no tempo que vai ser usada.
Clique em Salvar.

SQL

Use a instrução ALTER SCHEMA SET OPTIONS com a opção max_time_travel_hours para especificar a janela de tempo de viagem ao alterar um conjunto de dados. O valor max_time_travel_hours precisa 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).

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

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
ALTER SCHEMA DATASET_NAME
SET OPTIONS(
  max_time_travel_hours = HOURS);
```
Substitua:
- DATASET_NAME: o nome do conjunto de dados que você está atualizando.
- HOURS pela duração da janela de viagem no tempo em horas.
Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq update com a sinalização --max_time_travel_hours para especificar a janela de tempo de viagem ao alterar um conjunto de dados. O valor --max_time_travel_hours precisa 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).

bq update \
--dataset=true --max_time_travel_hours=HOURS \
PROJECT_ID:DATASET_NAME

Substitua:

PROJECT_ID: ID do projeto
DATASET_NAME: o nome do conjunto de dados que você está atualizando.
HOURS com a duração da janela de viagem no tempo em horas

API

Chame o método datasets.patch ou datasets.update com um recurso de conjunto de dados definido. em que você especificou um valor para o campo maxTimeTravelHours. O valor maxTimeTravelHours precisa 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).

Atualizar modelos de faturamento do armazenamento

Você pode alterar o modelo de faturamento do armazenamento para um conjunto de dados. Defina o valor de storage_billing_model como PHYSICAL para usar bytes físicos ao calcular mudanças no armazenamento ou como LOGICAL para usar bytes lógicos. O padrão é LOGICAL.

Leva 24 horas para alterar o modelo de faturamento de um conjunto de dados.

Depois de alterar o modelo de faturamento do armazenamento de um conjunto de dados, aguarde 14 dias antes de alterar o modelo de faturamento do armazenamento novamente.

Console

No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Expanda a opção Ações e clique em Abrir.
No painel Detalhes, clique em Editar detalhes.
Expanda Opções avançadas e selecione Ativar modelo de faturamento de armazenamento físico para usar o faturamento de armazenamento físico, ou desmarque essa opção para usar o faturamento de armazenamento lógico.
Clique em Salvar.

SQL

Para atualizar o modelo de faturamento de um conjunto de dados, use a instrução ALTER SCHEMA SET OPTIONS e defina a opção storage_billing_model:

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

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
ALTER SCHEMA DATASET_NAME
SET OPTIONS(
 storage_billing_model = 'BILLING_MODEL');
```
Substitua:
- DATASET_NAME pelo nome do conjunto de dados que você está alterando
- BILLING_MODEL pelo tipo de armazenamento que você quer usar, LOGICAL ou PHYSICAL
Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

Para atualizar o modelo de faturamento do armazenamento para todos os conjuntos de dados em um projeto, use a seguinte consulta SQL para cada região em que os conjuntos de dados estão localizados:

FOR record IN
 (SELECT CONCAT(catalog_name, '.', schema_name) AS dataset_path
 FROM PROJECT_ID.region-REGION.INFORMATION_SCHEMA.SCHEMATA)
DO
 EXECUTE IMMEDIATE
   "ALTER SCHEMA `" || record.dataset_path || "` SET OPTIONS(storage_billing_model = 'BILLING_MODEL')";
END FOR;

Substitua:

PROJECT_ID pelo ID do projeto;
REGION com um qualificador de região
BILLING_MODEL pelo tipo de armazenamento que você quer usar, LOGICAL ou PHYSICAL

bq

Para atualizar o modelo de faturamento de um conjunto de dados, use o bq update comando e defina a sinalização --storage_billing_model:

bq update -d --storage_billing_model=BILLING_MODEL PROJECT_ID:DATASET_NAME

Substitua:

PROJECT_ID: ID do projeto
DATASET_NAME: o nome do conjunto de dados que você está atualizando.
BILLING_MODEL: o tipo de armazenamento que você quer usar, LOGICAL ou PHYSICAL

API

Chame o método datasets.update com um recurso de conjunto de dados definido em que o campo storageBillingModel esteja definido.

O exemplo a seguir mostra como chamar datasets.update usando curl:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X PUT https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID -d '{"datasetReference": {"projectId": "PROJECT_ID", "datasetId": "DATASET_NAME"}, "storageBillingModel": "BILLING_MODEL"}'

Substitua:

PROJECT_ID: ID do projeto
DATASET_NAME: o nome do conjunto de dados que você está atualizando.
BILLING_MODEL: o tipo de armazenamento que você quer usar, LOGICAL ou PHYSICAL

Segurança do conjunto de dados

Para controlar o acesso a conjuntos de dados no BigQuery, consulte Como controlar o acesso a conjuntos de dados. Para saber mais sobre criptografia de dados, consulte Criptografia em repouso.

A seguir

Para mais informações sobre como criar conjuntos de dados, consulte esta página.
Consulte Como gerenciar conjuntos de dados, para mais informações.