Carregar dados de exportações do Datastore

O BigQuery suporta o carregamento de dados de exportações do Datastore criadas através do serviço de importação e exportação gerido do Datastore. Pode usar o serviço de importação e exportação gerido para exportar entidades do Datastore para um contentor do Cloud Storage. Em seguida, pode carregar a exportação para o BigQuery como uma tabela.

Para saber como criar um ficheiro de exportação do Datastore, consulte o artigo Exportar e importar entidades na documentação do Datastore. Para obter informações sobre a programação de exportações, consulte o artigo Programar uma exportação.

Nota: se pretender carregar uma exportação do Datastore para o BigQuery, tem de especificar um filtro de entidades no seu comando de exportação. Não é possível carregar no BigQuery dados exportados sem especificar um filtro de entidades.

Pode controlar que propriedades o BigQuery deve carregar definindo a propriedade projectionFields na API ou usando a flag --projection_fields na ferramenta de linha de comandos bq.

Se preferir ignorar o processo de carregamento, pode consultar a exportação diretamente configurando-a como uma origem de dados externa. Para mais informações, consulte o artigo Origens de dados externas.

Quando carrega dados do Cloud Storage para uma tabela do BigQuery, o conjunto de dados que contém a tabela tem de estar na mesma região ou multirregião que o contentor do Cloud Storage.

Limitações

Quando carrega dados para o BigQuery a partir de uma exportação do Datastore, tenha em atenção as seguintes restrições:

• Não pode usar um caráter universal no URI do Cloud Storage quando especifica um ficheiro de exportação do Datastore.
• Só pode especificar um URI do Cloud Storage quando carregar dados de exportações do Datastore.
• Não pode anexar dados de exportação do Datastore a uma tabela existente com um esquema definido.
• Para que uma exportação do Datastore seja carregada corretamente, as entidades nos dados de exportação têm de partilhar um esquema consistente com menos de 10 000 nomes de propriedades únicos.
• Não é possível carregar no BigQuery dados exportados sem especificar um filtro de entidades. O pedido de exportação tem de incluir um ou mais nomes de tipos no filtro de entidades.
• O tamanho máximo do campo para exportações do Datastore é de 64 KB. Quando carrega uma exportação do Datastore, qualquer campo com mais de 64 KB é truncado.

Antes de começar

Conceda funções de gestão de identidade e acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento.

Autorizações necessárias

Para carregar dados para o BigQuery, precisa de autorizações da IAM para executar uma tarefa de carregamento e carregar dados para tabelas e partições do BigQuery. Se estiver a carregar dados do Cloud Storage, também precisa de autorizações de IAM para aceder ao contentor que contém os seus dados.

Autorizações para carregar dados para o BigQuery

Para carregar dados para uma nova tabela ou partição do BigQuery, ou para anexar ou substituir uma tabela ou uma partição existente, precisa das seguintes autorizações de IAM:

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

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para carregar dados para uma tabela ou uma partição do BigQuery:

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

Além disso, se tiver a autorização bigquery.datasets.create, pode criar e atualizar tabelas através de uma tarefa de carregamento nos conjuntos de dados que criar.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Autorizações para carregar dados do Cloud Storage

Para receber as autorizações de que precisa para carregar dados de um contentor do Cloud Storage, peça ao seu administrador para lhe conceder a função de IAM Administrador de armazenamento (roles/storage.admin) no contentor. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para carregar dados a partir de um contentor do Cloud Storage. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para carregar dados de um contentor do Cloud Storage:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Carregar dados do serviço de exportação do Datastore

Para carregar dados de um ficheiro de metadados de exportação do Datastore:

Consola

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, expanda o seu projeto e, de seguida, selecione um conjunto de dados.
3. Na secção Informações do conjunto de dados, clique em Criar tabela.
4. No painel Criar tabela, especifique os seguintes detalhes:
1. Na secção Origem, selecione Google Cloud Storage na lista Criar tabela a partir de. Em seguida, faça o seguinte:
   1. Selecione um ficheiro do contentor do Cloud Storage ou introduza o URI do Cloud Storage. Não pode incluir vários URIs na Google Cloud consola, mas os carateres universais são suportados. O contentor do Cloud Storage tem de estar na mesma localização que o conjunto de dados que contém a tabela que quer criar, acrescentar ou substituir.
      O URI do ficheiro de exportação do Datastore tem de 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 ficheiro gerado pelo Datastore.
   2. Para Formato de ficheiro, selecione Cópia de segurança do Cloud Datastore.
2. Na secção Destino, especifique os seguintes detalhes:
   1. Para Conjunto de dados, selecione o conjunto de dados no qual quer criar a tabela.
   2. No campo Tabela, introduza o nome da tabela que quer criar.
   3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
