Importar e exportar dados

Você pode usar o serviço de exportação e importação gerenciado para recuperar a exclusão acidental de informações e exportar dados para processamento off-line. É possível exportar todos os documentos ou apenas coleções específicas. Da mesma forma, é possível importar todos os dados de uma exportação ou apenas coleções específicas. Os dados exportados de um banco de dados do Firestore com compatibilidade com o MongoDB podem ser importados para outro banco de dados do Firestore com compatibilidade com o MongoDB. Também é possível carregar exportações do Firestore com compatibilidade com o MongoDB no BigQuery.

Nesta página, descrevemos como exportar e importar documentos do Firestore com compatibilidade com o MongoDB usando o serviço gerenciado de importação e exportação e o Cloud Storage. O serviço gerenciado de importação e exportação do Firestore com compatibilidade com o MongoDB está disponível na ferramenta de linha de comando gcloud e na API do Firestore com compatibilidade com o MongoDB (REST, RPC).

Antes de começar

Antes de usar o serviço gerenciado de exportação e importação, é necessário concluir as tarefas a seguir:

  1. Ative o faturamento para o projeto do Google Cloud . Somente projetos do Google Cloud com faturamento ativado podem usar a funcionalidade de exportação e importação.
  2. Crie um bucket do Cloud Storage para seu projeto em um local próximo ao local do banco de dados do Firestore com compatibilidade com o MongoDB. Não é possível usar um intervalo de pagamentos do solicitante para operações de exportação e importação.

  3. Verifique se a conta tem as permissões necessárias para o Firestore com compatibilidade com o MongoDB e o Cloud Storage. Se você for o proprietário do projeto, sua conta já vai ter as permissões necessárias. Caso contrário, as funções a seguir concederão as permissões necessárias para operações de exportação e importação, além do acesso ao Cloud Storage:

Permissões do agente de serviço

As operações de exportação e importação usam um agente de serviço do Firestore para autorizar operações do Cloud Storage. O agente de serviço do Firestore usa a seguinte convenção de nomenclatura:

Agente de serviço do Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Para saber mais sobre os agentes de serviço, consulte Agentes de serviço.

O agente de serviço do Firestore requer acesso ao bucket do Cloud Storage usado em uma operação de exportação ou importação. Se o bucket do Cloud Storage estiver no mesmo projeto que o banco de dados do Firestore, o agente de serviço do Firestore poderá acessar o bucket por padrão.

Se o bucket do Cloud Storage estiver em outro projeto, será necessário conceder ao agente de serviço do Firestore acesso ao bucket.

Atribuir papéis ao agente de serviço

Use a ferramenta de linha de comando gsutil para atribuir um dos papéis abaixo. Por exemplo, para atribuir o papel de administrador do Storage ao agente de serviço do Firestore, execute o seguinte:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Substitua PROJECT_NUMBER pelo número do projeto, que é usado para nomear o agente de serviço do Firestore. Para ver o nome do agente de serviço, acesse Consultar o nome do agente de serviço.

Como alternativa, é possível atribuir esse papel usando o console do Google Cloud .

Consultar o nome do agente de serviço

É possível consultar a conta que suas operações de importação e exportação usam para autorizar solicitações na página Importar/Exportar no console Google Cloud . Também é possível verificar se o banco de dados usa o agente de serviço do Firestore ou a conta de serviço legada do App Engine.

  1. Veja a conta de autorização ao lado do rótulo Importar/exportar jobs executados como.

O agente de serviço precisa do papel Storage Admin para que o bucket do Cloud Storage seja usado para a operação de exportação ou importação.

Configurar gcloud para seu projeto

É possível iniciar operações de importação e exportação pelo console Google Cloud ou pela ferramenta de linha de comando gcloud. Para usar gcloud, configure a ferramenta de linha de comando e conecte-se ao seu projeto de uma das seguintes maneiras:

Importar dados

