Instruções da linguagem de controle de dados (DCL, na sigla em inglês) no SQL padrão

As instruções da linguagem de controle de dados (DCL, na sigla em inglês) do BigQuery permitem configurar e controlar recursos do BigQuery usando a sintaxe de consulta do SQL padrão.

Instruções do controle de acesso

Use estas instruções para conceder ou remover o acesso a recursos do BigQuery.

Para saber mais sobre como controlar o acesso a recursos específicos do BigQuery, consulte:

Permissões necessárias

As seguintes permissões são necessárias para executar as instruções GRANT e REVOKE.

Tipo de recurso Permissões
Conjunto de dados bigquery.datasets.update
Tabela bigquery.tables.setIamPolicy
Ver bigquery.tables.setIamPolicy

Instrução GRANT

Concede papéis a usuários nos recursos do BigQuery.

Sintaxe

GRANT role_list
  ON resource_type resource_name
  TO user_list

Em que:

  • role_list é um papel ou uma lista de papéis separados por vírgulas que contém as permissões que você quer conceder. Saiba mais sobre os tipos de papéis disponíveis em Noções básicas sobre papéis.

  • resource_type é o tipo de recurso ao qual o papel é aplicado. Os valores aceitos são: SCHEMA (equivalente ao conjunto de dados), TABLE, VIEW.

  • resource_name é o nome do recurso em que você quer conceder a permissão.

  • user_list é uma lista separada por vírgulas de usuários aos quais o papel é concedido.

user_list

Especifique os usuários usando os seguintes formatos:

Tipo de usuário Sintaxe Exemplo
Conta do Google user:$user@$domain user:first.last@example.com
Grupo do Google group:$group@$domain group:my-group@example.com
Conta de serviço serviceAccount:$user@$project.iam.gserviceaccount.com serviceAccount:robot@example.iam.gserviceaccount.com
Domínio do Google domain:$domain domain:example.com
Todas as contas do Google specialGroup:allAuthenticatedUsers specialGroup:allAuthenticatedUsers
Todos os usuários specialGroup:allUsers specialGroup:allUsers

Saiba mais sobre cada tipo de usuário da tabela em Conceitos relacionados à identidade.

Exemplo

O exemplo a seguir concede o papel bigquery.dataViewer aos usuários tom@example.com e sara@example.com em um conjunto de dados chamado my_dataset:

GRANT `roles/bigquery.dataViewer` ON SCHEMA `mycompany`.revenue
TO "user:tom@example.com", "user:sara@example.com"

Instrução REVOKE

Remove os papéis de uma lista de usuários nos recursos do BigQuery.

Sintaxe

REVOKE role_list
  ON {SCHEMA | TABLE | VIEW} resource_name
  FROM user_list

Em que:

  • role_list é um papel ou uma lista de papéis separados por vírgulas que contém as permissões que você quer remover. Saiba mais sobre os tipos de papéis disponíveis em Noções básicas sobre papéis.

  • resource type é o tipo de recurso do qual o papel será removido. Os valores aceitos são: SCHEMA (equivalente ao conjunto de dados), TABLE, VIEW.

  • resource_name é o nome do recurso no qual você quer revogar o papel.

  • user_list é uma lista separada por vírgulas de usuários que tiveram esse papel revogado.

Exemplo

O exemplo a seguir remove o papel bigquery.admin no conjunto de dados myProject.myDataset do grupo example-team@example.com e de uma conta de serviço:

REVOKE `roles/bigquery.admin` ON SCHEMA myProject.myDataset
FROM "group:example-team@example.com", "serviceAccount:user@test-project.iam.gserviceaccount.com"

Instruções de reserva

Use essas instruções para criar e excluir compromissos de capacidade, reservas e atribuições de reserva. Para mais informações, consulte Introdução às reservas.

Instrução CREATE CAPACITY

Compra slots criando um novo compromisso de capacidade.

CREATE CAPACITY
project_id.location_id.commitment_id
AS JSON
capacity_json_object

Em que:

  • project_id é o ID do projeto de administração que manterá a propriedade desse compromisso.
  • location_id é o local do projeto.
  • commitment_id é o ID do compromisso. O valor precisa ser exclusivo para o projeto e o local. Ele precisa começar e terminar com uma letra minúscula ou um número e conter apenas letras minúsculas, números e traços.
  • capacity_json_object é uma string JSON que descreve o compromisso de capacidade.

capacity_json_object

Especifica um objeto JSON que contém os seguintes campos:

NAME TYPE Detalhes
plan String O plano de compromisso a ser comprado. Os valores aceitos são: FLEX, MONTHLY, ANNUAL. Para mais informações, consulte Planos de compromisso;
renewal_plan String O plano de renovação de compromisso. Aplicável somente quando plan é ANNUAL. Para mais informações, consulte Como renovar compromissos.
slot_count Inteiro O número de slots no compromisso.

Exemplo

O exemplo a seguir cria um compromisso de capacidade de 100 slots flexíveis que estão localizados na região region-us e gerenciados por um projeto admin_project:

CREATE CAPACITY `admin_project.region-us.my-commitment`
AS JSON """{
 "slot_count": 100,
 "plan": "FLEX"
}"""

