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 os registros retornados pela consulta.

Ordenar listas de dados no retorno.

Paginar resultados com grandes volumes de registros.

Limitar a quantidade de resultados retornados.

Utilizar data de referência para consultas históricas.

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

⭐
Ao concluir esta seção, você saberá transformar retornos amplos em respostas mais precisas, leves e úteis para sua integração.

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:

Exemplo de chamada para um dataset:

Body:
{
  "Datasets": "basic_data{name, birthdate, taxidstatus, mothername}",
  "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

{
  "Datasets": "processes.filter(party_type=defendant)",
  "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}"
}

👍
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 na resposta da consulta.

Filtros

Definem quais registros devem aparecer no retorno.

Ordenação

Define a ordem em que os dados serão apresentados.

Paginação

Permite navegar por grandes volumes de registros.

Limitação

Define a quantidade máxima de registros retornados.

Data de referência

Retorna uma fotografia histórica dos dados em uma data específica.

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