Campo Indexado no Odoo: Guia Prático para Desenvolvedores e Consultores

Introdução

Se você passou algum tempo escrevendo ou revisando definições de campos do Odoo, provavelmente se deparou com algo como index=True em um campo. Parece pequeno, quase como um pensamento secundário. Mas esse único atributo pode fazer uma diferença significativa na rapidez com que sua instância do Odoo responde quando os usuários pesquisam, filtram ou navegam em grandes conjuntos de dados.

Este guia explica o que é um campo indexado no contexto do modelo de dados do Odoo, como ele afeta seu banco de dados e quando faz sentido usá-lo em seu próprio trabalho de desenvolvimento no Odoo. Seja você construindo um módulo personalizado ou revisando uma implementação existente, entender este conceito ajudará você a tomar melhores decisões.

O que é um Campo Indexado no Odoo

No ORM do Odoo, um campo é declarado indexado quando sua definição inclui index=True. Isso informa ao Odoo para pedir ao PostgreSQL que crie um índice B-tree na coluna correspondente do banco de dados quando o módulo é instalado ou atualizado.

Aqui está um exemplo simples de uma definição de campo do Odoo em Python:

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)

Do ponto de vista da interface do utilizador, não há nada visível sobre campos indexados. Um utilizador que preenche um formulário ou navega numa vista de lista não tem como saber se um campo está indexado ou não. A indexação é inteiramente uma preocupação a nível de base de dados.

O que afeta é a velocidade. Quando um campo está indexado, o PostgreSQL pode procurar registos correspondentes muito mais rapidamente, especialmente em tabelas com milhares ou milhões de linhas. Sem um índice, a base de dados tem que escanear cada linha da tabela para encontrar aquelas que correspondem aos seus critérios de pesquisa. Com um índice, navega numa estrutura ordenada e encontra os resultados diretamente.

Quais Tipos de Campo do Odoo Suportam index=True

A maioria dos tipos de campo escalar no ORM do Odoo suporta o index atributo:

• Char e Text campos
• Integer e Float campos
• Date e Datetime campos
• Selection campos
• Many2one campos (muito frequentemente indexados)
• Boolean campos

Campos relacionais como One2many e Many2many não têm uma coluna direta para indexar da mesma forma, portanto, o atributo index não é relevante para eles. Campos computados que não são armazenados também não podem ser indexados, uma vez que não possuem uma coluna no banco de dados.

Como o Campo Funciona

Quando o Odoo inicializa ou atualiza um módulo, ele lê todas as definições de campo e sincroniza o esquema do banco de dados. Para qualquer campo com index=True, o Odoo executa uma instrução SQL para criar um índice nessa coluna no PostgreSQL.

Por padrão, o PostgreSQL cria um índice B-tree, que é o tipo de índice padrão e funciona bem para comparações de igualdade (=), consultas de intervalo (>, <, BETWEEN) e ordenação. Isso cobre a grande maioria do que o Odoo faz ao filtrar registros em visualizações de lista ou ao computar pesquisas baseadas em domínio.

Como Interage com o ORM do Odoo

O ORM do Odoo traduz filtros de domínio em Python em consultas SQL. Quando você escreve um domínio como [('state', '=', 'sale')], o ORM gera algo como WHERE state = 'sale'. Se o campo state tiver um índice, o PostgreSQL o utiliza para resolver essa condição de forma eficiente, sem escanear toda a tabela.

Campos Many2one são um caso de uso muito comum. No modelo de dados do Odoo, um campo como partner_id em um pedido de venda armazena o ID inteiro do parceiro relacionado. Quando você abre a lista de pedidos filtrados por cliente, o Odoo executa uma consulta com uma condição WHERE partner_id = X. Com um índice em partner_id, essa busca é rápida mesmo com centenas de milhares de pedidos no banco de dados.

Índices e Desempenho de Escrita

Os índices não são gratuitos. Cada vez que um registro é criado, atualizado ou excluído, o PostgreSQL precisa atualizar todos os índices nessa tabela também. Em tabelas com muitos índices, as operações de escrita demoram um pouco mais. Para a maioria dos casos de uso do Odoo, essa troca vale a pena, mas é importante entender que indexar tudo nem sempre é a resposta certa.

A Opção index='trigram'

No Odoo 16 e versões posteriores, o atributo index aceita não apenas True, mas também o valor de string 'trigram'. Isso cria um índice GIN trigram usando a extensão pg_trgm do PostgreSQL, que suporta correspondência de padrões rápida com consultas ILIKE. Isso é particularmente útil para pesquisa de texto em campos como nomes de produtos ou nomes de parceiros, onde os usuários frequentemente digitam strings parciais na barra de pesquisa.

name = fields.Char(string='Nome do Produto', index='trigram')

Esta é uma opção mais avançada usada nos próprios módulos padrão do Odoo para campos que são frequentemente pesquisados por texto parcial.

Casos de Uso Empresarial

Os campos indexados aparecem em muitos fluxos de trabalho reais do Odoo. Aqui estão cinco exemplos práticos onde indexar um campo faz uma diferença notável.

