Tipos de índices no Cloud Firestore

Os índices são um fator importante no desempenho de um banco de dados. Semelhantes aos índices de livros que correlacionam os tópicos às páginas, os índices de bancos de dados referenciam os itens aos locais deles no banco de dados. Quando você faz uma consulta em um banco de dados, ele pode usar um índice para procurar rapidamente os locais dos itens solicitados.

Veja nesta página os dois tipos de índice usados pelo Cloud Firestore: índices de campo único e compostos.

Um índice para cada consulta

Caso não haja um índice em uma consulta, a maioria dos bancos de dados rastreará o conteúdo item por item, um processo demorado que fica ainda mais lento à medida que o banco de dados cresce. O Cloud Firestore garante alto desempenho de consulta usando índices em todas as consultas. Como resultado, o desempenho da consulta depende do tamanho do conjunto de resultados e não do número de itens inclusos no banco de dados.

Menos gerenciamento de índices, mais desenvolvimento de apps

O Cloud Firestore inclui recursos que reduzem o tempo necessário para gerenciar os índices. Os índices necessários para as consultas mais básicas são criados automaticamente. À medida que você usa e testa seu app, o Cloud Firestore ajuda a identificar e criar outros índices que sejam necessários para ele.

Tipos de índice

O Cloud Firestore usa dois tipos de índices, de campo único e compostos. O número de campos indexados não é a única diferença entre esses índices, o gerenciamento deles também é diferente.

Índices de campo único

Um índice de campo único armazena um mapeamento ordenado de todos os documentos em um conjunto com um campo específico. Cada entrada em um índice de campo único registra o valor de um documento para um campo específico e o local do documento no banco de dados. O Cloud Firestore usa esses índices para realizar muitas consultas básicas. É preciso definir as configurações de indexação automática e a isenção de índice do banco de dados para gerenciar índices de campo único.

Indexação automática

Por padrão, o Cloud Firestore mantém automaticamente os índices de campo único para cada campo em um documento e cada subcampo em um mapa. O Cloud Firestore usa as seguintes configurações para índices de campo único:

• Para cada campo que não seja de matriz ou de mapa, o Cloud Firestore define dois índices de campo único do escopo da coleção: um em modo crescente e o outro em modo decrescente.

• Para cada campo de mapa, o Cloud Firestore cria um índice crescente do escopo da coleção e um índice decrescente para cada subcampo no mapa que não seja de matriz ou de mapa.

• Para cada campo de matriz em um documento, o Cloud Firestore cria e mantém um índice "array-contains" do escopo da coleção.

• Índices de campo único com escopo de grupo de coleções não são mantidos por padrão.

Isenções de índice de campo único

É possível isentar um campo a partir das suas configurações de indexação automática criando uma isenção de índice de campo único. Uma isenção de indexação substitui as configurações de índice automático em todo o banco de dados. Uma isenção pode ativar um índice de campo único que suas configurações de indexação automática geralmente desativariam, ou desativar um índice de campo único que a indexação automática geralmente ativaria. Para ver casos em que as isenções podem ser úteis, consulte as práticas recomendadas de indexação.

Se você criar uma isenção para um índice de campo único no campo do mapa, os subcampos do mapa herdarão essas configurações. No entanto, é possível definir as isenções para um índice de campo único em subcampos específicos. Se você excluir a isenção de um subcampo, ele herdará as configurações de isenção do campo pai. Se essas configurações não existirem, ele herdará as configurações gerais do banco de dados.

Para criar e gerenciar isenções de índice de campo único, consulte Como gerenciar índices no Cloud Firestore.

Índices compostos

Um índice composto armazena um mapeamento ordenado de todos os documentos em uma coleção, com base em uma lista ordenada de campos a serem indexados.

O Cloud Firestore usa índices compostos para oferecer suporte às consultas que ainda não aceitam índices de campo único.

O Cloud Firestore não cria índices compostos automaticamente, como faria para os índices de campo único, devido ao grande número de combinações possíveis de campos. Em vez disso, ele ajuda a identificar e criar os índices compostos necessários à medida que você cria seu app.

Se você fizer a consulta acima sem antes criar o índice necessário, o Cloud Firestore retornará uma mensagem de erro contendo um link que pode ser acessado para criar o índice ausente. Isso acontecerá sempre que você fizer uma consulta que não for suportada por um índice. Também é possível criar e gerenciar índices compostos manualmente usando o console ou a CLI do Firebase. Para mais informações sobre esses processos, consulte Como gerenciar índices.

Modos de índice e escopos de consulta

A configuração de índices compostos e de campo único é feita de maneira diferente, mas ambos exigem que você configure modos de índice e escopos de consulta para seus índices.

Modos de índice

Ao definir um índice, você seleciona um modo de índice para cada campo indexado. O modo de índice de cada campo oferece suporte a cláusulas de consulta específicas nesse campo. É possível selecionar os seguintes modos de índice:

Escopos da consulta

Cada índice tem um escopo delimitado a uma coleção ou a um grupo de coleções. Isso é conhecido como o escopo da consulta do índice:

