Se já mexeu na configuração do Odoo, provavelmente já viu expressões de domínio por toda a interface — aqueles filtros entre colchetes que aparecem em regras automatizadas, ações de servidor, templates de email e botões. Menos óbvio é que o Odoo também dispõe de um tipo de campo próprio no ORM — o fields.Domain — pensado para armazenar essas expressões de forma estruturada, com validação e um editor visual integrado.
Compreender o campo Domain é útil tanto para quem desenvolve módulos personalizados como para quem configura fluxos automatizados sem código. Este guia explica desde o que exatamente o campo guarda até exemplos práticos, dicas de desenvolvimento e armadilhas a evitar.
O que é o campo Domain no Odoo
No Odoo, um domínio é uma lista de condições de filtro usada para selecionar registos. Tem uma sintaxe específica (tuplos e operadores lógicos) e, quando o Odoo executa a pesquisa, o domínio traduz-se numa cláusula WHERE do SQL.
Um exemplo típico de domínio seria:
[('customer_rank', '>', 0), ('active', '=', True)]Em linguagem simples: traga todos os registos cujo customer_rank seja maior que 0 E que estejam ativos (active = True).
O campo Domain (fields.Domain) é um tipo de campo do ORM criado para guardar essas expressões dentro de um registo. Ao contrário de um Char normal, ele faz validação e oferece um widget que permite construir filtros visualmente, sem escrever código.
Como se apresenta na interface
No ecrã, o campo Domain usa por defeito o editor de domínios: um construtor visual onde se escolhe o campo, o operador (igual, contém, maior que, etc.) e o valor. É o mesmo interface que aparece quando configura regras de acesso ou critérios em ações automatizadas.
No banco de dados, o valor do domínio é gravado como texto — a representação em string de uma lista Python. O tipo de campo trata da serialização e validação, de forma que o código Python trabalha com valores consistentes enquanto o armazenamento fica responsável pelo resto.
Isto encaixa no desenho mais amplo do modelo de dados do Odoo: um campo não é só armazenamento; define também comportamento na UI, significado semântico e regras de validação.
Como funciona o campo
Integração com o ORM e execução
Quando guarda e avalia um domínio, há várias transformações e verificações que acontecem por trás das cortinas do Odoo.
Armazenamento e avaliação dinâmica
O Odoo guarda o domínio como string e avalia esse texto em tempo de execução, o que permite usar variáveis especiais como uid para resolver o ID do utilizador atual. A avaliação usa safe_eval, que processa um subconjunto controlado de expressões Python e integra variáveis/contexto do Odoo.
O widget do domínio
O widget de domínio é o componente visual que oferece o construtor de filtros visto por utilizadores: adicionar condições, combinar com AND/OR e testar critérios sem tocar em código.
É esse widget que torna os domínios verdadeiramente acessíveis ao utilizador final — não é preciso conhecer a sintaxe para criar filtros funcionais.
Contexto do modelo
Um campo Domain pode estar ligado a um campo que contém o nome do modelo alvo (model_field). Isso diz ao widget quais campos oferecer no construtor. Sem esse contexto, o widget cai para um input de texto simples, que é muito menos amigável.
Esta ligação entre definição de campo e comportamento da UI é parte da arquitetura do Odoo: o campo «sabe» que modelo filtrar, e a interface adapta-se automaticamente.
Interacção com outros registos
Campos Domain são frequentemente usados com campos relacionais para controlar opções num Many2one, definir alvos de ações automatizadas ou limitar o âmbito de relatórios. Como o filtro é aplicado ao nível do ORM, respeita regras de segurança e permissões de campos.
Casos de utilização empresarial
Exemplos práticos no dia a dia do negócio
1. Ações automatizadas e disparo de emails
Ao configurar uma ação automatizada, define-se um domínio para especificar quais registos disparam a ação. Por exemplo, um email para facturas vencidas pode visar apenas facturas publicadas, não pagas e com data de vencimento ultrapassada — esse domínio fica armazenado no modelo base.automation e garante que a ação só corre para os registos que correspondem.
2. Regras de registo e controlo de acesso
As regras de segurança em Odoo usam domínios para limitar quais registos um grupo vê ou edita. Por exemplo, uma regra de vendas pode restringir a visibilidade aos registos atribuídos à equipa atual, avaliada em tempo de consulta — isto oferece segurança a nível de linha sem código personalizado.
3. Filtragem em inventário e operações
No armazém, domínios definem o âmbito de acções programadas e regras de reabastecimento — por exemplo, limitar uma reposição a produtos armazenáveis com stock abaixo do ponto de encomenda, evitando processamento desnecessário em milhares de SKUs.
4. Pipeline de CRM e qualificação de leads
No CRM, automações de estágio, regras de actividade e atribuição de leads usam domínios para segmentar e qualificar. Regras de atribuição baseadas em país, sector ou valor do negócio são simplesmente domínios configuráveis, o que evita alterações de código sempre que muda a lógica de negócio.
5. Listas Many2one dinâmicas
Num formulário personalizado, um domínio num campo Many2one controla que registos são mostrados na dropdown. Por exemplo, restringir fornecedores activos com ranking não nulo melhora a experiência do utilizador e reduz erros; esse domínio pode ainda depender de outros campos do formulário para ser dinâmico.
Criar ou personalizar o campo
Duas formas de trabalhar com campos Domain
Pode optar por configurações sem código com Odoo Studio ou por personalização técnica em Python/XML num módulo.
Usando Odoo Studio
O Odoo Studio não expõe diretamente um tipo fields.Domain no criador visual de campos, mas na prática raramente é necessário: os editores de domínio das ações automatizadas, regras e acções de servidor já dão acesso ao construtor visual. Para filtrar um Many2one no Studio, edite as propriedades do campo e introduza o domínio — o Studio valida a sintaxe e guarda o domínio na definição da vista.
Customização técnica em Python
Em módulos personalizados, adicionar um campo Domain segue as mesmas regras do ORM. É uma prática comum ligar o campo a outro campo que guarda o nome do modelo alvo.
from odoo import models, fields
class MyModel(models.Model):
_name = 'my.model'
model_name = fields.Char(default='res.partner')
filter_domain = fields.Domain(
string='Filter Domain',
model_field='model_name',
help='Domain expression to filter partner records'
)Aqui, model_field aponta para model_name, indicando ao widget qual o modelo cujos campos deve oferecer. Guardar o nome do modelo num campo separado também permite escolher dinamicamente o modelo quando necessário.
Expor o widget numa vista de formulário
Para que o construtor de domínios apareça no formulário, referencie ambos os campos (o que guarda o nome do modelo e o Domain) na vista XML:
<field name="model_name" invisible="1"/>
<field name="filter_domain" widget="domain"
options="{'model': 'model_name'}"/>Sem widget="domain" e sem a opção model, o campo aparece como texto simples. Inclua sempre ambos quando expõe configuração de domínios ao utilizador.
Gravar domínios via API XML-RPC
Ao definir valores de campo Domain através da API, envie sempre o domínio como string.
models.execute_kw(db, uid, api_key, 'my.model', 'write',
[[record_id], {
'filter_domain': "[('active', '=', True)]"
}]
)Enviar uma lista Python em vez de uma string é um erro comum que provoca falhas ou resultados silenciosos, conforme a versão do Odoo. Serializar para string antes de escrever evita surpresas.
Boas práticas
Há alguns hábitos práticos que ajudam a poupar tempo e evitar problemas com campos Domain.
Validar a sintaxe antes de pôr em produção
Um domínio inválido gera erros quando avaliado. Teste os domínios na barra de pesquisa do Odoo ou em modo developer antes de os guardar em regras automatizadas. Uma chamada search_count pela API confirma rapidamente se o domínio devolve o número de registos esperado.
Use variáveis dinâmicas sempre que possível
Evite codificar IDs de utilizador, empresa ou datas nos domínios. Utilize uid, context_today() e current_company_id para manter os domínios portáveis entre bases de dados e prevenir falhas silenciosas quando os valores mudam.
Vincule sempre o contexto do modelo
Quando adicionar um campo Domain a um modelo personalizado, defina model_field e inclua-o na vista. Sem isso, os utilizadores verão um campo de texto simples em vez do construtor visual, aumentando a probabilidade de guardar valores inválidos.
Mantenha os domínios legíveis
Domínios muito complexos com operadores | (OR) e & (AND) tornam-se difíceis de manter. Comente a intenção no código e, se necessário, considere usar uma ação de servidor ou um campo computado para lógica complexa — normalmente fica mais claro e testável.
Use safe_eval para avaliação programática
Ao avaliar domínios em código Python (ex.: numa acção de servidor), utilize safe_eval em vez de eval nativo: é mais seguro, lida com variáveis do Odoo e reflecte o comportamento interno da plataforma.
Teste com dados realistas
Verifique sempre que o domínio devolve os registos pretendidos antes de o pôr em produção — especialmente em ações automatizadas e regras de acesso, onde um filtro incorrecto pode processar registos errados ou negar acesso sem alerta.
Erros comuns
Erros frequentes e como os evitar
Confundir o tipo de campo com a sintaxe do domínio
Em Odoo, «domain» pode referir-se tanto à sintaxe do filtro como ao tipo de campo fields.Domain. O campo é só o recipiente; a expressão é a lógica do filtro. Novatos misturam frequentemente os dois conceitos; mantenha a distinção clara na sua documentação e código.
Enviar uma lista em vez de string pela API
Ao escrever num campo Domain via XML-RPC, passe sempre uma string. Enviar o objeto lista causa erros ou comportamentos silenciosos em várias versões do Odoo.
Esquecer o contexto do modelo no widget
Se o widget não souber qual o modelo a usar, apresenta um input de texto em vez do construtor visual. Garanta que a opção model_field está configurada na definição do campo e na vista.
Hardcoding de IDs de registo
Domínios que usam IDs fixos deixam de funcionar quando os registos são apagados ou quando move a configuração para outra base de dados. Prefira referências dinâmicas (uid, looks-ups relacionais) para manter a portabilidade.
Regras de registo demasiado abertas ou restritivas
Um domínio de regra de registo demasiado permissivo expõe dados indevidos; um demasiado restritivo pode esconder registos sem aviso. Teste as regras do ponto de vista do utilizador alvo, não do administrador.
Ignorar registos arquivados
Por defeito, Odoo exclui registos com active = False das pesquisas. Se precisa de incluir arquivados, acrescente ('active', 'in', [True, False]) ao domínio para evitar lacunas inesperadas.
Conclusão
Os campos Domain são um elemento fundamental e discreto que faz grande parte do trabalho pesado no Odoo. Desde controlo de acesso e automações até dropdowns dinâmicas e filtros de painéis, os domínios são a espinha dorsal da filtragem de registos, e fields.Domain oferece uma forma validada de guardar e expor essa lógica no modelo de dados.
Para utilizadores de negócio, o editor visual torna a configuração de filtros acessível sem código. Para desenvolvedores, o tipo Domain traz clareza a definições que antes usavam Char com overrides de widget. Seja em Odoo Studio, num módulo Python personalizado ou ao configurar automações, dominar os campos Domain abre muitas possibilidades.
Os conceitos deste guia aplicam-se a várias versões e módulos do Odoo. Investir tempo a entender campos Domain compensa, porque estão por toda a plataforma.
Precisa de ajuda com a sua implementação Odoo?
A Dasolo acompanha empresas na implementação, personalização e optimização do Odoo conforme necessidades específicas. Quer esteja a montar automações, a desenvolver módulos ou a tirar mais partido do seu sistema atual, a nossa equipa técnica pode ajudar a avançar com segurança.
Se tiver dúvidas sobre campos Domain ou qualquer outro aspecto do seu Odoo, entre em contacto connosco. Ficamos disponíveis para analisar a sua configuração e sugerir o melhor caminho a seguir.