Cómo ejecutar trabajos de consulta interactivos y por lotes

Este documento describe cómo ejecutar trabajos de consulta interactivos (bajo demanda) y por lotes.

Permisos necesarios

Los trabajos son acciones que ejecuta BigQuery por ti para cargar datos, exportar datos, consultar datos o copiar datos.

Cuando usas la consola, la IU web clásica de BigQuery o la CLI para cargar, exportar, consultar o copiar datos, se crea, programa y ejecuta automáticamente un recurso de trabajo. También puedes crear un trabajo de carga, exportación, consulta o copia de manera programática. Cuando creas un trabajo de manera programática, BigQuery programa y ejecuta el trabajo por ti.

Dado que los trabajos pueden tardar mucho tiempo en completarse, estos se ejecutan de forma asíncrona y se pueden sondear para determinar su estado. Las acciones más cortas, como realizar una lista de recursos o también obtener metadatos, no se administran mediante un recurso de trabajo.

La ejecución de un trabajo de consulta requiere permisos bigquery.jobs.create. Para que el trabajo de consulta se complete con éxito, el usuario o grupo también deben tener acceso al conjunto de datos que contiene las tablas a las que hace referencia la consulta.

Puedes configurar permisos bigquery.jobs.create a nivel del proyecto para otorgar cualquiera de las siguientes funciones de IAM:

• bigquery.user
• bigquery.jobUser
• bigquery.admin

Nota: A la mayoría de los usuarios, como a los analistas y a los científicos de datos, se les debe otorgar bigquery.user o bigquery.jobUser. bigquery.admin tiene permisos completos en todos los conjuntos de datos de un proyecto.

Si otorgas a un usuario o grupo la función bigquery.user a nivel del proyecto, no se otorga accesos a ninguno de los conjuntos de datos, tablas o vistas del proyecto de manera predeterminada. bigquery.user le da a los usuarios la capacidad de crear sus propios conjuntos de datos y ejecutar trabajos de consulta en los conjuntos de datos a los que tienen acceso. Si asignas la función bigquery.user o bigquery.jobUser, también debes asignar controles de acceso a cada conjunto de datos al que el usuario o grupo necesiten acceder y que no haya sido creado por el usuario.

Cuando otorgas acceso a un conjunto de datos, hay 3 opciones:

• Mapas "Puede ver" a la función bigquery.dataViewer para ese conjunto de datos.
• Mapas "Puede editar" a la función bigquery.dataEditor para ese conjunto de datos.
• Mapas "Es propietario" a la función bigquery.dataOwner para ese conjunto de datos.

El acceso mínimo requerido para que un usuario ejecute una consulta es "Puede ver".

Para obtener más información sobre las funciones IAM en BigQuery, consulta Control de acceso.

Cómo ejecutar consultas interactivas

De manera predeterminada, BigQuery ejecuta trabajos de consulta de tipo interactivo (bajo demanda), lo que significa que la consulta se ejecuta tan pronto como sea posible. Las consultas interactivas se toman en cuenta para tu límite de frecuencia concurrente y límite diario.

Los resultados de las consultas se almacenan siempre en una tabla temporal o permanente. Puedes elegir si deseas adjuntar o sobrescribir datos en una tabla existente o si deseas crear una tabla nueva si no existe ninguna con el mismo nombre.

Para ejecutar una consulta interactiva que escribe en una tabla temporal:

IU web

1. Ve a la IU web de BigQuery.
   Ir a la IU web de BigQuery

2. Haz clic en Redactar consulta.

3. Ingresa una consulta válida de SQL en BigQuery en el área de texto Consulta nueva.

4. Haz clic en Mostrar opciones.

5. (Opcional) En Ubicación de procesamiento, haz clic en No especificada y elige la ubicación de tus datos.

6. Haz clic en Ejecutar consulta.

Esto crea un trabajo de consulta que escribe el resultado en una tabla temporal.

Línea de comandos

Ingresa el comando bq query y luego incluye el texto de tu consulta. Proporciona la marca --location y configura el valor en tu ubicación.

Puedes especificar las siguientes marcas opcionales. Esta lista incluye algunas de las marcas más comunes. Para obtener una lista completa de las marcas del comando query, consulta bq query en la referencia de la herramienta de línea de comandos.

Especifica la:

