Visão geral do índice da edição Enterprise

O comportamento de indexação depende da edição do banco de dados. Esta página descreve a indexação da edição Enterprise do Firestore. Para a edição Standard do Firestore, consulte Visão geral dos índices da edição Standard do Firestore.

Esta seção descreve a indexação da edição Enterprise do Cloud Firestore. A edição Enterprise do Cloud Firestore não cria índices por padrão. Para reduzir custos e melhorar o desempenho do banco de dados, crie índices para as consultas mais usadas.

Os índices têm um grande impacto no desempenho de um banco de dados. Se houver um índice para uma consulta, o banco de dados poderá retornar resultados de maneira eficiente, reduzindo a quantidade de dados que precisam ser verificados e o trabalho necessário para classificar os resultados. No entanto, as entradas de índice aumentam os custos de armazenamento e a quantidade de trabalho realizado durante uma operação de gravação em campos indexados.

Definição e estrutura dos índices

Um índice consiste no seguinte:

  • um ID de coleção
  • uma lista de campos na coleção especificada
  • um modo de índice, crescente, decrescente ou "array-contains", para cada campo

Um índice também pode ativar as opções esparso ou único.

Ordenação de índice

A ordem e a direção de classificação de cada campo definem o índice de maneira exclusiva. Por exemplo, os índices a seguir são distintos e não podem ser trocados:

Coleção Campos
cidades país (ascendente), população (descendente)
cidades population (ascendente), country (descendente),

Ao criar um índice para oferecer suporte a uma consulta, inclua os campos na mesma ordem da consulta.

Densidade de índice

Por padrão, as entradas de índice armazenam dados de todos os documentos em uma coleção. Isso é conhecido como um índice não esparso. Uma entrada de índice será adicionada a um documento, independente de ele conter algum dos campos especificados no índice. Campos inexistentes são tratados como tendo um valor NULL ao gerar entradas de índice. Para mudar esse comportamento, defina o índice como esparso.

Índices esparsos

Um índice esparso indexa apenas os documentos da coleção que contêm um valor (inclusive nulo) para pelo menos um dos campos indexados. Um índice esparso reduz os custos de armazenamento e pode melhorar o desempenho.

Índices de matriz contém

Para otimizar o desempenho da consulta ao consultar um campo de matriz usando array-contains ou array-contains-any, indexe o campo no modo array-contains. Um índice pode ter no máximo um campo no modo array-contains.

Ao indexar um campo de matriz no modo array-contains, o mecanismo de consulta pode localizar rapidamente documentos que contêm valores de matriz específicos. Sem um índice, as consultas verificam os valores da matriz realizando uma verificação completa da coleção, o que aumenta as latências de consulta e os custos de leitura à medida que o tamanho da coleção aumenta.

Para indexar um campo de matriz, ele precisa atender ao seguinte requisito:

  • Requisito de matriz não vazia:uma entrada de índice só será criada se o campo de matriz existir no documento e não estiver vazio. Documentos com campos de matriz ausentes, não matrizes ou vazios não são indexados.

Como a densidade se relaciona com os índices array-contains

Para índices que incluem um campo array-contains, as regras de densidade de índice se aplicam apenas aos campos indexados ordenados. Se o requisito de matriz não vazia for atendido, as regras de densidade serão aplicadas aos campos indexados ordenados restantes no índice:

  • Índice não esparso (DENSE): uma entrada de índice é gerada para o documento. Os campos indexados ordenados ausentes no índice são armazenados como null na entrada do índice.
  • Índice esparso (SPARSE): uma entrada de índice é gerada somente se pelo menos um dos campos indexados ordenados existir no documento.

Exemplo: geração de entradas de índice

Considere o índice users (tags[*], status ASC):

Documento Índice NON-SPARSE Índice SPARSE
{
  tags: ["news"],
  status: "active"
}		 Indexado:
• (tags: "news", status: "active")		 Indexado:
• (tags: "news", status: "active")
{
  tags: ["news", "sports"],
  status: "active"
}		 Indexado:
• (tags: "news", status: "active")
• (tags: "sports", status: "active")		 Indexado:
• (tags: "news", status: "active")
• (tags: "sports", status: "active")
{
  tags: ["news", "news"],
  status: "active"
}		 Indexado:
• (tags: "news", status: "active") (deduplicado)		 Indexado:
• (tags: "news", status: "active") (deduplicado)
{
  tags: [null],
  status: "active"
}		 Indexado:
• (tags: null, status: "active")		 Indexado:
• (tags: null, status: "active")
{
  tags: ["news"]
}		 Indexado:
• (tags: "news", status: null)		 Não indexado (campo status ausente)
{
  tags: "news",
  status: "active"
}		 Não indexado (o campo não é uma matriz) Não indexado (o campo não é uma matriz)
{
  tags: null,
  status: "active"
}		 Não indexado (o campo não é uma matriz) Não indexado (o campo não é uma matriz)
{
  status: "active"
}		 Não indexado (campo tags ausente) Não indexado (campo tags ausente)
{
  tags: [],
  status: "active"
}		 Não indexado (matriz vazia) Não indexado (matriz vazia)

