Criar e gerenciar esquemas de protobuf

Neste documento, descrevemos como criar e realizar operações em pacotes de esquema.

No Bigtable, é possível usar esquemas de buffer de protocolo (protobuf) para consultar campos individuais em mensagens protobuf armazenadas como bytes nas colunas. Para isso, faça upload dos esquemas em um pacote de esquemas, um recurso no nível da tabela que contém um ou mais esquemas de protobuf.

O uso de pacotes de esquema oferece os seguintes benefícios:

  • Economiza tempo e esforço: com os buffers de protocolo, você define a estrutura de dados uma vez em um arquivo proto e, em seguida, usa o código-fonte gerado para gravar e ler os dados.
  • Melhora a consistência dos dados: ao usar um arquivo proto como uma única fonte de verdade, você garante que todos os aplicativos e serviços usem o mesmo modelo de dados.
  • Elimina a duplicação de dados: é possível usar buffers de protocolo em vários projetos definindo tipos de mensagem em arquivos proto que residem fora da base de código de um projeto específico.

O processo de uso de esquemas no Bigtable começa com os arquivos proto. Um arquivo proto é um arquivo de texto em que você define a estrutura dos seus dados. Use a ferramenta de compilador protobuf, também conhecida como protoc, para gerar um conjunto de descritores do arquivo protobuf, que é um esquema legível por máquina do seu arquivo proto. Em seguida, use esse conjunto de descritores para criar um pacote de esquema.

Para ver exemplos de arquivos proto e os conjuntos de descritores correspondentes, consulte Dados de exemplo.

O diagrama a seguir mostra o processo de uso de esquemas no Bigtable:

O processo de uso de esquemas de protobuf no Bigtable.
Figura 1. O processo de uso de esquemas protobuf no Bigtable (clique para ampliar).

É possível criar pacotes de esquema usando o console do Google Cloud ou a Google Cloud CLI. Depois de fazer upload de um pacote de esquema para o Bigtable, é possível consultar seus dados usando o criador de consultas do Bigtable Studio, o GoogleSQL para Bigtable ou as tabelas externas do Bigtable no BigQuery.

Antes de começar

Siga estas etapas se você planeja usar a CLI gcloud:

  1. Instale a CLI gcloud.
  2. Inicialize a CLI gcloud.

    gcloud init
    

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar pacotes de esquemas, peça ao administrador para conceder a você o papel do Identity and Access Management (IAM) de Administrador do Bigtable (roles/bigtable.admin) na tabela.

Esse papel predefinido contém as permissões que o Bigtable precisa para trabalhar com pacotes de esquema. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

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

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre os papéis e as permissões do Bigtable, consulte Controle de acesso com o IAM.

Gerar um conjunto de descritores de arquivos protobuf

Antes de criar um pacote de esquema, é necessário gerar um conjunto de descritores dos arquivos proto com a ferramenta de compilador protobuf.

  1. Para instalar o compilador, faça o download do pacote e siga as instruções no arquivo README.
  2. Execute o compilador:

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

    Substitua:

    • IMPORT_PATH: o diretório em que o compilador protoc procura arquivos proto.
    • DESCRIPTOR_OUTPUT_LOCATION: o diretório em que o compilador protoc salva o conjunto de descritores gerado.
    • PATH_TO_PROTO: o caminho para o arquivo proto.

Por exemplo, para criar um conjunto de descritores chamado library.pb para o arquivo library.proto no diretório atual, use o seguinte comando:

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

Criar um pacote de esquema

Console

  1. No console do Google Cloud , abra a lista de instâncias do Bigtable.

    Abrir a lista de instâncias

  2. Selecione uma instância na lista.

  3. No menu de navegação, clique em Bigtable Studio.

  4. No painel Explorer, ao lado da tabela em que você quer criar um pacote de esquema, clique em  Ver ações e em Criar pacote de esquema.

  5. Na caixa de diálogo Criar pacote de esquema, no campo Arquivo de esquema (.pb, .avsc ou .json), clique em Procurar e selecione o conjunto de descritores de arquivo protobuf (arquivo .pb) que você criou na seção Gerar um conjunto de descritores de arquivo protobuf deste documento. O arquivo não pode ter mais de 4 MB.

  6. No campo ID do pacote de esquema, mantenha o ID preenchido automaticamente com base no nome do arquivo ou insira um identificador exclusivo para o pacote de esquema.

    O ID precisa ter de 1 a 50 caracteres, conter apenas letras, números, sublinhados e hifens, não pode começar com um hífen e não pode conter o caractere de ponto (.).

  7. Clique em Criar.

    O pacote de esquemas é aberto em uma nova guia.