• marca --destination_table para crear una tabla permanente basada en los resultados de la consulta. Para escribir los resultados de la consulta en una tabla que no está en tu proyecto predeterminado, agrega el ID del proyecto al nombre del conjunto de datos en el siguiente formato: [PROJECT_ID]:[DATASET]. Si no se especifica --destination_table, se genera un trabajo de consulta que escribe el resultado en una tabla temporal (en caché).
• marca --append_table para adjuntar los resultados de la consulta a una tabla de destino.
• marca --destination_kms_key para usar una clave de Cloud KMS para encriptar los datos de la tabla de destino.
• marca --use_legacy_sql=false para usar la sintaxis de SQL estándar. Puedes configurar una sintaxis predeterminada para la herramienta de línea de comandos con el archivo .bigqueryrc.
• marca --label para aplicar una etiqueta al trabajo de carga en el formulario [KEY]:[VALUE]. Repite esta marca para especificar varios archivos.
• marca --max_rows o -n para especificar el número de filas a mostrar en los resultados de la consulta.
• marca --maximum_bytes_billed para limitar los bytes facturados para la consulta. Si la consulta supera el límite, falla (sin incurrir en cargos). Si no se especifica, los bytes facturados se configuran en el valor predeterminado del proyecto.
• marca --udf_resource para cargar y evaluar un archivo de código para utilizarlo como recurso de función definida por el usuario. Puedes especificar un URI de Cloud Storage o la ruta a un archivo de código local. Repite esta marca para especificar varios archivos.

Ingresa el siguiente comando para ejecutar una consulta interactiva mediante la sintaxis de SQL estándar:

bq --location=[LOCATION] query --use_legacy_sql=false '[QUERY]'

Donde:

• [LOCATION] es el nombre de la ubicación en la que se procesa la consulta. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
• [QUERY] es una consulta en la sintaxis de SQL estándar.

Ejemplos:

Nota: Estos ejemplos utilizan la marca --location=US porque estás realizando consultas en un conjunto de datos público. Los conjuntos de datos públicos de BigQuery se almacenan en la ubicación multirregión de EE.UU. Debido a que los conjuntos de datos públicos se almacenan en EE.UU., no puedes escribir resultados de consultas a datos públicos en una tabla de otra región ni unir tablas en conjuntos de datos públicos con tablas en otra región.

Ingresa el siguiente comando para escribir resultados de consultas interactivos en una tabla de destino llamada mytable en mydataset. El conjunto de datos se encuentra en tu proyecto predeterminado. La consulta recupera datos desde el conjunto de datos público Datos de nombres de EE.UU..

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Ingresa el siguiente comando para escribir resultados de consultas interactivos en una tabla de destino llamada mytable en mydataset. El conjunto de datos se encuentra en myotherproject, no en tu proyecto predeterminado. La consulta recupera datos de una tabla no particionada: el conjunto de datos público Datos de nombres de EE.UU.

bq --location=US query --destination_table myotherproject:mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Para obtener más información, consulta Cómo usar la herramienta de línea de comandos de bq.

API

Para ejecutar una consulta con la API, inserta un trabajo nuevo y propaga la propiedad jobs#configuration.query. Especifica tu ubicación en la propiedad location en la sección jobReference del recurso de trabajo.

Sondea los resultados mediante una llamada a getQueryResults. Sondea hasta que jobComplete sea equivalente a true. Comprueba si hay errores y advertencias en la lista errores.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para C#.

Ver en GitHub Comentarios

