Net-Base Rivista

08.11.2026

FireDAC: Parameter-Arrays per clausole IN – logica di espansione sicura, limiti per DB e debug della query SQL finale

IN (:ids) appare comodo, ma fallisce con liste grandi a causa dei limiti del DB e dei miti sul debugging. Questa guida pratica illustra una logica sicura di expand e chunking in FireDAC, i limiti tipici e una configurazione di tracing pulita con FDMonitor.

08.11.2026

Dal tema della rivista alla pratica di progetto

Pagine di servizi e tecniche correlate all'articolo

Video-Botschaft

FireDAC: Parameter-Arrays per clausole IN – logica di espansione sicura, limiti per DB e debug della query SQL finale

Warum IN (:ids) mit FireDAC im Betrieb an DB-Limits scheitert, wie Expand/Chunking robust hilft und wie man die finale SQL sauber traced.

Video mit KI erstellt

Transkript anzeigen

Hallo zusammen. IN (:ids) wirkt wie Komfort.

In der Praxis ist es oft ein Stolperdraht. Der Beitrag heißt: FireDAC: Parameter-Arrays für IN-Clauses – sichere Expand-Logik, Limits pro DB und Debugging der finalen SQL.

Der Fehler kommt selten im ersten Test. Er kommt nachts im Batch oder wenn jemand im Backoffice 1.400 Datensätze markiert.

Dann melden Datenbanken Grenzen wie ORA‑01795, „too many SQL variables“ oder ein Parameter-Limit. Wichtig ist die klare Trennung: Parameter sind gebundene Werte, keine Textliste.

Eine robuste Lösung expandiert sauber auf mehrere Platzhalter, arbeitet bei großen Listen mit Chunking in Blöcken und behandelt „Liste leer“ bewusst. Und fürs Debugging: nicht raten, sondern die finale SQL per Trace nachvollziehen, zum Beispiel mit FDMonitor.

Wenn Sie dazu Rückfragen haben, sprechen wir gern kurz über Ihren konkreten Fall.

L’errore raramente si manifesta al primo test. Si verifica di notte nel batch, o quando un amministratore nel backoffice seleziona “per prova” un insieme più ampio. Nel log compare qualcosa come “too many SQL variables”, ORA‑01795 o un errore di SQL Server che ha poco a che vedere con il caso d’uso effettivo. Chi a questo punto continua ad affidarsi al comodo schema WHERE id IN (:ids) si accorge in fretta: non è una funzione di comodità, ma una trappola.

Proprio di questo tratta la sostituzione di BDE con integrazione nativa: array di parametri per clausole IN non come escamotage per infilare liste arbitrarie “in un parametro”, ma come una logica robusta di espansione e suddivisione in blocchi che rispetta i limiti del DB e si lascia debuggare in modo pulito.

Il conflitto di obiettivi è reale e si ripete in quasi tutti i sistemi:

  • Massima sicurezza e manutenibilità: i valori vengono legati (no a SQL-Injection), i piani possono essere riutilizzati, la registrazione dei log resta controllabile.
  • Massima robustezza con liste di grandi dimensioni: evitare di superare limiti rigidi del DB, evitare errori del tipo “solo nel cliente X”, debug riproducibile.

Si possono conseguire entrambi gli obiettivi — ma solo separando chiaramente la meccanica: i parametri sono valori, le Macro/Substitution sono testo SQL. E: le liste lunghe richiedono meccanismi di controllo.

FireDAC: Parameter-Arrays für IN-Clauses in der Praxis

BDE-Ablosung mit nativer Anbindung distingue consapevolmente tra parametri (valori vincolati) e Macros/Substitution (frammenti di testo inseriti nel SQL prima del prepare). Il preprocessing può trasformare il testo del comando, espandere le macro e generare la struttura finale della statement – ma il binding dei valori rimane separato.[Fonte]

Sembra formalismo, ma è una questione di sicurezza e operatività: un parametro in SQL rappresenta tipicamente un valore. Se introduci una lista come testo nelle parentesi, sei molto rapidamente nella concatenazione di stringhe o nell’abuso di macro. Entrambe le pratiche trasformano una query sicura in una che devi costantemente difendere da SQL-Injection, caratteri speciali e conversioni di tipo — e che indebolisce anche il plan-caching del database.

