Como carregar dados de exportações do Cloud Firestore

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

Permissões necessárias

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, também precisará ter permissões storage.objects.list.

O papel do IAM predefinido storage.objectViewer pode ser concedido para fornecer permissões storage.objects.get e storage.objects.list.

Limitações

Ao carregar dados de uma exportação do Cloud Firestore no BigQuery, considere estas restrições:

  • 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.
  • Você pode especificar apenas um URI do Cloud Storage, e não pode usar um caractere curinga de URI.
  • Para que a exportação do Cloud 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 Cloud Firestore a uma tabela.
  • Seu comando de exportação deve especificar um filtro de collection-ids. Não é possível carregar os dados exportados no BigQuery sem a especificação de um filtro de código de coleção.

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

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

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

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acesse a IU da Web do BigQuery
  2. 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. Criar tabela
  3. Siga estas etapas na página Criar tabela, na seção Origem:

    • Em Criar uma tabela de, selecione Cloud Storage Criar fonte de tabela

    • No campo de origem, insira o URI do Cloud Storage. O intervalo do Cloud Storage deve estar no mesmo local que seu conjunto de dados. O URI do arquivo de exportação do Cloud Firestore deve terminar com [KIND_COLLECTION_ID].export_metadata. Por exemplo: default_namespace_kind_Book.export_metadata. Nesse exemplo, Book é o código de coleção, e default_namespace_kind_Book é o nome do arquivo gerado pelo Cloud Firestore.

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

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

  4. Siga estas etapas 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 para uma exportação do Cloud 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 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 selecione Criar nova tabela.
  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. O URI do arquivo de exportação do Cloud Firestore deve terminar com [KIND_COLLECTION_ID].export_metadata. Por exemplo: default_namespace_kind_Book.export_metadata. Nesse exemplo, Book é o código de coleção, e default_namespace_kind_Book é o nome do arquivo gerado pelo Cloud Firestore.

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

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

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

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

Para carregar apenas campos específicos, use o sinalizador --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 Cloud Datastore é a opção correta para o Cloud Firestore. O Cloud Firestore e o Cloud Datastore compartilham um formato de exportação.
  • [DATASET] é o conjunto de dados que contém a tabela em que 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 Firestore 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 Firestore usando a API.

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

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

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

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

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

  6. Se você estiver substituindo uma tabela atual, defina a propriedade writeDisposition como WRITE_TRUNCATE para especificar a disposição de gravação.

Opções do Cloud Firestore

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

Opção de CSV Opção da IU clássica Sinalização da CLI Propriedade da API BigQuery Descrição
Campos de projeção None --projection_fields projectionFields (Opcional) Uma lista separada por vírgulas que indica quais campos do documento serão carregados de uma exportação do Cloud Firestore. 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 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 documento nos arquivos de exportação do Cloud Firestore em tipos de dados do BigQuery. A tabela a seguir descreve a conversão entre os tipos de dados.

Tipo de dados do Cloud 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)

Propriedades da chave do Firestore

Cada documento do Cloud Firestore tem uma chave única que contém informações como o código 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.

Propriedade da chave Descrição Tipo de dados do BigQuery
__key__.app O nome do app Cloud Firestore. STRING
__key__.id O código 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 Cloud 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
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.