Com os arquivos de exportação no Cloud Storage, é possível importar documentos nesses arquivos de volta para seu projeto ou para outro projeto. Veja as informações a seguir sobre operações de importação:

  • Quando você importa dados, os índices necessários são atualizados usando as definições de índice atuais do seu banco de dados. Uma exportação não contém definições de índice.

  • As importações não atribuem novos IDs de documentos. Elas usam os códigos capturados no momento da exportação. O código de um documento é reservado durante o processo de importação de um documento para evitar colisões de código. Se já existir um documento com o mesmo código, a importação substituirá o documento existente.

  • Se uma entidade em seu banco de dados não for afetada por uma importação, ela permanecerá no banco de dados após esse processo.

  • O nome do arquivo .overall_export_metadata precisa ser igual ao nome da pasta mãe:

    gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

    Se você mover ou copiar os arquivos de saída de uma exportação, mantenha os nomes PARENT_FOLDER_NAME e .overall_export_metadata iguais.

  • Uma importação para um banco de dados do Firestore com compatibilidade com o MongoDB de uma exportação com subcoleções falha porque elas não são compatíveis com o Firestore com compatibilidade com o MongoDB.

  • Uma importação para um banco de dados da edição Standard do Firestore de uma exportação com tipos BSON falha porque eles não são compatíveis com a edição Standard do Firestore.

  • Uma importação para um banco de dados do Firestore com compatibilidade com o MongoDB não pode importar dados de namespaces não padrão (API Datastore).

    Uma importação para um banco de dados do Firestore com compatibilidade com o MongoDB de arquivos de dados que contêm namespaces não padrão só é permitida se a operação de exportação incluir um filtro --namespace-ids com o namespace padrão. Somente dados do namespace padrão são importados.

Importar todos os documentos de uma exportação

Console do Google Cloud

  1. No console do Google Cloud , acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione um banco de dados na lista.

  3. No menu de navegação, clique em Importar/Exportar.

  4. Clique em Importar.

  5. No campo Nome do arquivo, insira o nome do arquivo .overall_export_metadata de uma operação de exportação concluída. Use o botão Procurar para ajudar a selecionar o arquivo.

  6. Clique em Importar.

O console retorna à página Importar/Exportar. Se a operação for iniciada com êxito, a página adicionará uma entrada à página de importações e exportações recentes. Em caso de falha, a página mostra uma mensagem de erro.

gcloud

Use o comando firestore import para importar documentos de uma operação de exportação anterior.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

Substitua:

  • BUCKET_NAME/EXPORT_PREFIX: local dos arquivos de exportação.

  • DATABASE: nome do banco de dados.

Exemplo:

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

É possível confirmar o local dos arquivos de exportação no navegador do Cloud Storage no console Google Cloud :

Abrir o navegador do Cloud Storage

Após iniciar uma operação de importação, o fechamento do terminal não cancelará a operação. Saiba como cancelar uma operação.

Importar coleções específicas

Console do Google Cloud

Não é possível selecionar coleções específicas no console. Use gcloud.

gcloud

Para importar coleções específicas de um grupo de arquivos de exportação, use a flag --collection-ids. A operação importa somente as coleções com os IDs fornecidos. Especifique o nome do banco de dados usando a flag --database.

Somente uma exportação de coleções específicas é compatível com a importação dessas coleções. Não é possível importar coleções específicas de uma exportação de todos os documentos.

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2] \
  --database=[DATABASE]

Importar de uma exportação com dados PITR

Use as mesmas etapas de Importar todos os documentos ou Importar coleções específicas para importar dados de PITR. Se algum documento já existir no seu banco de dados, ele será substituído.

Exportar dados

Uma operação de exportação copia documentos no seu banco de dados para um conjunto de arquivos em um intervalo do Cloud Storage. É importante ressaltar que uma exportação não é um snapshot exato do banco de dados registrado no horário de início da exportação. Uma exportação pode incluir alterações feitas enquanto a operação estava em execução.

Exportar todos os documentos

Console do Google Cloud

  1. No console do Google Cloud , acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Importar/Exportar.

  4. Clique em Exportar.

  5. Clique na opção Exportar todo o banco de dados.

  6. Selecione Exportar o estado atual do banco de dados para exportar os dados atuais.

  7. Na seção Destino, insira o nome de um bucket do Cloud Storage ou use o botão Procurar para selecionar um bucket.

  8. Clique em Exportar.

O console retorna à página Importar/Exportar. Se a operação for iniciada com êxito, a página adicionará uma entrada à página de importações e exportações recentes. Em caso de falha, a página mostra uma mensagem de erro.

gcloud

Use o comando firestore export para exportar todos os documentos do banco de dados, substituindo [BUCKET_NAME] pelo nome do bucket do Cloud Storage. Adicione a sinalização --async para evitar que a ferramenta gcloud fique aguardando a conclusão da operação.

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Substitua:

  • BUCKET_NAME: organize suas exportações adicionando um prefixo de arquivo após o nome do bucket, por exemplo, BUCKET_NAME/my-exports-folder/export-name. Se você não fornecer um prefixo de arquivo, o serviço de exportação gerenciado vai criar um com base no carimbo de data e hora atual.

  • DATABASE: nome do banco de dados de onde você quer exportar os documentos.

Após iniciar uma operação de exportação, o fechamento do terminal não cancelará a operação. Saiba como cancelar uma operação.

Exportar coleções específicas

