Paginación a través de datos de tablas

En este documento, se describe cómo desplazarse a través de los datos de tablas con la API de REST de BigQuery.

Desplázate 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 de 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 antes, los resultados se paginarán según el valor máximo.

Una página es un subconjunto de la cantidad 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 usa para desplazarse por los datos de la tabla, usa un valor de desplazamiento de fila o un token de página. Consulta Explora datos de tablas para obtener más información.

Los siguientes ejemplos muestran la paginación a través de los datos de tablas 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. Si necesitas 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 este ejemplo, sigue las instrucciones de configuración de Java incluidas 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 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 este ejemplo, sigue las instrucciones de configuración de Go incluidas 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 Go de BigQuery.

La biblioteca cliente de Google Cloud para Go se pagina automáticamente de forma predeterminada, por lo que no necesitas implementar la paginación. 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 para Node.js 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 Node.js.

La biblioteca cliente de Google Cloud para Node.js se pagina automáticamente de forma predeterminada, por lo que no necesitas implementar la paginación, por ejemplo:


// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function browseRows() {
  // Displays rows from "my_table" in "my_dataset".

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

  // List 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. A fin de obtener más información, consulta la Documentación de referencia de la API de BigQuery para PHP.

La paginación se realiza de forma automática en la biblioteca cliente de Google Cloud para PHP con 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 este ejemplo, sigue las instrucciones de configuración de Python incluidas 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 Python de BigQuery.

La biblioteca cliente de Google Cloud para Python se pagina automáticamente de forma predeterminada, por lo que no necesitas implementar la paginación. Por ejemplo:

# 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 para Ruby que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Si deseas obtener más información, consulta la Documentación de referencia de la API de BigQuery de Ruby.

La paginación se realiza de forma automática 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

Solicita páginas arbitrarias y evita 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 ETags 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, de manera periódica, 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 con el encabezado if-none-match con ETags.

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

    Si solo deseas que se muestre una página con los valores de la lista en caso de que los valores no hayan cambiado, puedes usar el encabezado HTTP “if-match”. BigQuery hace coincidir los 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 ETags 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 en una tabla específica y usar ETags para determinar si la tabla ha cambiado antes de mostrar la respuesta completa.
¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Si necesitas ayuda, visita nuestra página de asistencia.