O erro que (quase) todo mundo comete no Oracle APEX: esquecer de adicionar os itens de página em “Page Items to Submit” no relatório

Se sua consulta usa itens de página como filtros e você só dá refresh na região (sem submit da página), o servidor não “vê” os novos valores porque eles não chegaram à sessão. Basta adicionar esses itens em Page Items to Submit na região (ou na ação dinâmica de Refresh, quando disponível) e tudo volta a funcionar.

Introdução

Você já montou um “filtro avançado” com vários itens de página — select lists, datas, checkboxes — e conectou tudo a um relatório (ou gráfico) no Oracle APEX. Na hora de testar, tudo funciona quando você clica num botão que faz Submit Page, mas… quebra quando você apenas faz um Refresh da região. Por quê?

A resposta está num detalhe que muita gente esquece: os Page Items to Submit. Sem eles, o APEX não envia os valores ao servidor durante o refresh via AJAX, e sua consulta roda com valores desatualizados (ou nulos), gerando resultados incorretos.

Neste artigo você vai entender:

1. O que o APEX faz com o estado de sessão durante um refresh de região
2. Como e onde configurar os Page Items to Submit
3. Receitas SQL seguras para filtros (simples e multi-seleção)
4. Bônus: o mesmo problema em Ações Dinâmicas
5. Um checklist rápido para nunca mais esquecer

O problema em 30 segundos

Cenário típico:

1. Você tem itens de filtro: P10_STATUS, P10_DATA_INI, P10_DATA_FIM, P10_CLIENTE.
2. A query do relatório usa esses itens:

SELECT *
  FROM pedidos
 WHERE (:P10_STATUS   IS NULL OR status = :P10_STATUS)
   AND (:P10_CLIENTE  IS NULL OR cliente_id = :P10_CLIENTE)
   AND (:P10_DATA_INI IS NULL OR data_pedido >= :P10_DATA_INI)
   AND (:P10_DATA_FIM IS NULL OR data_pedido < :P10_DATA_FIM + 1)

3. Você cria uma Ação Dinâmica que, ao mudar um filtro, dá Refresh na região do relatório.

E… nada acontece. O relatório não aplica os filtros. Você revisa a query, até duvida de si mesmo… Mas o problema não é a SQL — é que você esqueceu de passar os itens para o servidor.

Solução simples e rápida

A solução é dizer explicitamente ao APEX: “Ei, quando for atualizar esta região, leve junto os valores destes itens!”.

1. No Builder, selecione sua região de relatório.
2. Na propriedade Page Items to Submit, adicione P10_STATUS, P10_DATA_INI, P10_DATA_FIM, P10_CLIENTE.

Pronto: agora o refresh via AJAX leva os valores certos e o relatório atualiza corretamente.

Receitas SQL seguras para filtros

Mesmo configurando os itens, vale escrever sua SQL de forma flexível:

• Trate NULL e valores vazios:

WHERE (:P10_FILTRO IS NULL OR coluna = :P10_FILTRO)

• Para multi-seleção, use IN e APEX_STRING.SPLIT:

-- considere split_numbers para tratar valores numéricos
WHERE (:P10_CLIENTES IS NULL
       OR cliente_id IN (
         SELECT column_value
           FROM TABLE(
             APEX_STRING.SPLIT(:P10_CLIENTES, ',')
           )
       ))

Bônus: O mesmo problema em Ações Dinâmicas

Isso também acontece em SQL ou PL/SQL dentro de Ações Dinâmicas. Qualquer request ao servidor que use parâmetros precisa enviá-los em Items to Submit. Exemplos:

• Execute Server-side Code (PL/SQL)

Solução: Na ação “Execute Server-side Code”, adicione P10_CLIENTE_ID em "Items to Submit".

• Set Value

Solução: Adicione P10_UF em "Items to Submit".

Um checklist rápido para nunca mais esquecer

Antes de fechar a tarefa, passe por esta lista:

✅Identifiquei TODOS os itens de página usados na cláusula WHERE da minha query?

✅Adicionei todos eles ao campo “Page Items to Submit” (na região ou na ação dinâmica)?

✅Minha query SQL trata corretamente os valores nulos (ex: :P10_FILTRO IS NULL OR ...)?

✅Testei a funcionalidade alterando um filtro e garantindo que o relatório atualiza via Refresh, sem dar Submit na página inteira?

✅Testei o cenário “limpando” o filtro para ver se o relatório volta a mostrar todos os dados?

Conclusão

O “truque” é simples, mas crítico: quando sua consulta depende de filtros, você precisa garantir que esses valores cheguem ao servidor na hora do refresh da região. No Oracle APEX, isso significa configurar corretamente os “Page Items to Submit” (ou usar a alternativa de “Items to Submit” na própria ação de Refresh, quando disponível).

Esse ajuste elimina um dos bugs mais irritantes do dia a dia e melhora a previsibilidade do seu app — sem gambiarras.