1. CRM: Filtrando Leads por Vendedor

No CRM, os gerentes de vendas filtram regularmente o pipeline por vendedor. O campo user_id em crm.lead é indexado por padrão no Odoo, o que torna o filtragem por vendedor rápida, mesmo com milhares de leads. Se você adicionar um campo Many2one personalizado apontando para um usuário ou equipe, indexá-lo segue a mesma lógica.

2. Vendas: Pesquisando Pedidos por Status

O campo state em sale.order é indexado. Isso é o que torna o carregamento da lista de pedidos confirmados, ou o filtragem de pedidos aguardando entrega, rápido para empresas que processam grandes volumes. Campos de seleção que são frequentemente usados como critérios de filtragem são bons candidatos para indexação.

3. Inventário: Rastreando Movimentos por Produto

Os movimentos de estoque no Odoo podem crescer para volumes muito grandes, especialmente em negócios de distribuição ou fabricação. O campo product_id em stock.move é indexado, tornando eficiente consultar todos os movimentos para um produto específico. Sem esse índice, os relatórios de rastreabilidade de produtos se tornariam dolorosamente lentos em armazéns movimentados.

4. Contabilidade: Filtrando Lançamentos por Parceiro

Os contadores frequentemente abrem o livro razão para um cliente ou fornecedor específico. O partner_id em account.move.line é indexado para tornar essas consultas eficientes. Em empresas com anos de histórico contábil, esse índice é o que impede que o relatório de contas a receber atrasadas expire.

5. Módulos Personalizados: Campos de Referência para Rastreabilidade

Ao construir módulos personalizados, é comum adicionar campos de referência que vinculam registros entre modelos, por exemplo, um código de projeto personalizado ou um número de documento externo. Se os usuários pesquisarem ou filtrarem por esse campo de referência regularmente, adicionar index=True é uma maneira simples de manter essas pesquisas rápidas à medida que os dados crescem.

Criando ou Personalizando um Campo Indexado

Em Python (Desenvolvimento de Módulos Personalizados)

Adicionar index=True a uma definição de campo em um módulo Python é simples. Você simplesmente o inclui como um argumento de palavra-chave ao declarar o campo:

from odoo import models, fields

class ProjectTask(models.Model):
    _inherit = 'project.task'

    x_external_ref = fields.Char(
        string='Referência Externa',
        index=True,
        help='Número de referência do sistema externo'
    )

Após adicionar este campo ao seu módulo, execute odoo-bin -u seu_nome_do_módulo ou atualize o módulo através do menu Apps. O Odoo detectará o novo campo e criará o índice correspondente no banco de dados.

Você também pode adicionar um índice a um campo existente herdando-o e sobrescrevendo a definição, embora essa abordagem exija cuidado para evitar efeitos colaterais indesejados no comportamento do campo original.

No Odoo Studio

O Odoo Studio permite que usuários não técnicos criem campos através da interface. No entanto, o Studio atualmente não expõe uma opção para ativar ou desativar a indexação ao criar campos. Os campos criados através do Studio são armazenados no banco de dados como campos manuais e não têm index=True definido por padrão.

Se você precisar que um campo criado no Studio seja indexado por razões de desempenho, o caminho mais limpo é converter a personalização do Studio em um módulo Python adequado e adicionar index=True no código. Isso se enquadra em personalizações técnicas e é tipicamente tratado por um desenvolvedor Odoo em vez de um usuário do Studio.

Adicionando um Índice Diretamente no PostgreSQL

Em algumas situações, como ao otimizar um banco de dados de produção existente sem uma atualização de módulo, um administrador de banco de dados pode adicionar um índice diretamente usando SQL:

CREATE INDEX CONCURRENTLY idx_sale_order_partner_id
ON sale_order (partner_id);

Usar CONCURRENTLY evita o bloqueio da tabela durante a criação do índice, o que é importante em ambientes de produção. Dito isso, essa abordagem deve ser coordenada com a definição do módulo Odoo para manter o código Python e o banco de dados em sincronia. Se o módulo for atualizado posteriormente, o Odoo pode ou não gerenciar o índice dependendo do que está na definição do campo.

Melhores Práticas

Campos de Índice que Aparecem em Domínios de Pesquisa

Se um campo é regularmente utilizado em filtros de domínio, seja em filtros de visualização de lista, ações automatizadas, trabalhos agendados ou dependências de campos computados, é um bom candidato para indexação. Os exemplos mais comuns são campos relacionais Many2one, campos de estado e campos de referência ou código.

Siga as Próprias Convenções do Odoo

A melhor referência para saber quando usar index=True é o próprio código-fonte do Odoo. Veja as definições de campos padrão em sale.order, account.move ou stock.move para ver quais campos os próprios desenvolvedores do Odoo escolheram indexar. Essas escolhas são baseadas em padrões de uso reais e dados de desempenho de milhares de bancos de dados em produção.

Sempre Indexe Campos Many2one em Modelos de Alto Volume