La linea attendibile è quindi: o generi una IN-lista da più segnaposto e leghi ogni valore come parametro, oppure cambi tecnica e fornisci al database un insieme di valori come “tabella” (tabella temporanea, tipo Collection/Array, Table-Valued Parameter). FireDAC in sé non prende questa decisione architetturale per te.

Mappa di valutazione: tre strade per la lista IN – benefici, sforzo, rischi

Prima di discutere i dettagli di implementazione, conviene avere una visione chiara delle opzioni. Non si tratta di „giusto vs. sbagliato“, ma di stabilire quale rischio vuoi sostenere e dove: nel Delphi-code o nell’operatività del database.

Opzione 1: Espandere su molti parametri (IN (:p0,:p1,…))

Vantaggio: resta all’interno del binding dei parametri, funziona con FireDAC su più backend, nessun oggetto DB aggiuntivo.
Sforzo: moderato (costruzione della stringa + nomi dei parametri + binding).
Rischi/limiti: limiti rigidi (numero di parametri, espressioni IN); il numero di varianti di statement esplode se la dimensione della lista varia molto.
Plausibile per: liste di filtro fino a „alcune centinaia“, retrofit in software business esistente, multi-DB.

Opzione 2: Chunking (più blocchi IN uniti con OR, correttamente parentesizzati)

Vantaggio: rispetta i limiti, rimane multi-DB, può assorbire liste molto grandi senza funzionalità specifiche del DB.
Sforzo: maggiore (logica di parentesi, formazione dei blocchi, gestione dei parametri, test).
Rischi/limiti: clausole WHERE lunghe; catene di OR possono influenzare l’optimizer/i piani; il debugging deve fornire il contesto (dimensione dei blocchi/contatori).
Plausibile per: Oracle/SQL Server/SQLite in una base di codice condivisa, quando liste grandi compaiono sporadicamente.

Opzione 3: Passare i valori come „tabella“ (Temp-Tabelle / TVP / Collection)

Vantaggio: SQL rimane compatto, la stabilità dei piani spesso migliora, volumi molto grandi sono gestibili.
Sforzo: dipendente dal DB; operatività/deployment (schema, permessi, cleanup/transazioni) diventano parte della soluzione.
Rischi/limiti: più componenti in movimento (migrazioni, monitoring, autorizzazioni).
Plausibile per: volumi regolarmente grandi (migliaia+), elaborazione batch, quando il backend è definito e l’operatività può sostenerlo.

Limiti rigidi per database: i veri fattori che guidano la logica di espansione

I limiti sono il motivo per cui „funziona in locale“ non basta in produzione. Ciò che conta non è il tuo Delphi-code, ma ciò che il backend accetta in termini di forma dello statement e numero di parametri.

Database Limite rilevante Errore tipico Conseguenza pratica
Oracle Max. 1000 espressioni in una lista IN ORA-01795 Chunking o tecnica alternativa (join/collection) necessari non appena le liste diventano „veramente“ grandi
SQL Server Max. 2100 parametri per statement/batch Errore con troppi parametri Prevedere margine per parametri aggiuntivi; oltre la soglia valutare chunking o TVP
SQLite Max. host-parameter (di default storicamente spesso 999, dipendente da versione/build) „too many SQL variables“ Attivare il chunking precocemente; documentare il limite in produzione, poiché varia a seconda della distribuzione
PostgreSQL Il numero di parametri è limitato (per ragioni di protocollo/implementazione) Errore con quantità estreme di parametri Definire un limite superiore; per quantità molto grandi valutare una strategia basata su tabelle di valori

Per Oracle il limite dei 1000 è documentato in modo chiaro: nella condizione IN sono consentite fino a 1000 espressioni.[Fonte] Importante è la conseguenza: il limite va inteso come confine strutturale della condizione SQL, non come un “problema di literal”. AskTOM classifica ORA‑01795 come un limite netto della IN-list e indica il ramificare/concatenare come workaround tipico – in alternativa un join contro un insieme di valori.[Fonte]

SQLite è insidioso, perché non ti scontri con delle “IN-expressions”, ma con il numero delle variabili di bind. Il limite è documentato come SQLITE_MAX_VARIABLE_NUMBER e può variare significativamente a seconda di versione/build. Conseguenza: chi usa SQLite solo “ai margini” (test, tool, client offline) necessita comunque di una logica di espansione che non esploda improvvisamente a 999 parametri.[Fonte]

