Crea y administra esquemas de Protobuf

En este documento, se describe cómo crear y realizar operaciones en paquetes de esquemas.

En Bigtable, puedes usar esquemas de búfer de protocolo (protobuf) para consultar campos individuales dentro de mensajes protobuf almacenados como bytes en tus columnas. Para ello, sube tus esquemas en un paquete de esquemas, un recurso a nivel de tabla que contiene uno o más de tus esquemas de protobuf.

El uso de paquetes de esquemas ofrece los siguientes beneficios:

  • Ahorra tiempo y esfuerzo: Con los búferes de protocolo, defines tu estructura de datos una vez en un archivo proto y, luego, usas el código fuente generado para escribir y leer tus datos.
  • Mejora la coherencia de los datos: Si usas un archivo proto como fuente única de información, puedes asegurarte de que todas las aplicaciones y los servicios usen el mismo modelo de datos.
  • Elimina la duplicación de datos: Puedes usar búferes de protocolo en todos los proyectos definiendo tipos de mensajes en archivos proto que residen fuera de la base de código de un proyecto específico.

El proceso de uso de esquemas en Bigtable comienza con tus archivos proto. Un archivo proto es un archivo de texto en el que defines la estructura de tus datos. Usa la herramienta de compilación de protobuf, también conocida como protoc, para generar un conjunto de descriptores de archivos protobuf, que es un esquema legible por máquinas de tu archivo proto. Luego, usa este conjunto de descriptores para crear un paquete de esquemas.

Para ver ejemplos de archivos proto y sus conjuntos de descriptores correspondientes, consulta Datos de ejemplo.

En el siguiente diagrama, se muestra el proceso de uso de esquemas en Bigtable:

Es el proceso de usar esquemas de protobuf en Bigtable.
Figura 1. Proceso de uso de esquemas de Protobuf en Bigtable (haz clic para ampliar).

Puedes crear paquetes de esquemas con la consola de Google Cloud o la Google Cloud CLI. Después de subir un paquete de esquemas a Bigtable, puedes consultar tus datos con el compilador de consultas de Bigtable Studio, GoogleSQL para Bigtable o las tablas externas de Bigtable en BigQuery.

Antes de comenzar

Sigue estos pasos si planeas usar gcloud CLI:

  1. Instala la Google Cloud CLI.

  2. Inicializa gcloud CLI:

    gcloud init

Roles obligatorios

Para obtener los permisos que necesitas para crear y administrar paquetes de esquemas, pídele a tu administrador que te otorgue el rol de Identity and Access Management (IAM) de Administrador de Bigtable (roles/bigtable.admin) en la tabla.

Este rol predefinido contiene los permisos que Bigtable necesita para trabajar con paquetes de esquemas. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

  • bigtable.schemaBundles.create
  • bigtable.schemaBundles.update
  • bigtable.schemaBundles.delete
  • bigtable.schemaBundles.get
  • bigtable.schemaBundles.list

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

Para obtener más información sobre los roles y permisos de Bigtable, consulta Control de acceso con IAM.

Genera un conjunto de descriptores de archivos de protobuf

Antes de crear un paquete de esquemas, debes generar un conjunto de descriptores a partir de tus archivos proto con la herramienta del compilador de protobuf.

  1. Para instalar el compilador, descarga el paquete y sigue las instrucciones del archivo README.

  2. Ejecuta el compilador:

    protoc --proto_path=IMPORT_PATH --include_imports \
   --descriptor_set_out=DESCRIPTOR_OUTPUT_LOCATION PATH_TO_PROTO

    Reemplaza lo siguiente:

    • IMPORT_PATH: Es el directorio en el que el compilador protoc busca archivos proto.
    • DESCRIPTOR_OUTPUT_LOCATION: Es el directorio en el que el compilador protoc guarda el conjunto de descriptores generado.
    • PATH_TO_PROTO: Es la ruta de acceso a tu archivo proto.

