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.
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 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 IAM incluem as permissões bigquery.tables.create
e bigquery.tables.updateData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Além disso, quando um usuário tem permissões bigquery.datasets.create
e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner
ao conjunto.
O acesso bigquery.dataOwner
permite que o usuário crie e
atualize tabelas no conjunto de dados usando um job de carregamento.
Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Controle de acesso.
Permissões do Cloud Storage
Para carregar dados de um intervalo do Cloud Storage, você precisa ter
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 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 página do BigQuery no Console do Cloud.
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
No painel de detalhes, clique em Criar tabela.
Na página Criar tabela, 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
ouexport[NUM].export_metadata
. Por exemplo,default_namespace_kind_Book.export_metadata
. Neste exemplo,Book
é o nome do tipo, edefault_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 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 itens aplicáveis 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.
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 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 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çãojobReference
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
.
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 página do BigQuery no Console do Cloud. Acessar a página do BigQuery
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
No painel de detalhes, clique em Criar tabela.
Na página Criar tabela, 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, edefault_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 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.
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 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 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çãojobReference
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 | Sinalização 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 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 é ''. |
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 Blobstore | STRING |
Booleanos | 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 | 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.
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 |