Sichere Expand-Logik: was sie leisten muss (und was nicht)

Se implementi Expand/Chunking, fallo non come una “bastardatura di stringhe”, ma come un piccolo componente infrastrutturale. Dovrebbe svolgere quattro compiti in modo affidabile:

  • Generare solo placeholder: i valori vengono vincolati esclusivamente tramite parametri FireDAC.
  • Gestire esplicitamente liste vuote: percorso definito, nessun errore di sintassi SQL, nessuna modifica semantica silenziosa.
  • Considerare limiti e riserva: per ogni DB un valore limite, più un buffer per ulteriori parametri nella stessa istruzione.
  • Fornire contesto di debug: numero di valori, dimensione del blocco, numero di blocchi, eventuale fingerprint – invece di “tutto in chiaro”.

Liste vuote: il caso nullo è il più frequente in produzione

La situazione di “nessun ID” si verifica continuamente: filtri di autorizzazione, filtri di ricerca, record eliminati, selezione vuota. Ed è proprio qui che molte implementazioni diventano incerte, perché cercano di salvare in qualche modo “IN ()”.

Opzioni pragmatiche e facilmente testabili:

  • Nessuna chiamata al DB: se il tuo caso d’uso deve restituire un result set, ritorna direttamente vuoto (particolarmente sensato in servizi e API).
  • Condizione always-false: se per ragioni architetturali devi comunque eseguire l’istruzione, sostituisci la porzione IN con una condizione sicuramente falsa (es. 1=0), invece di inventare un “IN (NULL)”.

Chunking: perché la „riserva“ conta più del limite documentato

Il chunking non è solo “per Oracle”. È la tua assicurazione contro due realtà tipiche: parametri aggiuntivi (tenant, stato, intervallo temporale, autorizzazioni) e dimensioni delle liste imprevedibili.

Alcune linee guida che dovrebbero emergere nelle review:

  • Mai impostare la dimensione del blocco al massimo: se SQL Server consente 2100 parametri, una dimensione di blocco di 2090 non è una buona idea, perché raramente l’istruzione è composta solo dalla lista IN.
  • I blocchi OR devono essere racchiusi tra parentesi: non appena si aggiunge un altro AND, senza parentesi la logica cambia.
  • Nomina dei parametri deterministica: Prefisso + indice (p. es. :ids_0001) rende Traces, Repros e analisi diff molto più semplici.

Esempio (costruito): Quando un job batch improvvisamente fallisce in modo „specifico per il cliente“

Debugging della SQL finale: perché il desiderio è comprensibile – ma raramente è la soluzione giusta

Molti team cercano la „SQL finale“, cioè una stringa in cui tutti i valori dei parametri sono „inseriti“. Per i parametri vincolati si tratta spesso di un’esigenza apparente: il database riceve statement e valori separati. Questo è il caso normale per un’esecuzione sicura e per il riuso del piano. Una singola, canonica „SQL di esecuzione“ quindi spesso non esiste nel senso in cui la si intende quando si parla di SQL scritto manualmente.

In FireDAC il percorso di debug corretto passa per FDMonitor. Lì vedi Prepare/Execute, il testo dello statement, i valori dei parametri (con i tipi) e la sequenza delle azioni. Questo è più vicino a ciò che accade realmente nel backend rispetto a qualsiasi ricostruzione manuale della stringa.[Fonte]

Cosa dovresti analizzare nel trace

  1. Struttura della clausola WHERE: i blocchi OR sono racchiusi tra parentesi prima che seguano altri filtri AND?
  2. Conteggio dei parametri: quanti parametri ci sono realmente – incluso mandante/stato/intervallo temporale? Questo determina i limiti di SQL Server e SQLite.
  3. Associazione dei tipi: gli ID numerici sono associati come numeri? stringhe vs numeri non è una questione cosmetica, ma può influenzare l’uso degli indici e la scelta del piano.
  4. Varianti di statement: ogni diversa quantità di placeholder è un diverso testo di statement. Con liste variabili crei più varianti di Prepare; il chunking con dimensione blocco fissa può ridurre la varianza.

Logging: SQL + contesto invece di SQL + 2.400 valori

