Como carregar dados de exportações do Datastore

Com o BigQuery, é possível carregar dados das exportações do Datastore criadas por meio do serviço gerenciado de importação e exportação do Datastore. Use esse serviço para exportar entidades do Datastore para um intervalo do Cloud Storage. Depois, carregue a exportação no BigQuery como uma tabela.

Para saber como criar um arquivo de exportação do Datastore, consulte Como exportar e importar entidades na documentação do produto. Para mais informações sobre a programação de exportações, consulte este artigo.

Para controlar quais propriedades são carregadas pelo BigQuery, defina a propriedade projectionFields na API ou use a sinalização --projection_fields na linha de comando bq.

Se quiser ignorar o processo de carregamento, consulte a exportação diretamente ao defini-la como uma fonte de dados externa. Para mais informações, consulte Fontes de dados externas.

Quando você carrega dados do Cloud Storage em uma tabela do BigQuery, o conjunto de dados que contém a tabela precisa estar no mesmo local regional ou multirregional que o intervalo do Cloud Storage.

Limitações

Ao carregar dados de uma exportação do Datastore no BigQuery, as restrições a seguir são aplicadas:

  • Não é possível usar um caractere curinga no URI do Cloud Storage ao especificar um arquivo de exportação do Datastore.
  • É possível especificar apenas um URI do Cloud Storage ao carregar dados de exportações do Datastore.
  • Não é possível anexar dados de exportação do Datastore a uma tabela atual com um esquema definido.
  • Para que uma exportação do Datastore seja carregada corretamente, todas entidades nos dados exportados precisam ter o mesmo esquema consistente, com menos de 10.000 nomes exclusivos de propriedade.
  • Não é possível carregar dados no BigQuery sem a especificação de um filtro de entidade. A solicitação de exportação precisa incluir pelo menos um nome de tipo no filtro de entidade.
  • O tamanho máximo de campos das exportações do Datastore é de 64 KB. Ao carregá-las, os campos com mais de 64 KB ficam truncados.

Permissões necessárias

Ao carregar dados no BigQuery, você precisa de permissões para executar um job de carregamento e para carregar dados em tabelas e partições novas ou antigas do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de permissões para acessar o intervalo que contém os dados.

Permissões do BigQuery

Pelo menos as permissões a seguir são obrigatórias para carregar dados no BigQuery. Elas serão necessárias se você estiver carregando dados em uma nova tabela ou partição ou anexando/substituindo uma tabela ou partição.

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.tables.create e bigquery.tables.updateData:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Além disso, quando um usuário tem permissões bigquery.datasets.create e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner ao conjunto. O acesso bigquery.dataOwner permite que o usuário crie e atualize tabelas no conjunto de dados usando um job de carregamento.

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Controle de acesso.

Permissões do Cloud Storage

Para carregar dados de um intervalo do Cloud Storage, você precisa ter permissões storage.objects.get. Se você estiver usando um caractere curinga de URI, também precisará ter permissões storage.objects.list.

O papel predefinido storage.objectViewer do IAM concede as permissões storage.objects.get e storage.objects.list.

Como carregar dados do serviço de exportação do Datastore

Para carregar dados de um arquivo de metadados de exportação do Datastore, siga estas etapas:

Console

  1. Abra a página do BigQuery no Console do Cloud.

    Acesse a página do BigQuery

  2. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

  3. No painel de detalhes, clique em Criar tabela.

  4. Na página Criar tabela, na seção Origem:

    • Em Criar tabela de, selecione Cloud Storage
    • No campo de origem, insira o URI do Cloud Storage. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está criando. O URI do arquivo de exportação do Datastore precisa terminar com [KIND_NAME].export_metadata ou export[NUM].export_metadata. Por exemplo, default_namespace_kind_Book.export_metadata. Neste exemplo, Book é o nome do tipo, e default_namespace_kind_Book é o nome de arquivo gerado pelo Datastore.
    • Em Formato do arquivo, selecione Backup do Datastore.

  5. Na página Criar tabela, na seção Destino:

    • Em Nome do conjunto de dados, escolha o conjunto apropriado.

      Selecione o conjunto de dados.

    • No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.

    • Verifique se o Tipo de tabela está definido como Tabela nativa.

  6. Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Datastore.

  7. Selecione itens aplicáveis na seção Opções avançadas e clique em Criar tabela. Para mais informações sobre as opções disponíveis, consulte Opções do Datastore.

