Administra índices en Cloud Firestore

Cloud Firestore garantiza el rendimiento de las consultas, ya que usa índices en todas ellas. Crea automáticamente los índices necesarios para las consultas más básicas. A medida que usas y pruebas tu app, Cloud Firestore genera mensajes de error que te ayudan a crear los índices adicionales necesarios. En esta página, se describe cómo administrar los índices de campo único, compuestos y vectores.

Crea un índice faltante a través de un mensaje de error

Si intentas realizar una consulta compuesta con una cláusula de rango que no corresponda a un índice existente, recibirás un error. El mensaje de error incluye un vínculo directo para crear el índice que falta en Firebase console.

Usa el vínculo que se genera para ir a Firebase console, revisa la información que se propagó automáticamente y haz clic en Crear.

En caso de que se requiera un índice vectorial, el mensaje de error incluirá un comando de Google Cloud CLI para crear el índice vectorial faltante. Ejecuta el comando para crear el índice faltante.

Funciones y permisos

Antes de crear un índice en Cloud Firestore, asegúrate de tener asignado alguno de los siguientes roles:

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

Si definiste roles personalizados, asigna todos los permisos siguientes para crear índices:

  • datastore.indexes.create
  • datastore.indexes.delete
  • datastore.indexes.get
  • datastore.indexes.list
  • datastore.indexes.update

Usa Firebase console

Para crear un índice nuevo de forma manual desde Firebase console, haz lo siguiente:

Imagen de la interfaz de indexación de Firestore en Firebase console

  1. Ve a la sección Cloud Firestore de Firebase console
  2. Ve a la pestaña Índices y haz clic en Agregar índice.
  3. Ingresa el nombre de la colección y establece los campos que quieres usar para ordenar el índice.
  4. Haz clic en Crear.

Los campos de índice deben cumplir con las restricciones en las rutas de campo.

La creación de los índices puede tardar unos minutos, según el tamaño de la consulta. Después de crearlos, puedes ver tus índices y su estado en la sección Índices compuestos. Si el proceso de creación no está completo, Firebase console muestra una barra de estado de creación.

Quita índices

Para borrar un índice, haz lo siguiente:

  1. Ve a la sección Cloud Firestore de Firebase console
  2. Haz clic en la pestaña Índices.
  3. Desplaza el cursor sobre el índice que deseas borrar y selecciona Borrar en el menú contextual.
  4. Para confirmar que deseas borrarlo, haz clic en Borrar en la alerta.

Usa Firebase CLI

También puedes implementar índices con Firebase CLI. Para comenzar, ejecuta firebase init firestore en el directorio de tu proyecto. Durante la configuración, Firebase CLI genera un archivo JSON con los índices predeterminados en el formato correcto. Edita el archivo para agregar más índices y, luego, impleméntalo con el comando firebase deploy.

Para implementar solo índices y reglas de Cloud Firestore, agrega la marca --only firestore.

Si haces modificaciones en los índices con Firebase console, asegúrate de actualizar también tu archivo de índices local. Consulta la referencia de definición de índice JSON.

Usar Terraform

Crea índices en la base de datos

Las bases de datos de Cloud Firestore pueden incluir índices de campo único y compuestos. Puedes editar el archivo de configuración de Terraform para crear un índice para tu base de datos. Los índices de campo único y los compuestos usan tipos de recursos de Terraform distintos (google_firestore_index y google_firestore_field).

Índice de campo único

En el siguiente ejemplo de archivo de configuración de Terraform, se crea un índice de campo único en el campo name de la colección 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 {}
}
  • Reemplaza project-id con el ID del proyecto. Los ID de proyecto deben ser únicos.
  • Reemplaza database-id por el ID de tu base de datos.

Índice compuesto

En el siguiente ejemplo de archivo de configuración de Terraform, se crea un índice compuesto para una combinación del campo name y description de la colección 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"
  }

}
  • Reemplaza project-id con el ID del proyecto. Los ID de proyecto deben ser únicos.
  • Reemplaza database-id por el ID de tu base de datos.

