Consulta datos de Cloud Storage en tablas de BigLake

En este documento, se describe cómo consultar datos almacenados en una tabla de BigLake de Cloud Storage.

Antes de comenzar

Asegúrate de tener una tabla de BigLake de Cloud Storage.

Roles obligatorios

Para consultar tablas de BigLake de Cloud Storage, asegúrate de tener los siguientes roles:

Visualizador de datos de BigQuery (roles/bigquery.dataViewer)
BigQuery User (roles/bigquery.user)

Según los permisos que tengas, puedes otorgarte estos roles o pedirle a tu administrador que te los otorgue. Para obtener más información sobre cómo otorgar roles, consulta Visualiza los roles que se pueden otorgar en los recursos.

Para ver los permisos exactos necesarios para consultar las tablas de BigLake de Cloud Storage, expande la sección Permisos necesarios:

Permisos necesarios

bigquery.jobs.create
bigquery.readsessions.create (solo es necesario si lees datos con la API de BigQuery Storage Read)
bigquery.tables.get
bigquery.tables.getData

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos

Consulta tablas de BigLake

Después de crear una tabla de BigLake de Cloud Storage, puedes consultarla con la sintaxis de Google SQL, de la misma manera que si fuese una tabla de BigQuery estándar. Por ejemplo, SELECT field1, field2 FROM mydataset.my_cloud_storage_table;

Consulta tablas de BigLake con herramientas de procesamiento de datos externas

Puedes usar conectores de BigQuery con otras herramientas de procesamiento de datos para acceder a las tablas de BigLake en Cloud Storage. Para obtener más información, consulta Conectores.

Apache Spark

En el siguiente ejemplo, se usa Dataproc, pero también funciona con cualquier implementación de Spark que use el conector de BigQuery de Spark.

En este ejemplo, proporcionas el conector de BigQuery de Spark como una acción de inicialización cuando creas un clúster. Esta acción te permite usar un notebook de Zeppelin y hacer el recorrido del usuario de analistas de datos.

Las versiones del conector de BigQuery de Spark se enumeran en el repositorio de GoogleCloudDataproc/spark-bigquery-connector de GitHub.

Crea un clúster de nodo único con la acción de inicialización para el conector de BigQuery de Spark:

gcloud dataproc clusters create biglake-demo-cluster \
    --optional-components=ZEPPELIN \
    --region=REGION \
    --enable-component-gateway \
    --single-node \
    --initialization-actions gs://goog-dataproc-initialization-actions-REGION/connectors/connectors.sh \
    --metadata spark-bigquery-connector-url= gs://spark-lib/bigquery/spark-bigquery-with-dependencies_SCALA_VERSION-CONNECTOR_VERSION.jar

Apache Hive

En el siguiente ejemplo, se usa Dataproc, pero también funciona con cualquier implementación de Hive que use el conector de BigQuery de Hive.

En este ejemplo, proporcionas el conector de BigQuery de Hive como una acción de inicialización cuando creas un clúster.

Las versiones del conector de BigQuery de Hive se enumeran en el repositorio de GoogleCloudDataproc/hive-bigquery-connector de GitHub.

Crea un clúster de nodo único con la acción de inicialización para el conector de BigQuery de Hive:

gcloud dataproc clusters create biglake-hive-demo-cluster \
    --region=REGION \
    --single-node \
    --initialization-actions gs://goog-dataproc-initialization-actions-REGION/connectors/connectors.sh \
    --metadata hive-bigquery-connector-url=gs://goog-dataproc-artifacts-REGION/hive-bigquery/hive-bigquery-connector-CONNECTOR_VERSION.jar

Para obtener más información sobre el conector de Hive-BigQuery, consulta Usa el conector de Hive-BigQuery.

Dataflow

Para leer tablas de BigLake de Dataflow, usa el conector de Dataflow en modo DIRECT_READ para usar la API de BigQuery Storage. También se admite la lectura de una string de consulta. Consulta E/S de BigQuery en la documentación de Apache Beam.

Consulta tablas temporales de BigLake

Consultar una fuente de datos externa con una tabla temporal es útil para las consultas únicas ad-hoc sobre datos externos o procesos de extracción, transformación y carga (ETL).

Para consultar una fuente de datos externa sin crear una tabla permanente, debes proporcionar una definición de tabla para la tabla temporal y, luego, usar esa definición de tabla en un comando o llamada para consultar la tabla temporal. Puedes proporcionar la definición de la tabla de cualquiera de las siguientes maneras:

Un archivo de definición de tabla
Una definición de esquema intercalado
Un archivo de esquema JSON

Se emplea el archivo de definición de tabla o el esquema proporcionado para crear la tabla externa temporal, y es en esta donde se ejecuta la consulta.

Cuando usas una tabla externa temporal, no se crea una tabla en uno de los conjuntos de datos de BigQuery. Debido a que la tabla no se almacena de forma permanente en un conjunto de datos, no puede compartirse con otras personas.

Puedes crear y consultar una tabla temporal vinculada a una fuente de datos externa mediante la herramienta de línea de comandos de bq, la API o las bibliotecas cliente.

bq

Usa el comando bq query con la marca --external_table_definition.

Opcional: Proporciona la marca --location y configura el valor en tu ubicación.