gcloud

Para criar um pacote de esquema, use o 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

Substitua:

  • SCHEMA_BUNDLE_ID: um ID exclusivo para o novo pacote de esquema que não pode conter caracteres de ponto final (".").
  • INSTANCE_ID: o ID da instância em que você cria o pacote de esquema.
  • TABLE_ID: o ID da tabela em que você cria o pacote de esquema.
  • PROTO_DESCRIPTORS_FILE: o caminho para o conjunto de descritores que você criou na seção Gerar um conjunto de descritores de arquivos protobuf deste documento.

Java

Para criar um pacote de esquema, use o método createSchemaBundle:

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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());
}

Ver informações sobre pacotes de esquemas

Antes de ver informações sobre pacotes de esquemas, é necessário ter uma tabela do Bigtable com pelo menos um pacote de esquemas. Para receber informações sobre pacotes de esquemas em uma tabela, recupere a definição de um único pacote ou liste todos os pacotes de esquemas em uma tabela.

Receber definição do pacote de esquema

Console

  1. No console do Google Cloud , abra a lista de instâncias do Bigtable.

    Abrir a lista de instâncias

  2. Selecione uma instância na lista.

  3. No menu de navegação, clique em Bigtable Studio.

  4. No painel Explorer, expanda a tabela que contém o pacote de esquemas e, em seguida, expanda Pacotes de esquemas.

  5. Clique no pacote de esquemas que você quer visualizar ou, ao lado dele, clique em  Ver ações e em Ver detalhes.

    Uma guia é aberta com os detalhes do pacote de esquema e a definição do esquema.

  6. Opcional: para abrir uma guia do editor de consultas pré-preenchida com um exemplo de consulta SQL que usa o pacote de esquemas, ao lado do pacote de esquemas, clique em  Ver ações e em Exemplo de consulta.

gcloud

Para ver detalhes sobre um pacote de esquemas, use o comando gcloud bigtable schema-bundles describe:

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

Substitua:

  • SCHEMA_BUNDLE_ID: o ID do pacote de esquema.
  • INSTANCE_ID: o ID da instância.
  • TABLE_ID: o código da tabela.

Java

Para conferir a definição de um pacote de esquema, use o método getSchemaBundle. Esse método retorna um objeto SchemaBundle que contém a definição do esquema.

O exemplo a seguir mostra como receber um pacote de esquema e desserializar o conjunto de descritores para imprimir o conteúdo do esquema:

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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());
}

O resultado será o seguinte:

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

Listar pacotes de esquemas em uma tabela

Console

  1. No console do Google Cloud , abra a lista de instâncias do Bigtable.

    Abrir a lista de instâncias

  2. Selecione uma instância na lista.

  3. No menu de navegação, clique em Bigtable Studio.

  4. No painel Explorer, expanda a tabela que contém os pacotes de esquema que você quer visualizar.

  5. Abra Pacotes de esquema.

    A lista de pacotes de esquemas na tabela é exibida. Se a tabela não tiver pacotes de esquema, a opção Pacotes de esquema não será exibida.

gcloud

Para ver uma lista de pacotes de esquema de uma tabela, use o comando gcloud bigtable schema-bundles list:

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

Substitua:

  • INSTANCE_ID: o ID da instância.
  • TABLE_ID: o código da tabela.

Java

Para ver uma lista de todos os pacotes de esquemas em uma tabela, use o método listSchemaBundles. Esse método retorna uma lista de IDs de pacotes de esquema.

O exemplo a seguir mostra como listar os pacotes de esquema em uma tabela:

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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());
}

O resultado será o seguinte:

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

Atualizar um pacote de esquema

Quando você atualiza um pacote de esquema, o Bigtable verifica se o novo conjunto de descritores é compatível com versões anteriores com o atual. Se o Bigtable detectar incompatibilidade, a atualização vai falhar com um erro FailedPrecondition. Recomendamos que você reserve números de campo excluídos para evitar que sejam reutilizados. Para mais informações, consulte Práticas recomendadas de proto na documentação do protobuf.