Escopo da coleção

O Cloud Firestore cria índices com um escopo de coleção por padrão. Esses índices dão suporte a consultas que retornam resultados de uma única coleção.

Escopo do grupo de coleções

Um grupo de coleções inclui todas as coleções com o mesmo ID. Para executar uma consulta do grupo de coleções que retorne resultados filtrados ou ordenados de um desses grupos, é necessário criar um índice correspondente com o escopo de grupo de coleções.

Ordem padrão e o campo __name__

Além de classificar os documentos pelos modos de índice especificados para cada campo (crescente ou decrescente), os índices aplicam uma classificação final pelo campo __name__ de cada documento. O valor do campo __name__ é definido como o caminho completo do documento. Isso significa que os documentos no conjunto de resultados com os mesmos valores de campo são classificados por caminho.

Por padrão, o campo __name__ é classificado na mesma direção do último campo classificado na definição do índice. Exemplo:

Para classificar os resultados pela direção __name__ não padrão, crie esse índice.

Exemplo de indexação

Ao criar índices de campo único automaticamente para você, o Cloud Firestore permite que seu aplicativo dê suporte rapidamente às consultas mais básicas no banco de dados. Com os índices de campo único, é possível realizar consultas simples com base nos valores de campo e nos comparadores <, <=, ==, >=, > e in. Quando se trata de campos de matriz, eles permitem que você realize as consultas array-contains e array-contains-any.

Para entender melhor, examine os exemplos a seguir do ponto de vista da criação do índice. O snippet a seguir cria alguns documentoscity em uma coleção cities e define name, state, country, capital, population e tags campos para cada documento:

var citiesRef = db.collection("cities");

citiesRef.doc("SF").set({
    name: "San Francisco", state: "CA", country: "USA",
    capital: false, population: 860000,
    regions: ["west_coast", "norcal"] });
citiesRef.doc("LA").set({
    name: "Los Angeles", state: "CA", country: "USA",
    capital: false, population: 3900000,
    regions: ["west_coast", "socal"] });
citiesRef.doc("DC").set({
    name: "Washington, D.C.", state: null, country: "USA",
    capital: true, population: 680000,
    regions: ["east_coast"] });
citiesRef.doc("TOK").set({
    name: "Tokyo", state: null, country: "Japan",
    capital: true, population: 9000000,
    regions: ["kanto", "honshu"] });
citiesRef.doc("BJ").set({
    name: "Beijing", state: null, country: "China",
    capital: true, population: 21500000,
    regions: ["jingjinji", "hebei"] });
test.firestore.js

Considerando as configurações de indexação automática padrão, o Cloud Firestore atualiza um índice de campo único crescente por campo que não seja de matriz, um índice de campo único decrescente por campo que não seja de matriz e um índice de campo único "array-contains" para o campo de matriz. Cada linha na tabela a seguir representa uma entrada em um índice de campo único:

Consultas compatíveis com índices de campo único

Ao usar esses índices de campo único criados automaticamente, é possível executar consultas simples como as seguintes:

const stateQuery = citiesRef.where("state", "==", "CA");
const populationQuery = citiesRef.where("population", "<", 100000);
const nameQuery = citiesRef.where("name", ">=", "San Francisco");
test.firestore.js

Também é possível criar consultas in e de igualdade composta (==):

citiesRef.where('country', 'in', ["USA", "Japan", "China"])

// Compound equality queries
citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("country", "==", "USA")
         .where("capital", "==", false)
         .where("state", "==", "CA")
         .where("population", "==", 860000)

Se você precisar executar uma consulta composta que usa uma comparação de intervalo (<, <=, > ou >=) ou classificar por um campo diferente, crie um índice composto para essa consulta.

O índice array-contains permite consultar o campo de matriz regions:

citiesRef.where("regions", "array-contains", "west_coast")
// array-contains-any and array-contains use the same indexes
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])

Consultas compatíveis com índices compostos

O Cloud Firestore usa índices compostos para oferecer suporte a consultas compostas que ainda não aceitam índices de campo único. Por exemplo, você precisaria de um índice composto para as seguintes consultas:

citiesRef.where("country", "==", "USA").orderBy("population", "asc")
citiesRef.where("country", "==", "USA").where("population", "<", 3800000)
citiesRef.where("country", "==", "USA").where("population", ">", 690000)
// in and == clauses use the same index
citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)

Essas consultas exigem o índice composto abaixo. Como a consulta usa uma igualdade (== ou in) para o campo country, é possível usar um modo de índice crescente ou decrescente para esse campo. Por padrão, as cláusulas de desigualdade usam uma ordem de classificação crescente com base no campo na cláusula de desigualdade.

Para executar as mesmas consultas, mas com uma ordem de classificação decrescente, você precisa de um índice composto adicional na direção decrescente para population:

citiesRef.where("country", "==", "USA").orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", "<", 3800000)
         .orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", ">", 690000)
         .orderBy("population", "desc")

citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)
         .orderBy("population", "desc")

Também será necessário criar um índice composto para combinar uma consulta array-contains ou array-contains-any com outras cláusulas.