Para hacer una consulta en una tabla temporal vinculada a tu fuente de datos externa por medio de un archivo de definición de tablas, escribe el siguiente comando:

bq --location=LOCATION query \
--external_table_definition=TABLE::DEFINITION_FILE \
'QUERY'

Reemplaza lo siguiente:

LOCATION: El nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes establecer el valor de la marca en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
TABLE: Es el nombre de la tabla temporal que crearás.
DEFINITION_FILE: Es la ruta de acceso al archivo de definición de tabla en tu máquina local.
QUERY: es la consulta que enviarás a la tabla temporal.

Por ejemplo, con el siguiente comando, se crea y consulta una tabla temporal llamada sales mediante un archivo de definición de tablas denominado sales_def.

bq query \
--external_table_definition=sales::sales_def@us.myconnection \
'SELECT
  Region,
  Total_sales
FROM
  sales'

Para hacer una consulta en una tabla temporal vinculada a tu fuente de datos externa por medio de una definición de esquema intercalado, escribe el comando siguiente.

bq --location=LOCATION query \
--external_table_definition=TABLE::SCHEMA@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
'query'

Reemplaza lo siguiente:

LOCATION: El nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes establecer el valor de la marca en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
TABLE: Es el nombre de la tabla temporal que crearás.
SCHEMA: Es la definición de esquema intercalada en el formato field:data_type,field:data_type.
SOURCE_FORMAT: es el formato de la fuente de datos externa, por ejemplo, CSV.
BUCKET_PATH: la ruta al bucket de Cloud Storage que contiene los datos de la tabla, en el formato gs://bucket_name/[folder_name/]file_pattern.

Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (*) en la ruta de acceso file_pattern. Un ejemplo es gs://mybucket/file00*.parquet. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso.

En los siguientes ejemplos, se muestran valores uris válidos:
- gs://bucket/path1/myfile.csv
- gs://bucket/path1/*.parquet
- gs://bucket/path1/file1*, gs://bucket1/path1/*
Cuando especificas valores uris que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.

Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.
PROJECT_ID: el proyecto que contiene la conexión.
REGION: la región que contiene la conexión, por ejemplo, us.
CONNECTION_ID: el nombre de la conexión, por ejemplo, myconnection
QUERY: es la consulta que enviarás a la tabla temporal.

Por ejemplo, con el siguiente comando, se crea y consulta una tabla temporal llamada sales vinculada a un archivo CSV almacenado en Cloud Storage con la siguiente definición de esquema: Region:STRING,Quarter:STRING,Total_sales:INTEGER.

bq query \
--external_table_definition=sales::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv@us.myconnection \
'SELECT
  Region,
  Total_sales
FROM
  sales'

Para hacer una consulta en una tabla temporal vinculada a tu fuente de datos externa por medio de un archivo de esquema JSON, escribe el siguiente comando:

bq --location=LOCATION query \
--external_table_definition=SCHEMA_FILE@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
'QUERY'

Reemplaza lo siguiente:

LOCATION: El nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes establecer el valor de la marca en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
SCHEMA_FILE: la ruta al archivo de esquema JSON en tu máquina local.
SOURCE_FORMAT: es el formato de la fuente de datos externa, por ejemplo, CSV.
BUCKET_PATH: la ruta al bucket de Cloud Storage que contiene los datos de la tabla, en el formato gs://bucket_name/[folder_name/]file_pattern.

Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (*) en la ruta de acceso file_pattern. Un ejemplo es gs://mybucket/file00*.parquet. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso.

En los siguientes ejemplos, se muestran valores uris válidos:
- gs://bucket/path1/myfile.csv
- gs://bucket/path1/*.parquet
- gs://bucket/path1/file1*, gs://bucket1/path1/*
Cuando especificas valores uris que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.

Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.
PROJECT_ID: el proyecto que contiene la conexión.
REGION: la región que contiene la conexión, por ejemplo, us.
CONNECTION_ID: el nombre de la conexión, por ejemplo, myconnection
QUERY: es la consulta que enviarás a la tabla temporal.

Por ejemplo, con el comando siguiente, se crea y consulta una tabla temporal llamada sales vinculada a un archivo CSV almacenado en Cloud Storage con el archivo de esquema /tmp/sales_schema.json.

  bq query \
  --external_table_definition=sales::/tmp/sales_schema.json@CSV=gs://mybucket/sales.csv@us.myconnection \
  'SELECT
      Region,
      Total_sales
    FROM
      sales'

API

Para ejecutar una consulta con la API, sigue estos pasos:

Crea un objeto Job.
Propaga la sección configuration del objeto Job con un objeto JobConfiguration.
Propaga la sección query del objeto JobConfiguration con un objeto JobConfigurationQuery.
Propaga la sección tableDefinitions del objeto JobConfigurationQuery con un objeto ExternalDataConfiguration. Especifica la conexión que se usará para conectarse a Cloud Storage en el campo connectionId.
Llama al método jobs.insert para ejecutar la consulta de forma asíncrona o al método jobs.query para ejecutar la consulta de forma síncrona y pasar el objeto Job.

¿Qué sigue?

Obtén más información sobre cómo usar SQL en BigQuery.
Obtén más información sobre tablas de BigLake.
Obtén más información sobre las cuotas de BigQuery.