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.

Controle quais propriedades são carregadas pelo BigQuery. Para isso, defina a propriedade projectionFields na API ou use a sinalização --projection_fields na CLI.

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 Cloud IAM incluem permissões bigquery.tables.create e bigquery.tables.updateData:

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

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

bigquery.user
bigquery.jobUser
bigquery.admin

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. Ao obter o acesso bigquery.dataOwner, o usuário consegue criar e atualizar tabelas no conjunto de dados por meio de um job de carregamento.

Consulte Controle de acesso para mais informações sobre papéis e permissões do Cloud IAM no BigQuery.

Permissões do Cloud Storage

Para carregar dados de um intervalo do Cloud Storage, você precisa ter as 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 Cloud 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

Abra a IU da Web do BigQuery no Console do Cloud.

Acesse a IU da Web do BigQuery
Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados. Clique em Criar tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.
Na seção Origem da página Criar tabela, faça o seguinte:
- 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.
Na página Criar tabela, na seção Destino:
- Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.
- 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.
Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Datastore.
Selecione os itens adequados 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.

IU clássica

Acesse a versão clássica da IU da Web do BigQuery.
Acessar a IU da Web do BigQuery
No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo e clique em Criar nova tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.
Na seção Dados de origem da página Criar tabela, faça isto:
- Deixe a opção Criar a partir da origem selecionada.
- Em Local, selecione Cloud Storage e, 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.
Na seção Tabela de destino da página Criar tabela, faça isto:
- Em Nome da tabela, escolha o conjunto de dados apropriado. No campo do nome da tabela, insira um nome para a tabela que você está criando no BigQuery.
- Verifique se o Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Datastore.
Selecione os itens aplicáveis na seção Opções e clique em Criar tabela. Para mais informações sobre as opções disponíveis, consulte Opções do Datastore.

CLI

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]

onde:

[LOCATION] é o local. 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 que tem a tabela em que os dados serão carregados;
[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.

Crie um job de carregamento que aponte para os dados de origem no Cloud Storage.
Especifique seu local na propriedade location da seção jobReference do recurso do job.
Os URIs de origem precisam ser totalmente qualificados no formato gs://[BUCKET]/[OBJECT]. O nome do arquivo ou 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.
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

Abra a IU da Web do BigQuery no Console do Cloud. Acessar a IU da Web do BigQuery
Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados. Clique em Criar tabela. O processo de carregamento de dados é igual ao de criação de uma tabela em branco.
Siga estas etapas na página Criar tabela, localizada 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.
Na página Criar tabela, na seção Destino:
- Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.
- 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.
Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Datastore.
Na seção Opções avançadas, em Preferência de gravação, selecione Substituir tabela.
Clique em Criar tabela.

IU clássica

Acesse a versão clássica da IU da Web do BigQuery.
Acessar a IU da Web do BigQuery
No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo e clique em Criar nova tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.
Na seção Dados de origem da página Criar tabela, faça isto:
- Deixe a opção Criar a partir da origem selecionada.
- Em Local, selecione Cloud Storage e, 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.
Na seção Tabela de destino da página Criar tabela, faça isto:
- Em Nome da tabela, escolha o conjunto de dados apropriado e, no campo de nome da tabela, insira o nome da tabela que você está substituindo.
- Verifique se o Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Datastore.
Na seção Opções, em Preferência de gravação, escolha Substituir tabela.
Clique em Criar tabela.

CLI

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]

onde:

[LOCATION] é o local. 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 que tem 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.

Crie um job de carregamento que aponte para os dados de origem no Cloud Storage.
Especifique seu local na propriedade location da seção jobReference do recurso do job.
Os URIs de origem precisam ser totalmente qualificados no formato gs://[BUCKET]/[OBJECT]. O nome do arquivo ou 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.
Para especificar o formato de dados, defina a propriedade configuration.load.sourceFormat como DATASTORE_BACKUP.
Defina a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE para especificar a disposição de gravação.

Opções do Datastore

Para alterar a maneira como o BigQuery analisa os dados de exportação do Datastore, especifique outras opções na IU clássica da Web, na CLI ou na API.

Opção de CSV	Opção da IU clássica	Sinalização da CLI	Property da API BigQuery	Descrição
Campos de projeção	Nenhuma	`--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 é ''.
Número de registros corrompidos permitidos	Número de erros permitido	`--max_bad_records`	maxBadRecords	(Opcional) O número máximo de registros inválidos que o BigQuery pode ignorar ao executar o job. Se o número exceder esse valor, um erro inválido será retornado no resultado do job. O valor padrão é 0, o que exige que todos os registros sejam válidos.

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 do 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.

Property 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