Como carregar dados das exportações do Firestore

O BigQuery permite o carregamento de dados das exportações do Firestore criadas usando o serviço gerenciado de importação e exportação do Firestore. Esse serviço exporta documentos do Firestore para um intervalo do Cloud Storage. Depois disso, será possível carregar os dados exportados em uma tabela do BigQuery.

Limitações

Ao carregar dados de uma exportação do Firestore no BigQuery, as restrições a seguir se aplicam:

  • O conjunto de dados precisa estar no mesmo local regional ou multirregional que o intervalo do Cloud Storage que contém os arquivos de exportação.
  • Só é possível especificar um URI do Cloud Storage, e não é permitido usar um caractere curinga de URI.
  • Para que uma exportação do Firestore seja carregada corretamente, os documentos nos dados de exportação precisam compartilhar um esquema consistente com menos de 10.000 nomes de campo exclusivos.
  • Você pode criar uma nova tabela para armazenar os dados ou substituir uma tabela atual. Não é possível anexar dados de exportação do Firestore a uma tabela.
  • Seu comando de exportação precisa especificar um filtro collection-ids. Não é possível carregar no BigQuery os dados exportados sem especificação de um filtro de ID de coleção.

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 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 Cloud IAM incluem as permissões bigquery.tables.create e bigquery.tables.updateData:

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

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

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

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. Ao obter o acesso bigquery.dataOwner, o usuário consegue criar e atualizar tabelas no conjunto de dados por meio de um job de carregamento.

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

Permissões do Cloud Storage

Para carregar dados de um intervalo do Cloud Storage, você precisa ter as 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 Cloud IAM concede as permissões storage.objects.get e storage.objects.list.

Como carregar dados do serviço de exportação do Firestore

É possível carregar dados de um arquivo de metadados de exportação do Firestore usando a IU da Web do BigQuery, a ferramenta de linha de comando bq ou a API.

Às vezes, a terminologia do Datastore é usada na IU ou nos comandos, mas os procedimentos a seguir são compatíveis com os arquivos de exportação do Firestore. O Firestore e o Datastore compartilham um formato de exportação.

Console

  1. Abra a IU da Web do BigQuery no Console do Cloud.
    Acessar 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, 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. O URI do arquivo de exportação do Firestore precisa terminar com [KIND_COLLECTION_ID].export_metadata. Por exemplo, default_namespace_kind_Book.export_metadata. Nesse exemplo, Book é o ID do conjunto, e default_namespace_kind_Book é o nome do arquivo gerado pelo Firestore.

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

    • Em Formato do arquivo, selecione Backup do Datastore. Essa é a opção correta para o Firestore. O Firestore e o Datastore compartilham um formato de exportação.

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

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

      Selecionar 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 para uma exportação do Firestore.

  6. Selecione itens aplicáveis na seção Opções avançadas. Se você estiver substituindo uma tabela, defina Preferência de gravação como Substituir tabela.

    Substituir tabela

  7. Clique em Criar tabela.

IU clássica

  1. Acesse a versão clássica da IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery
  2. No painel de navegação, passe o cursor do mouse sobre um conjunto de dados, clique no ícone de seta para baixo imagem do ícone de seta para baixo e selecione Criar nova tabela.
  3. Na seção Dados de origem da página Criar tabela, faça o seguinte:

    • 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. O URI do arquivo de exportação do Firestore precisa terminar com [KIND_COLLECTION_ID].export_metadata. Por exemplo, default_namespace_kind_Book.export_metadata. Nesse exemplo, Book é o ID do conjunto, e default_namespace_kind_Book é o nome do arquivo gerado pelo Firestore.

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

    • Em Formato do arquivo, selecione Backup do Datastore. Essa é a opção correta para o Firestore. O Firestore e o Datastore compartilham um formato de exportação.

  4. Na seção Tabela de destino da página Criar tabela, faça o seguinte:

    • Em Table name, escolha o conjunto de dados apropriado. No campo do nome da tabela, insira um nome para a tabela que você está criando no BigQuery.
    • Verifique se Table type está definido como Native table.
  5. Na seção Esquema, nenhuma ação é necessária. O esquema é inferido para uma exportação do Firestore.

  6. Selecione itens aplicáveis na seção Opções. Se você estiver substituindo uma tabela, defina Preferência de gravação como Substituir tabela.

  7. Clique em Criar tabela.

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. Se você estiver substituindo uma tabela atual, adicione a sinalização --replace.

