Campo Indicizzato in Odoo: Guida Pratica per Sviluppatori e Consulenti

Introduzione

Se hai trascorso del tempo a scrivere o rivedere le definizioni dei campi di Odoo, probabilmente ti sei imbattuto in qualcosa come index=True su un campo. Sembra piccolo, quasi un pensiero secondario. Ma quell'attributo singolo può fare una differenza significativa nella velocità con cui la tua istanza Odoo risponde quando gli utenti cercano, filtrano o navigano in grandi set di dati.

Questa guida illustra cos'è effettivamente un campo indicizzato nel contesto del modello di dati di Odoo, come influisce sul tuo database e quando ha senso utilizzarlo nel tuo lavoro di sviluppo Odoo. Che tu stia costruendo un modulo personalizzato o rivedendo un'implementazione esistente, comprendere questo concetto ti aiuterà a prendere decisioni migliori.

Che cos'è un campo indicizzato in Odoo

Nell'ORM di Odoo, un campo è dichiarato indicizzato quando la sua definizione include index=True. Questo dice a Odoo di chiedere a PostgreSQL di creare un indice B-tree sulla corrispondente colonna del database quando il modulo viene installato o aggiornato.

Ecco un semplice esempio da una definizione di campo Odoo in 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)

Dal punto di vista dell'interfaccia utente, non c'è nulla di visibile riguardo ai campi indicizzati. Un utente che compila un modulo o naviga in una vista elenco non ha modo di sapere se un campo è indicizzato o meno. L'indicizzazione è interamente una questione a livello di database.

Ciò che influisce è la velocità. Quando un campo è indicizzato, PostgreSQL può cercare record corrispondenti molto più rapidamente, specialmente su tabelle con migliaia o milioni di righe. Senza un indice, il database deve esaminare ogni riga nella tabella per trovare quelle che corrispondono ai tuoi criteri di ricerca. Con un indice, naviga in una struttura ordinata e trova i risultati direttamente.

Quali tipi di campo Odoo supportano index=True

La maggior parte dei tipi di campo scalari nell'ORM Odoo supportano l'attributo index:

• Char e Text fields
• Integer e Float fields
• Date e Datetime fields
• Selection fields
• Many2one fields (molto comunemente indicizzati)
• Boolean fields

I campi relazionali come One2many e Many2many non hanno una colonna diretta da indicizzare nello stesso modo, quindi l'attributo index non è rilevante per loro. I campi calcolati che non sono memorizzati non possono essere indicizzati, poiché non hanno una colonna nel database.

Come funziona il campo

Quando Odoo inizializza o aggiorna un modulo, legge tutte le definizioni dei campi e sincronizza lo schema del database. Per ogni campo con index=True, Odoo esegue un'istruzione SQL per creare un indice su quella colonna in PostgreSQL.

Per impostazione predefinita, PostgreSQL crea un indice B-tree, che è il tipo di indice standard e funziona bene per confronti di uguaglianza (=), query di intervallo (>, <, BETWEEN) e ordinamento. Questo copre la stragrande maggioranza di ciò che Odoo fa quando filtra i record nelle viste elenco o calcola ricerche basate su dominio.

Come interagisce con l'ORM di Odoo

L'ORM di Odoo traduce i filtri di dominio Python in query SQL. Quando scrivi un dominio come [('state', '=', 'sale')], l'ORM genera qualcosa come WHERE state = 'sale'. Se il campo state ha un indice, PostgreSQL lo utilizza per risolvere quella condizione in modo efficiente senza scansionare l'intera tabella.

I campi Many2one sono un caso d'uso molto comune. Nel modello di dati di Odoo, un campo come partner_id su un ordine di vendita memorizza l'ID intero del partner correlato. Quando apri l'elenco degli ordini filtrati per cliente, Odoo esegue una query con una condizione WHERE partner_id = X. Con un indice su partner_id, quella ricerca è veloce anche con centinaia di migliaia di ordini nel database.

Indici e prestazioni di scrittura

