Como carregar dados de exportações do Cloud Datastore

O BigQuery é compatível com o carregamento de dados das exportações do Cloud Datastore criadas usando o serviço gerenciado de importação e exportação do Cloud Datastore. Use o serviço gerenciado de importação e exportação para exportar entidades do Cloud Datastore para um intervalo do Cloud Storage. Em seguida, carregue a exportação no BigQuery como uma tabela.

Para saber como criar um arquivo de exportação do Cloud Datastore, consulte Como exportar e importar entidades na documentação do Cloud Datastore. Se quiser mais informações sobre programação de exportações, consulte Como programar uma exportação.

É possível controlar quais propriedades o BigQuery deve carregar ao definir a propriedade projectionFields na API ou usando a sinalização --projection_fields na CLI.

Se preferir ignorar o processo de carregamento, consulte a exportação diretamente configurando-a como 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 Cloud Datastore no BigQuery, observe as restrições a seguir:

  • Não é possível usar um caractere curinga no URI do Cloud Storage ao especificar um arquivo de exportação do Cloud Datastore.
  • É possível especificar apenas um URI do Cloud Storage ao carregar dados de exportações do Cloud Datastore.
  • Não é possível anexar dados de exportação do Cloud Datastore a uma tabela atual com um esquema definido.
  • Para que a exportação do Cloud Datastore seja carregada corretamente, as entidades nos dados de exportação precisam compartilhar um esquema consistente.
  • Não é possível carregar no BigQuery os dados exportados sem a especificação de um filtro de entidade. A solicitação de exportação precisa incluir um ou mais nomes de tipo no filtro de entidade.
  • O tamanho máximo de campo para exportações do Cloud Datastore é 64 KB. Ao carregá-las, qualquer campo superior a 64 KB será truncado.

Permissões exigidas

Ao carregar dados no BigQuery, você precisa de permissões para executar um job de carga e para carregar dados em tabelas e partições novas ou antigas do BigQuery. Se 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 papéis predefinidos do Cloud IAM a seguir incluem as permissões bigquery.tables.create e bigquery.tables.updateData:

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

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

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

Além disso, quando um usuário com permissões bigquery.datasets.create cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner ao conjunto. Com o acesso bigquery.dataOwner, o usuário consegue criar e atualizar tabelas no conjunto de dados por meio de um job de carga.

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

Permissões do Cloud Storage

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

É possível conceder o papel predefinido storage.objectViewer do Cloud IAM para fornecer as permissões storage.objects.get e storage.objects.list.

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

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

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.

    Acesse a IU da Web do BigQuery

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

    Criar tabela

  3. Siga estas etapas na página Criar tabela, localizada na seção Origem:

    • Em Criar uma tabela a partir de, selecione Cloud Storage
    • No campo de origem, insira o URI do Cloud Storage. O intervalo do Cloud Storage deve 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 Cloud Datastore deve terminar com [KIND_NAME].export_metadata ou export[NUM].export_metadata. Por exemplo: default_namespace_kind_Book.export_metadata. Nesse exemplo, Book é o nome do tipo e default_namespace_kind_Book é o nome do arquivo gerado pelo Cloud Datastore.
    • Em Formato do arquivo, selecione Backup do Cloud Datastore.

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

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

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

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

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

IU clássica

  1. Acesse a IU da Web clássica do BigQuery.
    Acesse a IU da Web do BigQuery
  2. No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo imagem do í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 em branco.
  3. Na página Criar tabela, na seção Dados de origem:
    • Deixe a opção Criar da fonte 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 Cloud Datastore termina com [KIND_NAME].export_metadata. Por exemplo: default_namespace_kind_Book.export_metadata. Nesse exemplo, Book é o nome do tipo e default_namespace_kind_Book é o nome do arquivo gerado pelo Cloud Datastore.

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

    • Em Formato do arquivo, selecione Backup do Cloud Datastore.
  4. Na página Criar tabela, na seção Tabela de destino:
    • Em Nome da tabela, escolha o conjunto de dados apropriado e, no campo de 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.
  5. Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Cloud Datastore.
  6. Selecione os itens aplicáveis na seção Opções e clique em Criar tabela. Para informações sobre as opções disponíveis, consulte Opções do Cloud 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]

em que:

  • [LOCATION] é o local. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, poderá definir 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 para a qual você está carregando dados.
  • [TABLE] é a tabela para a qual 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 Cloud Datastore em uma tabela denominada 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 Cloud Datastore usando a API.

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

  2. Especifique o local na propriedade location na seção jobReference do recurso do job.

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

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

