Depois de enviar um job do BigQuery, é possível visualizar os dados dele, cancelá-lo, executá-lo novamente ou listar jobs.
Quando um job é enviado, ele pode estar em um destes três estados:
PENDING
(programado)RUNNING
DONE
(informado comoSUCCESS
ouFAILURE
se o job for concluído com erros)
Como ver dados do job
Veja os dados e metadados do job usando o Console do GCP, a IU da Web clássica, a CLI e a API. Esses dados incluem detalhes como o tipo, o estado e o usuário que executou o job.
Permissões exigidas
Para acessar os dados e metadados do job, é necessário ter, no mínimo, permissões bigquery.jobs.get
. O papel predefinido do Cloud IAM a seguir inclui permissões bigquery.jobs.get
:
bigquery.admin
Se você conceder a uma conta o papel bigquery.admin
, o usuário poderá visualizar todos os dados do job no projeto, independentemente de quem o enviou.
As permissões bigquery.jobs.get
para jobs autocriados são concedidas aos seguintes papéis: Esses usuários só podem visualizar os dados dos jobs que eles enviam:
bigquery.user
bigquery.jobUser
Para mais informações sobre papéis e permissões do Cloud IAM no BigQuery, consulte Controle de acesso.
Como visualizar informações sobre jobs
Para visualizar informações sobre um job:
Console
No painel de navegação, clique em Histórico da tarefa ou em Histórico de consultas para mais informações sobre jobs de consulta.
Clique em Histórico pessoal para visualizar os detalhes dos seus jobs. Clique em Histórico do projeto para visualizar os detalhes de todos os jobs executados no projeto.
IU clássica
No painel de navegação, clique em Histórico da tarefa ou em Histórico de consultas para mais informações sobre jobs de consulta.
Na seção Jobs recentes, clique no job para ver os detalhes. No caso de jobs de consulta, clique na guia Histórico de consultas para visualizar os detalhes do job.
CLI
Emita o comando bq show
com a sinalização -j
e o parâmetro "job id".
Quando você fornece o ID do job, é possível usar o código totalmente qualificado ou a forma abreviada. Por exemplo, os IDs de jobs, listados na IU da Web do BigQuery, são totalmente qualificados e incluem o projeto e o local:
my-project-1234:US.bquijob_123x456_123y123z123c
Os IDs dos jobs na ferramenta de linha de comando são listados usando a forma abreviada e não incluem o código e o local do projeto:
bquijob_123x456_123y123z123c
Para especificar o local do job, forneça a sinalização --location
e defina o valor do local. Essa sinalização é opcional, caso seja usado o ID do job totalmente qualificado. Se você incluir a sinalização --location
e estiver usando o ID do job totalmente qualificado, a sinalização --location
será ignorada.
O comando a seguir solicita informações sobre um job:
bq --location=location show -j job_id
Em que:
- location é opcional. Ele é o nome do local em que o job é executado. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como
asia-northeast1
. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc. - job_id é o ID do job.
Exemplos:
O comando a seguir recebe informações resumidas sobre o job US.bquijob_123x456_123y123z123c
em execução em myproject
.
bq show -j myproject:US.bquijob_123x456_123y123z123c
A saída tem esta aparência:
Job Type State Start Time Duration User Email Bytes Processed Bytes Billed Billing Tier Labels ---------- --------- ----------------- ---------- ------------------- ----------------- -------------- -------------- -------- extract SUCCESS 06 Jul 11:32:10 0:01:41 user@example.com
Para ver os detalhes completos do job, insira:
bq show --format=prettyjson -j myproject:US.bquijob_123x456_789y123z456c
A saída tem esta aparência:
{ "configuration": { "extract": { "compression": "NONE", "destinationUri": "[URI removed]", "destinationUris": [ "[URI removed]" ], "sourceTable": { "datasetId": "github_repos", "projectId": "bigquery-public-data", "tableId": "commits" } } }, "etag": "\"[etag removed]\"", "id": "myproject:bquijob_123x456_789y123z456c", "jobReference": { "jobId": "bquijob_123x456_789y123z456c", "projectId": "[Project ID removed]" }, "kind": "bigquery#job", "selfLink": "https://www.googleapis.com/bigquery/v2/projects/federated-testing/jobs/bquijob_123x456_789y123z456c", "statistics": { "creationTime": "1499365894527", "endTime": "1499365894702", "startTime": "1499365894702" }, "status": { "errorResult": { "debugInfo": "[Information removed for readability]", "message": "Operation cannot be performed on a nested schema. Field: author", "reason": "invalid" }, "errors": [ { "message": "Operation cannot be performed on a nested schema. Field: author", "reason": "invalid" } ], "state": "DONE" }, "user_email": "user@example.com" }
API
Chame jobs.get e forneça os parâmetros jobId
e projectId
. (Opcional) Insira o parâmetro location
e defina o valor do local em que o job é executado. Esse parâmetro é opcional se você usar o ID do job totalmente qualificado que inclui o local, por exemplo, my-project-1234:US.bquijob_123x456_123y123z123c
.
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 Go.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python em 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 Python.
Como listar jobs em um projeto
Seu projeto mantém o histórico de todos os jobs criados nos últimos seis meses. Para solicitar a exclusão automática de jobs com mais de 50 dias de existência, entre em contato com o suporte.
Para visualizar seu histórico de jobs do BigQuery:
- use o Console do Google Cloud Platform ou a IU clássica da Web;
- use a CLI;
- chame o método de API
jobs.list
; - use as bibliotecas de cliente.
O histórico de jobs inclui aqueles que estão no estado RUNNING
e que estão como DONE
, um campo que aparece quando o estado é informado como SUCCESS
ou FAILURE
.
Permissões exigidas
Para listar jobs, é necessário ter, no mínimo, permissões bigquery.jobs.list
. Os papéis predefinidos do Cloud IAM a seguir incluem as permissões bigquery.jobs.list
:
bigquery.user
bigquery.admin
O papel a seguir recebe permissões bigquery.jobs.list
apenas para jobs autocriados. As entidades com esse papel podem listar apenas os jobs que enviarem:
bigquery.jobUser
Quando você recebe permissões bigquery.jobs.list
, pode listar todos os jobs em um projeto, mas os detalhes e metadados são editados para jobs enviados por outros usuários. Permissões bigquery.jobs.list
permitem ver detalhes completos de jobs criados por você.
Para listar todos os jobs, incluindo detalhes de jobs criados por outros usuários, você precisa ter permissões bigquery.jobs.listAll
. Apenas o papel bigquery.admin
tem permissões bigquery.jobs.listAll
.
Para mais informações sobre papéis e permissões do Cloud IAM no BigQuery, consulte Controle de acesso.
Listar jobs
Ao listar jobs em um projeto, não é necessário fornecer um local. Atualmente, os jobs são listados para todos os locais.
Para listar jobs em um projeto:
Console
No painel de navegação, clique em Histórico de jobs.
Na seção Histórico pessoal, seus jobs são listados por tempo de criação com os mais recentes na parte superior. A lista inclui apenas os jobs do usuário atual. Para ver todos os jobs de um projeto, clique em Histórico do projeto. Se você não for o proprietário do projeto, talvez não tenha permissão para visualizar todos os jobs de um projeto.
IU clássica
No painel de navegação, clique em Histórico de jobs.
Na seção Jobs recentes, os jobs são listados por tempo de criação, com os mais recentes no topo. A lista inclui apenas os jobs do usuário atual. Para ver todos os jobs, use a ferramenta de linha de comando ou a API.
CLI
Emita o comando bq ls
com uma das seguintes sinalizações:
-j
é usada para identificar jobs como o recurso a ser listado.--all
ou-a
lista os jobs de todos os usuários. Para ver os detalhes completos (não editados) de todos os jobs, você precisa ter permissõesbigquery.jobs.listAll
.--min_creation_time
é usado para listar jobs após um valor de carimbo de data/hora ser fornecido.--max_creation_time
é usado para listar jobs antes de um valor de carimbo de data/hora ser fornecido.-n
limita os resultados. Por padrão, o limite é de 100.000 resultados.
bq ls -j -a \ --min_creation_time integer1 \ --max_creation_time integer2 \ -n integer3 \ project_id
Em que:
- integer1 é um número inteiro que representa um carimbo de data/hora.
- integer2 é um número inteiro que representa um carimbo de data/hora.
- integer3 é um número inteiro que indica o número de jobs retornados.
- project_id é o ID do projeto que contém os jobs que você está listando. Se você definir um projeto padrão, não precisará fornecer o parâmetro project_id.
Exemplos:
O comando a seguir lista todos os jobs do usuário atual. A execução deste comando requer permissões bigquery.jobs.list
.
bq ls -j myproject
O comando a seguir lista todos os jobs de todos os usuários. A execução deste comando requer permissões bigquery.jobs.listAll
.
bq ls -j -a myproject
O comando a seguir lista os 10 jobs mais recentes no myproject
:
bq ls -j -a -n 10 myproject
O comando a seguir lista todos os jobs enviados antes de 18 de outubro de 2018 às 16:04:53. Esse carimbo de data/hora (em milissegundos) é equivalente ao seguinte valor inteiro: 1539903893000
.
bq ls -j --max_creation_time 1539903893000
API
Chame jobs.list e forneça o parâmetro projectId
. Para listar jobs para todos os usuários, configure o parâmetro allUsers
como true
. É preciso ter as permissões bigquery.jobs.listAll
para definir allUsers
como true
.
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 Go.
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 Java.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python em 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 Python.
Como cancelar jobs
Para cancelar um job RUNNING
ou PENDING
:
- use o Console do GCP ou a IU clássica da Web do BigQuery;
- use a CLI;
- chame o método de API
jobs.cancel
; - use as bibliotecas de cliente.
Nem todos os tipos de job podem ser cancelados. Se o job não puder ser cancelado, um erro será retornado.
Mesmo que o job possa ser cancelado, o sucesso não é garantido. O job pode ter sido concluído no momento em que a solicitação de cancelamento foi enviada ou estar em uma etapa em que não pode ser cancelado.
Permissões exigidas
Para cancelar um job, é necessário ter, no mínimo, permissões bigquery.jobs.update
. O papel predefinido do Cloud IAM a seguir inclui permissões bigquery.jobs.update
:
bigquery.admin
Se você concede a uma conta o papel bigquery.admin
, o usuário pode cancelar qualquer job qualificado, independentemente de quem o enviou.
Os papéis a seguir podem cancelar jobs autocriados: Esses usuários só podem cancelar os jobs que enviam:
bigquery.user
bigquery.jobUser
Para mais informações sobre papéis e permissões do Cloud IAM no BigQuery, consulte Controle de acesso.
Como cancelar um job
Para cancelar um job:
Console
No painel de navegação, clique em Histórico de jobs.
Na seção Histórico pessoal, clique no job que você está cancelando. Os jobs mais recentes aparecem no topo da lista.
Nos detalhes do job, clique em Cancelar job.
IU clássica
No painel de navegação, clique em Histórico de jobs.
Na seção Jobs recentes, clique no job que você está cancelando. Os jobs mais recentes aparecem no topo da lista.
Nos detalhes do job, clique em Cancelar job.
CLI
Emita o comando bq cancel
com o parâmetro job_id
. É possível solicitar o cancelamento e retornar imediatamente usando a sinalização --nosync
. Por padrão, as solicitações de cancelamento aguardam a conclusão.
Quando você fornece o ID do job, é possível usar o código totalmente qualificado ou a forma abreviada. Por exemplo, os IDs de jobs, listados na IU da Web do BigQuery, são totalmente qualificados e incluem o projeto e o local:
my-project-1234:US.bquijob_123x456_123y123z123c
Os IDs dos jobs na ferramenta de linha de comando são listados usando a forma abreviada e não incluem o código e o local do projeto:
bquijob_123x456_123y123z123c
Para especificar o local do job, forneça a sinalização --location
e defina o valor do local. Essa sinalização é opcional, caso seja usado o ID do job totalmente qualificado. Se você incluir a sinalização --location
e estiver usando o ID do job totalmente qualificado, a sinalização --location
será ignorada.
Com o comando a seguir, você solicita o cancelamento do job e aguarda a conclusão: Se o ID do job totalmente qualificado for fornecido, a sinalização --location
será ignorada:
bq --location=location cancel job_id
O cancelamento do job é solicitado com o comando a seguir, com retorno imediato. Se o ID do job totalmente qualificado for fornecido, a sinalização --location
será ignorada:
bq --location=location --nosync cancel job_id
Em que:
- location é opcional. Ele é o nome do local em que o job é executado. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.
- job_id é o ID do job que você está cancelando. Se você copiar o ID do job da IU da Web do BigQuery, o ID e o local do projeto serão incluídos nele. Por exemplo,
my-project-1234:US.bquijob_123x456_123y123z123c
.
Exemplos:
Com o comando a seguir, você cancela o job my-project-1234:US.bquijob_123x456_123y123z123c
, em execução na multirregião US
em my-project-1234
e aguarda a conclusão. Como o ID do job que está sendo usado é totalmente qualificado, a sinalização de local não é fornecida.
bq cancel my-project-1234:US.bquijob_123x456_123y123z123c
Com o comando a seguir, você cancela o job bquijob_123x456_123y123z123c
, em execução na multirregião US
em my-project-1234
e aguarda a conclusão. Como a forma do ID do job que está sendo usada é abreviada, a sinalização --location
é fornecida.
bq --location=US cancel bquijob_123x456_123y123z123c
Com o comando a seguir, você cancela o job bquijob_123x456_123y123z123c
, em execução na multirregião dos US
em my-project-1234
, com retorno imediato.
Como está sendo usado o ID do job totalmente qualificado, a sinalização --location
não é fornecida.
bq --nosync cancel my-project-1234:US.bquijob_123x456_123y123z123c
API
Chame jobs.cancel e forneça os parâmetros jobId
e projectId
. Insira o parâmetro location
e defina o valor do local em que o job é executado.
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 Go.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python em 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 Python.
Como repetir um job
Não é possível executar um job novamente usando o mesmo código de job. Em vez disso, crie um novo job com a mesma configuração. Quando você envia o job novo no Console do GCP, na IU da Web clássica ou na CLI, um novo código de job é atribuído. Quando você envia o job usando a API ou bibliotecas de cliente, é necessário gerar um novo código de job.
Permissões exigidas
Para executar um job de consulta, é necessário ter, no mínimo, as permissões bigquery.jobs.create
. Os papéis predefinidos do Cloud IAM a seguir incluem as permissões bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Para mais informações sobre papéis e permissões do Cloud IAM no BigQuery, consulte Controle de acesso.
Como executar um job novamente
Para repetir um job:
Console
Para repetir um job de consulta:
No painel de navegação, clique em Histórico de consulta.
Na seção Histórico pessoal ou Histórico do projeto, clique na consulta que você quer executar novamente e, depois, em Abrir consulta no editor.
Clique em Executar.
Para repetir um job de carga:
No painel de navegação, clique em Histórico de jobs.
Na seção Histórico pessoal ou Histórico do projeto, clique no job que você quer executar novamente. Os jobs mais recentes aparecem no topo da lista.
Nos detalhes do trabalho, clique em Repetir job de carga.
IU clássica
Para repetir um job de consulta:
No painel de navegação, clique em Histórico de consulta.
Na seção Consultas, à direita da consulta, clique em Abrir consulta.
Clique em Executar.
Para repetir um job de carregamento:
No painel de navegação, clique em Histórico de jobs.
Na seção Jobs recentes, clique no job que você quer executar novamente. Os jobs mais recentes aparecem no topo da lista.
Nos detalhes do job, clique em Carregar o job novamente.
CLI
Emita o comando novamente, e o BigQuery gera automaticamente um job com um novo código.
API
Não há um método de chamada única para repetir um job. Para fazer isso:
Chame
jobs.get
para recuperar o recurso e executar o job novamente.remova os campos código, status e estatísticas. Altere o campo jobId para um novo valor gerado pelo código de cliente. Altere outros campos, conforme necessário;
Chame
jobs.insert
com o recurso modificado e o novo ID do job para iniciar o novo job.