Índice vectorial

En el siguiente ejemplo de archivo de configuración de Terraform, se crea un índice vectorial en el campo embedding de la colección chatrooms:

firestore.tf

resource "google_firestore_index" "vector-index" {
  project = "project-id"
  database = "database-id"
  collection = "chatrooms"

  fields {
    field_path = "__name__"
    order = "ASCENDING"
  }

  fields {
    field_path = "embedding"
    vector_config {
      dimension = 128
      flat {}
    }
  }
}
  • Reemplaza project-id con el ID del proyecto. Los ID de proyecto deben ser únicos.
  • Reemplaza database-id por el ID de tu base de datos.

Tiempo de compilación de índices

Para compilar un índice, Cloud Firestore debe configurar el índice y, luego, reabastecerlo con los datos existentes. El tiempo de compilación del índice es la suma del tiempo de configuración y el tiempo de reabastecimiento:

  • La configuración de un índice tarda unos minutos. El tiempo de compilación mínimo de un índice es de unos minutos, incluso para una base de datos vacía.

  • El tiempo de reabastecimiento depende de la cantidad de datos existentes en el índice nuevo. Cuantos más valores de campo coincidan con la definición del índice, más tiempo tardará el reabastecimiento.

Las compilaciones de índices son operaciones de larga duración.

Después de iniciar una compilación de índice, Cloud Firestore le asigna un nombre único a la operación. Los nombres de las operaciones incluyen el prefijo projects/[PROJECT_ID]/databases/(default)/operations/. Por ejemplo:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Sin embargo, puedes omitir el prefijo cuando especifiques el nombre de una operación para el comando describe.

Enumera todas las operaciones de larga duración

Para enumerar las operaciones de larga duración, usa el comando gcloud firestore operations list. Este comando enumera las operaciones en curso y las que se completaron recientemente. Las operaciones se enumeran durante algunos días luego de completarse:

gcloud firestore operations list

Verifica el estado de la operación

En lugar de enumerar todas las operaciones de larga duración, puedes enumerar los detalles de una sola operación:

gcloud firestore operations describe operation-name

Estima la hora de finalización

A medida que se ejecuta tu operación, mira el valor del campo state para conocer el estado general.

Una solicitud del estado de una operación de larga duración también muestra las métricas workEstimated y workCompleted. Estas métricas se muestran para la cantidad de documentos. workEstimated muestra la cantidad total estimada de documentos que procesará una operación. workCompleted muestra la cantidad de documentos procesados hasta el momento. Una vez que se completa la operación, workCompleted refleja la cantidad total de documentos que se procesaron, que podría ser diferente del valor de workEstimated.

Divide workCompleted entre workEstimated para obtener una estimación aproximada del progreso. Es posible que la estimación sea inexacta, ya que depende de la demora en la recopilación de estadísticas.

Por ejemplo, este es el estado de progreso de una compilación 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"
        }
       },
    },
    ...

Cuando se realiza una operación, su descripción contendrá "done": true. Consulta el valor del campo state para ver el resultado de la operación. Si el campo done no está establecido en la respuesta, su valor es false. No dependas de la existencia del valor done para las operaciones en curso.

Errores en la compilación de índices

Es posible que encuentres errores en la compilación de los índices cuando administres índices compuestos y exenciones de índices de campo único. Una operación de indexación puede fallar si Cloud Firestore encuentra un problema en los datos que se están indexando. Por lo general, esto quiere decir que alcanzaste el límite de índices. Por ejemplo, es posible que la operación haya alcanzado la cantidad máxima de entradas permitidas en un índice de un documento.

Si falla la creación de los índices, aparecerá un mensaje de error en la consola. Luego de verificar que no alcanzaste ningún límite de índices, reintenta la operación de índices.