Nei log di produzione raramente vuoi vedere ogni singolo valore. Vuoi diagnosi con dimensioni di log ragionevoli e senza esposizione inutile dei dati. Campi tipici e utili sono:

  • Numero di valori (Count)
  • Dimensione del blocco e numero di blocchi
  • Impronta della lista normalizzata (p. es. hash), per riconoscere ripetizioni senza scrivere i contenuti
  • Anteprima troncata (p. es. primi/ultimi 5 valori), se ciò è consentito dal punto di vista della protezione dei dati e della pratica operativa

Array di parametri in FireDAC: il termine che spesso induce in errore

FireDAC documenta „array di parametri“ soprattutto nel contesto di Array-DML (esecuzione in batch): molti record vengono eseguiti in una singola istruzione impostando i valori dei parametri come array. Si tratta di una caratteristica di performance per INSERT/UPDATE/DELETE – ma non risolve automaticamente il problema della „lista IN come un singolo parametro“. Sono due casi d’uso diversi, che linguisticamente suonano simili ma operativamente funzionano in modo differente.[Quelle]

Conseguenza pratica per la comunicazione nel team: se qualcuno dice „array di parametri per IN“, vale la pena chiarire con una domanda di ritorno: intendi Array-DML, oppure intendi Expand/Chunking per WHERE IN? Questa chiarezza evita che alla fine i valori finiscano di nuovo come sostituzioni testuali nell’SQL.

Checklist di revisione: insidie tipiche che poi diventano costose

1) „Tutto come stringa“ è comodo, ma può compromettere gli indici

Se la colonna è numerica, i parametri bindati dovrebbero essere numerici. Altrimenti possono verificarsi conversioni implicite. Sono difficili da individuare, ma costose: possono far sì che gli indici non vengano usati come previsto o che i piani peggiorino sotto carico.

2) Duplicati e valori non validi ti spingono inutilmente verso il limite

La deduplicazione riduce il numero di parametri senza svantaggi funzionali. Ugualmente utile è rimuovere precocemente stringhe vuote o ID chiaramente non validi. Non è un’ottimizzazione „per precauzione“, ma riduce direttamente la probabilità di superare i limiti.

3) Le parentesi sono semantica, non stile

Un blocco OR con le parentesi errate restituisce dati sbagliati – spesso senza errore. Questo è il caso peggiore: silenzioso, difficile da riprodurre e con implicazioni funzionali critiche. Se si usa il chunking, la corretta parentetizzazione dovrebbe essere verificata esplicitamente nei test (non solo che „giri“).

4) L’espansione libera genera molte varianti di statement

Se la dimensione della lista varia molto, varia anche il numero di placeholder e quindi il testo dello statement. Questo aumenta le varianti di Prepare e può mostrarsi nel monitoring come „molti Parse/Prepare“. Il chunking con una dimensione di blocco fissa (eccetto l’ultimo blocco) riduce la varianza, ma non la elimina completamente. Se questo è un problema reale, il passo successivo è quasi sempre l’approccio „tabella di valori“.

Piano di attuazione: come trasformare un caso limite in un componente standard

  1. Normalizzare l’input: rimuovere spazi esterni (trim), deduplicare, scartare valori non validi, opzionalmente ordinare (per fingerprint stabile).
  2. Definire il profilo backend: stabilire il limite per DB (espressioni IN o limite di parametri) e prevedere una riserva per parametri aggiuntivi.
  3. Scegliere la strategia: liste piccole → Expand; liste poco chiare o più grandi → Chunking; liste molto grandi e frequenti → valutare l’approccio tabella di valori.
  4. Generare l’SQL: solo placeholder; racchiudere i blocchi OR tra parentesi; mantenere filtri AND aggiuntivi chiaramente al di fuori del gruppo OR.
  5. Bindare i parametri: impostare i tipi corretti; gestire consapevolmente i valori NULL (NULL in IN è in genere inefficace e confonde il debug).
  6. Inserire la diagnostica: registrare Count/Chunk/Fingerprint nei log; documentare FDMonitor-Trace come „modalità di debug profondo“ nel runbook.
  7. Test ai limiti: 0, 1, Limite-1, Limite, Limite+1 (ciascuno con parametri aggiuntivi), per garantire che il comportamento rimanga stabile al variare.

Quando vale davvero la pena lo sforzo aggiuntivo (e quando no)