Por ejemplo, para crear un conjunto de descriptores llamado library.pb para el archivo library.proto en el directorio actual, puedes usar el siguiente comando:

protoc --include_imports --descriptor_set_out=library.pb
library.proto

Crea un paquete de esquemas

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, junto a la tabla en la que deseas crear un paquete de esquemas, haz clic en el menú de acciones more_vert y, luego, en Crear paquete de esquemas.

  5. En el cuadro de diálogo Crear paquete de esquemas, en el campo ID del paquete de esquemas, ingresa un identificador único para el paquete de esquemas.

    El ID debe tener entre 1 y 50 caracteres, solo puede contener letras, números, guiones bajos y guiones, no puede comenzar con un guion y no puede contener el carácter de punto (.).

  6. En el campo Conjunto de descriptores de archivos (archivo .pb), haz clic en Explorar para seleccionar el conjunto de descriptores de archivos protobuf que creaste en la sección Genera un conjunto de descriptores de archivos protobuf de este documento. El tamaño del archivo no puede superar los 4 MB.

  7. Haz clic en Crear.

    El paquete de esquemas se abrirá en una pestaña nueva.

gcloud

Para crear un paquete de esquemas, usa el comando gcloud bigtable schema-bundles create:

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: un ID único para el paquete de esquemas nuevo que no puede contener ningún carácter de punto ('.').
  • INSTANCE_ID: Es el ID de la instancia en la que creas el paquete de esquemas.
  • TABLE_ID: el ID de la tabla en la que creas el paquete de esquemas.
  • PROTO_DESCRIPTORS_FILE: Es la ruta de acceso al conjunto de descriptores que creaste en la sección Genera un conjunto de descriptores de archivos protobuf de este documento.

Java

Para crear un paquete de esquemas, usa el método createSchemaBundle:

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

try (InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  CreateSchemaBundleRequest request =
      CreateSchemaBundleRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .setSchemaBundleId(schemaBundleId)
          .setSchemaBundle(schemaBundleObj)
          .build();
  SchemaBundle schemaBundle = adminClient.createSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s created successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to create a schema bundle: " + e.getMessage());
}

Visualiza información sobre los paquetes de esquemas

Antes de poder ver información sobre los paquetes de esquemas, debes tener una tabla de Bigtable con al menos un paquete de esquemas. Puedes obtener información sobre los paquetes de esquemas de una tabla recuperando la definición de un solo paquete de esquemas o enumerando todos los paquetes de esquemas de una tabla.

Obtén la definición del paquete de esquemas

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, expande la tabla que contiene el paquete de esquemas y, luego, expande Paquetes de esquemas.

  5. Haz clic en el paquete de esquemas que deseas ver o en el menú de acciones more_vert junto al paquete de esquemas y, luego, en Ver detalles.

    Se abrirá una pestaña que muestra la definición del paquete de esquemas.

  6. Opcional: Para abrir una pestaña del editor de consulta en SQL con una consulta de ejemplo que use el paquete de esquemas, haz clic en el menú de acciones more_vert junto al paquete de esquemas y, luego, en Consulta de ejemplo.

gcloud

Para obtener detalles sobre un paquete de esquemas, usa el comando gcloud bigtable schema-bundles describe:

gcloud bigtable schema-bundles describe SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: Es el ID del paquete de esquemas.
  • INSTANCE_ID: el ID de la instancia
  • TABLE_ID: el ID de la tabla.

Java

Para obtener la definición de un paquete de esquemas, usa el método getSchemaBundle. Este método devuelve un objeto SchemaBundle que contiene la definición del esquema.

En el siguiente ejemplo, se muestra cómo obtener un paquete de esquemas y deserializar el conjunto de descriptores para imprimir el contenido del esquema:

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