Gli indici non sono gratuiti. Ogni volta che un record viene creato, aggiornato o eliminato, PostgreSQL deve aggiornare tutti gli indici su quella tabella. Su tabelle con molti indici, le operazioni di scrittura richiedono leggermente più tempo. Per la maggior parte dei casi d'uso di Odoo, questo compromesso vale la pena, ma è importante comprendere che indicizzare tutto non è sempre la risposta giusta.

L'opzione index='trigram'

In Odoo 16 e versioni successive, l'attributo index accetta non solo True ma anche il valore stringa 'trigram'. Questo crea un indice trigram GIN utilizzando l'estensione PostgreSQL pg_trgm, che supporta il rapido abbinamento di modelli con query ILIKE. Questo è particolarmente utile per la ricerca di testo su campi come nomi di prodotto o nomi di partner dove gli utenti digitano spesso stringhe parziali nella barra di ricerca.

name = fields.Char(string='Product Name', index='trigram')

Questa è un'opzione più avanzata utilizzata nei moduli standard di Odoo per campi che vengono frequentemente cercati per testo parziale.

Casi d'uso aziendali

I campi indicizzati compaiono in molti flussi di lavoro reali di Odoo. Ecco cinque esempi pratici in cui indicizzare un campo fa una differenza evidente.

1. CRM: Filtrare i Lead per Venditore

Nel CRM, i responsabili delle vendite filtrano regolarmente il pipeline per venditore. Il campo user_id su crm.lead è indicizzato per impostazione predefinita in Odoo, il che rende veloce il filtraggio per venditore anche con migliaia di lead. Se aggiungi un campo Many2one personalizzato che punta a un utente o a un team, indicizzarlo segue la stessa logica.

2. Vendite: Ricercare Ordini per Stato

Il campo state su sale.order è indicizzato. Questo è ciò che rende veloce il caricamento dell'elenco degli ordini confermati, o il filtraggio per ordini in attesa di consegna, per le aziende che elaborano grandi volumi. I campi di selezione che vengono frequentemente utilizzati come criteri di filtro sono buoni candidati per l'indicizzazione.

3. Inventario: Tracciare i Movimenti per Prodotto

I movimenti di magazzino in Odoo possono crescere a volumi molto elevati, specialmente nelle aziende di distribuzione o manifattura. Il campo product_id su stock.move è indicizzato, rendendo efficiente la query di tutti i movimenti per un prodotto specifico. Senza questo indice, i rapporti di tracciabilità del prodotto diventerebbero dolorosamente lenti nei magazzini affollati.

4. Contabilità: Filtrare le Scritture Contabili per Partner

I contabili aprono frequentemente il libro mastro per un cliente o fornitore specifico. Il partner_id su account.move.line è indicizzato per rendere efficienti quelle ricerche. Nelle aziende con anni di storia contabile, questo indice è ciò che impedisce al rapporto sulle fatture scadute di andare in timeout.

5. Moduli Personalizzati: Campi di Riferimento per la Tracciabilità

Quando si costruiscono moduli personalizzati, è comune aggiungere campi di riferimento che collegano record tra modelli, ad esempio un codice progetto personalizzato o un numero di documento esterno. Se gli utenti cercheranno o filtreranno regolarmente per quel campo di riferimento, aggiungere index=True è un modo semplice per mantenere veloci quelle ricerche man mano che i dati crescono.

Creare o personalizzare un campo indicizzato

In Python (Sviluppo di Moduli Personalizzati)

Aggiungere index=True a una definizione di campo in un modulo Python è semplice. È sufficiente includerlo come argomento keyword durante la dichiarazione del campo:

from odoo import models, fields

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

    x_external_ref = fields.Char(
        string='Riferimento Esterno',
        index=True,
        help='Numero di riferimento dal sistema esterno'
    )

Dopo aver aggiunto questo campo al tuo modulo, esegui odoo-bin -u your_module_name oppure aggiorna il modulo tramite il menu Apps. Odoo rileverà il nuovo campo e creerà l'indice corrispondente nel database.