Para carregar apenas campos específicos, use a sinalização --projection_fields.

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

em que:

  • [LOCATION] é o local. A sinalização --location é opcional;
  • [FORMAT] é DATASTORE_BACKUP. O backup do Datastore é a opção correta para o Firestore. O Firestore e o Datastore compartilham um formato de exportação;
  • [DATASET] é o conjunto de dados que contém a tabela em que os dados serão carregados;
  • [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 Firestore 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 Filestore por meio da API.

  1. Crie uma configuração de job de load que aponte para os dados de origem no Cloud Storage.

  2. Especifique seu local na property location da seção jobReference do recurso do job.

  3. sourceUris precisa ser totalmente qualificado, no formato gs://[BUCKET]/[OBJECT], na configuração do job de carregamento. O nome do arquivo ou objeto precisa terminar com [KIND_NAME].export_metadata. Apenas um URI é permitido para exportações do Firestore, e não é possível usar um caractere curinga.

  4. Para especificar o formato de dados, defina a property sourceFormat como DATASTORE_BACKUP na configuração do job de carregamento. O backup do Datastore é a opção correta para o Firestore. O Firestore e o Datastore compartilham um formato de exportação.

  5. Para carregar apenas campos específicos, defina a property projectionFields.

  6. Se você estiver substituindo uma tabela atual, especifique a disposição de gravação definindo a property writeDisposition como WRITE_TRUNCATE.

Opções do Firestore

Para alterar a forma como o BigQuery analisa os dados de exportação do Firestore, especifique as seguintes opções:

Opção de CSV Opção da IU clássica Sinalização da CLI Property da API BigQuery Descrição
Campos de projeção Nenhum --projection_fields projectionFields Opcional: uma lista separada por vírgulas que indica quais campos do documento de uma exportação do Firestore serão carregados. Por padrão, o BigQuery carrega todos os campos. Os nomes dos campos fazem distinção entre maiúsculas e minúsculas e precisam estar presentes na exportação. Não é possível especificar caminhos de campo dentro de um campo de mapa, como map.foo.
Número de registros corrompidos permitidos Número de erros permitido --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 exceder esse valor, um erro inválido será 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 documento nos arquivos de exportação do Firestore em tipos de dados do BigQuery. Veja na tabela a seguir a conversão entre os tipos de dados.

Tipo de dados do Firestore Tipo de dados do BigQuery
Matriz RECORD
Booleano BOOLEAN
Referência RECORD
Data e hora TIMESTAMP
Mapa RECORD
Número de ponto flutuante FLOAT
Ponto geográfico

RECORD


[{"lat","FLOAT"},
 {"long","FLOAT"}]
        
Número inteiro INTEGER
String STRING (truncada para 64 KB)

Properties da chave do Firestore

Cada documento do Firestore tem uma chave única que contém informações, como o ID e o caminho do documento. O BigQuery cria um tipo de dados RECORD (também conhecido como STRUCT) para a chave com campos aninhados para cada informação, conforme descrito na tabela a seguir.

Property da chave Descrição Tipo de dados do BigQuery
__key__.app O nome do app do Firestore. STRING
__key__.id O ID do documento ou null se __key__.name estiver definido. INTEGER
__key__.kind O código de coleção do documento. STRING
__key__.name O nome do documento ou null se __key__.id estiver definido. STRING
__key__.namespace O Firestore não permite namespaces personalizados. O namespace padrão é representado por uma string vazia. STRING
__key__.path O caminho do documento: a sequência do documento e os pares de coleções da coleção raiz. Por exemplo, "Country", "USA", "PostalCode", 10011, "Route", 1234. STRING