SchemaBundle schemaBundle = null;
try {
  schemaBundle =
      adminClient.getSchemaBundle(
          "projects/"
              + projectId
              + "/instances/"
              + instanceId
              + "/tables/"
              + tableId
              + "/schemaBundles/"
              + schemaBundleId);
  // Deserialize and print the FileDescriptorSet
  DescriptorProtos.FileDescriptorSet fileDescriptorSet =
      DescriptorProtos.FileDescriptorSet.parseFrom(
          schemaBundle.getProtoSchema().getProtoDescriptors());

  System.out.println("--------- Deserialized FileDescriptorSet ---------");
  for (DescriptorProtos.FileDescriptorProto fileDescriptorProto :
      fileDescriptorSet.getFileList()) {
    System.out.println("File: " + fileDescriptorProto.getName());
    System.out.println("  Package: " + fileDescriptorProto.getPackage());
    for (DescriptorProtos.DescriptorProto messageType :
        fileDescriptorProto.getMessageTypeList()) {
      System.out.println("  Message: " + messageType.getName());
    }
  }
  System.out.println("--------------------------------------------------");
} catch (InvalidProtocolBufferException e) {
  System.err.println("Failed to parse FileDescriptorSet: " + e.getMessage());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to retrieve metadata from a non-existent schema bundle: " + e.getMessage());
}

El resultado es similar a lo siguiente:

--------- Deserialized FileDescriptorSet ---------
File: my_schema.proto
Package: my_package
Message: MyMessage
--------------------------------------------------

Enumera los paquetes de esquemas en una tabla

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, expande la tabla que contiene los paquetes de esquemas que deseas ver.

  5. Expande Paquetes de esquemas.

    Aparecerá la lista de paquetes de esquemas en la tabla. Si la tabla no tiene ningún paquete de esquemas, no se muestra la lista Paquetes de esquemas.

gcloud

Para ver una lista de paquetes de esquemas de una tabla, usa el comando gcloud bigtable schema-bundles list:

gcloud bigtable schema-bundles list \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Reemplaza lo siguiente:

  • INSTANCE_ID: el ID de la instancia
  • TABLE_ID: el ID de la tabla.

Java

Para ver una lista de todos los paquetes de esquemas de una tabla, usa el método listSchemaBundles. Este método devuelve una lista de IDs de paquetes de esquemas.

En el siguiente ejemplo, se muestra cómo enumerar los paquetes de esquemas en una tabla:

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

List<String> schemaBundleIds = new ArrayList<>();
try {
  ListSchemaBundlesRequest request =
      ListSchemaBundlesRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .build();
  for (SchemaBundle bundle : adminClient.listSchemaBundles(request).iterateAll()) {
    String id = SchemaBundleName.parse(bundle.getName()).getSchemaBundle();
    System.out.println(id);
    schemaBundleIds.add(id);
  }
} catch (NotFoundException e) {
  System.err.println(
      "Failed to list schema bundles from a non-existent table: " + e.getMessage());
}

El resultado es similar a lo siguiente:

my-schema-bundle-1
my-schema-bundle-2

Actualiza un paquete de esquemas

Cuando actualizas un paquete de esquemas, Bigtable verifica si el nuevo conjunto de descriptores es retrocompatible con el existente. Si Bigtable detecta incompatibilidad, la actualización falla con un error FailedPrecondition. Te recomendamos que reserves los números de campo borrados para evitar que se vuelvan a usar. Para obtener más información, consulta Prácticas recomendadas para Proto en la documentación de protobuf.

Si tienes la certeza de que los cambios incompatibles son seguros y quieres forzar una actualización, puedes usar la marca --ignore-warnings con gcloud CLI. Sin embargo, no puedes forzar cambios incompatibles si el paquete de esquemas está en uso por una vista materializada continua o una vista lógica. Las vistas dependen de las definiciones de mensajes del paquete de esquemas para analizar y consultar datos, por lo que los cambios incompatibles interrumpirían las consultas en las vistas lógicas y provocarían que las vistas materializadas continuas fallen durante el procesamiento de datos. Para realizar cambios incompatibles con versiones anteriores en un paquete de esquemas al que hace referencia una vista, primero debes actualizar o borrar las vistas de referencia.

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, expande la tabla que contiene el paquete de esquemas y, luego, expande Paquetes de esquemas.

  5. Junto al paquete de esquemas que deseas actualizar, haz clic en el menú de acciones more_vert y, luego, en Actualizar.

  6. En el cuadro de diálogo Actualizar paquete de esquemas, en el campo Conjunto de descriptores de archivos (archivo .pb), selecciona el nuevo conjunto de descriptores de archivos protobuf. El tamaño del archivo no puede superar los 4 MB.

  7. Haz clic en Guardar.