Puoi anche aggiungere un indice a un campo esistente ereditandolo e sovrascrivendo la definizione, anche se questo approccio richiede attenzione per evitare effetti collaterali indesiderati sul comportamento del campo originale.

In Odoo Studio

Odoo Studio consente agli utenti non tecnici di creare campi tramite l'interfaccia. Tuttavia, Studio attualmente non espone un'opzione per attivare o disattivare l'indicizzazione durante la creazione dei campi. I campi creati tramite Studio sono memorizzati nel database come campi manuali e non hanno index=True impostato per impostazione predefinita.

Se hai bisogno che un campo creato in Studio sia indicizzato per motivi di prestazioni, il percorso più pulito è convertire la personalizzazione di Studio in un modulo Python adeguato e aggiungere index=True nel codice. Questo rientra nella personalizzazione tecnica ed è tipicamente gestito da uno sviluppatore Odoo piuttosto che da un utente di Studio.

Aggiungere un Indice Direttamente in PostgreSQL

In alcune situazioni, come quando si ottimizza un database di produzione esistente senza un aggiornamento del modulo, un amministratore di database può aggiungere un indice direttamente utilizzando SQL:

CREATE INDEX CONCURRENTLY idx_sale_order_partner_id
ON sale_order (partner_id);

Utilizzare CONCURRENTLY evita di bloccare la tabella durante la creazione dell'indice, il che è importante negli ambienti di produzione. Detto ciò, questo approccio dovrebbe essere coordinato con la definizione del modulo Odoo per mantenere il codice Python e il database sincronizzati. Se il modulo viene successivamente aggiornato, Odoo potrebbe o meno gestire l'indice a seconda di ciò che è presente nella definizione del campo.

Migliori pratiche

Campi Indice che Appaiono nei Domini di Ricerca

Se un campo viene utilizzato regolarmente nei filtri di dominio, sia nei filtri della vista elenco, nelle azioni automatizzate, nei lavori pianificati o nelle dipendenze dei campi calcolati, è un buon candidato per l'indicizzazione. Gli esempi più comuni sono i campi relazionali Many2one, i campi di stato e i campi di riferimento o codice.

Segui le Convenzioni di Odoo

Il miglior riferimento per quando utilizzare index=True è il codice sorgente di Odoo stesso. Guarda le definizioni dei campi standard in sale.order, account.move o stock.move per vedere quali campi gli sviluppatori di Odoo hanno scelto di indicizzare. Queste scelte si basano su modelli di utilizzo reali e dati sulle prestazioni provenienti da migliaia di database di produzione.

Indicizza Sempre i Campi Many2one sui Modelli ad Alto Volume

Per i modelli che accumulano un gran numero di record nel tempo (registrazioni di giornale, movimenti di magazzino, righe di ordini di vendita), indicizza sempre i campi Many2one utilizzati per il filtraggio. Il costo di un indice extra su una tabella con molte scritture è quasi sempre giustificato dal miglioramento delle prestazioni in lettura.

Considera l'Indicizzazione Trigram per i Campi di Ricerca Testuale

Su Odoo 16 e versioni successive, se gli utenti cercano frequentemente record digitando stringhe parziali in un campo Char come il nome di un prodotto, il nome di un partner o un riferimento a un documento, considera di utilizzare index='trigram' invece dell'indice B-tree predefinito. Gli indici trigram sono specificamente progettati per il pattern matching ILIKE.

Verifica che gli Indici Vengano Effettivamente Utilizzati

Dopo aver aggiunto un indice, puoi verificare che PostgreSQL lo stia utilizzando eseguendo un EXPLAIN ANALYZE sulla query. Se il pianificatore di query sceglie ancora una scansione sequenziale, la tabella potrebbe essere troppo piccola perché l'indice sia vantaggioso, oppure le condizioni della query potrebbero non essere compatibili con il tipo di indice.

Documenta le Tue Decisioni di Indicizzazione

Quando costruisci moduli personalizzati, lascia un breve commento che spieghi perché un campo è indicizzato. Questo aiuta i futuri sviluppatori e consulenti a comprendere l'intento e a evitare di rimuovere accidentalmente l'indice durante una ristrutturazione.

