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 bucket 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 na mesma região ou multirregião que o bucket 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.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento.

Permissões necessárias

Para carregar dados no BigQuery, você precisa de permissões do IAM para executar um job de carregamento e carregar dados nas tabelas e partições do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de permissões do IAM para acessar o bucket que contém os dados.

Permissões para carregar dados no BigQuery

Para carregar dados em uma nova tabela ou partição do BigQuery ou anexar ou substituir uma tabela ou partição existente, você precisa das seguintes permissões do IAM:

bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create

Cada um dos seguintes papéis de IAM predefinidos inclui as permissões necessárias para carregar dados em uma tabela ou partição do BigQuery:

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin (inclui a permissão bigquery.jobs.create)
bigquery.user (inclui a permissão bigquery.jobs.create)
bigquery.jobUser (inclui a permissão bigquery.jobs.create)

Além disso, se você tiver a permissão bigquery.datasets.create, poderá criar e atualizar tabelas usando um job de carregamento nos conjuntos de dados que criar.

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Permissões para carregar dados do Cloud Storage

Para receber as permissões necessárias para carregar dados de um bucket do Cloud Storage, peça ao administrador para conceder a você o o papel IAM doAdministrador de armazenamento (roles/storage.admin) no bucket. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém as permissões necessárias para carregar dados de um bucket do Cloud Storage. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para carregar dados de um bucket do Cloud Storage:

storage.buckets.get
storage.objects.get
storage.objects.list (required if you are using a URI wildcard)

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

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

No Console do Google Cloud, acesse a página BigQuery.

Acessar o BigQuery
No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
Na seção Informações do conjunto de dados, clique em Criar tabela.
No painel Criar tabela, especifique os seguintes detalhes:

Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de. Em seguida, faça o seguinte:
1. Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
  O URI do arquivo de exportação do Datastore precisa terminar com KIND_NAME.export_metadata ou export[NUM].export_metadata. Por exemplo, em default_namespace_kind_Book.export_metadata, Book é o nome do tipo, e default_namespace_kind_Book é o nome do arquivo gerado pelo Datastore.
2. Em Formato do arquivo, selecione Backup do Cloud Datastore.
Na seção Destino, especifique os seguintes campos:
1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
2. No campo Tabela, insira o nome da tabela que você quer criar.
3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, nenhuma ação é necessária. O esquema é inferido para uma exportação do Datastore.
Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster.
Clique em Opções avançadas e faça o seguinte:
- Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Usando essa opção, você cria uma nova tabela e carrega seus dados nela.
- Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
- Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
Selecione Criar tabela.

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.

Crie um job de carregamento que aponte para os dados de origem no Cloud Storage.
Especifique seu local na property location da seção jobReference do recurso do job.
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.
Para especificar o formato de dados, defina a propriedade configuration.load.sourceFormat como DATASTORE_BACKUP.

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

No Console do Google Cloud, acesse a página BigQuery.

Acessar o BigQuery
No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
Na seção Informações do conjunto de dados, clique em Criar tabela.
No painel Criar tabela, especifique os seguintes detalhes:

Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de. Em seguida, faça o seguinte:
1. Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
  O URI do arquivo de exportação do Datastore precisa terminar com KIND_NAME.export_metadata ou export[NUM].export_metadata. Por exemplo, em default_namespace_kind_Book.export_metadata, Book é o nome do tipo, e default_namespace_kind_Book é o nome do arquivo gerado pelo Datastore.
2. Em Formato do arquivo, selecione Backup do Cloud Datastore.

Na seção Destino, especifique os seguintes campos:
1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
2. No campo Tabela, insira o nome da tabela que você quer criar.
3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, nenhuma ação é necessária. O esquema é inferido para uma exportação do Datastore.

Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster. Não é possível anexar ou substituir uma tabela para convertê-la em uma particionada ou em cluster. O console do Cloud não é compatível com anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
Clique em Opções avançadas e faça o seguinte:
- Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
- Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
- Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
Selecione 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.

Crie um job de carregamento que aponte para os dados de origem no Cloud Storage.
Especifique seu local na property location da seção jobReference do recurso do job.
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.
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 forma como o BigQuery analisa os dados de exportação do Datastore, especifique a seguinte opção:

Opção do console	flag 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 carrega 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
Matriz	`ARRAY`
Blob	`BYTES`
Booleano	`BOOLEAN`
Data e hora	`TIMESTAMP`
Entidade incorporada	`RECORD`
Número de ponto flutuante	`FLOAT`
Ponto geográfico	`RECORD` [{"lat","DOUBLE"}, {"long","DOUBLE"}]
Inteiro	`INTEGER`
Chave	`RECORD`
Nulo	`STRING`
String de texto	`STRING` (truncado para 64 KB)

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