bq

Use o comando bq load com source_format definido como DATASTORE_BACKUP. Forneça a sinalização --location e defina o valor como seu local.

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Substitua:

  • LOCATION: sua localização. A sinalização --location é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.
  • FORMAT: DATASTORE_BACKUP.
  • DATASET: o conjunto de dados que contém a tabela em que você está carregando dados;
  • TABLE: a tabela em que você está carregando dados. Se a tabela não existir, ela será criada.
  • PATH_TO_SOURCE: o URI do Cloud Storage.

Por exemplo, o comando a seguir carrega o arquivo de exportação gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata do Datastore em uma tabela chamada book_data. mybucket e mydataset foram criados no local multirregional US.

bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Defina as propriedades a seguir para carregar dados de exportação do Datastore por meio da API.

  1. Crie um job de carregamento que aponte para os dados de origem no Cloud Storage.

  2. Especifique seu local na property location da seção jobReference do recurso do job.

  3. Os URIs de origem precisam estar totalmente qualificados no formato gs://[BUCKET]/[OBJECT]. O nome o arquivo (objeto) precisa terminar com [KIND_NAME].export_metadata. Apenas um URI é permitido para exportações do Datastore, e não é possível usar um caractere curinga.

  4. Para especificar o formato de dados, defina a propriedade configuration.load.sourceFormat como DATASTORE_BACKUP.

Backups do Datastore Admin

Quando você usa o recurso de backups do Datastore Admin para exportar dados do Datastore, a extensão do arquivo é .backup_info em vez de .export_metadata. Ao importar dados para o BigQuery, é possível usar um arquivo .backup_info ou .export_metadata quando o serviço de backups do Datastore Admin está disponível.

Como anexar ou substituir uma tabela com dados do Datastore

Quando você carrega dados de exportação do Datastore no BigQuery, é possível criar uma nova tabela para armazenamento ou substituir uma tabela atual. Não é possível anexar esses dados a uma tabela atual.

Se você tentar anexar dados de exportação do Datastore a uma tabela atual, este erro será exibido: Cannot append a datastore backup to a table that already has a schema. Try using the WRITE_TRUNCATE write disposition to replace the existing table.

Para substituir uma tabela atual por dados de exportação do Datastore, siga estas etapas:

Console

  1. Abra a página do BigQuery no Console do Cloud. Acessar a página do BigQuery

  2. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

  3. No painel de detalhes, clique em Criar tabela.

  4. Na página Criar tabela, na seção Origem:

    • Em Criar tabela de, selecione Cloud Storage

    • No campo de origem, insira o URI do Cloud Storage. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está criando. O URI do arquivo de exportação do Datastore precisa terminar com [KIND_NAME].export_metadata. Por exemplo, default_namespace_kind_Book.export_metadata. Neste exemplo, Book é o nome do tipo, e default_namespace_kind_Book é o nome de arquivo gerado pelo Datastore.

      Verifique se [KIND_NAME] está especificado no URI do Cloud Storage. Se você especificar o URI sem [KIND_NAME], este erro será exibido: does not contain valid backup metadata. (error code: invalid).

    • Em Formato do arquivo, selecione Backup do Datastore.

  5. Na página Criar tabela, na seção Destino:

    • Em Nome do conjunto de dados, escolha o conjunto apropriado.

      Selecione o conjunto de dados.

    • No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.

    • Verifique se o Tipo de tabela está definido como Tabela nativa.

  6. Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Datastore.

  7. Na seção Opções avançadas, em Preferência de gravação, selecione Substituir tabela.

  8. Clique em Criar tabela.

bq

