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 que o bucket 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.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento.

Permissões necessárias

Para carregar dados no BigQuery, você precisa de permissões do IAM para executar um job de carregamento e carregar dados nas tabelas e partições do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de permissões do IAM para acessar o bucket que contém os dados.

Permissões para carregar dados no BigQuery

Para carregar dados em uma nova tabela ou partição do BigQuery ou anexar ou substituir uma tabela ou partição existente, você precisa das seguintes permissões do IAM:

bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create

Cada um dos seguintes papéis de IAM predefinidos inclui as permissões necessárias para carregar dados em uma tabela ou partição do BigQuery:

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin (inclui a permissão bigquery.jobs.create)
bigquery.user (inclui a permissão bigquery.jobs.create)
bigquery.jobUser (inclui a permissão bigquery.jobs.create)

Além disso, se você tiver a permissão bigquery.datasets.create, poderá criar e atualizar tabelas usando um job de carregamento nos conjuntos de dados que criar.

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Permissões para carregar dados do Cloud Storage

Para receber as permissões necessárias para carregar dados de um bucket do Cloud Storage, peça ao administrador para conceder a você o o papel IAM doAdministrador de armazenamento (roles/storage.admin) no bucket. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para carregar dados de um bucket do Cloud Storage. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para carregar dados de um bucket do Cloud Storage:

storage.buckets.get
storage.objects.get
storage.objects.list (required if you are using a URI wildcard)

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

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 o Console do Google Cloud, a ferramenta de linha de comando bq ou API.

Às vezes, a terminologia do Datastore é usada no console do Google Cloud e na ferramenta de linha de comando bq, 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

No Console do Google Cloud, acesse a página BigQuery.

Acessar o BigQuery
No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
Na seção Informações do conjunto de dados, clique em Criar tabela.
No painel Criar tabela, especifique os seguintes detalhes:

Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de. Em seguida, faça o seguinte:
1. Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
  O URI do arquivo de exportação do Firestore precisa terminar com KIND_COLLECTION_ID.export_metadata. Por exemplo, em default_namespace_kind_Book.export_metadata, Book é o ID da coleção, e default_namespace_kind_Book é o nome do arquivo gerado pelo Firestore. Se o URI não terminar com KIND_COLLECTION_ID.export_metadata, você receberá a seguinte mensagem de erro: não contém metadados de backup válidos. (error code: invalid).
  Observação: não use o arquivo com o final overall_export_metadata. Esse arquivo não pode ser usado pelo BigQuery.
2. Em Formato do arquivo, selecione Backup do Cloud Datastore. O Firestore e o Datastore compartilham o formato de exportação.
Na seção Destino, especifique os seguintes campos:
1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
2. No campo Tabela, insira o nome da tabela que você quer criar.
3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, nenhuma ação é necessária. O esquema é inferido para uma exportação do Firestore.
Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster.
Clique em Opções avançadas e faça o seguinte:
- Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Usando essa opção, você cria uma nova tabela e carrega seus dados nela.
- Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
- Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
Selecione Criar tabela.

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. 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

Substitua:

LOCATION: sua localização. A sinalização --location é opcional.
FORMAT: DATASTORE_BACKUP. 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 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 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.

Crie uma configuração de job de load que aponte para os dados de origem no Cloud Storage.
Especifique seu local na property location da seção jobReference do recurso do job.
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.
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.
Para carregar apenas campos específicos, defina a property projectionFields.
Se você estiver substituindo uma tabela atual, especifique a disposição de gravação definindo a property writeDisposition como WRITE_TRUNCATE.

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

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 do Console do Google Cloud	Sinalização "bq"	Propriedade da API BigQuery	Descrição
Indisponível	`--projection_fields`	`projectionFields` (Java, Python)	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`.

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. Confira na tabela a seguir a conversão entre os tipos de dados compatíveis.

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.

Propriedade 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 ID 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