Developers Query Language(DQL)

A Developers Query Language(DQL) é uma feature das APIs que permite utilizar cláusulas de consulta nos Query Parameters de uma requisição de listagem, oferecendo funcionalidade extendida em relação aos filtros comuns.

Para saber de uma API possui a DQL implementada, visite seu respectivo endpoint na API reference e veja se este possui o seguinte tipo de aviso:

📘
Developers Query Language(DQL)
Este endpoint suporta requisições utilizando a Developers Query Language(DQL).
Campos Operadores
accountId in
date lt, gt

Campos	Operadores
accountId	`in`
date	`lt`, `gt`

Cláusulas de consulta

Cláusula de consulta é a forma que é denominada a únidade minima utilizada pela DQL para realizar uma consulta na API em que a suporta.

Uma cláusula de consulta pode ser dividida em 3 partes:

Campo
Operador
Valor

Campo

O campo é a propriedade em que será aplicada a operação descrita no Operador.

Operador

O operador é a unidade lógica da cláusula, que indica qual a operação que deverá ser executada utilizando o Valor no Campo.

Operador	Descrição
`gt`	`Greater than`, `Maior que` Este operador realiza a query apenas de valores superiores ao informado
`lt`	`Less than` `Menor que` Este operador realiza a query apenas de valores inferiores ao informado
`in`	`Em` `Dentro de` Este operador realiza a query apenas de valores informados ou contidos na lista

Valor

O valor é a parte da cláusula que indica um valor ou lista de valores separados por vírgula a serem utilizados na execução do Operador no Campo informado.

Formato da cláusula

Uma cláusula de consulta assume o formato Campo:Operador=Valor e sempre será utilizado como um query parameter.

Por exemplo:

curl --request GET \
  --url 'https://api.uat.empresas.btgpactual.com/37297902000141/banking/accounts/statements?date%3Alt=2024-07-16&date%3Agt=2024-06-09&accountId%3Ain=37297902000141-208-50-009999990' \
...

Nesta requisição, podemos ver empregadas três cláusulas, cada uma utilizando um operador diferente:

date:lt=2024-07-16
date:gt=2024-06-09
accountId:in=37297902000141-208-50-009999990

Onde:

Unidade	Valor
Cláusula	date:lt=2024-07-16
Campo	date
Operador	lt
Valor	2024-07-16
Resultado	Filtra na requisição os retornos com a data anterior a 2024-07-16

Unidade	Valor
Cláusula	date:gt=2024-06-09
Campo	date
Operador	gt
Valor	2024-07-16
Resultado	Filtra na requisição os retornos com a data posterior a 2024-06-09

Unidade	Valor
Cláusula	accountId:in=37297902000141-208-50-009999990
Campo	accountId
Operador	in
Valor	37297902000141-208-50-009999990
Resultado	Filtra na requisição os retornos com o accountId igual a 37297902000141-208-50-009999990