Console do Google Cloud

  1. No console do Google Cloud , acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Importar/Exportar.

  4. Clique em Exportar.

  5. Clique na opção Exportar um ou mais grupos de coleções. Use o menu suspenso para selecionar uma ou mais coleções.

  6. Selecione Exportar o estado atual do banco de dados para exportar os dados atuais.

  7. Na seção Destino, insira o nome de um bucket do Cloud Storage ou use o botão Procurar para selecionar um bucket.

  8. Clique em Exportar.

O console retorna à página Importar/Exportar. Se a operação for iniciada com êxito, a página adicionará uma entrada à página de importações e exportações recentes. Em caso de falha, a página mostra uma mensagem de erro.

gcloud

Para exportar coleções específicas, use a flag --collection-ids. A operação exporta apenas as coleções com os IDs fornecidos.

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2] \
--database=[DATABASE]

Por exemplo, é possível projetar uma coleção restaurants no banco de dados foo para incluir outras coleções, como ratings, reviews ou outlets. Para exportar a coleção específica restaurants e reviews, o comando fica desta forma:

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

Exportar de um carimbo de data/hora PITR

É possível exportar seu banco de dados para o Cloud Storage de dados PITR. É possível exportar dados PITR em que o carimbo de data/hora é um minuto inteiro nos últimos sete dias, mas não anterior ao earliestVersionTime. Se os dados não existirem mais no carimbo de data/hora especificado, a operação de exportação falhará.

A operação de exportação de PITR é compatível com todos os filtros, inclusive a exportação de todos os documentos e a exportação de coleções específicas.

Observe os seguintes pontos antes de exportar dados PITR:

  • Especifique o carimbo de data/hora no formato RFC 3339. Por exemplo, 2020-09-01T23:59:30.234233Z.
  • Verifique se o carimbo de data/hora especificado é de um minuto inteiro nas últimas 7 horas, mas não antes do earliestVersionTime. Se os dados não existirem mais no carimbo de data/hora especificado, será gerado um erro.
  • Você não vai receber cobranças por uma falha na exportação da PITR.

Console

  1. No console do Google Cloud , acesse a página Bancos de dados.

    Acessar "Bancos de dados"
  2. Selecione um banco de dados na lista.
  3. No menu de navegação, clique em Importar/Exportar.
  4. Clique em Exportar.
  5. Configure a origem da exportação para exportar todo o banco de dados ou apenas coleções específicas.

  6. Na seção Escolha o estado do banco de dados que vai ser exportado, selecione Exportar de um momento mais antigo.

    Selecione um horário de snapshot para usar na exportação

  7. Na seção Destino, insira o nome de um bucket do Cloud Storage ou use o botão Procurar para selecionar um bucket.

  8. Clique em Exportar.

    O console retorna à página Importar/Exportar. Se a operação for iniciada com êxito, a página adicionará uma entrada à página de importações e exportações recentes. Em caso de falha, a página mostra uma mensagem de erro.

gcloud

É possível exportar seu banco de dados para o Cloud Storage de dados PITR usando o comando gcloud firestore export.

Exporte o banco de dados, especificando o parâmetro snapshot-time para um carimbo de data/hora de recuperação. Execute o comando a seguir para exportar o banco de dados para o bucket.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Em que PITR_TIMESTAMP é um carimbo de data/hora da PITR na granularidade de minutos, por exemplo, 2023-05-26T10:20:00.00Z.

Adicione a flag --collection-ids para exportar coleções específicas.

Gerenciar operações de exportação e importação

Depois de iniciar uma operação de exportação ou importação, o Firestore com compatibilidade com o MongoDB atribui um nome exclusivo a ela. Use esse nome para excluir, cancelar ou verificar a operação.

Os nomes das operações são prefixados com projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/, por exemplo:

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

No entanto, é possível omitir o prefixo ao especificar um nome de operação para os comandos describe, cancel e delete.

Listar todas as operações de exportação e importação

Console do Google Cloud

É possível consultar uma lista de operações recentes de exportação e importação na página Importação/Exportação do console Google Cloud .

  1. No console do Google Cloud , acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Importar/Exportar.

gcloud

Use o comando operations list para ver todas as operações de exportação e importação em execução e as que foram concluídas recentemente:

gcloud firestore operations list

Verificar o status da operação

Console do Google Cloud

É possível consultar o status de uma operação de exportação ou importação recente na página Importação/Exportação do console Google Cloud .

  1. No console do Google Cloud , acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Importar/Exportar.

gcloud

Use o comando operations describe para mostrar o status de uma operação de exportação ou importação.

gcloud firestore operations describe [OPERATION_NAME]

Estimar o tempo de conclusão

