Do tema da revista à prática do projeto
Páginas de serviços e técnicas correspondentes ao artigo
Video-Botschaft
FireDAC: Arrays de parâmetros para cláusulas IN – lógica de expansão segura, limites por DB e depuração do SQL final
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.
O erro raramente aparece no primeiro teste. Aparece à noite durante o processamento em lote, ou quando um Admin no Backoffice „simplesmente“ marca uma seleção maior. No Log aparece então algo como „too many SQL variables“, ORA‑01795 ou um erro do SQL Server que tem pouco a ver com o caso de uso real. Quem nesta altura ainda aposta no padrão conveniente WHERE id IN (:ids) percebe rapidamente: não é uma funcionalidade de conforto, mas um fio de tropeço.
É exatamente disso que trata BDE-Substituição com integração nativa: Arrays de parâmetros para cláusulas IN: não se trata de um kit de truques para „encaixar“ listas arbitrariamente longas em um único parâmetro, mas de uma lógica robusta de expansão e chunking que respeita os limites do DB e permite depuração limpa.
O conflito de objetivos por trás disso é real e repete-se em quase todos os sistemas:
- Segurança e mantenibilidade máximas: os valores são vinculados (sem SQL‑Injection), planos podem ser reutilizados, o logging permanece controlável.
- Robustez máxima para listas grandes: sem rupturas por limites rígidos do BD, sem erros „só no cliente X“, depuração reproduzível.
É possível alcançar ambos — mas apenas se a mecânica estiver claramente separada: parâmetros são valores, Macros/Substitution são texto SQL. E: listas grandes precisam de Guardrails.
FireDAC: Arrays de parâmetros para cláusulas IN na prática
BDE-Ablosung mit nativer Anbindung diferencia deliberadamente entre parâmetros (valores vinculados) e Macros/Substitution (fragmentos de texto que são inseridos no texto SQL antes do Prepare). O pré-processamento pode transformar o Command-Text, expandir Macros e gerar a estrutura final do Statement — mas a ligação de valores permanece separada.[Fonte]
Pode parecer formalismo, mas é uma questão de segurança e operação: um parâmetro representa tipicamente um valor em SQL. Se você insere uma lista como texto entre parênteses „às pressas“, rapidamente recorre à concatenação de strings ou ao abuso de Macros. Ambos transformam uma Query segura numa que você precisa defender constantemente contra SQL‑Injection, caracteres especiais e conversões de tipo — e que, além disso, enfraquece o plan‑caching do banco de dados.
A linha de separação robusta é, portanto: ou você gera uma lista IN a partir de vários Placeholders e vincula cada valor como parâmetro, ou muda de técnica e fornece ao banco de dados um conjunto de valores como uma „tabela“ (tabela temporária, tipo Collection/Array, Table-Valued Parameter). FireDAC por si só não tira essa decisão arquitetural de você.
Mapa de ponderação: três caminhos para a lista IN – benefício, esforço, riscos
Antes de discutir detalhes de implementação, vale a pena olhar claramente as opções. Não se trata de “certo vs. errado”, mas da questão de qual risco você quer assumir e onde: no Delphi-Code ou na operação do banco de dados.
Weg 1: Expand auf viele Parameter (IN (:p0,:p1,…))
Nutzen: permanece dentro da vinculação de parâmetros, funciona com FireDAC em vários backends, sem objetos adicionais no BD.
Aufwand: moderado (construção de string + nomes de parâmetros + bindings).
Risiken/Grenzen: limites rígidos (número de parâmetros, expressões IN), variantes de statements explodem com variações fortes no tamanho da lista.
Plausibel für: listas de filtro até “algumas centenas”, retrofit em software de negócio existente, cross-DB.
Weg 2: Chunking (mehrere IN-Blöcke per OR, sauber geklammert)
Nutzen: respeita limites, continua cross-DB, pode amortecer listas muito grandes sem recursos específicos do BD.
Aufwand: maior (lógica de parênteses, formação de blocos, gestão de parâmetros, testes).
Risiken/Grenzen: cláusulas WHERE longas; cadeias de OR podem afetar o otimizador/planos; o depurador precisa fornecer contexto (tamanho do bloco/contagens).
Plausibel für: Oracle/SQL Server/SQLite numa base de código única, quando listas grandes ocorrem de forma esporádica.
Weg 3: Werte als „Tabelle“ übergeben (Temp-Tabelle / TVP / Collection)
Nutzen: SQL permanece curto, estabilidade do plano frequentemente melhor, quantidades muito grandes são manejáveis.
Aufwand: específico ao BD; operação/deploy (esquema, permissões, cleanup/transações) tornam-se parte da solução.
Risiken/Grenzen: mais partes móveis (migrações, monitoramento, permissões).
Plausibel für: quantidades grandes regulares (milhares+), processamento em batch, quando o backend está definido e a operação pode suportar.
Harte Limits pro Datenbank: die eigentlichen Treiber für Expand-Logik
Os limites é que explicam por que “funciona localmente” não basta em produção. O decisivo não é seu código Delphi, mas o que o backend aceita em termos de forma de statement e número de parâmetros.
| Banco de dados | Limite relevante | Erro típico | Consequência prática |
|---|---|---|---|
| Oracle | Máx. 1000 expressões numa lista IN | ORA-01795 | Chunking ou técnica alternativa (Join/Collection) necessária assim que as listas se tornarem realmente grandes |
| SQL Server | Máx. 2100 parâmetros por statement/batch | Erro por excesso de parâmetros | Prever reserva para parâmetros adicionais; a partir desse limite avaliar chunking ou TVP |
| SQLite | Máx. de parâmetros host (por padrão historicamente frequentemente 999, dependendo da versão/build) | “too many SQL variables” | Ativar chunking cedo; documentar o limite em produção, pois varia conforme a distribuição |
| PostgreSQL | O número de parâmetros é limitado (por causa do protocolo/implementação) | Erros com quantidades extremas de parâmetros | Definir um limite superior; para quantidades muito grandes, considerar estratégia de tabelas de valores |
Para Oracle, o limite de 1000 está bem documentado: na condição IN são permitidas até 1000 expressões.[Fonte] Importante é a conclusão: o limite deve ser entendido como um limite estrutural da condição SQL, não como um „problema de literal“. AskTOM classifica ORA‑01795 como um limite rígido da IN-List e cita dividir/unir como solução alternativa típica – alternativamente, um JOIN contra um conjunto de valores.[Fonte]
SQLite é traiçoeiro, porque você não esbarra nas „IN-Expressions“, mas sim no número de variáveis de ligação. O limite está documentado como SQLITE_MAX_VARIABLE_NUMBER e pode variar consideravelmente conforme a versão/build. Consequência: quem usa o SQLite apenas „nas bordas“ (testes, ferramentas, clientes offline) precisa ainda assim de uma lógica de expansão que não atinja abruptamente 999 parâmetros.[Fonte]
Lógica de expansão segura: o que ela deve cumprir (e o que não)
Se você implementar Expand/Chunking, não o faça como uma manipulação improvisada de strings, mas como um pequeno componente de infraestrutura. Ele deve fazer quatro coisas de forma confiável:
- Apenas gerar placeholders: os valores devem ser vinculados exclusivamente por parâmetros FireDAC.
- Tratar lista vazia explicitamente: caminho definido, sem erros de sintaxe SQL, sem mudanças silenciosas de semântica.
- Considerar limites e reserva: por banco de dados um limite, além de uma margem para outros parâmetros na instrução.
- Fornecer contexto de debug: número de valores, tamanho do bloco, número de blocos, fingerprint opcional – em vez de „tudo em texto claro“.
Listas vazias: o caso nulo é o caso mais comum em produção
„Sem IDs“ acontece o tempo todo: filtros de permissões, filtros de busca, registros excluídos, seleção vazia. E é justamente aqui que muitas implementações se tornam imprecisas, pois tentam de alguma forma consertar o IN ().
Opções pragmáticas e bem testáveis:
- Sem chamada ao BD: se seu caso de uso deve retornar um conjunto de resultados, retorne diretamente vazio (especialmente apropriado em serviços e APIs).
- Condição sempre falsa: se, por razões arquiteturais, você precisar executar a instrução, substitua a passagem IN por uma condição certamente falsa (por exemplo, 1=0), em vez de inventar um „IN (NULL)“.
Chunking: por que a „reserva“ conta mais do que o limite documentado
Chunking não é só „para Oracle“. É sua proteção contra duas realidades típicas: parâmetros adicionais (mandante, status, período, permissões) e tamanhos de lista imprevisíveis.
Algumas diretrizes que devem chamar atenção em revisões:
- Tamanho do bloco nunca no máximo: se o SQL Server permite 2100 parâmetros, um tamanho de bloco de 2090 não é uma boa ideia, porque a instrução raramente consiste apenas na lista IN.
- Blocos OR devem estar entre parênteses: assim que um AND adicional entra, a lógica muda sem parênteses.
- Nomes de parâmetro determinísticos: Prefixo + índice (p. ex. :ids_0001) facilita significativamente traces, repros e análises de diff.
Exemplo (construído): Wenn ein Batch-Job plötzlich „kundenspezifisch“ scheitert
Depuração do SQL final: Por que o desejo é compreensível – mas raramente é o correto
Muitas equipes procuram pela „SQL final“, isto é, uma string em que todos os valores de parâmetro estejam „inseridos“. Para parâmetros ligados isso é muitas vezes uma exigência ilusória: o banco de dados recebe statement e valores separadamente. Esse é o comportamento normal para execução segura e reuso de planos. Uma única e canônica „SQL de execução“ frequentemente não existe no sentido em que se entende o SQL escrito manualmente.
Em FireDAC o caminho correto de depuração é via FDMonitor. Lá você vê Prepare/Execute, o texto do statement, os valores dos parâmetros (com tipos) e a sequência de ações. Isso está mais próximo do que realmente acontece no backend do que qualquer reconstrução de string feita à mão.[Fonte]
O que você deve avaliar especificamente no trace
- Estrutura da cláusula WHERE: Os blocos OR estão agrupados entre parênteses antes de outros filtros AND?
- Contagem de parâmetros: Quantos parâmetros existem de fato – incluindo mandante/status/período? Isso determina os limites do SQL Server e do SQLite.
- Ligação de tipo: IDs numéricas também são vinculadas como numéricas? Strings versus números não é um tema cosmético; pode afetar o uso de índices e a escolha do plano.
- Variações de statement: Cada número diferente de placeholders resulta em um texto de statement distinto. Com listas de tamanho variável você gera mais variantes de Prepare; chunking com tamanho fixo de bloco pode reduzir a variância.
Logging: SQL + contexto em vez de SQL + 2.400 valores
Em logs de produção raramente você quer ver cada valor individual. Você quer diagnóstico com tamanho de log aceitável e sem exposição desnecessária de dados. Campos típicos e úteis são:
- Número de valores (Count)
- Tamanho do bloco e número de blocos
- Impressão digital da lista normalizada (p. ex. hash), para identificar repetições sem escrever os conteúdos
- Prévia truncada (p. ex. primeiros/últimos 5 valores), se isso for aceitável do ponto de vista de proteção de dados e técnico
Arrays de parâmetros em FireDAC: o termo que frequentemente leva na direção errada
FireDAC documenta “arrays de parâmetros” sobretudo no contexto de Array-DML (execução em lote): muitos registros são executados em uma única instrução, definindo-se os valores dos parâmetros como arrays. Isso é um recurso de desempenho para INSERT/UPDATE/DELETE – mas não resolve automaticamente o problema de “lista IN como um parâmetro”. São dois casos de uso distintos, que soam semelhantes linguisticamente, mas funcionam operacionalmente de forma diferente.[Fonte]
Consequência prática para a comunicação da equipe: quando alguém diz “arrays de parâmetros para IN”, vale a pena perguntar: você quer dizer Array-DML ou quer dizer Expand/Chunking para WHERE IN? Essa clareza evita que, no fim, valores sejam novamente inseridos por substituição de texto no SQL.
Checklist de revisão: armadilhas típicas que ficam caras posteriormente
1) “Tudo como string” é confortável, mas pode neutralizar índices
Se a coluna é numérica, os parâmetros vinculados devem ser numéricos. Caso contrário, podem surgir conversões implícitas. Elas são difíceis de detectar, mas custosas: podem fazer com que índices não sejam utilizados como esperado ou que planos desestabilizem sob carga.
2) Duplicatas e valores inválidos aumentam desnecessariamente a chance de atingir limites
A deduplicação reduz o número de parâmetros sem prejuízo funcional. O mesmo vale para remover cedo strings vazias ou IDs claramente inválidos. Isso não é uma otimização “por precaução”, mas reduz diretamente a probabilidade de ultrapassar limites.
3) Parênteses definem semântica, não estilo
Um bloco OR com parênteses incorretos retorna dados errados – muitas vezes sem mensagem de erro. Esse é o cenário mais indesejável: silencioso, difícil de reproduzir e com impacto funcional sério. Quando se usa chunking, a parentização deve ser verificada explicitamente nos testes (não apenas “funciona”).
4) Expansão livre gera muitas variantes de instrução
Se o tamanho da lista varia muito, varia também o número de placeholders e, com isso, o texto da instrução. Isso aumenta as variantes de Prepare e pode aparecer no monitoramento como muito Parse/Prepare. Chunking com tamanho de bloco fixo (exceto o último bloco) reduz a diversidade, mas não a elimina por completo. Se isso realmente prejudica, a próxima etapa costuma ser “valores como tabela”.
Roteiro de implementação: como um caso marginal vira um componente padrão
- Normalizar a entrada: remover espaços (trim), deduplicar, descartar valores inválidos, opcionalmente ordenar (para impressão digital estável).
- Definir perfil do backend: estabelecer limite por DB (expressões IN ou limite de parâmetros) e reservar uma reserva para parâmetros adicionais.
- Escolher estratégia: listas pequenas → Expand; listas incertas ou maiores → Chunking; listas muito grandes e frequentes → avaliar abordagem de tabelas de valores.
- Gerar SQL: apenas placeholders; agrupar blocos OR; manter filtros AND adicionais claramente fora do grupo OR.
- Vincular parâmetros: definir tipos apropriados; tratar conscientemente valores NULL (NULL em IN geralmente é ineficaz e confunde a depuração).
- Inserir diagnóstico: Count/Chunk/Fingerprint no log; documentar FDMonitor-Trace como “modo de debug profundo” no runbook.
- Testes de limite: 0, 1, Limite-1, Limite, Limite+1 (cada caso com parâmetros adicionais), para que o comportamento permaneça estável diante de alterações.
Quando o esforço adicional realmente compensa (e quando não)
Nem toda aplicação precisa da caixa de ferramentas completa. O esforço adicional compensa especialmente quando pelo menos um dos seguintes pontos se aplica:
- Listas provêm de seleção de usuário ou de escopos de permissões (tamanho difícil de prever).
- Processos em lote executam-se sem supervisão (erros devem ser rapidamente diagnosticáveis).
- É necessário suporte a múltiplos bancos de dados (mix Oracle/SQL Server/SQLite, p.ex. para ferramentas/testes).
- A tabela em questão é grande e crítica para desempenho (vinculação de tipo e estabilidade do plano contam).
Se, em contrapartida, você tem um backend claramente limitado e o caso de uso garante listas pequenas (p.ex. filtros de UI com no máximo 50 IDs), então uma solução simples de Expand pode ser suficiente — desde que você não esqueça o caso nulo e um teste de limite. Isso não é uma „arquitetura excessiva“, mas proteção contra o primeiro caso real de borda operacional.
Conclusão: estabilidade não surge por truques, mas por limites e observabilidade
FireDAC facilita o que é correto: vincular parâmetros, tratar Macros separadamente, pré-processar o texto do comando antes do Prepare e preparar os statements de forma limpa. O problema só surge onde as listas IN crescem descontroladamente. Quem implementa Expand/Chunking como um componente padronizado, respeita os limites por banco de dados, trata listas vazias como um caminho normal e aceita o FDMonitor como fonte de verdade para depuração, tira o susto do tema. O código vale a pena quando você não quer mais adivinhar por que um recurso falha „apenas com grandes volumes de dados“ — e quando, em operação, você quer chegar à causa em minutos em vez de horas.
Fontes e informações complementares
As afirmações técnicas centrais foram editorialmente contextualizadas com base nas seguintes fontes externas.
- Preprocessing Command Text (FireDAC) – RAD Studio (docwiki.embarcadero.com)
FireDAC separa a ligação de parâmetros de Macros/Substitution e pré-processa o texto do comando antes do Prepare; valores pertencem a parâmetros, fragmentos SQL a Macros. - IN Condition (docs.oracle.com)
A Oracle permite no máximo 1000 expressões numa lista IN; portanto, Chunking ou uma técnica alternativa é necessária a partir de listas grandes. - Limit and conversion very long IN list : WHERE x IN ( ,,, …) – Ask TOM (asktom.oracle.com)
ORA-01795 é identificado como o limite da lista IN (máx. 1000); soluções típicas são dividir e encadear ou alternativas como JOIN contra conjuntos de valores. - Implementation Limits For SQLite (www.sqlite.org)
O SQLite limita o número de parâmetros host (SQLITE_MAX_VARIABLE_NUMBER), o que restringe diretamente listas IN expandidas.
FDMonitor é a ferramenta central de FireDAC para rastrear de forma verificável instruções SQL, valores de parâmetros, tipos e passos de execução.
FireDAC-arrays de parâmetros são documentados primariamente para Array-DML/Batched Execution e não constituem automaticamente uma solução para o binding de listas IN.
Para este tema são também importantes FireDAC cláusula IN e Delphi expansão de parâmetros. O artigo enquadra esses aspectos de forma compreensível e mostra no que importa no dia a dia.
Discutir projeto ou iniciativa de modernização com Net-Base.
Próximo passo
Quando o tema se tornar um projeto real, arquitetura, ambiente existente e operação devem ser considerados em conjunto desde o início.
Não apenas apoiamos questões pontuais, mas também quando fragmentos de código-fonte, temas legados ou ideias de portais precisam evoluir para um projeto empresarial robusto.
- Estado atual, estado-alvo e riscos técnicos são avaliados em conjunto.
- REST, o acesso a dados, os portais e o Rollout não são adiados para fases posteriores.
- Você identifica cedo qual caminho é viável econômica e operacionalmente.