Como gerenciar jobs

Depois de enviar um job do BigQuery, é possível visualizar dados do job, listar, cancelar ou reexecutar jobs.

Quando um job é enviado, ele pode estar em um destes três estados:

  • PENDING (programado)
  • RUNNING
  • DONE (informado como SUCCESS ou FAILURE 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 ver os dados e metadados do job, você precisa ter as permissões bigquery.jobs.get. O papel do IAM predefinido em nível do projeto inclui permissões bigquery.jobs.get:

Se você concede 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:

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso.

Como visualizar informações sobre jobs

Para visualizar informações sobre um job:

Console

  1. No painel de navegação, clique em Histórico de jobs.

  2. Na seção Histórico pessoal, clique no job para visualizar os detalhes.

IU clássica

  1. No painel de navegação, clique em Histórico de jobs.

  2. Na seção Jobs recentes, clique no job para ver os detalhes.

CLI

Emita o comando bq show com a sinalização -j e o parâmetro job_id. Forneça a sinalização --location e defina o valor do local.

O comando a seguir solicita informações sobre um job:

bq --location=[LOCATION] show -j [JOB_ID]

em que:

  • [LOCATION] é 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 código do job.

Exemplos:

O comando a seguir recebe informações resumidas sobre o job bquijob_123x456_123y123z123c em execução no myproject no local multirregional US:

bq --location=US show -j myproject: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 --location=US show --format=prettyjson -j myproject: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"
}

O comando a seguir recebe informações resumidas sobre o job bquijob_123x456_123y123z123c em execução em myproject na região asia-northeast1:

bq --location=asia-northeast1 show -j myproject:bquijob_123x456_123y123z123c

API

Chame jobs.get 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 Início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API do BigQuery para Go. 

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
job, err := client.JobFromID(ctx, jobID)
if err != nil {
	return err
}

status := job.LastStatus()
state := "Unknown"
switch status.State {
case bigquery.Pending:
	state = "Pending"
case bigquery.Running:
	state = "Running"
case bigquery.Done:
	state = "Done"
}
fmt.Printf("Job %s was created %v and is in state %s\n",
	jobID, status.Statistics.CreationTime, state)

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para Python. 

# TODO(developer): Uncomment the lines below and replace with your values.
# from google.cloud import bigquery
# client = bigquery.Client()
# job_id = 'bq-job-123x456-123y123z123c'  # replace with your job ID
# location = 'us'                         # replace with your location

job = client.get_job(job_id, location=location)  # API request

# Print selected job properties
print("Details for job {} running in {}:".format(job_id, location))
print(
    "\tType: {}\n\tState: {}\n\tCreated: {}".format(
        job.job_type, job.state, job.created
    )
)

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.

Veja o histórico de jobs do BigQuery pelo Console do Google Cloud Platform, pela IU da Web clássica, pela CLI ou pela API. Esse histórico inclui jobs que estão no estado RUNNING e DONE, indicados pelos estados SUCCESS ou FAILURE.

Permissões exigidas

Para listar os jobs, você precisa ter as permissões bigquery.jobs.list. Os papéis do IAM predefinidos para envolvidos no projeto a seguir incluem permissões bigquery.jobs.list:

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.

O papel a seguir recebe permissões bigquery.jobs.list apenas para jobs autocriados. Esses usuários só podem listar os jobs que enviam:

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso.

Como 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

  1. No painel de navegação, clique em Histórico de jobs.

  2. Na seção Histórico pessoal, seus jobs são listados por tempo de criação com os mais recentes em cima. 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

  1. No painel de navegação, clique em Histórico de jobs.

  2. 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 detalhes completos (não editados) de todos os jobs, você precisa ter permissões bigquery.jobs.listAll.
  • min_creation_time é usado para listar jobs após um valor de carimbo de data e hora ser fornecido.
  • max_creation_time é usado em listas de jobs antes de um valor de registro de data e hora ser fornecido.

  • -n limita os 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 registro de data e hora;
  • [INTEGER2] é um número inteiro que representa um registro de data e hora;
  • [INTEGER3] é um número inteiro que indica o número de jobs retornados;
  • [PROJECT_ID] é o código do projeto que contém os jobs que você está listando. Se você definir um projeto padrão, não será necessário 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 registro de data e 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 fazer a configuração de allUsers como true.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API do BigQuery para Go. 

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
it := client.Jobs(ctx)
for i := 0; i < 10; i++ {
	j, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	state := "Unknown"
	switch j.LastStatus().State {
	case bigquery.Pending:
		state = "Pending"
	case bigquery.Running:
		state = "Running"
	case bigquery.Done:
		state = "Done"
	}
	fmt.Printf("Job %s in state %s\n", j.ID(), state)
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para Java. 

Page<Job> jobs = bigquery.listJobs(JobListOption.pageSize(100));
for (Job job : jobs.iterateAll()) {
  // do something with the job
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para Python. 

# TODO(developer): Uncomment the lines below and replace with your values.
# from google.cloud import bigquery
# project = 'my_project'  # replace with your project ID
# client = bigquery.Client(project=project)
import datetime

# List the 10 most recent jobs in reverse chronological order.
# Omit the max_results parameter to list jobs from the past 6 months.
print("Last 10 jobs:")
for job in client.list_jobs(max_results=10):  # API request(s)
    print(job.job_id)

# The following are examples of additional optional parameters:

# Use min_creation_time and/or max_creation_time to specify a time window.
print("Jobs from the last ten minutes:")
ten_mins_ago = datetime.datetime.utcnow() - datetime.timedelta(minutes=10)
for job in client.list_jobs(min_creation_time=ten_mins_ago):
    print(job.job_id)

# Use all_users to include jobs run by all users in the project.
print("Last 10 jobs run by all users:")
for job in client.list_jobs(max_results=10, all_users=True):
    print("{} run by user: {}".format(job.job_id, job.user_email))

# Use state_filter to filter by job state.
print("Jobs currently running:")
for job in client.list_jobs(state_filter="RUNNING"):
    print(job.job_id)

Como cancelar jobs

Cancele um job RUNNING ou PENDING no Console do GCP, na IU da web clássica, na CLI ou na API. No entanto, 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, você precisa ter as permissões bigquery.jobs.update. O papel do IAM predefinido em nível do projeto a seguir inclui as permissões bigquery.jobs.update:

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:

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso.

Como cancelar um job

Para cancelar um job:

Console

  1. No painel de navegação, clique em Histórico de jobs.

  2. Na seção Histórico pessoal, clique no job que você está cancelando. Os jobs mais recentes aparecem no topo da lista.

  3. Nos detalhes do job, clique em Cancelar job.

IU clássica

  1. No painel de navegação, clique em Histórico de jobs.

  2. Na seção Jobs recentes, clique no job que você está cancelando. Os jobs mais recentes aparecem no topo da lista.

  3. Nos detalhes do job, clique em Cancelar job.

    Cancelar job

CLI

Emita o comando bq cancel com o parâmetro job_id. Você pode 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] é 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 código do job que você está cancelando. Se você copiar o código do job da IU da Web do BigQuery, o código 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 dos US no my-project-1234 e aguarda a conclusão. Como está sendo usado o ID do job totalmente qualificado, a sinalização do 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 dos US no my-project-1234 e aguarda a conclusão. Como está sendo usada a forma abreviada do ID do job, 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 Início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API do BigQuery para Go. 

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
job, err := client.JobFromID(ctx, jobID)
if err != nil {
	return nil
}
return job.Cancel(ctx)

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para Python. 

# TODO(developer): Uncomment the lines below and replace with your values.
# from google.cloud import bigquery
# client = bigquery.Client()
# job_id = 'bq-job-123x456-123y123z123c'  # replace with your job ID
# location = 'us'                         # replace with your location

job = client.cancel_job(job_id, location=location)

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, é necessário ter as permissões bigquery.jobs.create. Os papéis do IAM predefinidos no nível do projeto a seguir incluem permissões bigquery.jobs.create:

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso.

Como executar um job novamente

Para repetir um job:

Console

Para repetir um job de consulta:

  1. No painel de navegação, clique em Histórico de consulta.

  2. Na seção Histórico pessoal, clique na consulta que quer executar novamente e, em seguida, clique em Abrir consulta no editor.

  3. Clique em Executar.

Para repetir um job de carga:

  1. No painel de navegação, clique em Histórico de jobs.

  2. Na seção Histórico pessoal, clique no job que você quer repetir. Os jobs mais recentes aparecem no topo da lista.

  3. Nos detalhes do trabalho, clique em Repetir job de carga.

IU clássica

Para repetir um job de consulta:

  1. No painel de navegação, clique em Histórico de consulta.

  2. Na seção Consultas, à direita da consulta, clique em Abrir consulta.

  3. Clique em Executar consulta.

Para repetir um job de carregamento:

  1. No painel de navegação, clique em Histórico de jobs.

  2. Na seção Jobs recentes, clique no job que você quer repetir. Os jobs mais recentes aparecem no topo da lista.

  3. Nos detalhes do job, clique em Repetir job de carregamento.

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:

  1. Chame jobs.get para recuperar o recurso para o job ser repetido.

  2. 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;

  3. Chame jobs.insert com o recurso modificado e o novo código do job para iniciar o novo job.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
BigQuery
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.