Cómo paginar los resultados de consulta

Este documento describe cómo desplazarse a través de los resultados de consultas con la API de REST de BigQuery.

Cómo desplazarse por los resultados mediante la API

Todos los métodos collection.list muestran resultados paginados bajo determinadas circunstancias. El número de resultados por página está controlado por la propiedad maxResults.

Método Criterios de paginación Valor maxResults predeterminado Valor maxResults máximo
Tabledata.list Muestra resultados paginados si el tamaño de la respuesta supera los 10 MB de JSON serializado o las filas establecidas en maxResults. 100,000 100,000
Todo los demás métodos collection.list Muestra resultados paginados si el tamaño de la respuesta supera las filas en maxResults. 50 1,000

Si configuras maxResults en un valor superior al valor máximo mencionado anteriormente, los resultados se paginarán según el valor máximo.

Una página es un subconjunto del número total de filas. Si tus resultados ocupan más de una página de datos, los datos de resultado tendrán una propiedad pageToken. Para recuperar la página siguiente de resultados, realiza otra llamada a list; incluye el valor del token como un parámetro URL llamado pageToken.

El método bigquery.tabledata.list, que se utiliza para desplazarse por los datos de la tabla, utiliza un valor de desplazamiento de fila o un token de página. Consulta Cómo explorar los datos de la tabla para obtener más información.

Los siguientes ejemplos muestran la paginación a través de los resultados de BigQuery.

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#.

using Google.Api.Gax;
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryBrowseTable
{
    public void BrowseTable(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        TableReference tableReference = new TableReference()
        {
            TableId = "shakespeare",
            DatasetId = "samples",
            ProjectId = "bigquery-public-data"
        };
        // Load all rows from a table
        PagedEnumerable<TableDataList, BigQueryRow> result = client.ListRows(
            tableReference: tableReference,
            schema: null
        );
        // Print the first 10 rows
        foreach (BigQueryRow row in result.Take(10))
        {
            Console.WriteLine($"{row["corpus"]}: {row["word_count"]}");
        }
    }
}

Java

Antes de probar esta muestra, sigue las instrucciones de configuración de Java 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 Java.

TableId tableIdObject = TableId.of(datasetName, tableName);
// This example reads the result 100 rows per RPC call. If there's no need to limit the number,
// simply omit the option.
TableResult tableData =
    bigquery.listTableData(tableIdObject, TableDataListOption.pageSize(100));
for (FieldValueList row : tableData.iterateAll()) {
  // do something with the row
}

Go

Antes de probar esta muestra, sigue las instrucciones de configuración para Go 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 Go.

La biblioteca cliente de Google Cloud para Go se pagina automáticamente de forma predeterminada, por lo que no es necesario que la implementes tú mismo, por ejemplo:

table := client.Dataset(datasetID).Table(tableID)
it := table.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Node.js

Antes de probar esta muestra, sigue las instrucciones de configuración de 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.

La biblioteca cliente de Google Cloud para Node.js se pagina automáticamente de forma predeterminada, por lo que no es necesario que la implementes tú mismo, por ejemplo:

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

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = "your-project-id";
// const datasetId = "my_dataset";
// const tableId = "my_table";

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

// Lists rows in the table
const [rows] = await bigquery
  .dataset(datasetId)
  .table(tableId)
  .getRows();

console.log('Rows:');
rows.forEach(row => console.log(row));

PHP

Antes de probar esta muestra, sigue las instrucciones de configuración de 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.

La paginación se realiza automáticamente en la biblioteca cliente de Google Cloud para PHP con el uso de la función de generador rows, que recupera la siguiente página de resultados durante la iteración.

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId   = 'The BigQuery table ID';
// $maxResults = 10;

$maxResults = 10;
$startIndex = 0;

$options = [
    'maxResults' => $maxResults,
    'startIndex' => $startIndex
];
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$numRows = 0;
foreach ($table->rows($options) as $row) {
    print('---');
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, $value);
    }
    $numRows++;
}

Python

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

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