gcloud

Para actualizar un paquete de esquemas y usar un conjunto de descriptores diferente, usa el comando gcloud bigtable schema-bundles update:

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: Es el ID del paquete de esquemas que se actualizará.
  • INSTANCE_ID: Es el ID de la instancia que contiene el paquete de esquemas.
  • TABLE_ID: Es el ID de la tabla que contiene el paquete de esquemas.
  • PROTO_DESCRIPTORS_FILE: Es la ruta de acceso al nuevo archivo de conjunto de descriptores.

Opcional: Para forzar la actualización incluso si hay cambios incompatibles, agrega la marca --ignore-warnings al comando. No puedes forzar cambios incompatibles si el paquete de esquemas está en uso por una vista materializada continua o una vista lógica.

Java

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

try (InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setName(
              "projects/"
                  + projectId
                  + "/instances/"
                  + instanceId
                  + "/tables/"
                  + tableId
                  + "/schemaBundles/"
                  + schemaBundleId)
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  UpdateSchemaBundleRequest request =
      UpdateSchemaBundleRequest.newBuilder()
          .setSchemaBundle(schemaBundleObj)
          .setUpdateMask(FieldMask.newBuilder().addPaths("proto_schema").build())
          .build();
  SchemaBundle schemaBundle = adminClient.updateSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s updated successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to modify schema bundle: " + e.getMessage());
}

Borra un paquete de esquemas

No puedes borrar un paquete de esquemas si lo usa una vista materializada continua o una vista lógica. Si borras el paquete, las consultas en las vistas lógicas fallarán y se impedirá que las vistas materializadas continuas procesen los datos entrantes. Para borrar el paquete de esquemas, primero debes borrar las vistas que hacen referencia a él o actualizarlas para quitar la referencia.

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, expande la tabla que contiene el paquete de esquemas y, luego, expande Paquetes de esquemas.

  5. Junto al paquete de esquemas que quieres borrar, haz clic en el menú de acciones more_vert y, luego, en Borrar.

  6. En el diálogo de confirmación, haz clic en Borrar.

gcloud

Para borrar un paquete de esquemas, usa el comando gcloud bigtable schema-bundles delete:

gcloud bigtable schema-bundles delete SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: Es el ID del paquete de esquemas que se borrará.
  • INSTANCE_ID: Es el ID de la instancia que contiene el paquete de esquemas.
  • TABLE_ID: Es el ID de la tabla que contiene el paquete de esquemas.

Java

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

try {
  adminClient.deleteSchemaBundle(
      "projects/"
          + projectId
          + "/instances/"
          + instanceId
          + "/tables/"
          + tableId
          + "/schemaBundles/"
          + schemaBundleId);
  System.out.printf("SchemaBundle: %s deleted successfully%n", schemaBundleId);
} catch (NotFoundException e) {
  System.err.println("Failed to delete a non-existent schema bundle: " + e.getMessage());
}

Limitaciones

Los paquetes de esquemas tienen las siguientes limitaciones:

  • Puedes crear hasta 10 paquetes de esquemas por tabla. Este límite se aplica a los paquetes de esquemas de protobuf y Avro.
  • El tamaño total de los descriptores de búfer de protocolo serializados dentro de un paquete de esquema no puede superar los 4 MB. No hay un límite directo para la cantidad de esquemas individuales que puedes incluir en un paquete, siempre que el tamaño total de este no supere el límite.

¿Qué sigue?