Crear una tabla externa de Bigtable

En esta página se describe cómo crear una tabla externa permanente de BigQuery que se puede usar para consultar datos almacenados en Bigtable. La consulta de datos en Bigtable está disponible en todas las ubicaciones de Bigtable.

Antes de empezar

Antes de crear una tabla externa, reúne información y asegúrate de que tienes permiso para crearla.

Roles obligatorios

Para crear una tabla externa que se use para consultar tus datos de Bigtable, debes ser un principal con el rol Administrador de Bigtable (roles/bigtable.admin) de la instancia que contiene la tabla de origen.

También necesitas el permiso bigquery.tables.create Gestión de Identidades y Accesos (IAM) de BigQuery.

Cada uno de los siguientes roles predefinidos de gestión de identidades y accesos incluye este permiso:

• Editor de datos de BigQuery (roles/bigquery.dataEditor)
• Propietario de datos de BigQuery (roles/bigquery.dataOwner)
• Administrador de BigQuery (roles/bigquery.admin)

Si no eres un principal de ninguno de estos roles, pide a tu administrador que te dé acceso o que cree la tabla externa por ti.

Para obtener más información sobre los roles y permisos de gestión de identidades y accesos en BigQuery, consulta el artículo sobre roles y permisos predefinidos. Para ver información sobre los permisos de Bigtable, consulta Control de acceso con Gestión de Identidades y Accesos. Para ver los roles necesarios para consultar la tabla externa, consulta Consultar datos de Bigtable.

Crear o identificar un conjunto de datos

Antes de crear una tabla externa, debe crear un conjunto de datos que la contenga. También puedes usar un conjunto de datos que ya tengas.

Planificar el uso de los recursos de computación

Vista previa

Este producto o función está sujeto a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Los productos y las funciones previos a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Determina el tipo de proceso que quieres usar al consultar tus datos. Indicas que quieres usar Data Boost o que quieres enrutar a un clúster dedicado en la configuración del perfil de tu aplicación.

Data Boost

Para evitar que afecte al tráfico de servicio de tu aplicación, puedes usar el servicio de computación sin servidor Data Boost cuando uses una tabla externa de BigQuery para leer tus datos de Bigtable. Para usar Data Boost, debe usar un perfil de aplicación de Data Boost e incluir el ID del perfil de aplicación al crear su URI de Bigtable. Para obtener más información sobre Data Boost, consulta el resumen de Bigtable Data Boost.

Nodos aprovisionados

Si no usas Data Boost, los nodos del clúster se utilizan para el cálculo.

Si no usas Data Boost y tienes previsto consultar con frecuencia los mismos datos que sirven a tu aplicación de producción, te recomendamos que designes un clúster de tu instancia de Bigtable para que se use únicamente en los análisis de BigQuery. De esta forma, se aísla el tráfico del clúster o los clústeres que usas para las lecturas y escrituras de tu aplicación. Para obtener más información sobre la replicación y la creación de instancias que tengan más de un clúster, consulta Acerca de la replicación.

Identificar o crear un perfil de aplicación

Antes de crear una tabla externa, decide qué perfil de aplicación de Bigtable debe usar BigQuery para leer los datos. Te recomendamos que uses un perfil de aplicación que designes para usarlo únicamente con BigQuery. El perfil de aplicación puede ser un perfil de aplicación estándar o un perfil de aplicación Data Boost, en función del tipo de computación que quieras usar para consultar tus datos.

Si tienes un clúster en tu instancia de Bigtable que está dedicado al acceso de BigQuery, configura el perfil de aplicación para que use el enrutamiento de un solo clúster a ese clúster.

Para usar la computación sin servidor de Data Boost, crea un perfil de aplicación de Data Boost. Para usar nodos de clúster para computación, crea un perfil de aplicación estándar. Para saber cómo funcionan los perfiles de aplicación de Bigtable, consulta Acerca de los perfiles de aplicación. Para saber cómo crear un perfil de aplicación, consulta el artículo Crear y configurar perfiles de aplicaciones.

Obtener el URI de Bigtable

Para crear una tabla externa de una fuente de datos de Bigtable, debes proporcionar el URI de Bigtable. Para obtener el URI de Bigtable, haga lo siguiente:

1. Abre la página de Bigtable en la consola.

   Ir a Bigtable