Uma solicitação para o status de uma operação de longa duração retorna as métricas workEstimated e workCompleted. Cada uma dessas métricas é retornada no número de bytes e no número de entidades:

  • workEstimated mostra o número total estimado de bytes e documentos que uma operação processará. O Firestore com compatibilidade com o MongoDB pode omitir essa métrica se não puder fazer uma estimativa.

  • workCompleted mostra o número de bytes e documentos processados até o momento. Após a conclusão da operação, o valor mostrará o número total de bytes e documentos que foram realmente processados, o que pode ser maior do que o valor de workEstimated.

Divida workCompleted por workEstimated para ter uma estimativa aproximada do andamento. A estimativa pode ser imprecisa, porque ela depende da coleção de estatísticas em atraso.

Cancelar uma operação

Console do Google Cloud

É possível cancelar uma operação de exportação ou importação em execução na página Importar/Exportar do console Google Cloud .

  1. No console do Google Cloud , acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Importar/Exportar.

Na tabela Importações e exportações recentes, as operações em execução incluem o botão Cancelar na coluna Concluído. Clique no botão Cancelar para interromper a operação. O botão muda para uma mensagem Cancelando e para Cancelado quando a operação é completamente interrompida.

Tabela de importações e exportações recentes no console mostrando uma importação de dados em andamento com a opção "Cancelar" para interromper a operação.

gcloud

Use o comando operations cancel para interromper uma operação em andamento:

gcloud firestore operations cancel [OPERATION_NAME]

Se você cancelar uma operação em execução, ela não será desfeita. Uma operação de exportação cancelada deixará os documentos já exportados no Cloud Storage, e uma operação de importação cancelada manterá as atualizações já feitas no seu banco de dados. Não é possível importar uma exportação parcialmente concluída.

Excluir uma operação

Use o comando gcloud firestore operations delete para remover uma operação da lista de operações recentes. Esse comando não excluirá arquivos de exportação do Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

Faturamento e preços para operações de exportação e importação

É necessário ativar o faturamento para o projeto do Google Cloud antes de usar o serviço gerenciado de exportação e importação.

Essas operações são cobradas por unidades de leitura e gravação conforme as taxas listadas em Preços do Firestore com compatibilidade com o MongoDB.

Os arquivos de saída armazenados no Cloud Storage contam para os custos de armazenamento de dados do Cloud Storage.

As operações de exportação ou importação não vão acionar os alertas do orçamento doGoogle Cloud até a conclusão. As operações de exportação e importação não vão afetar o uso mostrado na seção de uso do console.

Como visualizar os custos de exportação e importação

As operações de exportação e importação aplicam o rótulo goog-firestoremanaged:exportimport às operações faturadas. Na página de relatórios do Cloud Billing, é possível usar esse rótulo para visualizar os custos relacionados às operações de importação e exportação:

Acesse o rótulo goog-firestoremanaged no menu de filtros.

Exportar para o BigQuery

É possível carregar dados de uma exportação do Firestore com compatibilidade com o MongoDB para o BigQuery, mas somente se você tiver especificado um filtro collection-ids. Consulte Como carregar dados de exportações do Firestore com compatibilidade com o MongoDB.

Ao carregar dados de compatibilidade do Firestore com o MongoDB no BigQuery, os tipos de dados BSON são representados com o tipo de dados STRING.

Limite de colunas do BigQuery

O BigQuery impõe um limite de 10 mil colunas por tabela. As operações de exportação do Firestore com compatibilidade com o MongoDB geram um esquema de tabela do BigQuery para cada coleção. Nesse esquema, cada nome de campo exclusivo dentro de uma coleção se torna uma coluna de esquema.

Se o esquema do BigQuery de uma coleção ultrapassar 10 mil colunas, a operação de exportação do Firestore com compatibilidade com o MongoDB tentará permanecer abaixo do limite da coluna ao considerar campos de mapa como bytes. Se essa conversão resultar em menos de 10 mil colunas, será possível carregar os dados no BigQuery, mas não consultar os subcampos dentro dos campos do mapa. Se o número de colunas ainda exceder 10 mil,a operação de exportação não vai gerar um esquema do BigQuery para a coleção, e não será possível carregar seus dados no BigQuery.

Exportar arquivos de formatos e metadados

A saída de uma exportação gerenciada usa o formato de registro LevelDB.

Arquivos de metadados

Uma operação de exportação cria um arquivo de metadados para cada coleção que você especificar. Os arquivos de metadados geralmente são denominados ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

Os arquivos de metadados são buffers de protocolo. É possível decodificá-los com o compilador de protocolo protoc. Por exemplo, é possível decodificar um arquivo de metadados para determinar as coleções dos arquivos de exportação:

protoc --decode_raw < export0.export_metadata