Backups do Administrador do Cloud Datastore

Se você usar o recurso de backup do Administrador do Cloud Datastore para exportar dados do Cloud Datastore, observe que a extensão de arquivo será .backup_info vez de .export_metadata. Ao importar os dados no BigQuery, será possível usar um arquivo .backup_info ou .export_metadata até que o serviço de backups do Administrador do Cloud Datastore se torne indisponível.

Como anexar ou substituir uma tabela com dados do Cloud Datastore

Ao carregar dados de exportação do Cloud Datastore para o BigQuery, é possível criar uma nova tabela para armazenar os dados ou substituir uma tabela atual. Não é possível anexar dados de exportação do Cloud Datastore a uma tabela atual.

Se você tentar anexar dados de exportação do Cloud Datastore a uma tabela atual, ocorrerá este 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 atual por dados de exportação do Cloud Datastore:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP. Acesse a IU da Web do BigQuery
  2. 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. Criar tabela

  3. Siga estas etapas na página Criar tabela, localizada na seção Origem:

    • Em Criar uma tabela a partir de, selecione Cloud Storage

    • No campo de origem, insira o URI do Cloud Storage. O intervalo do Cloud Storage deve 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 Cloud Datastore termina com [KIND_NAME].export_metadata. Por exemplo: default_namespace_kind_Book.export_metadata. Nesse exemplo, Book é o nome do tipo e default_namespace_kind_Book é o nome do arquivo gerado pelo Cloud Datastore.

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

    • Em Formato do arquivo, selecione Backup do Cloud Datastore.

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

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

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

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

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

  7. Clique em Criar tabela.

IU clássica

  1. Acesse a IU da Web clássica do BigQuery.
    Acesse a IU da Web do BigQuery
  2. No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo imagem do í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 em branco.
  3. Na página Criar tabela, na seção Dados de origem:
    • Deixe a opção Criar da fonte 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 Cloud Datastore termina com [KIND_NAME].export_metadata. Por exemplo: default_namespace_kind_Book.export_metadata. Nesse exemplo, Book é o nome do tipo e default_namespace_kind_Book é o nome do arquivo gerado pelo Cloud Datastore.

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

    • Em Formato do arquivo, selecione Backup do Cloud Datastore.
  4. Na página Criar tabela, na seção Tabela de destino:
    • 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.
  5. Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Cloud Datastore.
  6. Na seção Opções, em Preferência de gravação, escolha Substituir tabela.
  7. 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]

em que:

  • [LOCATION] é o local. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, poderá definir 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 para a qual você está carregando dados.
  • [TABLE] é a tabela que você está substituindo.
  • [PATH_TO_SOURCE] é o URI do Cloud Storage.

Por exemplo, o comando a seguir carrega o arquivo de exportação do Cloud Datastore para gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata e substitui uma tabela denominada 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 da API.

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

  2. Especifique o local na propriedade location na seção jobReference do recurso do job.

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

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

  5. Especifique a disposição de gravação definindo a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE.

Opções do Cloud Datastore

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

Opção de CSV Opção da IU clássica Sinalização da CLI Propriedade da API BigQuery Descrição
Campos de projeção Nenhum --projection_fields projectionFields Uma lista separada por vírgulas que indica quais propriedades da entidade serão carregadas no BigQuery de uma exportação do Cloud 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 alguma propriedade nomeada não for encontrada na exportação do Cloud Datastore, um erro "inválido" será retornado no resultado do job. O valor padrão é ''.
Número de registros corrompidos permitidos Número de erros permitidos --max_bad_records maxBadRecords (Opcional) O número máximo de registros corrompidos que o BigQuery pode ignorar ao executar o job. Se o número de registros corrompidos exceder esse valor, o erro "inválido" é 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 Cloud Datastore em tipos de dados do BigQuery. A tabela a seguir descreve a conversão entre os tipos de dados.

Tipo de dados do Cloud Datastore Tipo de dados do BigQuery
Blob O BigQuery descarta esses valores ao carregar os dados.
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 O BigQuery descarta esses valores ao carregar os dados.
String STRING (truncada para 64 KB)
Usuário

RECORD


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

Propriedades da chave do Datastore

Cada entidade no Cloud 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 Cloud Datastore. STRING
__key__.id O código 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 Se o app do Cloud Datastore usa um namespace personalizado, o namespace da entidade. O namespace padrão também é 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
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
BigQuery
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.