Errori comuni

Indicizzare Ogni Campo per Default

Un errore comune quando si impara a conoscere l'indicizzazione è aggiungere index=True a ogni campo solo per essere al sicuro. Questo è controproducente. Ogni indice occupa spazio di archiviazione e aggiunge sovraccarico a ogni operazione di scrittura. Su tabelle che ricevono un alto volume di inserimenti o aggiornamenti, indici non necessari possono rallentare notevolmente il sistema.

Indicizzazione dei campi su tabelle piccole

Su tabelle con alcune centinaia di righe, il pianificatore di query di PostgreSQL spesso decide che una scansione sequenziale è più veloce rispetto all'uso di un indice. Gli indici iniziano a fornire un reale beneficio man mano che le tabelle crescono fino a migliaia di record e oltre. Indicizzare piccole tabelle di ricerca o modelli personalizzati raramente popolati aggiunge complessità senza alcun beneficio pratico.

Dimenticare di aggiornare il modulo dopo aver aggiunto index=True

Aggiungere semplicemente index=True a una definizione di campo in Python non crea automaticamente l'indice nel database. È necessario aggiornare il modulo utilizzando -u module_name o tramite il backend di Odoo. Dimenticare questo passaggio è una fonte frequente di confusione durante lo sviluppo e può portare a problemi di prestazioni negli ambienti di staging o produzione dove l'aggiornamento è stato saltato.

Aspettarsi che gli indici accelerino le ricerche ILIKE su campi Char

Un indice B-tree regolare con index=True non aiuta con le query ILIKE '%keyword%' dove il carattere jolly è all'inizio del modello. PostgreSQL non può utilizzare un indice B-tree per valutare un jolly iniziale. Se hai bisogno di una ricerca testuale parziale veloce, utilizza index='trigram' su Odoo 16+ o esplora le opzioni di ricerca full-text.

Non considerare i campi calcolati memorizzati

I campi calcolati memorizzati (quelli con store=True) hanno effettivamente una colonna nel database e possono essere indicizzati. Gli sviluppatori a volte trascurano questo e perdono un'opportunità per migliorare le prestazioni su campi che aggregano o derivano valori utilizzati frequentemente nei filtri. Se un campo calcolato memorizzato appare nei filtri di dominio attraverso report o viste, indicizzarlo vale la pena considerarlo.

Conclusione

L'attributo index=True è un piccolo dettaglio nella definizione del campo Odoo, ma ha un reale impatto sulle prestazioni del database man mano che i tuoi dati crescono. Usato correttamente, mantiene le ricerche veloci, le viste elenco reattive e i report rapidi da generare. Usato con superficialità, aggiunge sovraccarico senza alcun beneficio.

Il punto chiave è semplice: indicizza i campi che vengono utilizzati regolarmente nei filtri di dominio, specialmente i campi Many2one su modelli ad alto volume. Segui i modelli stabiliti dai moduli standard di Odoo. Evita di sovraindicizzare tabelle piccole o campi che non vengono mai filtrati. E se sei su Odoo 16 o versioni successive, considera index='trigram' per i campi di ricerca testuale in cui gli utenti digitano stringhe parziali.

Ottenere la strategia di indicizzazione giusta fin dall'inizio di un progetto di sviluppo personalizzato è molto più facile che diagnosticare query lente in produzione successivamente.

Stai lavorando a un'implementazione di Odoo?

Da Dasolo, aiutiamo le aziende a implementare, personalizzare e ottimizzare Odoo. Che tu stia costruendo moduli personalizzati, migliorando le prestazioni di un'istanza esistente, o pianificando un nuovo progetto Odoo da zero, portiamo competenze tecniche pratiche in ogni impegno.

Se stai affrontando query lente, personalizzazioni complesse, o hai bisogno di indicazioni sulle migliori pratiche di sviluppo Odoo, siamo felici di aiutarti. Contatta il team di Dasolo e facci sapere su cosa stai lavorando.