O Cloud Firestore garante o desempenho da consulta exigindo um índice para cada consulta. Os índices necessários para as consultas mais básicas são criados automaticamente para você. À medida que você usa e testa seu app, o Cloud Firestore gera mensagens de erro que ajudam a criar índices adicionais exigidos pelo seu app. Esta página descreve como gerenciar índices compostos e de campo único .
Crie um índice ausente por meio de uma mensagem de erro
Se você tentar uma consulta composta com uma cláusula de intervalo que não mapeia para um índice existente, receberá um erro. A mensagem de erro inclui um link direto para criar o índice ausente no console do Firebase.
Siga o link gerado para o console do Firebase, revise as informações preenchidas automaticamente e clique em Criar .
Funções e permissões
Antes de criar um índice no Cloud Firestore, certifique-se de ter uma das seguintes funções atribuídas a você:
-
roles/datastore.owner -
roles/datastore.indexAdmin -
roles/editor -
roles/owner
Se você definiu funções personalizadas, atribua todas as permissões a seguir para criar índices:
-
datastore.indexes.create -
datastore.indexes.delete -
datastore.indexes.get -
datastore.indexes.list -
datastore.indexes.update
Usar o console do Firebase
Para criar manualmente um novo índice no console do Firebase:
- Vá para a seção Cloud Firestore do console do Firebase .
- Vá para a guia Índices e clique em Adicionar índice .
- Insira o nome da coleção e defina os campos pelos quais deseja ordenar o índice.
- Clique em Criar .
Os campos de índice devem estar em conformidade com as restrições nos caminhos dos campos .
Os índices podem levar alguns minutos para serem criados, dependendo do tamanho da consulta. Depois de criá-los, você poderá ver seus índices e seus status na seção Índices Compostos. Se ainda estiverem em construção, o Firebase Console inclui uma barra de status de construção.
Remover índices
Para excluir um índice:
- Vá para a seção Cloud Firestore do console do Firebase .
- Clique na guia Índices .
- Passe o mouse sobre o índice que deseja excluir e selecione Excluir no menu de contexto.
- Confirme que deseja excluí-lo clicando em Excluir do alerta.
Usar a CLI do Firebase
Você também pode implantar índices com a CLI do Firebase . Para começar, execute firebase init firestore no diretório do seu projeto. Durante a configuração, a CLI do Firebase gera um arquivo JSON com os índices padrão no formato correto. Edite o arquivo para adicionar mais índices e implante-o com o comando firebase deploy .
Para implantar apenas índices e regras do Cloud Firestore, adicione a sinalização --only firestore .
Se você fizer edições nos índices usando o console do Firebase, atualize também o arquivo de índices locais. Consulte a referência de definição de índice JSON .
Usar o Terraform
Criando índices no banco de dados
O banco de dados Cloud Firestore pode incluir um índice de campo único ou um índice composto. Você pode editar o arquivo de configuração do Terraform para criar um índice para seu banco de dados.
Índice de campo único
O exemplo de arquivo de configuração do Terraform a seguir cria um índice de campo único no campo name na coleção de chatrooms :
firestore.tf
resource "random_id" "variable"{
byte_length = 8
}
resource "google_firestore_field" "single-index" {
project = "project-id"
database = "database-id"
collection = "chatrooms_${random_id.variable.hex}"
field = "name"
index_config {
indexes {
order = "ASCENDING"
query_scope = "COLLECTION_GROUP"
}
indexes {
array_config = "CONTAINS"
}
}
ttl_config {}
}
- Substitua project-id pelo ID do seu projeto. Os IDs do projeto devem ser exclusivos.
- Substitua database-id pelo ID do seu banco de dados.
Índice composto
O exemplo de arquivo de configuração do Terraform a seguir cria um índice composto para uma combinação do campo name e do campo description na coleção chatrooms :
firestore.tf
resource "google_firestore_index" "composite-index" {
project = "project-id"
database = "database-id"
collection = "chatrooms"
fields {
field_path = "name"
order = "ASCENDING"
}
fields {
field_path = "description"
order = "DESCENDING"
}
}
- Substitua project-id pelo ID do seu projeto. Os IDs do projeto devem ser exclusivos.
- Substitua database-id pelo ID do seu banco de dados.
Tempo de construção do índice
Para criar um índice, o Cloud Firestore deve configurá-lo e preenchê-lo com os dados existentes. O tempo de construção do índice é a soma do tempo de configuração e do tempo de preenchimento:
A configuração de um índice leva alguns minutos. O tempo mínimo de construção de um índice é de alguns minutos, mesmo para um banco de dados vazio.
O tempo de preenchimento depende da quantidade de dados existentes que pertencem ao novo índice. Quanto mais valores de campo corresponderem à definição do índice, mais tempo levará para preencher o índice.
As compilações de índice são operações de longa duração .
Depois de iniciar a criação de um índice, o Cloud Firestore atribui um nome exclusivo à operação. Os nomes das operações são prefixados com projects/[PROJECT_ID]/databases/(default)/operations/ , por exemplo:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
No entanto, você pode omitir o prefixo ao especificar um nome de operação para o comando describe .
Listando todas as operações de longa duração
Para listar operações de longa duração, use o comando gcloud firestore Operations List . Este comando lista as operações em andamento e as concluídas recentemente. As operações são listadas por alguns dias após a conclusão:
gcloud firestore operations list
Verifique o status da operação
Em vez de listar todas as operações de longa duração, você pode listar os detalhes de uma única operação:
gcloud firestore operations describe operation-name
Estimando o tempo de conclusão
À medida que sua operação é executada, consulte o valor do campo state para ver o status geral da operação.
Uma solicitação para o status de uma operação de longa duração também retorna as métricas workEstimated e workCompleted . Essas métricas são retornadas para o número de documentos. workEstimated mostra o número total estimado de documentos que uma operação processará. workCompleted mostra o número de documentos processados até o momento. Após a conclusão da operação, workCompleted reflete o número total de documentos que foram realmente processados, que pode ser diferente do valor de workEstimated .
Divida workCompleted pelo workEstimated para obter uma estimativa aproximada do progresso. A estimativa pode ser imprecisa porque depende do atraso na recolha de estatísticas.
Por exemplo, aqui está o status do progresso de uma construção de índice:
{
"operations": [
{
"name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
"metadata": {
"@type": "type.googleapis.com/google.firestore.admin.v1.IndexOperationMetadata",
"common": {
"operationType": "CREATE_INDEX",
"startTime": "2020-06-23T16:52:25.697539Z",
"state": "PROCESSING"
},
"progressDocuments": {
"workCompleted": "219327",
"workEstimated": "2198182"
}
},
},
...
Quando uma operação for concluída, a descrição da operação conterá "done": true . Veja o valor do campo state para o resultado da operação. Se o campo done não estiver definido na resposta, seu valor será false . Não dependa da existência do valor done para operações em andamento.
Erros de construção de índice
Você pode encontrar erros de criação de índice ao gerenciar índices compostos e isenções de índice de campo único. Uma operação de indexação poderá falhar se o Cloud Firestore encontrar um problema com os dados que está indexando. Geralmente, isso significa que você atingiu um limite de índice . Por exemplo, a operação pode ter atingido o número máximo de entradas de índice por documento.
Se a criação do índice falhar, você verá a mensagem de erro no console. Depois de verificar se não está atingindo nenhum limite de índice , tente novamente a operação de índice.