Use o comando bq load com a sinalização --replace e com source_format definido como DATASTORE_BACKUP. Forneça a sinalização --location e defina o valor como seu local.

bq --location=LOCATION load \
--source_format=FORMAT \
--replace \
DATASET.TABLE \
PATH_TO_SOURCE

Substitua:

  • LOCATION: sua localização. A sinalização --location é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.
  • FORMAT: DATASTORE_BACKUP.
  • DATASET: o conjunto de dados que contém a tabela em que você está carregando dados.
  • TABLE: a tabela que você está substituindo.
  • PATH_TO_SOURCE: o URI do Cloud Storage.

Por exemplo, com o comando a seguir, você carrega o arquivo de exportação gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata do Datastore e substitui uma tabela chamada book_data:

bq load --source_format=DATASTORE_BACKUP \
--replace \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Defina as propriedades a seguir para carregar dados por meio da API.

  1. Crie um job de carregamento que aponte para os dados de origem no Cloud Storage.

  2. Especifique seu local na property location da seção jobReference do recurso do job.

  3. Os URIs de origem precisam estar totalmente qualificados no formato gs://[BUCKET]/[OBJECT]. O nome o arquivo (objeto) precisa terminar com [KIND_NAME].export_metadata. Apenas um URI é permitido para exportações do Datastore, e não é possível usar um caractere curinga.

  4. Para especificar o formato de dados, defina a propriedade configuration.load.sourceFormat como DATASTORE_BACKUP.

  5. Defina a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE para especificar a disposição de gravação.

Opções do Datastore

Para alterar a forma como o BigQuery analisa os dados de exportação do Datastore, especifique a seguinte opção:

Opção do console Sinalização da ferramenta bq Propriedade da API BigQuery Descrição
Indisponível --projection_fields projectionFields Uma lista separada por vírgulas que indica quais propriedades da entidade serão carregadas no BigQuery a partir de uma exportação do Datastore. Os nomes de propriedades diferenciam maiúsculas de minúsculas e precisam ser propriedades de nível superior. Se nenhuma propriedade for especificada, o BigQuery carregará todas. Se nenhuma propriedade nomeada for encontrada na exportação do Datastore, o resultado do job mostrará um erro inválido. O valor padrão é ''.

Conversão do tipo de dados

O BigQuery converte dados de cada entidade nos arquivos de exportação do Datastore em tipos de dados do BigQuery. Veja na tabela a seguir a conversão entre os tipos de dados.

Tipo de dados do Datastore Tipo de dados do BigQuery
Blob BYTES
Chave Blobstore STRING
Booleanos BOOLEAN
Categoria STRING
Chave do Datastore RECORD
Data e hora TIMESTAMP
E-mail STRING
Entidade incorporada RECORD
Número de ponto flutuante FLOAT
Ponto geográfico

RECORD


[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
Manipulador IM STRING
Número inteiro INTEGER
Vincular STRING
Número de telefone STRING
Endereço postal STRING
Classificação INTEGER
Blob curto BYTES
String STRING (truncada para 64 KB)
Usuário

RECORD


[{"email","STRING"}
 {"userid","STRING"}]

Propriedades da chave do Datastore

Cada entidade do Datastore tem uma chave única que contém informações como o namespace e o caminho. O BigQuery cria um tipo de dados RECORD para a chave com campos aninhados para cada informação conforme descrito na tabela a seguir.

Propriedade da chave Descrição Tipo de dados do BigQuery
__key__.app O nome do app do Datastore. STRING
__key__.id O ID da entidade, ou null se __key__.name estiver definido. INTEGER
__key__.kind O tipo de entidade. STRING
__key__.name O nome da entidade, ou null se __key__.id estiver definido. STRING
__key__.namespace O namespace da entidade se o aplicativo do Datastore usa um namespace personalizado. Já o namespace padrão é representado por uma string vazia. STRING
__key__.path O caminho ancestral da entidade simplificado, que consiste na sequência de pares tipo/identificador extraídos da entidade raiz para a própria entidade. Por exemplo, "Country", "USA", "PostalCode", 10011, "Route", 1234. STRING