using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryQuery
{
    public void Query(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        string query = @"
            SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013`
            WHERE state = 'TX'
            LIMIT 100";
        BigQueryJob job = client.CreateQueryJob(
            sql: query,
            parameters: null,
            options: new QueryOptions { UseQueryCache = false });
        // Wait for the job to complete.
        job.PollUntilCompleted();
        // Display the results
        foreach (BigQueryRow row in client.GetQueryResults(job.Reference))
        {
            Console.WriteLine($"{row["name"]}");
        }
    }
}

Go

Antes de probar esta muestra, sigue las instrucciones de configuración para Go de la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Ver en GitHub Comentarios

// 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")

q := client.Query(
	"SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " +
		"WHERE state = \"TX\" " +
		"LIMIT 100")
// Location must match that of the dataset(s) referenced in the query.
q.Location = "US"
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

Antes de probar esta muestra, sigue las instrucciones de configuración para Java de la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Ver en GitHub Comentarios

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig = QueryJobConfiguration.newBuilder(query).build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Node.js

Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de API de BigQuery para Node.js.

Ver en GitHub Comentarios

// Imports the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');

// Creates a client
const bigquery = new BigQuery();

const query = `SELECT name
  FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
  WHERE state = 'TX'
  LIMIT 100`;
const options = {
  query: query,
  // Location must match that of the dataset(s) referenced in the query.
  location: 'US',
};

// Runs the query as a job
const [job] = await bigquery.createQueryJob(options);
console.log(`Job ${job.id} started.`);

// Waits for the query to finish
const [rows] = await job.getQueryResults();

// Prints the results
console.log('Rows:');
rows.forEach(row => console.log(row));

PHP

Antes de probar esta muestra, sigue las instrucciones de configuración para PHP que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para PHP.

Ver en GitHub Comentarios

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $query = 'SELECT id, view_count FROM `bigquery-public-data.stackoverflow.posts_questions`';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$jobConfig = $bigQuery->query($query);
$job = $bigQuery->startQuery($jobConfig);

$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
$queryResults = $job->queryResults();

$i = 0;
foreach ($queryResults as $row) {
    printf('--- Row %s ---' . PHP_EOL, ++$i);
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, json_encode($value));
    }
}
printf('Found %s row(s)' . PHP_EOL, $i);

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Ver en GitHub Comentarios

# from google.cloud import bigquery
# client = bigquery.Client()

query = (
    'SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` '
    'WHERE state = "TX" '
    'LIMIT 100')
query_job = client.query(
    query,
    # Location must match that of the dataset(s) referenced in the query.
    location='US')  # API request - starts the query

for row in query_job:  # API request - fetches results
    # Row values can be accessed by field name or index
    assert row[0] == row.name == row['name']
    print(row)

Ruby

Antes de probar esta muestra, sigue las instrucciones de configuración para Ruby que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Ruby.

Ver en GitHub Comentarios

require "google/cloud/bigquery"

def query
  bigquery = Google::Cloud::Bigquery.new
  sql = "SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " +
        "WHERE state = 'TX' " +
        "LIMIT 100"

  # Location must match that of the dataset(s) referenced in the query.
  results = bigquery.query sql do |config|
    config.location = "US"
  end

  results.each do |row|
    puts row.inspect
  end
end

Cómo ejecutar consultas por lotes

BigQuery también ofrece consultas por lotes. BigQuery pone en cola cada consulta por lotes por ti, y luego inicia la consulta tan pronto como los recursos inactivos estén disponibles, por lo general en unos minutos. Si BigQuery no ha iniciado la consulta en 24 horas, BigQuery cambia la prioridad del trabajo a interactivo.

Las consultas por lotes no cuentan para tu límite de frecuencia concurrente, lo que puede facilitar el inicio de muchas consultas a la vez. Las consultas por lotes utilizan los mismos recursos que las consultas interactivas (bajo demanda). Si usas consultas por lotes y consultas interactivas con tarifa plana, comparte tus espacios asignados.

Para ejecutar una consulta por lotes:

IU web

1. Ve a la IU web de BigQuery.
   Ir a la IU web de BigQuery

2. Haz clic en el botón Redactar consulta.

3. Ingresa una consulta válida de SQL en BigQuery en el área de texto Consulta nueva.

4. Haz clic en el botón Mostrar opciones.

5. Selecciona la opción Por lotes en la sección Prioridad de la consulta.

6. (Opcional) En Ubicación de procesamiento, haz clic en No especificada y elige la ubicación de tus datos.

7. Haz clic en el botón Ejecutar consulta.

Línea de comandos

Ingresa el comando bq query y luego incluye el texto de tu consulta. Especifica la marca --batch para ejecutar una consulta por lotes. Proporciona la marca --location y configura el valor en tu ubicación.

Puedes especificar las siguientes marcas opcionales. Esta lista incluye algunas de las marcas más comunes. Para obtener una lista completa de las marcas del comando query, consulta bq query en la referencia de la herramienta de línea de comandos.

Especifica la:

• marca --destination_table para crear una tabla permanente basada en los resultados de la consulta. Para escribir los resultados de la consulta en una tabla que no está en tu proyecto predeterminado, agrega el ID del proyecto al nombre del conjunto de datos en el siguiente formato: [PROJECT_ID]:[DATASET]. Si no se especifica --destination_table, se genera un trabajo de consulta que escribe el resultado en una tabla temporal (en caché).
• marca --append_table para adjuntar los resultados de la consulta a una tabla de destino.
• marca --destination_kms_key para usar una clave de Cloud KMS para encriptar los datos de la tabla de destino.
• marca --use_legacy_sql=false para usar la sintaxis de SQL estándar. Puedes configurar una sintaxis predeterminada para la herramienta de línea de comandos con el archivo .bigqueryrc.
• marca --label para aplicar una etiqueta al trabajo de carga en el formulario [KEY]:[VALUE]. Repite esta marca para especificar varios archivos.
• marca --max_rows o -n para especificar el número de filas a mostrar en los resultados de la consulta.
• marca --maximum_bytes_billedpara limitar los bytes facturados para la consulta. Si la consulta supera el límite, falla (sin incurrir en cargos). Si no se especifica, los bytes facturados se configuran en el valor predeterminado del proyecto.
• marca --udf_resource para cargar y evaluar un archivo de código para utilizarlo como recurso de función definida por el usuario. Puedes especificar un URI de Cloud Storage o la ruta a un archivo de código local. Repite esta marca para especificar varios archivos.

Ingresa el siguiente comando para ejecutar una consulta por lotes con la sintaxis de SQL estándar:

bq --location=[LOCATION] query --batch --use_legacy_sql=false '[QUERY]'

Donde:

• [LOCATION] es el nombre de la ubicación en la que se procesa la consulta. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
• [QUERY] es una consulta en la sintaxis de SQL estándar.

Ejemplos:

Nota: Estos ejemplos utilizan la marca --location=US porque estás realizando consultas en un conjunto de datos público. Los conjuntos de datos públicos de BigQuery se almacenan en la ubicación multirregión de EE.UU. Debido a que los conjuntos de datos públicos se almacenan en EE.UU., no puedes escribir resultados de consultas a datos públicos en una tabla de otra región ni unir tablas en conjuntos de datos públicos con tablas en otra región.

Ingresa el siguiente comando para escribir los resultados de la consulta por lotes en una tabla de destino llamada mytable en mydataset . El conjunto de datos se encuentra en tu proyecto predeterminado. La consulta recupera datos desde el conjunto de datos público Datos de nombres de EE.UU..

bq --location=US query --batch --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Ingresa el siguiente comando para escribir los resultados de la consulta por lotes en una tabla de destino llamada mytable en mydataset . El conjunto de datos se encuentra en myotherproject, no en tu proyecto predeterminado. La consulta recupera datos de una tabla no particionada: el conjunto de datos público Datos de nombres de EE.UU.

bq --location=US query --batch --destination_table myotherproject:mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Para obtener más información, consulta Cómo usar la herramienta de línea de comandos de bq.

API

Para ejecutar una consulta con la API, inserta un trabajo nuevo y propaga la propiedad jobs#configuration.query. Especifica tu ubicación en la propiedad location en la sección jobReference del recurso de trabajo.

Cuando propagues las propiedades del trabajo de consulta, incluye la propiedad configuration.query.priority con el valor configurado en BATCH.

Go

Antes de probar esta muestra, sigue las instrucciones de configuración para Go de la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Ver en GitHub Comentarios

	// 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")
	// Build an aggregate table.
	q := client.Query(`
		SELECT
  			corpus,
  			SUM(word_count) as total_words,
  			COUNT(1) as unique_words
		FROM ` + "`bigquery-public-data.samples.shakespeare`" + `
		GROUP BY corpus;`)
	q.Priority = bigquery.BatchPriority
	q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)

	// Start the job.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Job is started and will progress without interaction.
	// To simulate other work being done, sleep a few seconds.
	time.Sleep(5 * time.Second)
	status, err := job.Status(ctx)
	if err != nil {
		return err
	}

	state := "Unknown"
	switch status.State {
	case bigquery.Pending:
		state = "Pending"
	case bigquery.Running:
		state = "Running"
	case bigquery.Done:
		state = "Done"
	}
	// You can continue to monitor job progress until it reaches
	// the Done state by polling periodically.  In this example,
	// we print the latest status.
	fmt.Printf("Job %s in Location %s currently in state: %s\n", job.ID(), job.Location(), state)