Non tutte le applicazioni richiedono l’intero arsenale di strumenti. L’onere aggiuntivo è giustificato soprattutto se ricorre almeno una delle seguenti condizioni:

  • Le liste provengono da selezioni utente o da ambiti di autorizzazione (la loro dimensione è difficile da prevedere).
  • I processi batch vengono eseguiti senza supervisione (gli errori devono essere diagnosticabili rapidamente).
  • Vengono supportati più database (mix Oracle/SQL Server/SQLite, p. es. per strumenti/test).
  • La tabella interessata è di grandi dimensioni e critica per le prestazioni (binding dei tipi e stabilità del piano sono rilevanti).

Se invece hai un backend chiaramente delimitato e il caso d’uso garantisce liste piccole (p. es. filtri UI con massimo 50 ID), allora può essere sufficiente una semplice soluzione Expand — purché non dimentichi il caso della lista vuota e un test limite. Questo non è una „sovraarchitettura“, ma protezione contro il primo vero caso limite operativo.

Conclusione: la stabilità non si ottiene con trucchi, ma con limiti e osservabilità

FireDAC rende semplice fare la cosa giusta: legare i parametri, trattare le macro separatamente, preparare correttamente gli statement. Il problema sorge solo quando le liste IN crescono in modo incontrollato. Chi costruisce Expand/Chunking come componente standardizzato, rispetta i limiti per database, tratta le liste vuote come percorso normale e accetta FDMonitor come fonte di verità per il debug, toglie gran parte dell’incertezza sull’argomento. Il codice ripaga quando non vuoi più dover indagare perché una funzionalità „si guasta solo con grandi volumi di dati“ — e quando vuoi arrivare alla causa in produzione in minuti invece che in ore.

Fonti e informazioni di approfondimento

Le affermazioni tecniche principali sono state contestualizzate editorialmente sulla base delle seguenti fonti esterne.

  1. Preprocessing Command Text (FireDAC) – RAD Studio (docwiki.embarcadero.com)
    FireDAC separa il binding dei parametri dalle macro/sostituzioni e preprocessa il Command-Text prima del Prepare; i valori vanno nei parametri, i frammenti SQL nelle macro.
  2. IN Condition (docs.oracle.com)
    Oracle consente al massimo 1000 espressioni in una lista IN, perciò è necessario il chunking o una tecnica alternativa per liste di grandi dimensioni.
  3. Limit and conversion very long IN list : WHERE x IN ( ,,, …) – Ask TOM (asktom.oracle.com)
    ORA-01795 è identificato come limite della lista IN (max 1000); i workaround tipici sono la suddivisione e la ricombinazione o alternative come il join contro insiemi di valori.
  4. Implementation Limits For SQLite (www.sqlite.org)
    SQLite limita il numero di parametri host (SQLITE_MAX_VARIABLE_NUMBER), il che limita direttamente le liste IN espanse.
  5. FDMonitor – RAD Studio (docwiki.embarcadero.com)
    FDMonitor è lo strumento centrale FireDAC per tracciare in modo comprensibile Statements, valori dei parametri, tipi e passaggi di esecuzione.
  6. Array DML (FireDAC) – RAD Studio (docwiki.embarcadero.com)
    FireDAC-array di parametri sono documentati principalmente per Array-DML/Batched Execution e non rappresentano automaticamente una soluzione per il binding di liste IN.

Per questo tema sono importanti anche la In Clause di FireDAC e l’espansione dei parametri di Delphi. L’articolo contestualizza questi aspetti in modo comprensibile e mostra cosa conta nella pratica quotidiana.

Discutere un progetto o un intervento di modernizzazione con Net-Base.

Passo successivo

Quando un tema diventa un progetto reale, architettura, sistemi esistenti e gestione operativa dovrebbero essere considerati insieme fin dalle fasi iniziali.

Non forniamo solo supporto per questioni isolate, ma anche quando da frammenti di codice sorgente, tematiche legacy o idee di portale deve nascere un progetto aziendale solido.

  • Stato attuale, stato obiettivo e rischi tecnici vengono valutati insieme.
  • REST, l'accesso ai dati, i portali e il rollout non vengono rinviati a fasi successive.
  • Vede in anticipo quale percorso è economicamente e operativamente sostenibile.

Condividi il post

Condividi direttamente questo articolo

LinkedIn, X, Facebook, WhatsApp und E-Mail sind sofort verfügbar. für Instagram bereiten wir Link und Kurztext direkt vor.

E-mail

Instagram si apre in una nuova scheda. Il link e il breve testo vengono copiati prima negli appunti.

Scrivi un commento

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert