{"id":167176,"date":"2025-07-28T09:00:00","date_gmt":"2025-07-28T09:00:00","guid":{"rendered":"https:\/\/gtechgroup.it\/blog\/acf-query-avanzate-wp-query-meta-query\/"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-29T22:00:00","slug":"acf-query-avanzate-wp-query-meta-query","status":"publish","type":"post","link":"https:\/\/gtechgroup.it\/blog\/acf-query-avanzate-wp-query-meta-query\/","title":{"rendered":"Query Avanzate con ACF: WP_Query, Meta Query e Performance"},"content":{"rendered":"

Query sui Campi ACF: Fondamenti e Strategie<\/h2>\n

Una delle esigenze più comuni quando si lavora con Advanced Custom Fields è la necessità di interrogare il database<\/strong> per recuperare post in base ai valori dei campi personalizzati. Vuoi mostrare tutti gli eventi futuri ordinati per data? Tutti i prodotti con un prezzo inferiore a 100 euro? Tutti gli immobili in una determinata città con almeno 3 camere? Tutte queste operazioni richiedono l’uso di WP_Query<\/strong> con meta_query<\/strong>, lo strumento di WordPress per filtrare i contenuti in base ai metadati.<\/p>\n

Tuttavia, le query sui metadati presentano sfide significative in termini di performance<\/strong>, soprattutto quando il database cresce e le condizioni di filtro si moltiplicano. La tabella wp_postmeta<\/code>, dove ACF salva tutti i suoi dati, utilizza il modello EAV (Entity-Attribute-Value) che, pur essendo flessibile, non è ottimizzato per query complesse con molti filtri. In questo articolo analizzeremo come costruire query efficaci, come ottimizzarle per le performance e quali strategie adottare quando le meta query non bastano.<\/p>\n

WP_Query e Meta Query: La Sintassi Base<\/h2>\n

WordPress permette di filtrare i risultati di WP_Query<\/code> in base ai metadati attraverso il parametro meta_query<\/code>. Ecco un esempio di query che recupera tutti i post con un campo ACF “prezzo” inferiore a 100:<\/p>\n

<?php\n$args = array(\n    post_type      => prodotto,\n    posts_per_page => 20,\n    meta_query     => array(\n        array(\n            key     => prezzo,\n            value   => 100,\n            compare => <,\n            type    => NUMERIC,\n        ),\n    ),\n);\n$query = new WP_Query($args);\n\nif($query->have_posts()):\n    while($query->have_posts()): $query->the_post();\n        echo <h2> . get_the_title() . <\/h2>;\n        echo <p>Prezzo: &euro; . get_field(prezzo) . <\/p>;\n    endwhile;\n    wp_reset_postdata();\nendif;\n?><\/code><\/pre>\n
I parametri principali di ogni condizione meta_query sono: key<\/strong> (il nome del campo ACF, corrispondente al meta_key nel database), value<\/strong> (il valore da confrontare), compare<\/strong> (l’operatore di confronto) e type<\/strong> (il tipo di dato per il confronto). Gli operatori di confronto disponibili sono: =<\/code>, !=<\/code>, ><\/code>, >=<\/code>, <<\/code>, <=<\/code>, LIKE<\/code>, NOT LIKE<\/code>, IN<\/code>, NOT IN<\/code>, BETWEEN<\/code>, NOT BETWEEN<\/code>, EXISTS<\/code> e NOT EXISTS<\/code>.<\/p>\n
\"Gestione<\/p>\n
Il parametro type<\/strong> è fondamentale e spesso trascurato. I valori nella tabella wp_postmeta<\/code> sono sempre salvati come stringhe, indipendentemente dal tipo di campo ACF. Senza specificare il tipo, il confronto avviene come stringa, il che può produrre risultati errati per i numeri: ad esempio, “9” risulterebbe maggiore di “100” in un confronto stringa. Specificando type => NUMERIC<\/code> (o DECIMAL<\/code>, SIGNED<\/code>, UNSIGNED<\/code>), WordPress esegue un CAST nel database per trattare i valori come numeri.<\/p>\n
Meta Query Complesse: AND e OR<\/h2>\n
Per filtrare in base a più campi contemporaneamente, puoi combinare condizioni con la logica AND<\/strong> (tutte le condizioni devono essere vere) oppure OR<\/strong> (almeno una condizione deve essere vera). Il parametro relation<\/strong> all’interno di meta_query<\/code> controlla la logica:<\/p>\n
<?php\n\/\/ Prodotti con prezzo < 100 E in stock\n$args = array(\n    post_type  => prodotto,\n    meta_query => array(\n        relation => AND,\n        array(\n            key     => prezzo,\n            value   => 100,\n            compare => <,\n            type    => NUMERIC,\n        ),\n        array(\n            key     => in_stock,\n            value   => 1,\n            compare => =,\n        ),\n    ),\n);\n?><\/code><\/pre>\n
Puoi anche annidare gruppi di condizioni per logiche più complesse. Ad esempio: “prodotti con prezzo tra 50 e 200 E (colore rosso OPPURE colore blu)”. Questo si traduce in un meta_query con relation AND al primo livello e un sotto-gruppo con relation OR. Ogni livello di annidamento aggiunge un JOIN sulla tabella postmeta nella query SQL risultante, il che ha implicazioni significative sulle performance che analizzeremo più avanti.<\/p>\n
Ordinare per Valore del Campo ACF<\/h2>\n
Per ordinare i risultati in base al valore di un campo ACF, usa i parametri meta_key<\/code>, orderby<\/code> e order<\/code> di WP_Query:<\/p>\n
<?php\n\/\/ Eventi ordinati per data (dal più prossimo)\n$args = array(\n    post_type  => evento,\n    meta_key   => data_evento,\n    orderby    => meta_value,\n    order      => ASC,\n    meta_query => array(\n        array(\n            key     => data_evento,\n            value   => date(Ymd),\n            compare => >=,\n        ),\n    ),\n);\n?><\/code><\/pre>\n
Per l’ordinamento numerico, usa orderby => meta_value_num<\/code> invece di meta_value<\/code>. Questo è essenziale per campi che contengono numeri (prezzi, quantità, valutazioni) per evitare l’ordinamento lessicografico. Puoi anche ordinare per più campi contemporaneamente usando meta query con nome (named meta queries) e un array nel parametro orderby.<\/p>\n
<?php\n$args = array(\n    post_type  => prodotto,\n    meta_query => array(\n        prezzo_clause => array(\n            key  => prezzo,\n            type => NUMERIC,\n        ),\n        rating_clause => array(\n            key  => valutazione,\n            type => NUMERIC,\n        ),\n    ),\n    orderby => array(\n        rating_clause => DESC,\n        prezzo_clause => ASC,\n    ),\n);\n?><\/code><\/pre>\n
Query su Campi Specifici di ACF<\/h2>\n
Diversi tipi di campo ACF richiedono attenzioni particolari nelle query. I campi Date Picker<\/strong> salvano le date nel formato Ymd<\/code> (es. “20260315”), che è perfetto per i confronti cronologici con gli operatori <<\/code>, ><\/code>, BETWEEN<\/code>. Per trovare eventi in un range di date specifico:<\/p>\n
array(\n    key     => data_evento,\n    value   => array(20260301, 20260331),\n    compare => BETWEEN,\n)<\/code><\/pre>\n
\"Configurazione<\/p>\n
I campi True\/False<\/strong> salvano 1<\/code> (vero) o 0<\/code> (falso, o campo non compilato). Per trovare i post con un campo True\/False attivo: key => in_evidenza, value => 1, compare => =<\/code>. Attenzione: un campo True\/False mai salvato non ha una riga in postmeta (a differenza di un campo esplicitamente impostato su false che ha valore “0”). Se vuoi trovare i post dove il campo è false O non esiste, usa l’operatore NOT EXISTS<\/code> o una logica OR combinata.<\/p>\n
I campi Select<\/strong> e Checkbox<\/strong> salvano i valori selezionati come stringhe. Per i Select a selezione singola, il confronto è diretto: value => rosso, compare => =<\/code>. Per i Checkbox (selezione multipla), i valori sono salvati come array serializzato, il che rende le query più complesse: devi usare LIKE<\/code> con il valore racchiuso tra virgolette serializzate: value => \"rosso\", compare => LIKE<\/code>. Questo è un’area dove le meta query mostrano i loro limiti: le query LIKE su dati serializzati sono lente e non sfruttano gli indici del database.<\/p>\n
Performance delle Meta Query: Il Problema<\/h2>\n
Le meta query sono lo strumento più diretto per filtrare i post in base ai campi ACF, ma hanno un costo di performance significativo<\/strong>. La tabella wp_postmeta<\/code> utilizza il modello EAV dove ogni campo è una riga separata. Per filtrare per un singolo campo, WordPress esegue un JOIN tra wp_posts<\/code> e wp_postmeta<\/code>. Per filtrare per due campi contemporaneamente, servono due JOIN. Per tre campi, tre JOIN. E così via.<\/p>\n
Ogni JOIN aggiuntivo aumenta esponenzialmente il tempo di esecuzione della query, specialmente quando la tabella postmeta contiene milioni di righe (cosa comune in siti con migliaia di post e decine di campi ACF per post). Una query con 5 condizioni meta_query può richiedere secondi interi per essere eseguita su un database di medie dimensioni, rendendo impossibile un’esperienza utente fluida per pagine con filtri in tempo reale.<\/p>\n
Per visualizzare la query SQL generata e capire dove sono i colli di bottiglia, puoi abilitare il debug delle query aggiungendo define(SAVEQUERIES, true)<\/code> al file wp-config.php<\/code> (solo in ambiente di sviluppo!) e poi ispezionare $wpdb->queries<\/code>. Plugin come Query Monitor ti permettono di vedere le query SQL, il loro tempo di esecuzione e i possibili problemi di performance direttamente nella toolbar di WordPress.<\/p>\n
Strategie di Ottimizzazione<\/h2>\n
Esistono diverse strategie per migliorare le performance delle query sui campi ACF. La prima e più efficace è ridurre il numero di condizioni meta_query<\/strong>. Se puoi spostare alcuni filtri a livello di tassonomia (categorie, tag, tassonomie personalizzate), le query saranno molto più efficienti perché le tabelle delle tassonomie sono ottimizzate per il filtraggio con indici appropriati.<\/p>\n
La seconda strategia è aggiungere indici personalizzati<\/strong> alla tabella wp_postmeta<\/code>. L’indice predefinito copre meta_key<\/code>, ma un indice composto su (meta_key, meta_value)<\/code> può migliorare significativamente le performance delle query con confronti di uguaglianza. Attenzione: questa modifica è a livello di database e può avere effetti collaterali sulle operazioni di scrittura.<\/p>\n
\"Strumenti<\/p>\n
La terza strategia è implementare il caching dei risultati<\/strong>. Puoi usare la Transients API di WordPress per cachare i risultati delle query più costose: set_transient(prodotti_scontati, $risultati, HOUR_IN_SECONDS)<\/code>. Il transient viene invalidato dopo il tempo specificato, e puoi anche invalidarlo manualmente quando i dati cambiano (ad esempio, nell’hook acf\/save_post<\/code>). Questa strategia è particolarmente efficace per query che vengono eseguite frequentemente ma i cui risultati cambiano raramente.<\/p>\n
Tabelle Personalizzate come Alternativa<\/h2>\n
Per siti con esigenze di performance critiche, la soluzione più radicale è abbandonare la tabella wp_postmeta<\/code> e utilizzare tabelle personalizzate<\/strong> nel database. Con questo approccio, crei una tabella dedicata (ad esempio wp_prodotti_meta<\/code>) con una colonna per ogni campo, e salvi\/leggi i dati direttamente da questa tabella. Le query diventano semplici SELECT con WHERE sulle colonne, senza JOIN, con performance ordini di grandezza superiori.<\/p>\n
ACF non supporta nativamente le tabelle personalizzate, ma puoi implementare questa soluzione con codice personalizzato utilizzando gli hook acf\/save_post<\/code> (per scrivere nella tabella personalizzata quando un post viene salvato) e acf\/pre_load_value<\/code> (per leggere dalla tabella personalizzata invece che da postmeta). In alternativa, plugin come Meta Box<\/strong> con l’addon Custom Table offrono questa funzionalità out of the box.<\/p>\n
La decisione di passare alle tabelle personalizzate deve essere ponderata attentamente. I vantaggi in performance sono significativi, ma gli svantaggi includono: complessità aggiuntiva nella gestione del database, perdita di compatibilità con plugin che si aspettano i dati in postmeta, necessità di una logica di migrazione per i dati esistenti, e maggiore difficoltà nel debugging. Per la maggior parte dei siti, le strategie di ottimizzazione meno invasive (caching, indici, tassonomie) sono sufficienti.<\/p>\n
La Funzione acf_query() e le API Avanzate<\/h2>\n
ACF non fornisce una funzione di query dedicata, ma le sue funzioni interne possono essere sfruttate per ottimizzare il recupero dei dati. La funzione get_field()<\/code> internamente utilizza il caching dell’oggetto per evitare query ripetute: se chiami get_field(prezzo, $post_id)<\/code> più volte per lo stesso post, la query al database viene eseguita solo la prima volta.<\/p>\n
Per precaricare i metadati di più post in una singola query (riducendo il problema N+1), puoi usare la funzione nativa di WordPress update_post_meta_cache($post_ids)<\/code> che carica tutti i metadati degli ID specificati in una singola query. Questo è particolarmente utile nelle pagine archivio dove mostri una lista di post con i loro campi ACF: invece di una query per campo per post, ottieni tutti i dati con una singola query aggiuntiva.<\/p>\n
Le query avanzate con ACF richiedono un equilibrio tra funzionalità e performance. Per i casi semplici, le meta query standard funzionano perfettamente. Per i casi complessi, le strategie di ottimizzazione descritte in questo articolo ti permetteranno di mantenere tempi di risposta accettabili anche con dataset di grandi dimensioni. La chiave è misurare, ottimizzare e misurare di nuovo, utilizzando strumenti come Query Monitor per identificare i colli di bottiglia reali.<\/p>\n
\n
Leggi anche gli altri articoli della serie ACF<\/h3>\n