Java

Antes de probar esta muestra, sigue las instrucciones de configuración para Java de la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para ejecutar una consulta por lotes, establece la prioridad de la consulta en QueryJobConfiguration.Priority.BATCH cuando crees una QueryJobConfiguration.

Ver en GitHub

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    QueryJobConfiguration.newBuilder(query)
        // Run at batch priority, which won't count toward concurrent rate
        // limit.
        .setPriority(QueryJobConfiguration.Priority.BATCH)
        .build();

// Location must match that of the dataset(s) referenced in the query.
JobId jobId = JobId.newBuilder().setRandomJob().setLocation("US").build();
String jobIdString = jobId.getJob();

// API request - starts the query.
bigquery.create(JobInfo.newBuilder(queryConfig).setJobId(jobId).build());

// Check on the progress by getting the job's updated state. Once the state
// is `DONE`, the results are ready.
Job queryJob = bigquery.getJob(
    JobId.newBuilder().setJob(jobIdString).setLocation("US").build());
System.out.printf(
    "Job %s in location %s currently in state: %s%n",
    queryJob.getJobId().getJob(),
    queryJob.getJobId().getLocation(),
    queryJob.getStatus().getState().toString());

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Ver en GitHub Comentarios

# from google.cloud import bigquery
# client = bigquery.Client()

job_config = bigquery.QueryJobConfig()
# Run at batch priority, which won't count toward concurrent rate limit.
job_config.priority = bigquery.QueryPriority.BATCH
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""
# Location must match that of the dataset(s) referenced in the query.
location = 'US'

# API request - starts the query
query_job = client.query(sql, location=location, job_config=job_config)

# Check on the progress by getting the job's updated state. Once the state
# is `DONE`, the results are ready.
query_job = client.get_job(
    query_job.job_id, location=location)  # API request - fetches job
print('Job {} is currently in state {}'.format(
    query_job.job_id, query_job.state))