Para modelos que acumulam um grande número de registros ao longo do tempo (lançamentos contábeis, movimentos de estoque, linhas de pedidos de venda), sempre indexe campos Many2one que são usados para filtragem. O custo de um índice extra em uma tabela com muitas gravações quase sempre vale a melhoria de desempenho de leitura.

Considere a Indexação Trigrama para Campos de Pesquisa de Texto

No Odoo 16 e versões posteriores, se os usuários frequentemente pesquisam registros digitando strings parciais em um campo Char, como nome de produto, nome de parceiro ou referência de documento, considere usar index='trigram' em vez do índice B-tree padrão. Os índices trigram são especificamente projetados para correspondência de padrões ILIKE.

Verifique se os Índices Estão Sendo Realmente Usados

Após adicionar um índice, você pode verificar se o PostgreSQL está usando-o executando um EXPLAIN ANALYZE na consulta. Se o planejador de consultas ainda estiver escolhendo uma varredura sequencial, a tabela pode ser muito pequena para que o índice seja benéfico, ou as condições da consulta podem não ser compatíveis com o tipo de índice.

Documente Suas Decisões de Indexação

Ao construir módulos personalizados, deixe um breve comentário explicando por que um campo é indexado. Isso ajuda futuros desenvolvedores e consultores a entender a intenção e evitar a remoção acidental do índice durante uma refatoração.

Armadilhas Comuns

Indexar Cada Campo por Padrão

Um erro comum ao aprender sobre indexação é adicionar index=True a cada campo apenas para garantir. Isso é contraproducente. Cada índice ocupa espaço de armazenamento e adiciona sobrecarga a cada operação de escrita. Em tabelas que recebem um alto volume de inserções ou atualizações, índices desnecessários podem desacelerar visivelmente o sistema.

Indexação de Campos em Tabelas Pequenas

Em tabelas com algumas centenas de linhas, o planejador de consultas do PostgreSQL frequentemente decide que uma varredura sequencial é mais rápida do que usar um índice. Os índices começam a fornecer benefícios reais à medida que as tabelas crescem para milhares de registros e além. Indexar pequenas tabelas de pesquisa ou modelos personalizados raramente populados adiciona complexidade sem nenhum benefício prático.

Esquecer de Atualizar o Módulo Após Adicionar index=True

Adicionar simplesmente index=True a uma definição de campo em Python não cria automaticamente o índice no banco de dados. Você precisa atualizar o módulo usando -u module_name ou através do backend do Odoo. Esquecer este passo é uma fonte frequente de confusão durante o desenvolvimento e pode levar a problemas de desempenho em ambientes de teste ou produção onde a atualização foi pulada.

Esperar que Índices Acelerem Pesquisas ILIKE em Campos Char

Um índice B-tree regular com index=True não ajuda em consultas ILIKE '%keyword%' onde o caractere curinga está no início do padrão. O PostgreSQL não pode usar um índice B-tree para avaliar um curinga inicial. Se você precisa de uma pesquisa de texto parcial rápida, use index='trigram' no Odoo 16+ ou explore opções de pesquisa de texto completo.

Não Considerar Campos Computados Armazenados

Campos computados armazenados (aqueles com store=True) têm uma coluna no banco de dados e podem ser indexados. Os desenvolvedores às vezes ignoram isso e perdem uma oportunidade de melhorar o desempenho em campos que agregam ou derivam valores usados intensamente em filtros. Se um campo computado armazenado aparece em filtros de domínio em relatórios ou visualizações, indexá-lo vale a pena considerar.

Conclusão

O atributo index=True é um pequeno detalhe na definição de campo do Odoo, mas tem um impacto real no desempenho do banco de dados à medida que seus dados crescem. Usado corretamente, mantém as pesquisas rápidas, as visualizações de lista responsivas e os relatórios rápidos de gerar. Usado descuidadamente, adiciona sobrecarga sem nenhum benefício.

A principal conclusão é simples: indexe campos que são regularmente usados em filtros de domínio, especialmente campos Many2one em modelos de alto volume. Siga os padrões estabelecidos pelos próprios módulos padrão do Odoo. Evite sobre-indexar tabelas pequenas ou campos que nunca são filtrados. E se você estiver no Odoo 16 ou posterior, considere index='trigram' para campos de pesquisa de texto onde os usuários digitam strings parciais.

Acertar a estratégia de indexação desde o início de um projeto de desenvolvimento personalizado é muito mais fácil do que diagnosticar consultas lentas em produção mais tarde.

Trabalhando em uma Implementação do Odoo?

Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo. Quer esteja a construir módulos personalizados, a melhorar o desempenho de uma instância existente ou a planear um novo projeto Odoo do zero, trazemos experiência técnica prática a cada colaboração.

Se estiver a lidar com consultas lentas, personalizações complexas ou precisar de orientação sobre as melhores práticas de desenvolvimento Odoo, teremos todo o gosto em ajudar. Entre em contacto com a equipa da Dasolo e diga-nos no que está a trabalhar.