O Google 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. Para informações sobre programação de exportações, consulte Como programar uma exportação.
Você pode controlar quais propriedades o BigQuery deve carregar definindo 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 na mesma região ou multirregião que o intervalo do Cloud Storage.
Permissões exigidas
Ao carregar dados no BigQuery, você precisa de permissões para os envolvidos no projeto ou no nível do conjunto de dados para carregar dados em tabelas e partições novas ou antigas do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará acessar o intervalo que contém os dados.
Permissões do BigQuery
Ao carregar dados no BigQuery a partir do Cloud Storage, você precisa ter concedido os papéis bigquery.dataOwner ou bigquery.dataEditor para envolvidos no projeto ou no nível do conjunto de dados. Os dois papéis concedem aos usuários e grupos permissão para carregar dados em uma nova tabela, anexá-los a uma tabela ou substitui-la.
Ao conceder os papéis para envolvidos no projeto, os usuários ou grupos têm permissão para carregar dados em tabelas em cada conjunto de dados no projeto. Já com os papéis no nível do conjunto de dados, os usuários ou grupos podem carregar dados apenas em tabelas desse conjunto de dados.
Para mais informações sobre como configurar o acesso aos conjuntos de dados, consulte Como controlar o acesso a conjuntos de dados. Para saber mais sobre papéis do IAM no BigQuery, consulte Controle de acesso.
Permissões do Cloud Storage
Para carregar dados de um intervalo do Cloud Storage, você precisa de permissões storage.objects.get no nível do projeto ou do intervalo individual. Se você estiver usando um caractere curinga de URI, será necessário também ter permissões storage.objects.list.
É possível conceder o papel do IAM predefinido storage.objectViewer para fornecer permissões storage.objects.get e storage.objects.list.
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.
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
Abra a IU da Web do BigQuery no Console do GCP.
No painel de navegação, na seção Recursos, expanda seu 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 página Criar tabela, 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_metadataouexport[NUM].export_metadata. Por exemplo:default_namespace_kind_Book.export_metadata. Nesse exemplo,Booké o nome do tipo edefault_namespace_kind_Booké o nome do arquivo gerado pelo Cloud Datastore.Em Formato do arquivo, selecione Backup do Cloud Datastore.
Na página Criar tabela, na seção Destino:
Em Nome do conjunto de dados, escolha o conjunto 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 Cloud Datastore.
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
- Acesse a IU da Web clássica do BigQuery.
Acesse a IU da Web do BigQuery - No painel de navegação, passe o mouse 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 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 edefault_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], você receberá o seguinte erro:does not contain valid backup metadata. (error code: invalid). - Em Formato do arquivo, selecione Backup do Cloud Datastore.
- 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.
- Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Cloud Datastore.
- 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.
Linha de comando
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 comoasia-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.
Crie um job de carregamento que aponte para os dados de origem no Cloud Storage.
Especifique o local na propriedade
locationna seçãojobReferencedo recurso de job.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.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
- Abra a IU da Web do BigQuery no Console do GCP. Acesse a IU da Web do BigQuery
- No painel de navegação, na seção Recursos, expanda seu 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 página Criar tabela, 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 edefault_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], você receberá o seguinte erro:does not contain valid backup metadata. (error code: invalid).Em Formato do arquivo, selecione Backup do Cloud Datastore.
Na página Criar tabela, na seção Destino:
Em Nome do conjunto de dados, escolha o conjunto 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 Cloud 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 IU da Web clássica do BigQuery.
Acesse a IU da Web do BigQuery - No painel de navegação, passe o mouse 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 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 edefault_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], você receberá o seguinte erro:does not contain valid backup metadata. (error code: invalid). - Em Formato do arquivo, selecione Backup do Cloud Datastore.
- 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.
- Na seção Esquema, nenhuma ação é necessária. O esquema é inferido de uma exportação do Cloud Datastore.
- Na seção Opções, em Preferência de gravação, escolha Substituir tabela.
- Clique em Criar tabela.
Linha de comando
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 comoasia-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.
Crie um job de carregamento que aponte para os dados de origem no Cloud Storage.
Especifique o local na propriedade
locationna seçãojobReferencedo recurso de job.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.Especifique o formato de dados definindo a propriedade configuration.load.sourceFormat como
DATASTORE_BACKUP.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 |
| Booleano | BOOLEAN |
| Categoria | STRING |
| Chave do Datastore | RECORD |
| Data e hora | TIMESTAMP |
| 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 |
Precisa de ajuda? Acesse nossa