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 Explorer, expanda o projeto e selecione um conjunto de dados.
No painel Detalhes, clique no ícone de lápis ao lado de Descrição para editar o texto da descrição.
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.
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
:
ALTER SCHEMA mydataset SET OPTIONS( description="Description of mydataset" )
Para informações sobre como executar uma consulta SQL no BigQuery, consulte Como executar jobs de consulta interativa e em lote.
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 Explorer, expanda o projeto e selecione um conjunto de dados.
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 Save.
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
.
ALTER SCHEMA mydataset SET OPTIONS( default_table_expiration_days=3.75 )
Para informações sobre como executar uma consulta SQL no BigQuery, consulte Como executar jobs de consulta interativa e em lote.
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.
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
:
ALTER SCHEMA mydataset SET OPTIONS( default_partition_expiration_days=3.75 )
Para informações sobre como executar uma consulta SQL no BigQuery, consulte Como executar jobs de consulta interativa e em lote.
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
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
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.