2. Obtén los siguientes detalles sobre tu fuente de datos de Bigtable:

   • El ID de tu proyecto.
   • Tu ID de instancia de Bigtable.
   • El ID del perfil de aplicación de Bigtable que tienes previsto usar. Puede ser un perfil de aplicación estándar o un perfil de aplicación de Data Boost, en función del tipo de cálculo que quieras usar. Si no especificas un ID de perfil de aplicación, se usará el perfil de aplicación predeterminado.
   • El nombre de tu tabla de Bigtable.

3. Crea el URI de Bigtable con el siguiente formato:

   • PROJECT_ID es el proyecto que contiene tu instancia de Bigtable.
   • INSTANCE_ID es el ID de la instancia de Bigtable.
   • APP_PROFILE (opcional) es el identificador del perfil de aplicación que quieres usar.
   • TABLE_NAME es el nombre de la tabla que estás consultando.

   https://googleapis.com/bigtable/projects/PROJECT_ID/instances/INSTANCE_ID[/appProfiles/APP_PROFILE]/tables/TABLE_NAME

Nota: Solo se puede especificar un URI de Bigtable, que debe ser una URL de HTTPS válida y totalmente especificada de una tabla de Bigtable. No se admiten comodines en las fuentes de datos externas de Bigtable.

Crear tablas externas permanentes

Cuando creas una tabla externa permanente en BigQuery que está vinculada a una fuente de datos de Bigtable, tienes dos opciones para especificar el formato de la tabla externa:

• Si usas la API o la herramienta de línea de comandos bq, debes crear un archivo de definición de tabla que defina el esquema y los metadatos de la tabla externa.
• Si usas SQL, debes usar la opción uri de la sentencia CREATE EXTERNAL TABLE para especificar la tabla de Bigtable de la que quieres extraer datos y la opción bigtable_options para especificar el esquema de la tabla.

Los datos de la tabla externa no se almacenan en la tabla de BigQuery. Como la tabla es permanente, puedes usar los controles de acceso a nivel de conjunto de datos para compartirla con otros usuarios que también tengan acceso a la fuente de datos de Bigtable subyacente.

Para crear una tabla permanente, elige uno de los siguientes métodos.

SQL

Puedes crear una tabla externa permanente ejecutando la CREATE EXTERNAL TABLE instrucción DDL. Debe especificar el esquema de la tabla de forma explícita como parte de las opciones de la instrucción.

1. En la Google Cloud consola, ve a la página BigQuery.

   Ir a BigQuery

2. En el editor de consultas, introduce la siguiente instrucción:

   CREATE EXTERNAL TABLE DATASET.NEW_TABLE
   OPTIONS (
     format = 'CLOUD_BIGTABLE',
     uris = ['URI'],
     bigtable_options = BIGTABLE_OPTIONS );

   Haz los cambios siguientes:

   • DATASET: el conjunto de datos en el que se creará la tabla externa de Bigtable.
   • NEW_TABLE: el nombre de la tabla externa de Bigtable.
   • URI: el URI de la tabla de Bigtable que quieras usar como fuente de datos. Este URI debe seguir el formato descrito en Obtener el URI de Bigtable.
   • BIGTABLE_OPTIONS: el esquema de la tabla de Bigtable en formato JSON. Para ver una lista de las opciones de definición de tablas de Bigtable, consulta BigtableOptions en la referencia de la API REST.

3. Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

Una instrucción para crear una tabla externa de Bigtable podría ser similar a la siguiente:

CREATE EXTERNAL TABLE mydataset.BigtableTable
OPTIONS (
  format = 'CLOUD_BIGTABLE',
  uris = ['https://googleapis.com/bigtable/projects/myproject/instances/myBigtableInstance/appProfiles/myAppProfile/tables/table1'],
  bigtable_options =
    """
    {
      columnFamilies: [
        {
          "familyId": "familyId1",
          "type": "INTEGER",
          "encoding": "BINARY"
        }
      ],
      readRowkeyAsString: true
    }
    """
);

bq

Para crear una tabla en la herramienta de línea de comandos bq, usa el comando bq mk. Cuando usas la herramienta de línea de comandos bq para crear una tabla vinculada a una fuente de datos externa, identificas el esquema de la tabla mediante un archivo de definición de tabla.