dataset_ref = client.dataset('samples', project='bigquery-public-data')
table_ref = dataset_ref.table('shakespeare')
table = client.get_table(table_ref)  # API call

# Load all rows from a table
rows = client.list_rows(table)
assert len(list(rows)) == table.num_rows

# Load the first 10 rows
rows = client.list_rows(table, max_results=10)
assert len(list(rows)) == 10

# Specify selected fields to limit the results to certain columns
fields = table.schema[:2]  # first two columns
rows = client.list_rows(table, selected_fields=fields, max_results=10)
assert len(rows.schema) == 2
assert len(list(rows)) == 10

# Use the start index to load an arbitrary portion of the table
rows = client.list_rows(table, start_index=10, max_results=10)

# Print row data in tabular format
format_string = '{!s:<16} ' * len(rows.schema)
field_names = [field.name for field in rows.schema]
print(format_string.format(*field_names))  # prints column headers
for row in rows:
    print(format_string.format(*row))      # prints row data

Ruby

Antes de probar esta muestra, sigue las instrucciones de configuración de 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.

La paginación se realiza automáticamente en la biblioteca cliente de Google Cloud para Ruby mediante Table#data y Data#next.

require "google/cloud/bigquery"

def browse_table
  bigquery = Google::Cloud::Bigquery.new project_id: "bigquery-public-data"
  dataset  = bigquery.dataset "samples"
  table    = dataset.table "shakespeare"

  # Load all rows from a table
  rows = table.data

  # Load the first 10 rows
  rows = table.data max: 10

  # Print row data
  rows.each { |row| puts row }
end

Cómo solicitar páginas arbitrarias y evitar llamadas redundantes a las listas

Cuando retrocedes la página o saltas a páginas arbitrarias utilizando valores de pageToken almacenados en caché, es posible que los datos de tus páginas hayan cambiado desde la última vez que se vieron, pero no hay una indicación clara de que los datos hayan cambiado. Para mitigar esto, puedes usar la propiedad Etag.

Cada método collection.list (excepto Tabledata) muestra una propiedad Etag en el resultado. Esta propiedad es un hash de los resultados de la página que se puede usar para verificar si la página ha cambiado desde la última solicitud. Cuando realizas una solicitud a BigQuery con un valor Etag, BigQuery compara el valor Etag con el valor de ETag mostrado por la API y responde si los valores ETag coinciden. Puedes usar ETags para ayudar a evitar llamadas redundantes a las listas de las siguientes maneras:

  • Si solo deseas que se muestren los valores de la lista si los valores han cambiado:

    Si solo deseas que se muestre una página con los valores de la lista si los valores han cambiado, puedes crear una llamada a la lista con un ETag previamente almacenado mediante el encabezado HTTP "if-none-match". Si el ETag que proporcionas no coincide con el ETag en el servidor, BigQuery muestra una página de valores de lista nuevos. Si los ETag coinciden, BigQuery muestra un resultado HTTP 304 "Not Modified" y no hay valores. Un ejemplo de esto podría ser una página web donde los usuarios pueden completar periódicamente información que se encuentra almacenada en BigQuery. Puedes evitar hacer llamadas redundantes a las listas en BigQuery si no hay cambios en tus datos utilizando el encabezado if-none-match con ETag.

  • Si solo deseas que se muestren los valores de la lista si los valores han cambiado:

    Si solo deseas que se muestre una página con los valores de la lista si los valores han cambiado, puedes usar el encabezado HTTP "if-match". BigQuery hace coincidir valores de los ETag y muestra la página de resultados si los resultados no han cambiado, o muestra un resultado 412 "Precondition Failed" si la página ha cambiado.

Nota: A pesar de que los ETag son una excelente manera de evitar la realización de llamadas redundantes a las listas, puedes aplicar los mismos métodos para identificar si algún objeto ha cambiado. Por ejemplo, puedes realizar una solicitud Obtener para una tabla específica y usar ETag para determinar si la tabla ha cambiado antes de mostrar la respuesta completa.


¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.