Gerenciar índices

Nesta página, descrevemos como gerenciar seus índices. Para saber mais sobre índices, consulte Visão geral dos índices.

Antes de começar

Antes de criar um índice no Firestore com compatibilidade com o MongoDB, confirme se um dos papéis a seguir foi atribuído:

  • roles/datastore.owner
  • roles/datastore.indexAdmin
  • roles/editor
  • roles/owner

Para conceder um papel, consulte Conceder um único papel. Para mais informações sobre os papéis do Firestore e as permissões associadas, consulte Papéis predefinidos.

Se você tiver definido papéis personalizados, 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

Criar um índice

Para criar um índice, siga estas etapas:

API MongoDB

Use o método createIndex() para criar um índice. Exemplo:

  •   db.restaurants.createIndex({"cuisine" : 1})
  
  •   db.restaurants.createIndex({"cuisine" : 1}, {sparse: true})

  • A criação de índices com db.runCommand() também é compatível com no máximo um índice.

      db.runCommand({"createIndexes":"restaurant", "index": [{"key": {"cuisine":1}, {"name": "cuisine_index"}]})

Observe as seguintes limitações:

  • É possível criar apenas um índice por solicitação. db.collection.createIndexes() não é compatível.
  • Os registros de auditoria para criação de índice com a API MongoDB usam o nome do método google.firestore.admin.v1.FirestoreAdmin.CreateIndex.
  • Para opções de índice compatíveis, consulte índices e propriedades de índice.
Console doGoogle Cloud

  1. No console do Google Cloud , acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione um banco de dados na lista.
  3. No menu de navegação, clique em Índices.
  4. Clique em Criar índice.
  5. Insira um ID de coleção.
  6. Adicione um ou mais caminhos de campo e selecione uma opção de índice para cada um.
  7. Selecione uma opção de presença de campo, esparsa ou não esparsa.
  8. Se quiser, defina as opções índice de várias chaves ou índice exclusivo.
  9. Clique em Criar.
  10. O novo índice é exibido na lista, e o Firestore com compatibilidade com o MongoDB começa a criá-lo. Quando o processo de criação terminar, você verá uma marca de seleção verde próxima ao índice. Se o índice não for criado, consulte Erros na criação do índice para descobrir as possíveis causas.
CLI da gcloud

Para criar um índice, use o comando gcloud firestore indexes composite create. Defina api-scope como mongodb-compatible-api. 

gcloud firestore indexes composite create \
--database='DATABASE_ID' \
--collection-group=COLLECTION \
--field-config=FIELD_CONFIGURATION \
--query-scope=collection-group \
--density=dense \
--api-scope=mongodb-compatible-api

Substitua:

  • DATABASE_ID: um ID do banco de dados.
  • COLLECTION: um nome de coleção.
  • FIELD_CONFIGURATION: uma configuração de campo. Para cada campo, adicione --field-config=field-path=. Exemplo: 
        --field-config=field-path=user-id,order=descending \
    --field-config=field-path=score,order=descending

    Para mais informações sobre como configurar esses campos, consulte --field-config.

Para criar um índice esparso, defina --density=sparse-any.

Para criar um índice de várias chaves, adicione a sinalização --multikey.

Para criar um índice de várias chaves, adicione a sinalização --unique.

Terraform

Use o recurso google_firestore_index e defina api_scope como MONGODB_COMPATIBLE_API e query_scope como COLLECTION_GROUP. 

resource "google_firestore_index" "index" {
  database    = "DATABASE_ID"
  collection  = "COLLECTION"
  api_scope   = "MONGODB_COMPATIBLE_API"
  query_scope = "COLLECTION_GROUP"

  // You can include multiple field blocks
  fields {
    field_path = "FIELD_PATH"
    order      = "ORDER"
  }

  // Optional
  multikey = true
  density  = "DENSITY"
}

Substitua:

  • DATABASE_ID: o ID do banco de dados escolhido.
  • COLLECTION: o nome da coleção a ser indexada.
  • FIELD_PATH: o nome do campo a ser indexado
  • ORDER: um de ASCENDING ou DESCENDING
  • DENSITY: um de SPARSE_ANY ou DENSE

Criar um índice de texto

Crie um índice de texto se quiser fazer uma pesquisa de texto por strings específicas em uma coleção.

Para criar um índice de texto para sua coleção, siga estas etapas:

API MongoDB

Use o método createIndex() para criar um índice de texto. No exemplo a seguir, quando um documento é gravado na coleção cities com os campos country ou food preenchidos, esses campos são indexados para fins de pesquisa.

db.cities.createIndex({"country": "text", "food": "text"})

Um campo precisa ser uma string ou uma matriz de strings para ser indexado. Os índices de matriz não são indexados para pesquisa. Como resultado, a indexação de a.1.b vai indexar something em {a: {1: {b: something}}}, mas não em {a: [one, {b: something}]}.

Também é possível criar índices com db.runCommand(). É possível ter apenas um índice de texto por grupo de coleções, mas é possível criar vários índices de diferentes tipos em um db.runCommand(). O exemplo a seguir usa db.runCommand() para criar um índice de texto:

db.runCommand({
  createIndexes: "cities",
  indexes: [
    {
      key: { "country": "text", "food": "text" },
      name: "country_text_food_text"
    }
  ]
})

Especificar um idioma padrão

Você também pode especificar um idioma padrão ou um caminho de campo no documento que vai conter o idioma padrão.

No exemplo a seguir, myLanguageField é especificado como o language_override. Quando um documento na coleção cities contém um campo chamado myLanguageField, o valor desse campo é usado para determinar o idioma da indexação do campo country para esse documento específico. Esse valor substitui o idioma padrão de french.

db.cities.createIndex({"country": "text"}, {"default_language": "french", "language_override": "myLanguageField"})
  • Você pode inserir um idioma usando o nome completo (english) ou o código ISO de duas letras (en).
  • Se o idioma padrão não for definido, o Firestore vai usar o inglês.
  • O campo de substituição de idioma precisa ser um campo de nível superior. Se não for definido, o campo de substituição de idioma vai usar o padrão language.
  • Se você definir o idioma padrão como o caractere null, o Firestore com compatibilidade com o MongoDB não usará nenhum campo como substituição de idioma.

Clique para conferir uma lista de idiomas disponíveis

Código do idioma Nome do idioma
"und" Detectar automaticamente
"af" Africâner
"ak" Acã
"sq" Albanês
"am" Amárico
"ar" Árabe
"hy" Armênio
"az" Azerbaijano
"eu" Basco
"ser" Bielorrusso
"bn" Bengali
"bs" Bósnio
"bg" Búlgaro
"meu" Birmanês
"ca" Catalão
"ceb" Cebuano
"chr" Cheroqui
"zh" Chinês
"zh-Hant" Chinese_Traditional
"hr" Croata
"cs" Tcheco
"da" Dinamarquês
"nl" Holandês
"en" Inglês
"eo" Esperanto
"et" Estoniano
"fil" Filipino
"fi" Finlandês
"fr" Francês
"gl" Galego
"ka" Georgiano
"de" Alemão
"el" Grego
"gu" Gujarati
"ht" Crioulo_haitiano
"ha" Hauçá
"haw" Havaiano
"iw" Hebraico
"oi" Hindi
"hmn" Hmong
"hu" Húngaro
"is" Islandês
"ig" Igbo
"id" Indonésio
"ga" Irlandês
"it" Italiano
"ja" Japonês
"jv" Javanês
"kn" Canarês
"kk" Cazaque
"km" Khmer
"ko" Coreano
"lo" Laosiano
"la" Latim
"lv" Letão
"lt" Lituano
"lb" Luxemburguês
"mk" Macedônio
"mg" Malgaxe
"ms" Malaio
"ml" Malaiala
"mt" Maltês
"mi" Maori
"mr" Marati
"mfe" Morisyen
"mn" Mongol
"sr-ME" Serbian_Montenegro
"ne" Nepalês
"não" Norueguês
"ny" Nianja
"ou" Oriá
"fa" Persa
"pl" Polonês
"pt-BR" Portuguese_Brazil
"pt-PT" Portuguese_Portugal
"pa" Punjabi
"ro" Romeno
"ru" Russo
"gd" Gaélico escocês
"sr" Sérvio
"st" Soto do sul
"si" Cingalês
"sk" Eslovaco
"sl" Esloveno
"então" Somali
"es" Espanhol
"su" Sudanês
"sw" Suaíli
"sv" Sueco
"tg" Tadjique
"ta" Tâmil
"te" Télugo
"th" Tailandês
"tr" Turco
"uk" Ucraniano
"ur" Urdu
"uz" Uzbeque
"vi" Vietnamita
"cy" Galês
"yi" Ídiche
"yo" Iorubá
"zu" Zulu

Dividir um índice de texto

Também é possível particionar o índice usando um campo para filtrar consultas por um valor de campo específico. Essa configuração permite executar consultas mais eficientes se você sempre precisar de um campo específico filtrado no índice que está consultando.

Para criar um índice com uma partição, configure o campo firestoreOptions da seguinte maneira:

db.runCommand({
  createIndexes: "cities",
  indexes: [
    {
      key: { "country": "text", "food": "text"},
      name: "country_text_food_text"
      firestoreOptions: {"customPartitionFields": ["PARTITIONED_FIELD"]
    }
  ]
})

Em que:

  • PARTITIONED_FIELD é o nome do campo usado para a partição. Esse valor precisa ser uma string e se referir a um campo de nível superior. Ao executar uma consulta em um índice particionado, é possível filtrar os resultados com base em um valor desse campo. Por exemplo, você pode particionar seu índice usando city. Se um campo city for definido no seu índice de texto, os usuários poderão consultar uma cidade específica.

    A partição precisa ser apenas um campo. Se você particionar um índice, só poderá executar consultas em que o campo particionado é especificado.

Limitações

  • É possível criar apenas um índice por solicitação.
  • Os registros de auditoria para criação de índice com a API MongoDB usam o nome do método google.firestore.admin.v1.FirestoreAdmin.CreateIndex.
  • Para opções de índice compatíveis, consulte índices e propriedades de índice.

Console do Google Cloud

  1. No Google Cloud console, acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione um banco de dados na lista.

  3. No menu de navegação, clique em Índices.

  4. Clique em Criar índice e em Criar índice de pesquisa.

  5. (Opcional) Insira um nome para o índice.

  6. Acesse Tipo de pesquisa e selecione Texto.

  7. Insira um ID de coleção.

  8. Insira pelo menos um Caminho do campo.

  9. Opcional: especifique um idioma padrão.

    Por exemplo, defina o caminho de substituição do idioma como myLanguageField. Quando um documento na sua coleção contém um campo chamado myLanguageField, o valor desse campo é usado para determinar o idioma da indexação dos campos definidos no índice. Esse valor substitui o idioma padrão do seu índice.

  10. Clique em Criar.

  11. O novo índice é exibido na lista, e as operações compatíveis com o MongoDB começam a criá-lo. Quando o processo de criação terminar, você verá uma marca de seleção verde próxima ao índice. Se o índice não for criado, consulte Erros na criação do índice para descobrir as possíveis causas.

Criar um índice 2dsphere

Crie um índice 2dsphere para realizar consultas geoespaciais e pesquisar documentos que existam em um determinado intervalo de uma longitude e latitude específicas.

Para criar um índice 2dsphere para sua coleção, siga estas etapas:

API MongoDB

Use o método createIndex() para criar um índice. Exemplo:

db.restaurants.createIndex({"location" : "2dsphere", "region": "2dsphere"})

A criação de índices com db.runCommand() também é compatível com no máximo um índice:

db.runCommand({
  createIndexes: "restaurants",
  indexes: [
    {
      key: { "location": "2dsphere", "region": "2dsphere" },
      name: "location_2dsphere_region_2dsphere"
    }
  ]
})

Particionar um índice 2dsphere

Também é possível particionar o índice usando um campo para filtrar consultas por um valor de campo específico. Essa configuração permite executar consultas mais eficientes se você sempre precisar de um campo específico filtrado no índice que está consultando.

Para criar um índice com uma partição, configure o campo firestoreOptions da seguinte maneira:

db.runCommand({
  createIndexes: "restaurants",
  indexes: [
    {
      key: { "location": "2dsphere", "region": "2dsphere" },
      name: "location_2dsphere_region_2dsphere"
      firestoreOptions: {"customPartitionFields": ["PARTITIONED_FIELD"]
    }
  ]
})

Em que:

  • PARTITIONED_FIELD é o nome do campo usado para a partição. Ao executar uma consulta em um índice particionado, é possível filtrar os resultados com base em um valor desse campo. Por exemplo, se o índice tiver um campo region para locais regionais, você poderá particionar o índice usando region para que os usuários possam consultar restaurantes na região deles.

    Se você particionar um índice, só poderá executar consultas em que o campo particionado é especificado.

Limitações

  • É possível criar apenas um índice por solicitação.
  • Os registros de auditoria para criação de índice com a API MongoDB usam o nome do método google.firestore.admin.v1.FirestoreAdmin.CreateIndex.
  • Para opções de índice compatíveis, consulte índices e propriedades de índice.

Console do Google Cloud

  1. No Google Cloud console, acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Selecione um banco de dados na lista.

  3. No menu de navegação, clique em Índices.

  4. Clique em Criar índice e em Criar índice de pesquisa.

  5. Insira um ID de coleção.

  6. Acesse Tipo de pesquisa e selecione Geo (2dsphere).

  7. Clique em Criar.

  8. O novo índice é exibido na lista, e as operações compatíveis com o MongoDB começam a criá-lo. Quando o processo de criação terminar, você verá uma marca de seleção verde próxima ao índice. Se o índice não for criado, consulte Erros na criação do índice para descobrir as possíveis causas.

Excluir um índice

Para excluir um índice, siga estas etapas:

API MongoDB

Use o método dropIndex() para excluir um índice. Exemplo:

Excluir um índice usando o nome dele

db.restaurants.dropIndex("cuisine_index")

Excluir um índice usando a definição de índice

db.restaurants.dropIndex({"cuisine" : 1})
Console doGoogle Cloud

  1. No console do Google Cloud , acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Na lista, selecione um banco de dados.
  3. No menu de navegação, clique em Índices.
  4. Na lista de índices, escolha Excluir no botão Mais do índice que você quer excluir.
  5. Clique em Excluir índice.
CLI da gcloud

  1. Para encontrar o nome do índice, use o comando gcloud firestore indexes composite list.

    gcloud firestore indexes composite list \
--database='DATABASE_ID'

    Substitua DATABASE_ID pelo ID do banco de dados.

  2. Para excluir o índice, use o comando gcloud firestore indexes composite delete.

    gcloud firestore indexes composite delete INDEX_NAME \
--database='DATABASE_ID'

    Substitua:

    • INDEX_NAME: o nome de um índice
    • DATABASE_ID: um ID do banco de dados.

Tempo de criação do índice

Para criar um índice, o Firestore com compatibilidade com o MongoDB precisa criar o índice e, em seguida, preencher as entradas do índice com os dados atuais. O tempo necessário para criar um índice é determinado pelo seguinte:

  • O tempo de build mínimo de um índice é de alguns minutos, mesmo para um banco de dados vazio.

  • O tempo necessário para fazer o preenchimento das entradas de índice depende da quantidade de dados existentes que pertencem ao novo índice. Quanto mais valores de campo corresponderem à definição do índice, mais demorado será o preenchimento.

Gerenciar operações de longa duração

As versões de índice são operações de longa duração. As seções a seguir descrevem como trabalhar com operações de longa duração para índices.

Depois de começar a criar um índice, o Firestore com compatibilidade com o MongoDB atribui um nome exclusivo à operação. Os nomes das operações são prefixados com projects/PROJECT_ID/databases/DATABASE_ID/operations/, por exemplo:

projects/PROJECT_ID/databases/DATABASE_ID/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

É possível omitir o prefixo ao especificar um nome de operação para o comando describe.

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

Para estimar o progresso de uma operação, divida workCompleted por workEstimated.

Confira um exemplo do progresso da criação de um í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 vai 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, isso significa que a operação não foi concluída.