Se você tiver certeza de que as mudanças incompatíveis são seguras e quiser forçar uma atualização, use a flag --ignore-warnings com a CLI gcloud. No entanto, não é possível forçar mudanças incompatíveis se o pacote de esquema estiver sendo usado por uma visualização materializada contínua ou uma visualização lógica. As visualizações dependem das definições de mensagem do pacote de esquemas para analisar e consultar dados. Portanto, mudanças incompatíveis interromperiam as consultas em visualizações lógicas e fariam com que as visualizações materializadas contínuas falhassem durante o processamento de dados. Para fazer mudanças incompatíveis com versões anteriores em um pacote de esquemas referenciado por uma visualização, primeiro é necessário atualizar ou excluir as visualizações de referência.

Console

  1. No console do Google Cloud , abra a lista de instâncias do Bigtable.

    Abrir a lista de instâncias

  2. Selecione uma instância na lista.

  3. No menu de navegação, clique em Bigtable Studio.

  4. No painel Explorer, expanda a tabela que contém o pacote de esquemas e, em seguida, expanda Pacotes de esquemas.

  5. Ao lado do pacote de esquemas que você quer atualizar, clique em  Ver ações e em Atualizar.

  6. Na caixa de diálogo Atualizar pacote de esquema, no campo Arquivo de esquema (.pb, .avsc ou .json), clique em Procurar e selecione o novo conjunto de descritores do arquivo protobuf (arquivo .pb). O tamanho do arquivo não pode exceder 4 MB.

  7. Clique em Salvar.

gcloud

Para atualizar um pacote de esquema para usar um conjunto de descritores diferente, use o 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

Substitua:

  • SCHEMA_BUNDLE_ID: o ID do pacote de esquemas a ser atualizado.
  • INSTANCE_ID: o ID da instância que contém o pacote de esquema.
  • TABLE_ID: o ID da tabela que contém o pacote de esquemas.
  • PROTO_DESCRIPTORS_FILE: o caminho para o novo arquivo de conjunto de descritores.

Opcional: para forçar a atualização mesmo que haja mudanças incompatíveis, adicione a flag --ignore-warnings ao comando. Não é possível forçar mudanças incompatíveis se o pacote de esquema estiver sendo usado por uma visualização materializada contínua ou lógica.

Java

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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());
}

Excluir um pacote de esquema

Não é possível excluir um pacote de esquemas se ele estiver sendo usado por uma visualização materializada contínua ou uma visualização lógica. A exclusão do pacote faria com que as consultas em visualizações lógicas falhassem e impediria que as visualizações materializadas contínuas processassem os dados recebidos. Para excluir o pacote de esquemas, primeiro exclua todas as visualizações que fazem referência a ele ou atualize-as para remover a referência.

Console

  1. No console do Google Cloud , abra a lista de instâncias do Bigtable.

    Abrir a lista de instâncias

  2. Selecione uma instância na lista.

  3. No menu de navegação, clique em Bigtable Studio.

  4. No painel Explorer, expanda a tabela que contém o pacote de esquemas e, em seguida, expanda Pacotes de esquemas.

  5. Ao lado do pacote de esquemas que você quer excluir, clique em  Ver ações e em Excluir.

  6. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Para excluir um pacote de esquema, use o comando gcloud bigtable schema-bundles delete:

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

Substitua:

  • SCHEMA_BUNDLE_ID: o ID do pacote de esquemas a ser excluído.
  • INSTANCE_ID: o ID da instância que contém o pacote de esquema.
  • TABLE_ID: o ID da tabela que contém o pacote de esquemas.

Java

Para saber como instalar e usar a biblioteca de cliente do Bigtable, consulte Bibliotecas de cliente do Bigtable.

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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());
}

Limitações

Os pacotes de esquema têm as seguintes limitações:

  • É possível criar até 10 pacotes de esquema por tabela. Esse limite se aplica a pacotes de esquemas do Protobuf e do Avro.
  • O tamanho total dos descritores de buffer de protocolo serializados em um pacote de esquema não pode exceder 4 MB. Não há limite direto para o número de esquemas individuais que podem ser incluídos em um pacote, desde que o tamanho total não exceda esse limite.

A seguir