Como gerenciar índices

O Firestore garante o alto desempenho das consultas ao exigir um índice de todas elas. Os índices necessários para as consultas mais básicas são criados automaticamente para você. medida que você usa e testa o aplicativo, o Cloud Firestore gera mensagens de erro para ajudar na criação de outros índices necessários. Nesta página, você aprende a gerenciar índices de campo único e compostos.

Criar um índice inexistente usando uma mensagem de erro

Se você tentar executar uma consulta composta com uma cláusula de intervalo que não seja mapeada para um índice atual, um erro será retornado. A mensagem desse erro inclui um link direto para você criar o índice inexistente no Console do Firebase.

Abra o link gerado para o Console do Firebase, revise as informações preenchidas automaticamente e clique em Criar.

Usar o Console do Google Cloud Platform

No Console do Google Cloud Platform, é possível gerenciar isenções de indexação de campo único e índices compostos.

Criar um índice composto

Para criar manualmente um novo índice composto no Console do GCP:

  1. Vá para a seção ndices compostos.

    Ir para a seção ndices compostos

  2. Clique em Criar índice.

  3. Insira um ID de coleção. Adicione os nomes dos campos que você quer indexar e um modo de índice para cada um. Clique em Salvar índice.

O novo índice aparecerá na lista de índices compostos, e o Firestore começará a criar o índice. Quando a criação do índice for concluída, você verá uma marca de seleção verde ao lado dele.

Excluir um índice composto

Para excluir um índice composto, faça o seguinte:

  1. Vá para a seção ndices compostos.

    Ir para a seção ndices compostos

  2. Na lista de índices compostos, clique no botão Mais referente ao índice que você quer excluir. Clique em Excluir.

  3. Clique em Excluir índice no alerta para confirmar a exclusão.

Adicionar uma isenção para índice de campo único

As isenções para um índice de campo único permitem modificar as configurações de índice automático para campos específicos de uma coleção. É possível adicionar isenções de campo único no console:

  1. Vá para a seção ndices de campo único.

    Ir para a seção ndices de campo único

  2. Clique em Adicionar isenção.

  3. Insira um ID de coleção e um caminho de campo.

  4. Selecione novas configurações de indexação para este campo. Ative ou desative os índices de campo único crescentes, decrescentes e contendo matriz automaticamente.

  5. Clique em Salvar isenção.

Excluir uma isenção de índice de campo único

Para excluir uma isenção de índice de campo único, faça o seguinte:

  1. No visualizador do Firestore, acesse a seção ndices de campo único.

    Ir para a seção ndices de campo único

  2. Na lista de isenções de índice de campo único, clique no botão Mais na isenção que você quer excluir. Clique em Excluir.

  3. Confirme que você quer excluir essa isenção clicando em Excluir no alerta.

Quando você exclui uma isenção de campo único, o campo ou subcampo especificado usa as configurações de indexação herdadas. Os campos do documento são revertidos para as configurações de índice automático do seu banco de dados. Os subcampos em um mapa herdam qualquer isenção nos campos pai antes de herdar as configurações automáticas de índice.

Usar a CLI do Firebase

Também é possível implantar índices com a CLI do Firebase. Para começar, execute o comando firebase init firestore no diretório do projeto. Durante a configuração, a Firebase CLI gera um arquivo JSON com os índices padrão no formato correto. Edite o arquivo para adicionar mais índices e faça a implantação usando o comando firebase deploy. Se você quer apenas implantar índices, adicione a sinalização --only firestore:indexes. Se você fizer edições nos índices usando o Console do Firebase, atualize o arquivo de índices local. Consulte a referência de definição do índice JSON.

Tempo de criação do índice

Para criar um índice, o Firestore precisa configurar o índice e, em seguida, preencher o índice com os dados existentes. O tempo de criaçã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 de criação mínimo de um índice é de alguns minutos, mesmo para um banco de dados vazio.

  • O tempo de preenchimento depende da quantidade de dados no índice novo. Quanto mais valores de campo corresponderem à definição do índice, mais demorado será o preenchimento.

As versões de índice são operações de longa duração.

Depois de iniciar um build de índice, o Firestore atribui à operação um nome exclusivo. 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, é possível omitir o prefixo ao especificar um nome de operação para o comando describe.

Como listar todas as operações de longa duração

Para listar operações de longa duração, use o comando gcloud firestore operations list. Esse comando lista as operações contínuas e as concluídas recentemente. As operações são listadas por alguns dias após a conclusão:

gcloud firestore operations list

Verificar o status da operação

Em vez de listar todas as operações de longa duração, é possível listar os detalhes de uma única operação:

gcloud firestore operations describe operation-name

Como estimar o tempo de conclusão

Conforme sua operação é executada, consulte o valor do campo state para 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, o que pode ser diferente do valor de workEstimated.

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

Por exemplo, veja o status do progresso de uma criaçã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. Consulte o valor do campo state para ver o resultado da operação. Se o campo done não for definido na resposta, seu valor será false. Não dependa da existência do valor done para operações em andamento.

Erros na criação do índice

Talvez você encontre erros na criação ao gerenciar índices compostos e isenções de índices de campo único. A indexação pode falhar se o Firestore encontrar um problema com a indexação de dados. Isso costuma significar 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. Verifique se você atingiu algum limite de índice. Depois, tente novamente a operação de indexação.