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:
- Descrição
- prazo de validade padrão das tabelas novas
- validade da partição padrão das tabelas particionadas novas
- Controles de acesso
- Marcadores
Permissões necessárias
Para atualizar propriedades de conjuntos de dados, é necessário ter pelo menos as permissões bigquery.datasets.update
e bigquery.datasets.get
. Os
seguintes papéis predefinidos do IAM incluem as permissões bigquery.datasets.update
e bigquery.datasets.get
:
bigquery.dataOwner
bigquery.admin
Além disso, quando um usuário tem permissões bigquery.datasets.create
e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner
ao conjunto.
Com o acesso de bigquery.dataOwner
, os usuários conseguem atualizar as propriedades dos conjuntos de dados criados por eles.
Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Controle de acesso.
Como atualizar descrições de conjunto de dados
É possível atualizar a descrição de um conjunto de dados das seguintes maneiras:
- usando o Console do Cloud;
- usando o comando
bq
da ferramenta de linha de comandobq update
; - Chamada do método de API
datasets.patch
- usando bibliotecas de cliente;
Para atualizar a descrição de um conjunto de dados:
Console
No painel Recursos, selecione o conjunto de dados.
Na página Detalhes, clique no ícone de lápis ao lado de Descrição para editar o texto.
Insira uma nova ou edite uma descrição atual na caixa de diálogo. Clique em Atualizar para salvar o novo texto da descrição.
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 projetodataset
: 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 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 em Go.
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 em Java.
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 (links em inglês).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 BigQuery Node.js.
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.
Configure a propriedade Dataset.description e chame Client.update_dataset() (ambos em inglês) para enviar a atualização para a API.Como atualizar o prazo de validade padrão de tabelas
É possível atualizar o prazo de validade padrão da tabela de um conjunto de dados das seguintes maneiras:
- usando o Console do Cloud;
- usando o comando
bq
da ferramenta de linha de comandobq update
; - Chamada do 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 a configurar no nível do conjunto de dados e não defini-la quando a tabela for criada, a tabela nunca expirará, e você precisará excluí-la manualmente.
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 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 Recursos, selecione o conjunto de dados.
Na página 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 Save.
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. Especifique0
para remover o prazo de validade atual. Qualquer tabela criada no conjunto de dados será excluídainteger
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
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á em myotherproject
, e não no projeto padrão.
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
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 em Go.
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 em Java.
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 (links em inglês).Configure o prazo de validade padrão com o método Dataset.Builder.setDefaultTableLifetime() (link em inglês).
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 BigQuery Node.js.
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.
Configure a propriedade Dataset.default_table_expiration_ms e chame Client.update_dataset() para enviar a atualização para a API (links em inglês).Como 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
da ferramenta de linha de comandobq update
; - Chamada do 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 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 Cloud.
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. Especifique0
para remover o prazo de validade atual. Todas as partições nas tabelas particionadas recém-criadas serão excluídasinteger
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
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á em myotherproject
, e não no projeto padrão.
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
.
Como atualizar controles de acesso do 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 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:
- 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. - Visualização autorizada: fornece acesso de visualização ao conjunto de dados.
Para atualizar os controles de acesso em um conjunto de dados:
Console
Clique no conjunto de dados na seção Recursos do painel de navegação.
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:
Insira a entidade na caixa Adicionar membros.
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.
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á emmyotherproject
.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 entradasspecialGroup
:projectOwners
,projectWriters
,projectReaders
eallAuthenticatedUsers
. É possível adicionar, remover ou modificar qualquer uma destas opções:userByEmail
,groupByEmail
edomain
.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
.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á emmyotherproject
.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
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 em Go.
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 em Java.
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 (links em inglês).Configure os controles de acesso com o método Dataset.Builder.setAcl() (link em inglês).
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 BigQuery Node.js.
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.
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.Próximas etapas
- Para mais informações sobre como criar conjuntos de dados, consulte esta página.
- Consulte Como gerenciar conjuntos de dados, para mais informações.