1. Usa el comando bq mk para crear una tabla permanente.

   bq mk \
   --external_table_definition=DEFINITION_FILE \
   DATASET.TABLE

   Haz los cambios siguientes:

   • DEFINITION_FILE: la ruta al archivo de definición de tabla en tu máquina local.
   • DATASET: el nombre del conjunto de datos que contiene la tabla.
   • TABLE: el nombre de la tabla que vas a crear.

API

Usa el método de la API tables.insert y crea un ExternalDataConfiguration en el recurso Table que le envíes.

En la propiedad sourceUris del recurso Table, especifica solo un URI de Bigtable. Debe ser una URL HTTPS válida.

En el caso de la propiedad sourceFormat, especifica "BIGTABLE".

Java

Antes de probar este ejemplo, sigue las Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.BigtableColumn;
import com.google.cloud.bigquery.BigtableColumnFamily;
import com.google.cloud.bigquery.BigtableOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;
import com.google.cloud.bigquery.TableResult;
import com.google.common.collect.ImmutableList;
import org.apache.commons.codec.binary.Base64;

// Sample to queries an external bigtable data source using a permanent table
public class QueryExternalBigtablePerm {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String bigtableInstanceId = "MY_INSTANCE_ID";
    String bigtableTableName = "MY_BIGTABLE_NAME";
    String bigqueryDatasetName = "MY_DATASET_NAME";
    String bigqueryTableName = "MY_TABLE_NAME";
    String sourceUri =
        String.format(
            "https://googleapis.com/bigtable/projects/%s/instances/%s/tables/%s",
            projectId, bigtableInstanceId, bigtableTableName);
    String query = String.format("SELECT * FROM %s ", bigqueryTableName);
    queryExternalBigtablePerm(bigqueryDatasetName, bigqueryTableName, sourceUri, query);
  }

  public static void queryExternalBigtablePerm(
      String datasetName, String tableName, String sourceUri, String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      BigtableColumnFamily.Builder statsSummary = BigtableColumnFamily.newBuilder();

      // Configuring Columns
      BigtableColumn connectedCell =
          BigtableColumn.newBuilder()
              .setQualifierEncoded(Base64.encodeBase64String("connected_cell".getBytes()))
              .setFieldName("connected_cell")
              .setType("STRING")
              .setEncoding("TEXT")
              .build();
      BigtableColumn connectedWifi =
          BigtableColumn.newBuilder()
              .setQualifierEncoded(Base64.encodeBase64String("connected_wifi".getBytes()))
              .setFieldName("connected_wifi")
              .setType("STRING")
              .setEncoding("TEXT")
              .build();
      BigtableColumn osBuild =
          BigtableColumn.newBuilder()
              .setQualifierEncoded(Base64.encodeBase64String("os_build".getBytes()))
              .setFieldName("os_build")
              .setType("STRING")
              .setEncoding("TEXT")
              .build();

      // Configuring column family and columns
      statsSummary
          .setColumns(ImmutableList.of(connectedCell, connectedWifi, osBuild))
          .setFamilyID("stats_summary")
          .setOnlyReadLatest(true)
          .setEncoding("TEXT")
          .setType("STRING")
          .build();

      // Configuring BigtableOptions is optional.
      BigtableOptions options =
          BigtableOptions.newBuilder()
              .setIgnoreUnspecifiedColumnFamilies(true)
              .setReadRowkeyAsString(true)
              .setColumnFamilies(ImmutableList.of(statsSummary.build()))
              .build();

      TableId tableId = TableId.of(datasetName, tableName);
      // Create a permanent table linked to the Bigtable table
      ExternalTableDefinition externalTable =
          ExternalTableDefinition.newBuilder(sourceUri, options).build();
      bigquery.create(TableInfo.of(tableId, externalTable));

      // Example query
      TableResult results = bigquery.query(QueryJobConfiguration.of(query));

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));

      System.out.println("Query on external permanent table performed successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Consultar tablas externas

Para obtener más información, consulta Consultar datos de Bigtable.

Esquema generado

De forma predeterminada, BigQuery expone los valores de una familia de columnas como un array de columnas y, dentro de este, como un array de valores escritos en diferentes marcas de tiempo. Este esquema conserva el diseño natural de los datos en Bigtable, pero las consultas SQL pueden ser complejas. Es posible ascender columnas a subcampos dentro de la familia de columnas principal y leer solo el valor más reciente de cada celda. Representa ambas matrices del esquema predeterminado como valores escalares.

Ejemplo

Almacenas perfiles de usuario de una red social ficticia. Un modelo de datos para esto podría ser una familia de columnas profile con columnas individuales para gender, age y email:

rowkey | profile:gender| profile:age| profile:email
-------| --------------| -----------| -------------
alice  | female        | 30         | [e-mail]

Con el esquema predeterminado, una consulta de GoogleSQL para contar el número de usuarios varones mayores de 30 años es la siguiente:

SELECT
  COUNT(1)
FROM
  `dataset.table`
OMIT
  RECORD IF NOT SOME(profile.column.name = "gender"
    AND profile.column.cell.value = "male")
  OR NOT SOME(profile.column.name = "age"
    AND INTEGER(profile.column.cell.value) > 30)

Consultar los datos es más sencillo si gender y age se exponen como subcampos. Para exponerlos como subcampos, incluye gender y age como columnas con nombre en la familia de columnas profile al definir la tabla. También puede indicar a BigQuery que muestre los valores más recientes de esta familia de columnas, ya que, normalmente, solo interesa el valor más reciente (y, posiblemente, el único valor).

Después de exponer las columnas como subcampos, la consulta de GoogleSQL para contar el número de usuarios masculinos mayores de 30 años es la siguiente:

SELECT
  COUNT(1)
FROM
  `dataset.table`
WHERE
  profile.gender.cell.value="male"
  AND profile.age.cell.value > 30

Fíjate en cómo se hace referencia a gender y age directamente como campos. La configuración JSON de esta configuración es la siguiente:

  "bigtableOptions": {
    "readRowkeyAsString": "true",
    "columnFamilies": [
      {
          "familyId": "profile",
          "onlyReadLatest": "true",
          "columns": [
              {
                  "qualifierString": "gender",
                  "type": "STRING"
              },
              {
                  "qualifierString": "age",
                  "type": "INTEGER"
              }
          ]
      }
    ]
  }

Codificación de valores

Bigtable almacena los datos como bytes sin procesar, independientemente de la codificación de los datos. Sin embargo, los valores de bytes tienen un uso limitado en el análisis de consultas SQL. Bigtable proporciona dos tipos básicos de decodificación escalar: texto y binario de HBase.

El formato de texto presupone que todos los valores se almacenan como cadenas de texto alfanuméricas. Por ejemplo, el número entero 768 se almacenará como la cadena "768". La codificación binaria asume que se ha usado la clase de métodos Bytes.toBytes de HBase para codificar los datos y aplica un método de decodificación adecuado.

Regiones y zonas admitidas

La consulta de datos en Bigtable está disponible en todas las zonas de Bigtable admitidas. Puedes consultar la lista de zonas aquí. En las instancias multiclúster, BigQuery dirige el tráfico en función de la configuración del perfil de aplicación de Bigtable.

Limitaciones

• No puedes crear tablas externas sobre objetos basados en SQL de Bigtable, como vistas y vistas materializadas continuas.
• Para obtener más información sobre las limitaciones que se aplican a las tablas externas, consulta Limitaciones de las tablas externas.

Ámbitos de las instancias de Compute Engine

Cuando creas una instancia de Compute Engine, puedes especificar una lista de ámbitos para la instancia. Los ámbitos controlan el acceso de la instancia a los productos de Google Cloud, incluido Bigtable. Las aplicaciones que se ejecutan en la VM usan la cuenta de servicio para llamar a las APIs de Google Cloud .

Si configuras una instancia de Compute Engine para que se ejecute como una cuenta de servicio y esa cuenta de servicio accede a una tabla externa vinculada a una fuente de datos de Bigtable, debes añadir el ámbito de acceso de solo lectura a los datos de Bigtable (https://www.googleapis.com/auth/bigtable.data.readonly) a la instancia. Para obtener más información, consulta el artículo Crear una instancia de Compute Engine para Bigtable.

Para obtener información sobre cómo aplicar ámbitos a una instancia de Compute Engine, consulta el artículo Cambiar la cuenta de servicio y los ámbitos de acceso de una instancia. Para obtener más información sobre las cuentas de servicio de Compute Engine, consulta el artículo Cuentas de servicio.

Siguientes pasos

• Más información sobre el diseño de esquemas de Bigtable
• Consulte la introducción a las fuentes de datos externas.