Os recursos desta página permitem refinar o retorno das APIs da Plataforma de Dados, entregando apenas as informações necessárias para o seu fluxo.

Aqui você aprenderá como:

Selecionar campos específicos de um dataset
Filtrar registros retornados
Ordenar listas de dados
Paginar resultados
Limitar a quantidade de resultados
Utilizar data de referência

Essas funcionalidades ajudam a reduzir o volume de dados trafegados, melhorar a performance das integrações e tornar as respostas mais alinhadas à sua necessidade.

1️⃣ Selecionar campos de um dataset

Em alguns cenários, não é necessário receber todos os campos disponíveis em um dataset.
Para isso, é possível informar, no momento da chamada, quais campos devem ser retornados, diretamente no parâmetro Datasets.

A seleção de campos é feita informando o nome do dataset seguido dos campos desejados entre chaves, separados por vírgula ({campo1, campo2}).

Exemplos:

Seleção de campos em um dataset

Body:
{
    "Datasets": "basic_data{name, birthdate, taxidstatus, mothername}",
    "q": "doc{12345678900}"
}

Múltiplos datasets com seleção em apenas um deles

Quando a chamada inclui mais de um dataset, a seleção de campos pode ser aplicada apenas àquele desejado:

Body:
{
    "Datasets": "basic_data{name, birthdate, taxidstatus, mothername}, kyc, processes",
    "q": "doc{12345678900}"
}

❗️
Nas consultas à API On-demand, não é possível realizar a seleção de campos para retorno.

2️⃣ Filtrar resultados retornados

Alguns datasets permitem filtrar os resultados retornados, selecionando apenas informações que atendam a critérios específicos.

As regras de filtragem seguem os princípios abaixo:

Não há diferenciação entre letras maiúsculas e minúsculas
É possível filtrar por múltiplos valores em um mesmo campo
É possível aplicar filtros em mais de um campo simultaneamente

Filtro simples

{
    "Datasets": "processes.filter(party_type=defendant)",
    "q": "doc{12345678900}"
}

Filtro com múltiplos valores

{
    "Datasets": "phones.filter(areacode=[21,11])",
    "q": "doc{12345678900}"
}

Filtros em múltiplos campos

{
    "Datasets": "emails.filter(Type=work,validationstatus=VALID)",
    "q": "doc{12345678900}"
}

📘
Para saber se um dataset específico suporta filtros, consulte sua documentação.

3️⃣ Ordenar listas de resultados

Diversos datasets retornam listas de resultados, como nos casos de contatos (telefones, endereços e e-mails) e relacionamentos.

Por padrão, essas listas são retornadas seguindo uma ordem de priorização interna, que considera critérios de relevância conforme o contexto do dado.

Caso seja necessário alterar essa ordenação, é possível ordenar os resultados de forma crescente(ascending) ou decrescente(descending) por qualquer campo disponível no dataset.

Ordenação de resultados

{
    "Datasets": "emails.order(EmailTotalPassages=ascending)",
    "q": "doc{12345678900}"
}

4️⃣ Paginar resultados

Alguns datasets retornam listas extensas de registros. Quando houver mais resultados disponíveis, o retorno incluirá o campo Next, contendo o identificador da próxima página.

Para recuperar os próximos registros, utilize o parâmetro .next(x) no campo Datasets, logo após o nome do dataset, informando o valor retornado em Next e mantendo o mesmo parâmetro q da consulta original.

Recuperar próxima página

{
    "Datasets": "media_profile_and_exposure.next(AoJw14Wy0ZYDP0No...)",
    "q": "doc{12345678900}"
}

📘
Importante:
A paginação não gera custo adicional e as próximas páginas permanecem disponíveis por até 3 horas após a consulta inicial.

5️⃣ Limitar quantidade de resultados

Alguns datasets podem retornar uma quantidade elevada de registros para uma mesma entidade, como é o caso de Prêmios e Certificações, Contatos ou Relacionamentos.

Nesses cenários, pode ser interessante definir um limite máximo de resultados retornados, garantindo respostas mais rápidas, organizadas e alinhadas ao seu fluxo de negócio.

Para isso, utilize o parâmetro .limit(x) no campo Datasets, logo após o nome do dataset ao qual deseja aplicar essa personalização.

Limitando a quantidade de resultados

{
    "Datasets": "awards_and_certifications.limit(10)",
    "q": "doc{12345678900}"
}

6️⃣ Utilizar datas de referência

É possível realizar consultas considerando uma data específica como referência, retornando uma fotografia dos dados naquele momento. Para isso, é obrigatório o envio das chaves referencedate{DATA} e dateformat{FORMATO} dentro do parâmetro q.

Essa funcionalidade é útil para análises históricas e backtests, sem necessidade de solicitação adicional à equipe da BigDataCorp.

Exemplos de chamada com data de referência

{
    "Datasets": "addresses",
    "q": "doc{12345678900},referencedate{03-09-2018},dateformat{dd-MM-yyyy}"
}

{
    "Datasets": "political_involvement",
    "q": "doc{12345678900},referencedate{12-2020},dateformat{MM-yyyy}"
}

🚧
Se a data enviada for inválida, a data atual será considerada como referência.

7️⃣ Resumo prático

Seleção de campos → define quais informações serão retornadas
Filtros → definem quais registros devem aparecer no retorno
Ordenação → define em que ordem os dados são apresentados
Paginação → permite navegar por grandes volumes de registros
Limitação → define qual o máximo de registros devem aparecer no retorno
Data de referência → retorna uma fotografia histórica dos dados

Esses recursos podem ser combinados para criar respostas mais enxutas, organizadas e alinhadas ao seu fluxo.

Próximos passos

Agora que você sabe como personalizar o retorno das consultas, siga para:

Recursos adicionais – uso de dochash, tags e funcionalidades complementares

✨ A partir daqui, você já sabe como moldar o retorno das consultas. Agora é só explorar os recursos adicionais!