Instrução CREATE RESERVATION

Cria uma reserva.

CREATE RESERVATION
project_id.location_id.reservation_id
AS JSON
reservation_json_object

Em que:

  • project_id é o ID do projeto de administração em que o compromisso de capacidade foi criado.
  • location_id é o local do projeto.
  • reservation_id é o ID da reserva.
  • reservation_json_object é uma string JSON que descreve a reserva.

reservation_json_object

Especifica um objeto JSON que contém os seguintes campos:

NAME TYPE Detalhes
ignore_idle_slots Booleano Se o valor for true, a reserva usará apenas os slots provisionados para ele. O valor padrão é false. Para mais informações, consulte Slots inativos.
slot_capacity Inteiro o número de slots a serem alocados para a reserva.

Exemplo

O exemplo a seguir cria uma reserva de 100 slots no projeto admin_project:

CREATE RESERVATION `admin_project.region-us.prod`
AS JSON """{
 "slot_capacity": 100
}"""

Instrução CREATE ASSIGNMENT

Atribui um projeto, uma pasta ou uma organização a uma reserva.

CREATE ASSIGNMENT
project_id.location_id.reservation_id.assignment_id
AS JSON
assignment_json_object

Em que:

  • project_id é o ID do projeto de administração em que a reserva foi criada.
  • location_id é o local do projeto.
  • reservation_id é o ID da reserva.
  • assignment_id é o ID da atribuição. O valor precisa ser exclusivo para o projeto e o local. Ele precisa começar e terminar com uma letra minúscula ou um número e conter apenas letras minúsculas, números e traços.
  • assignment_json_object é uma string JSON que descreve a atribuição.

Para remover um projeto de qualquer reserva e usar o faturamento sob demanda, defina reservation_id como none.

assignment_json_object

Especifica um objeto JSON que contém os seguintes campos:

NAME TYPE Detalhes
assignee String O ID do projeto, da pasta ou da organização a ser atribuído à reserva.
job_type String o tipo de job a ser atribuído a essa reserva. Os valores aceitos incluem: QUERY, PIPELINE e ML_EXTERNAL. Para mais informações, consulte Atribuições.

Exemplo

O exemplo a seguir atribui o projeto my_project à reserva prod para jobs de consulta:

CREATE ASSIGNMENT `admin_project.region-us.prod.my_assignment`
AS JSON """{
 "assignee": "projects/my_project",
 "job_type": "QUERY"
}"""

O exemplo a seguir atribui uma organização à reserva prod para jobs de pipeline, como jobs de carregamento e de exportação:

CREATE ASSIGNMENT `admin_project.region-us.prod.my_assignment`
AS JSON """{
 "assignee": "organizations/1234",
 "job_type": "PIPELINE"
}"""

Instrução DROP CAPACITY

Exclui uma confirmação de capacidade.

DROP CAPACITY [IF EXISTS]
project_id.location_id.capacity-commitment-id

Em que:

  • IF EXISTS: se você incluir essa cláusula e o compromisso especificado não existir, a instrução será bem-sucedida sem ação. Se você omitir essa cláusula e o compromisso não existir, a instrução retornará um erro.
  • project_id é o ID do projeto de administração em que a reserva foi criada.
  • location_id é o local do projeto.
  • capacity-commitment-id é o ID do compromisso de capacidade.

Para encontrar o ID do compromisso de capacidade, consulte a tabela INFORMATION_SCHEMA.CAPACITY_COMMITMENTS_BY_PROJECT.

Exemplo

No exemplo a seguir, o compromisso de capacidade é excluído:

DROP RESERVATION `admin_project.region-us.1234`

Instrução DROP RESERVATION

Exclui uma reserva.

DROP RESERVATION [IF EXISTS]
project_id.location_id.reservation_id

Em que:

  • IF EXISTS: se você incluir essa cláusula e a reserva especificada não existir, a instrução será bem-sucedida sem ação. Se você omitir essa cláusula e a reserva não existir, a instrução retornará um erro.
  • project_id é o ID do projeto de administração em que a reserva foi criada.
  • location_id é o local do projeto.
  • reservation_id é o ID da reserva.

Exemplo

No exemplo a seguir, a reserva prod é excluída:

DROP RESERVATION `admin_project.region-us.prod`

Instrução DROP ASSIGNMENT

Exclui uma atribuição de reserva.

DROP ASSIGNMENT [IF EXISTS]
project_id.location_id.reservation_id.assignment_id

Em que:

  • IF EXISTS: se você incluir essa cláusula e a atribuição especificada não existir, a instrução será bem-sucedida sem ação. Se você omitir essa cláusula e a atribuição não existir, a instrução retornará um erro.
  • project_id é o ID do projeto de administração em que a reserva foi criada.
  • location_id é o local do projeto.
  • reservation_id é o ID da reserva.
  • assignment_id é o ID da atribuição.

É possível encontrar o ID da atribuição consultando a tabela INFORMATION_SCHEMA.ASSIGNMENTS_BY_PROJECT.

Exemplo

O exemplo a seguir exclui uma atribuição da reserva chamada prod:

DROP ASSIGNMENT `admin_project.region-us.prod.1234`