Skip to main content
POST
/
api
/
v1
/
schemas
/
{slug}
/
query
curl -X POST \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["nome", "idade", "cidade"],
    "where": [
      {"field": "idade", "op": ">", "value": 18},
      {"field": "cidade", "op": "in", "value": ["São Paulo", "Rio de Janeiro"]}
    ],
    "order_by": [
      {"field": "nome", "direction": "asc"}
    ],
    "limit": 50
  }'

{
  "data": [
    {
      "nome": "João Silva",
      "idade": 30,
      "cidade": "São Paulo"
    },
    {
      "nome": "Maria Santos",
      "idade": 25,
      "cidade": "Rio de Janeiro"
    }
  ],
  "meta": {
    "columns": [
      {"name": "nome", "type": "String"},
      {"name": "idade", "type": "UInt32"},
      {"name": "cidade", "type": "String"}
    ]
  },
  "statistics": {
    "elapsed": 0.003,
    "rows_read": 1000,
    "bytes_read": 50000
  }
}

​
Interface Gráfica Disponível

Para usuários iniciantes: Se você não sabe como usar este endpoint ou prefere uma interface visual, temos uma tela perfeita para realizar essas consultas! Você pode executar todas essas consultas diretamente pelo app DataSnap de forma intuitiva e visual, sem precisar conhecer a sintaxe da API.
Acesse o app DataSnap: Faça login em app.datasnap.com.br e navegue até a seção de consultas do seu schema para usar a interface gráfica amigável.

​
Autenticação

Este endpoint requer autenticação. Inclua seu token Bearer no cabeçalho Authorization.
Authorization: Bearer SEU_TOKEN_AQUI

​
Parâmetros de Caminho

​
slug
string
required
O slug do schema

​
Corpo da Requisição

​
select
array
required
Array de nomes de colunas ou expressões para selecionar. O uso de * não é permitido.
​
where
array
Array de condições de filtro para aplicar à consulta.
​
group_by
array
Array de nomes de colunas para agrupar
​
order_by
array
Array de especificações de ordenação.
​
limit
integer
default:"100"
Número máximo de registros para retornar (1-10000)
​
offset
integer
default:"0"
Número de registros para pular (não pode ser usado com page_token)
​
page_token
string
Cursor codificado em Base64 para paginação. Não pode ser usado com offset.
​
format
string
default:"json_compact"
Formato da resposta. Opções: json, json_compact, json_compact_strings, jsonl
​
include_meta
boolean
default:"true"
Se deve incluir metadados na resposta

​
Resposta

O formato da resposta depende do parâmetro format:

​
Formato JSON (json)

​
data
array
Array de objetos, onde cada objeto representa uma linha com nomes de colunas como chaves
​
meta
object
Metadados da consulta incluindo informações das colunas
​
statistics
object
Estatísticas de execução da consulta (tempo decorrido, linhas lidas, bytes lidos)

​
Formato JSON Compacto (json_compact)

​
meta
array
Array de objetos de metadados de colunas com propriedades name e type
​
data
array
Array de arrays, onde cada array interno representa uma linha com valores na mesma ordem das colunas meta
​
statistics
object
Estatísticas de execução da consulta

​
Formato JSONL (jsonl)

Retorna cada linha como um objeto JSON separado em sua própria linha (JSON delimitado por quebras de linha). 
curl -X POST \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["nome", "idade", "cidade"],
    "where": [
      {"field": "idade", "op": ">", "value": 18},
      {"field": "cidade", "op": "in", "value": ["São Paulo", "Rio de Janeiro"]}
    ],
    "order_by": [
      {"field": "nome", "direction": "asc"}
    ],
    "limit": 50
  }'

{
  "data": [
    {
      "nome": "João Silva",
      "idade": 30,
      "cidade": "São Paulo"
    },
    {
      "nome": "Maria Santos",
      "idade": 25,
      "cidade": "Rio de Janeiro"
    }
  ],
  "meta": {
    "columns": [
      {"name": "nome", "type": "String"},
      {"name": "idade", "type": "UInt32"},
      {"name": "cidade", "type": "String"}
    ]
  },
  "statistics": {
    "elapsed": 0.003,
    "rows_read": 1000,
    "bytes_read": 50000
  }
}

​
Códigos de Erro

​
200
Success
Consulta executada com sucesso
​
400
Error
Requisição inválida - Schema sem tabela Datasnap Big Data ou credenciais ausentes
​
401
Error
Não autorizado - Token de autenticação inválido ou ausente
​
422
Error
Erro de validação ou parâmetros de consulta inválidos
​
500
Error
Erro interno do servidor

​
Exemplos de Consulta

​
Filtragem Básica

{
  "select": ["nome", "email", "criado_em"],
  "where": [
    {"field": "status", "op": "=", "value": "ativo"},
    {"field": "criado_em", "op": ">", "value": "2024-01-01"}
  ],
  "limit": 100
}

​
Filtragem Avançada com IN e BETWEEN

{
  "select": ["nome_produto", "preco", "categoria"],
  "where": [
    {"field": "categoria", "op": "in", "value": ["eletrônicos", "livros"]},
    {"field": "preco", "op": "between", "value": [10, 100]},
    {"field": "estoque", "op": "is not null"}
  ]
}

​
Agregação com Agrupamento

{
  "select": ["categoria", "count(*) as total_produtos", "avg(preco) as preco_medio"],
  "group_by": ["categoria"],
  "order_by": [
    {"field": "total_produtos", "direction": "desc"}
  ]
}

​
Consulta Complexa com Múltiplas Condições

{
  "select": ["id_usuario", "nome", "ultimo_login", "total_pedidos"],
  "where": [
    {"field": "ultimo_login", "op": ">=", "value": "2024-01-01"},
    {"field": "total_pedidos", "op": ">", "value": 5},
    {"field": "status", "op": "!=", "value": "suspenso"}
  ],
  "order_by": [
    {"field": "total_pedidos", "direction": "desc"},
    {"field": "ultimo_login", "direction": "desc"}
  ],
  "limit": 50
}

​
Paginação

​
Paginação Baseada em Offset

{
  "select": ["id", "nome"],
  "order_by": [{"field": "id", "direction": "asc"}],
  "limit": 25,
  "offset": 100
}

​
Paginação Baseada em Cursor (Recomendado)

Para melhor performance com grandes conjuntos de dados, use paginação baseada em cursor: 
{
  "select": ["id", "nome", "criado_em"],
  "order_by": [{"field": "criado_em", "direction": "desc"}],
  "limit": 25,
  "page_token": "base64_encoded_cursor"
}
Não é possível usar offset e page_token juntos. Escolha um método de paginação.

​
Formatos de Resposta

​
Escolhendo o Formato Certo

  • json: Melhor para conjuntos de resultados pequenos a médios onde você precisa de colunas nomeadas
  • json_compact: Mais eficiente para grandes conjuntos de resultados, reduz o tamanho da resposta
  • json_compact_strings: Todos os valores retornados como strings, útil para tipagem consistente
  • jsonl: Melhor para streaming de grandes conjuntos de resultados, um objeto JSON por linha

​
Dicas e Melhores Práticas

Sempre especifique nomes de colunas explícitos no array select. O uso de * não é permitido por razões de segurança e performance.
Use o formato json_compact para grandes conjuntos de resultados para reduzir o tamanho da resposta e melhorar a performance.
Prefira paginação baseada em cursor (page_token) ao invés de paginação baseada em offset para grandes conjuntos de dados.
Ao usar funções de agregação no select, alguns campos ORDER BY (especialmente campos do sistema com prefixo underscore) podem ser automaticamente filtrados.