3. Na secção Esquema, não é necessária nenhuma ação. O esquema é inferido para uma exportação do Datastore.
4. Opcional: especifique as definições de partição e cluster. Para mais informações, consulte os artigos Criar tabelas particionadas e Criar e usar tabelas agrupadas.
5. Clique em Opções avançadas e faça o seguinte:
   • Para Preferência de escrita, deixe a opção Escrever se estiver vazio selecionada. Esta opção cria uma nova tabela e carrega os seus dados na mesma.
   • Se quiser ignorar valores numa linha que não estejam presentes no esquema da tabela, selecione Valores desconhecidos.
   • Para Encriptação, clique em Chave gerida pelo cliente para usar uma chave do Cloud Key Management Service. Se deixar a definição Google-managed key, o BigQuery encripta os dados em repouso.
   Para obter informações sobre as opções disponíveis, consulte Opções de armazenamento de dados.
6. Clique em Criar tabela.

bq

Use o comando bq load com source_format definido como DATASTORE_BACKUP. Forneça a flag --location e defina o valor para a sua localização.

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

Substitua o seguinte:

• LOCATION: a sua localização. A flag --location é opcional. Por exemplo, se estiver a usar o BigQuery na região de Tóquio, pode definir o valor da flag como asia-northeast1. Pode definir um valor predefinido para a localização através do ficheiro.bigqueryrc.
• FORMAT: DATASTORE_BACKUP.
• DATASET: o conjunto de dados que contém a tabela para a qual está a carregar dados.
• TABLE: a tabela para a qual está a carregar dados. Se a tabela não existir, é criada.
• PATH_TO_SOURCE: o URI do Cloud Storage.

Por exemplo, o comando seguinte carrega o ficheiro de exportação do Datastore numa tabela denominada book_data.gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata mybucket e mydataset foram criados na localização 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 seguintes propriedades para carregar dados de exportação do Datastore através da API.

1. Crie uma tarefa de carregamento que aponte para os dados de origem no Cloud Storage.

2. Especifique a sua localização na propriedade location na secção jobReference do recurso de emprego.

3. Os URIs de origem têm de ser totalmente qualificados, no formato gs://[BUCKET]/[OBJECT]. O nome do ficheiro (objeto) tem de terminar em [KIND_NAME].export_metadata. Só é permitido um URI para exportações do Datastore e não pode usar um caráter universal.

4. Especifique o formato de dados definindo a propriedade JobConfigurationLoad.sourceFormat como DATASTORE_BACKUP.

Anexar ou substituir uma tabela com dados do Datastore

Quando carrega dados de exportação do Datastore para o BigQuery, pode criar uma nova tabela para armazenar os dados ou pode substituir uma tabela existente. Não pode anexar dados de exportação do Datastore a uma tabela existente.

Se tentar acrescentar dados de exportação do Datastore a uma tabela existente, é apresentado o seguinte erro: 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 existente por dados de exportação do Datastore:

Consola

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, expanda o seu projeto e, de seguida, selecione um conjunto de dados.
3. Na secção Informações do conjunto de dados, clique em Criar tabela.
4. No painel Criar tabela, especifique os seguintes detalhes:
1. Na secção Origem, selecione Google Cloud Storage na lista Criar tabela a partir de. Em seguida, faça o seguinte:
   1. Selecione um ficheiro do contentor do Cloud Storage ou introduza o URI do Cloud Storage. Não pode incluir vários URIs na Google Cloud consola, mas os carateres universais são suportados. O contentor do Cloud Storage tem de estar na mesma localização que o conjunto de dados que contém a tabela que quer criar, acrescentar ou substituir.
      O URI do ficheiro de exportação do Datastore tem de 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 ficheiro gerado pelo Datastore.
   2. Para Formato de ficheiro, selecione Cópia de segurança do Cloud Datastore.
Nota: é possível modificar o esquema da tabela quando a anexa ou substitui. Para mais informações sobre as alterações de esquema suportadas durante uma operação de carregamento, consulte o artigo Modificar esquemas de tabelas.
2. Na secção Destino, especifique os seguintes detalhes:
   1. Para Conjunto de dados, selecione o conjunto de dados no qual quer criar a tabela.
   2. No campo Tabela, introduza o nome da tabela que quer criar.
   3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