Exemplo de consulta

Web
// Query for users where 'tags' contains 'news' and 'status' is 'active'
const query = db.collection("users")
  .where("tags", "array-contains", "news")
  .where("status", "==", "active");

// Documents returned by the query:
// [
//   {
//     "id": "alice",
//     "tags": ["news", "tech"],
//     "status": "active"
//   }
// ]

Índices exclusivos

Defina a opção de índice exclusivo para aplicar valores únicos aos campos indexados. Para índices em vários campos, cada combinação de valores precisa ser exclusiva em todo o índice. O banco de dados rejeita qualquer operação de atualização e inserção que tente criar entradas de índice com valores duplicados. Se os dados dos campos indexados contiverem valores duplicados e você tentar criar um índice exclusivo, a criação do índice vai falhar com uma mensagem de erro nos detalhes da operação.

Campos ausentes em um índice exclusivo

Se você inserir um documento com campos ausentes para o índice exclusivo, o índice definirá valores null para os campos ausentes. A entrada de índice resultante precisa ser única, ou a operação vai falhar.

Por exemplo, com este índice:

Coleção Campos indexados Escopo da consulta
cidades Nome (crescente) Coleção

Se você adicionar o documento {"abbreviation": "LA"} à coleção, o índice exclusivo vai criar uma entrada com name definido como null. Se você tentar adicionar o documento {"abbreviation": "NYC"}, a operação vai falhar porque a entrada resultante para o índice exclusivo é a mesma.

O mesmo comportamento se aplica a índices exclusivos com vários campos. Ao criar ou atualizar um documento, os campos indexados ausentes são definidos como null, e a entrada de índice resultante precisa ser única no índice.

Índices exclusivos em valores de matriz

Um índice array-contains exclusivo proíbe documentos com elementos de matriz sobrepostos.

Esse tipo de índice não garante que uma matriz tenha valores exclusivos em um único documento.

Por exemplo, com um índice exclusivo em um campo chamado tags:

O documento a seguir, doc1, é válido para inserção:

{
  "tags": [ "news", "tech", "news", "music" ]
}

O índice permite valores duplicados ("news") na mesma matriz de um único documento.

Se você tentar inserir um segundo documento, doc2, com um elemento duplicado, a operação vai falhar:

{
  "tags": [ "sports", "music" ]
}

A operação falha porque "music" já está presente na matriz de doc1 e mapeado no índice.

Se você precisar garantir que os elementos na mesma matriz em um único documento sejam exclusivos, faça isso na lógica do aplicativo.

Matrizes vazias, campos ausentes e valores nulos

Normalmente, os campos ausentes em um índice exclusivo são tratados como null e precisam ser exclusivos em todos os documentos (consulte Campos ausentes em um índice exclusivo). No entanto, para índices exclusivos em campos de matriz:

  • Matrizes vazias, campos ausentes e valores nulos independentes:se o campo de matriz estiver vazio, ausente ou tiver um valor null independente (não dentro de uma matriz), nenhuma chave de índice será gerada para o documento. Portanto, vários documentos podem ter campos vazios ou valores null independentes sem acionar erros de chave duplicada.
  • Elementos nulos dentro de uma matriz:se a matriz tiver um valor null como um elemento (por exemplo, ["news", null]), o elemento null será indexado. Qualquer documento subsequente que contenha um elemento null no campo de matriz indexada vai falhar com um erro de chave duplicada.

Resolver problemas de erros na criação do índice

Talvez você encontre erros na criação ao gerenciar seus índices. A indexação pode falhar se o banco de dados encontrar um problema com os dados. As operações de indexação podem falhar pelos seguintes motivos:

  • 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ê vai receber uma mensagem de erro. Se você não atingiu um limite de índice, tente de novo a operação de indexação.
  • Você define a opção de índice exclusivo, e os dados dos campos indexados criam entradas de índice duplicadas. Para continuar, remova as combinações duplicadas de valores dos dados.