citiesRef.where("regions", "array-contains", "east_coast")
         .where("capital", "==", true)

// array-contains-any and array-contains use the same index
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])
         .where("capital", "==", true)

Consultas compatíveis com índices de grupo de coleções

Para demonstrar um índice com escopo de grupo de coleções, adicione uma subcoleção landmarks a alguns dos documentos city:

var citiesRef = db.collection("cities");

citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Bridge",
    category : "bridge" });
citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Park",
    category : "park" });

citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Gallery of Art",
    category : "museum" });
citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Mall",
    category : "park" });

Ao usar o seguinte índice de campo único com escopo de coleção, é possível consultar uma coleção de landmarks de uma única cidade com base no campo category:

citiesRef.doc("SF").collection("landmarks").where("category", "==", "park")
citiesRef.doc("SF").collection("landmarks").where("category", "in", ["park", "museum"])

Agora, suponha que você tem interesse em consultar os pontos turísticos de todas as cidades. Para realizar essa consulta no grupo de coleções que consiste em todas as coleções de landmarks, você precisa ativar um índice de campo único landmarks com escopo do grupo de coleções:

Com esse índice ativado, é possível consultar o grupo de coleçõeslandmarks:

var landmarksGroupRef = db.collectionGroup("landmarks");

landmarksGroupRef.where("category", "==", "park")
landmarksGroupRef.where("category", "in", ["park", "museum"])

Para executar uma consulta de grupo de coleções que retorne resultados filtrados ou ordenados, você precisa ativar um índice correspondente composto ou de campo único com o escopo do grupo de coleções. No entanto, as consultas de grupo de coleções que não filtram ou ordenam os resultados não exigem definições de índice adicionais.

Por exemplo, é possível executar a seguinte consulta de grupo de coleções sem ativar um índice adicional:

db.collectionGroup("landmarks").get()

Entradas de índice

Os índices configurados do projeto e a estrutura de um documento determinam o número de entradas de índice de um documento. As entradas do índice são contabilizadas no limite de contagem de entradas do índice.

O exemplo a seguir demonstra as entradas de índice de um documento.

Documentos

/cities/SF

city_name : "San Francisco"
temperatures : {summer: 67, winter: 55}
neighborhoods : ["Mission", "Downtown", "Marina"]

Índices de campo único

• city_name ASC
• city_name DESC
• temperatures.summer ASC
• temperatures.summer DESC
• temperatures.winter ASC
• temperatures.winter DESC
• neighborhoods Array Contains (ASC e DESC)

Índices compostos

• city_name ASC, neighborhoods ARRAY
• city_name DESC, neighborhoods ARRAY

Entradas de índice

Essa configuração de indexação resulta nas 18 entradas de índice a seguir para o documento:

Índices e preços

Os índices são contabilizados nos custos de armazenamento do seu aplicativo. Para saber mais sobre como é calculado o tamanho do armazenamento para índices, consulte o tamanho da entrada de índices.

Como usar a mesclagem de índices

Embora o Cloud Firestore use um índice para cada consulta, ele não exige necessariamente um índice por consulta. Para consultas com múltiplas cláusulas de igualdade (==) e, opcionalmente, uma cláusula orderBy, o Cloud Firestore pode reutilizar índices existentes. O Cloud Firestore pode mesclar os índices de filtros de igualdade simples para criar os índices compostos necessários a consultas de igualdade maiores.

É possível reduzir os custos de indexação ao identificar situações em que é possível aproveitar a mesclagem de índices. Por exemplo, imagine um conjunto restaurants para um app de classificação de restaurantes:

• collections_bookmark restaurants

  • class burgerthyme

    name : "Burger Thyme"
category : "burgers"
city : "San Francisco"
editors_pick : true
star_rating : 4
    

Agora imagine que esse app use consultas como as mostradas abaixo. Observe que ele usa combinações de cláusulas de igualdade para category, city e editors_pick enquanto sempre classifica por crescente star_rating:

db.collection("restaurants").where("category", "==", "burgers")
                            .orderBy("star_rating")

db.collection("restaurants").where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==" "San Francisco")
                            .where("editors_pick", "==", true )
                            .orderBy("star_rating")

Você poderia criar um índice para cada consulta:

Uma solução melhor seria reduzir o número de índices aproveitando o recurso de mesclagem de cláusulas de igualdade do Cloud Firestore:

Esse conjunto de índices é menor e também aceita uma consulta adicional:

db.collection("restaurants").where("editors_pick", "==", true)
                            .orderBy("star_rating")

Limites de indexação

Os limites a seguir são aplicáveis aos índices. Para mais informações sobre cotas e limites, consulte Cotas e limites.

Práticas recomendadas de indexação

Para a maioria dos aplicativos, você pode confiar na indexação automática e nos links de mensagens de erro para gerenciar seus índices. No entanto, você pode querer adicionar isenções de campo único nos seguintes casos:

Consulte a página de solução de problemas para mais informações sobre como resolver problemas de indexação (fanout de índice, erros INVALID_ARGUMENT).