Introducción
Si alguna vez has revisado definiciones de campos en Odoo, habrás visto a menudo algo como index=True en la declaración de un campo. Parece un detalle menor, casi cosmético, pero ese pequeño ajuste puede transformar por completo la velocidad de búsqueda y filtrado cuando la base de datos crece.
Esta guía explica qué significa realmente que un campo esté indexado dentro del modelo de datos de Odoo, qué ocurre en la base de datos y en qué situaciones merece la pena activarlo. Tanto si desarrollas módulos a medida como si revisas una implementación existente, comprender este aspecto te ayudará a tomar decisiones de rendimiento más acertadas.
¿Qué es un campo indexado en Odoo?
En el ORM de Odoo, marcar un campo como indexado se hace añadiendo index=True en su definición. Eso instruye a Odoo para que, al instalar o actualizar el módulo, solicite a PostgreSQL la creación de un índice sobre la columna correspondiente.
Ejemplo sencillo en una definición de campo (concepto)
class SaleOrder(models.Model):
_name = 'sale.order'
reference = fields.Char(string='Reference', index=True)
state = fields.Selection([...], index=True)
partner_id = fields.Many2one('res.partner', index=True)Desde el punto de vista del usuario no hay ningún cambio visible: rellenar un formulario o listar registros no revela si un campo está indexado. El índice es una optimización que sólo existe en la capa de la base de datos.
El impacto real es en el rendimiento. Un índice permite a PostgreSQL localizar registros coincidentes con mucha más rapidez en tablas grandes. Sin índice, el motor debe examinar fila a fila (sequential scan); con índice, accede a una estructura ordenada que conduce directamente a los resultados deseados.
Tipos de campo de Odoo que aceptan index=True
La mayoría de los tipos escalares del ORM soportan el atributo index:
- Char y Text
- Integer y Float
- Date y Datetime
- Selection
- Many2one (muy habitual índice)
- Boolean
Campos relacionales como One2many o Many2many no corresponden a una sola columna en la tabla y por tanto no se indexan con index=True. Tampoco se pueden indexar los campos computados no almacenados porque no generan una columna física en la base de datos.
Cómo funciona el índice
Cuando Odoo inicializa o actualiza un módulo, sincroniza el esquema leyendo las definiciones de campos. Para cada campo con index=True, Odoo ejecuta la instrucción SQL necesaria para crear el índice en PostgreSQL.
Por defecto PostgreSQL crea un índice B-tree, el tipo estándar que funciona bien para comparaciones de igualdad (=), búsquedas por rangos (>, <, BETWEEN) y ordenación. Eso cubre la mayoría de filtros y dominios que Odoo genera.
Interacción con el ORM de Odoo
El ORM convierte los filtros de dominios de Python en consultas SQL. Un dominio como [('state', '=', 'sale')] se traduce en un WHERE state = 'sale'. Si state tiene índice, PostgreSQL puede resolver esa condición sin escanear toda la tabla.
Los campos Many2one son un caso práctico muy habitual. Un campo como partner_id almacena el ID entero del socio relacionado; al filtrar pedidos por cliente Odoo ejecuta WHERE partner_id = X. Con un índice en partner_id la búsqueda sigue siendo rápida aunque la tabla tenga cientos de miles de pedidos.
Índices y coste en operaciones de escritura
Los índices no son gratis: al crear, actualizar o borrar registros, PostgreSQL debe actualizar también todos los índices asociados a la tabla. En tablas con muchos índices las operaciones de escritura se ralentizan un poco. En la mayoría de casos de uso de Odoo ese coste compensa, pero indexarlo todo rara vez es la mejor estrategia.
La opción index='trigram'
A partir de Odoo 16 el atributo index puede aceptar la cadena 'trigram'. Esto crea un índice GIN basado en trigrams usando la extensión pg_trgm, optimizado para búsquedas por patrón con ILIKE, útil cuando los usuarios buscan por fragmentos de texto en nombres o referencias.
name = fields.Char(string='Product Name', index='trigram')Es una opción avanzada que Odoo emplea en módulos estándar para campos que se buscan frecuentemente por texto parcial.
Casos prácticos en la empresa
A continuación, ejemplos reales donde indexar un campo mejora notablemente la experiencia.
1. CRM: filtrar oportunidades por responsable
En CRM los gestores filtran constantemente el embudo por responsable. El campo user_id en crm.lead viene indexado por defecto para que filtrar miles de oportunidades siga siendo ágil. Si añades un Many2one personalizado hacia usuarios o equipos, el mismo razonamiento aplica.
2. Ventas: buscar pedidos por estado
El state en sale.order está indexado para facilitar cargados y filtros rápidos (pedidos confirmados, pendientes de envío, etc.), algo crucial en empresas con alto volumen de pedidos.
3. Inventario: consultar movimientos por producto
En logística los movimientos de stock pueden ser masivos. El product_id en stock.move suele estar indexado para que los informes de trazabilidad y las consultas por producto sean eficientes en almacenes concurridos.
4. Contabilidad: localizar asientos por partner
Los contables suelen abrir el libro mayor por cliente o proveedor. Indexar partner_id en líneas contables mantiene ágiles las consultas incluso con años de historial y evita que informes como antigüedad de cobros fallen por tiempo de ejecución.
5. Módulos a medida: referencias para trazabilidad
Al crear módulos personalizados es habitual añadir campos de referencia (códigos de proyecto, números externos). Si los usuarios filtran por esos campos con regularidad, activar index=True ayuda a mantener la respuesta rápida a medida que crece la base de datos.
Crear o personalizar un campo indexado
En Python (desarrollo de módulos)
Agregar index=True en un módulo Python es directo: se añade como argumento al declarar el campo.
from odoo import models, fields
class ProjectTask(models.Model):
_inherit = 'project.task'
x_external_ref = fields.Char(
string='External Reference',
index=True,
help='Reference number from the external system'
)Tras modificar el módulo, actualízalo con odoo-bin -u your_module_name o mediante el interfaz de Apps. Odoo detectará el nuevo campo y creará el índice en la base de datos.
También puedes indexar un campo existente heredándolo y sobrescribiendo la definición, aunque hay que hacerlo con cuidado para no alterar comportamientos previos del campo original.
En Odoo Studio
Odoo Studio permite crear campos sin código, pero hoy por hoy no ofrece la opción de activar o desactivar el indexado desde la interfaz. Los campos creados con Studio no llevan index=True por defecto.
Si un campo creado en Studio necesita índice por motivos de rendimiento, la solución más ordenada es convertir esa personalización en un módulo Python y añadir index=True, tarea que normalmente realiza un desarrollador.
Crear un índice directamente en PostgreSQL
En entornos productivos a veces el DBA crea índices manualmente para optimizar sin desplegar un módulo:
CREATE INDEX CONCURRENTLY idx_sale_order_partner_id
ON sale_order (partner_id);La opción CONCURRENTLY evita bloquear la tabla durante la creación, lo cual es crucial en producción. No obstante, hay que coordinarlo con la definición del módulo para mantener coherencia entre código y estructura de la base de datos, porque una futura actualización del módulo podría no reflejar ese índice.
Buenas prácticas
Indexar campos que aparecen en dominios de búsqueda
Si un campo se usa frecuentemente en filtros —filtros de vista lista, acciones automatizadas, jobs programados o dependencias de campos calculados— es candidato a indexado. Los ejemplos más comunes son Many2one, campos de estado y referencias o códigos.
Seguir las convenciones de Odoo
La referencia más fiable es el propio código de Odoo: revisa cómo están definidos los campos en módulos estándar como sale.order, account.move o stock.move. Las decisiones de los desarrolladores de Odoo se basan en patrones de uso y datos de rendimiento reales.
Indexar siempre Many2one en modelos de alto volumen
En modelos que acumulan muchos registros (asientos contables, movimientos de stock, líneas de pedido) conviene indexar los Many2one que se usan para filtrar: el coste extra en escrituras suele compensar con creces la mejora en lecturas.
Valorar trigram para búsquedas de texto
En Odoo 16+ considera index='trigram' en campos Char que se buscan por fragmentos (nombre de producto, socio, referencias). Los índices por trigram están diseñados para acelerar las búsquedas ILIKE con coincidencias parciales.
Comprobar que los índices se usan realmente
Tras crear un índice conviene verificar su uso con un EXPLAIN ANALYZE. Si el planificador elige un sequential scan, puede deberse a que la tabla es todavía pequeña o a que la consulta no aprovecha el tipo de índice.
Documentar por qué se añadió un índice
Al desarrollar módulos, deja un comentario breve justificando cada índice. Eso ayuda a futuros mantenedores a entender la intención y evita que índices necesarios se eliminen accidentalmente en refactors.
Errores comunes
No indexar todo por defecto
Un error habitual es poner index=True en todos los campos “por si acaso”. Cada índice ocupa espacio y añade coste a las escrituras; en tablas con muchas inserciones o actualizaciones, índices innecesarios pueden ralentizar el sistema.
Indexar tablas pequeñas
En tablas con pocas filas PostgreSQL suele preferir un sequential scan; los índices empiezan a rendir cuando las tablas alcanzan miles de registros. Añadir índices en tablas de consulta fija o poco pobladas aporta más complejidad que beneficio.
Olvidar actualizar el módulo tras añadir index=True
Agregar index=True en el código no crea el índice automáticamente hasta que se actualiza el módulo con -u module_name o desde el backend. Olvidar este paso es una fuente común de confusión durante el desarrollo.
Esperar que un B-tree acelere búsquedas ILIKE con comodines al principio
Un índice B-tree no sirve para consultas ILIKE '%palabra%' con comodín inicial; PostgreSQL no puede usarlo en ese caso. Si necesitas búsquedas parciales rápidas, usa index='trigram' en Odoo 16+ o considera búsquedas full‑text.
No valorar campos computados almacenados
Los campos computados con store=True sí generan columna física y pueden indexarse. A veces se pasa por alto esta opción y se pierde la oportunidad de optimizar filtros frecuentes que usan valores derivados.
Conclusión
Aunque index=True parece un detalle menor en la definición de un campo, su efecto en el rendimiento a medida que crece la base de datos es real. Bien empleado mantiene búsquedas y vistas rápidas; mal empleado añade carga sin ventaja.
La recomendación esencial: indexa los campos que se usan habitualmente en dominios, especialmente Many2one en modelos de alto volumen. Sigue las decisiones de los módulos estándar de Odoo. Evita sobreindexar tablas pequeñas o campos que nunca se filtran. Y si estás en Odoo 16+, valora index='trigram' para búsquedas por texto parcial.
Es más sencillo definir una estrategia de índices al inicio del proyecto que diagnosticar consultas lentas en producción después.
¿Trabajáis en una implantación de Odoo?
En Dasolo acompañamos a empresas en la implantación, personalización y optimización de Odoo. Desde el desarrollo a medida hasta la mejora del rendimiento de una instancia existente o la planificación de un nuevo proyecto, aportamos experiencia técnica práctica en cada intervención.
Si te enfrentas a consultas lentas, personalizaciones complejas o necesitas orientación sobre buenas prácticas de desarrollo en Odoo, podemos ayudarte. Contacta con el equipo de Dasolo y cuéntanos en qué estáis trabajando.