3. Na secção Esquema, não é necessária nenhuma ação. O esquema é inferido para uma exportação do Datastore.
Nota: é possível modificar o esquema da tabela quando a anexa ou substitui. Para mais informações sobre as alterações de esquema suportadas durante uma operação de carregamento, consulte o artigo Modificar esquemas de tabelas.
4. Opcional: especifique as definições de partição e cluster. Para mais informações, consulte os artigos Criar tabelas particionadas e Criar e usar tabelas agrupadas. Não pode converter uma tabela numa tabela particionada ou agrupada anexando-a ou substituindo-a. A Google Cloud consola não suporta a anexação nem a substituição de tabelas particionadas ou agrupadas num trabalho de carregamento.
5. Clique em Opções avançadas e faça o seguinte:
   • Para Preferência de escrita, escolha Anexar à tabela ou Substituir tabela.
   • Se quiser ignorar valores numa linha que não estejam presentes no esquema da tabela, selecione Valores desconhecidos.
   • Para Encriptação, clique em Chave gerida pelo cliente para usar uma chave do Cloud Key Management Service. Se deixar a definição Google-managed key, o BigQuery encripta os dados em repouso.
   Para obter informações sobre as opções disponíveis, consulte Opções de armazenamento de dados.
6. Clique em Criar tabela.

bq

Use o comando bq load com o sinalizador --replace e com source_format definido como DATASTORE_BACKUP. Forneça a flag --location e defina o valor para a sua localização.

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

Substitua o seguinte:

• LOCATION: a sua localização. A flag --location é opcional. Por exemplo, se estiver a usar o BigQuery na região de Tóquio, pode definir o valor da flag como asia-northeast1. Pode definir um valor predefinido para a localização através do ficheiro.bigqueryrc.
• FORMAT: DATASTORE_BACKUP.
• DATASET: o conjunto de dados que contém a tabela na qual está a carregar dados.
• TABLE: a tabela que está a substituir.
• PATH_TO_SOURCE: o URI do Cloud Storage.

Por exemplo, o comando seguinte carrega o ficheiro de exportação do Datastore e substitui uma tabela denominada book_data:gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

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 seguintes propriedades para carregar dados da API.

1. Crie uma tarefa de carregamento que aponte para os dados de origem no Cloud Storage.

2. Especifique a sua localização na propriedade location na secção jobReference do recurso de emprego.

3. Os URIs de origem têm de ser totalmente qualificados, no formato gs://[BUCKET]/[OBJECT]. O nome do ficheiro (objeto) tem de terminar em [KIND_NAME].export_metadata. Só é permitido um URI para exportações do Datastore e não pode usar um caráter universal.

4. Especifique o formato de dados definindo a propriedade JobConfigurationLoad.sourceFormat como DATASTORE_BACKUP.

5. Especifique a disposição de escrita definindo a propriedade JobConfigurationLoad.writeDisposition como WRITE_TRUNCATE.

Opções de armazenamento de dados

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

Opção da consola	Sinalização da ferramenta bq	Propriedade da API BigQuery	Descrição
Não disponível	--projection_fields	projectionFields	Uma lista separada por vírgulas que indica as propriedades da entidade a carregar no BigQuery a partir de uma exportação do Datastore. Os nomes das propriedades são sensíveis a maiúsculas e minúsculas e têm de ser propriedades de nível superior. Se não forem especificadas propriedades, o BigQuery carrega todas as propriedades. Se não for encontrada nenhuma propriedade com nome na exportação do Datastore, é devolvido um erro inválido no resultado da tarefa. O valor predefinido é "".

Conversão de tipo de dados

O BigQuery converte os dados de cada entidade nos ficheiros de exportação do Datastore em tipos de dados do BigQuery. A tabela seguinte descreve a conversão entre tipos de dados.

Tipo de dados do armazenamento de dados	Tipo de dados do BigQuery
Matriz	ARRAY
Blob	BYTES
Booleano	BOOLEAN
Data e hora	TIMESTAMP
Entidade incorporada	RECORD
Número de vírgula flutuante	FLOAT
Ponto geográfico	RECORD [{"lat","DOUBLE"}, {"long","DOUBLE"}]
Número inteiro	INTEGER
Chave	RECORD
Nulo	STRING
String de texto	STRING (truncado para 64 KB)

Propriedades de chaves do Datastore

Cada entidade no 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 parte das informações, conforme descrito na tabela seguinte.

Propriedade principal	Descrição	Tipo de dados do BigQuery
__key__.app	O nome da app do armazenamento de dados.	STRING
__key__.id	O ID da entidade ou null se __key__.name estiver definido.	INTEGER
__key__.kind	O tipo da entidade.	STRING
__key__.name	O nome da entidade ou null se __key__.id estiver definido.	STRING
__key__.namespace	Se a app Datastore usar um espaço de nomes personalizado, o espaço de nomes da entidade. Caso contrário, o espaço de nomes predefinido é representado por uma string vazia.	STRING
__key__.path	O caminho ancestral da entidade simplificado, composto pela sequência de pares de identificadores de tipos da entidade raiz para a própria entidade. Por exemplo: "Country", "USA", "PostalCode", 10011, "Route", 1234.	STRING