Crie uma cláusula WHERE SQL parametrizada com filtros

Cada nome de campo recebe aspas de identificador SQL, inclusive cada segmento de um nome qualificado, enquanto os valores ficam fora do texto SQL. Os filtros mantêm a ordem original e são unidos por AND, tornando o resultado previsível para construtores de consultas, ferramentas administrativas, telas de relatórios e endpoints que já recebem filtros como dados.

Monte a estrutura SQL sem concatenar valores

Telas de pesquisa dinâmica normalmente começam com registros que parecem inofensivos: um campo, um operador e um valor. O risco surge ao transformar esses registros em SQL inserindo o valor diretamente em uma string. Este construtor mantém estrutura e dados separados. Ele retorna uma cláusula WHERE SQL parametrizada com placeholders posicionais no estilo PostgreSQL, como $1 e $2, além de um array params exatamente na ordem correspondente. Acrescente a cláusula a uma instrução SELECT, UPDATE ou DELETE maior e forneça params a um driver compatível. O construtor não executa consultas, não se conecta ao banco, não inspeciona esquemas nem decide quais colunas podem ser usadas. Sua aplicação ainda deve manter uma lista de permissão quando usuários puderem influenciar os campos. As aspas impedem que pontuação e palavras reservadas quebrem a sintaxe, mas a autorização continua sob responsabilidade da aplicação. Como os filtros são unidos por AND na ordem recebida, a saída é estável e simples de registrar, comparar ou combinar com um prefixo fixo de consulta.

Entenda operadores, placeholders e verificações de nulo

São aceitos operadores de igualdade, desigualdade, comparação de ordem, LIKE, NOT LIKE, IN, NOT IN, IS NULL e IS NOT NULL. O texto do operador é normalizado em maiúsculas e espaços repetidos são reduzidos, portanto uma forma como “not like” produz SQL canônico. Cada comparação comum consome um parâmetro. IN e NOT IN exigem um array não vazio e o expandem em um placeholder por elemento, preservando a ordem. Operadores de nulo não consomem parâmetros nem exigem valor, pois sua gramática SQL não contém placeholder. A ausência de valor em qualquer outro operador é rejeitada em vez de gerar SQL incompleto. Valores escalares JSON são aceitos, incluindo strings, números, booleanos e null; arrays ficam reservados aos dois operadores de lista. O resultado usa intencionalmente placeholders numerados com cifrão, adequados ao PostgreSQL e a bibliotecas compatíveis. Caso seu driver utilize pontos de interrogação ou parâmetros nomeados, adapte a sintaxe de modo controlado sem alterar a ordem retornada dos parâmetros.

Coloque identificadores entre aspas e valide a política

Cada campo é tratado como um identificador possivelmente qualificado. Um nome como users.created_at vira dois segmentos com aspas independentes, enquanto uma aspa dupla interna é escapada por duplicação conforme as regras padrão de identificadores SQL. Nomes vazios e segmentos vazios separados por pontos são rejeitados. Esse tratamento evita que uma string de campo seja confundida com sintaxe SQL sem aspas, mas não pressupõe que todos os bancos tenham regras idênticas. Confirme a compatibilidade com o banco de destino, principalmente se ele não adotar identificadores entre aspas duplas. Além disso, escapar não equivale a autorizar. Se uma pessoa externa puder escolher campos, mapeie as chaves públicas para um conjunto explícito de colunas reais antes de chamar o construtor. Faça o mesmo com operadores em nível de negócio: um endpoint de relatórios pode permitir igualdade e intervalos, porém negar padrões mesmo com suporte a LIKE. Qualquer operador SQL desconhecido gera um erro de entrada claro em vez de repassar sintaxe imprevista. A capacidade é determinística, não faz solicitações de rede e retorna somente a cláusula e os parâmetros.