Consulta de Registros

curl -X POST \
  "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["nome", "idade", "cidade"],
    "event_from": "2024-01-01",
    "event_to": "2024-12-31",
    "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
  }'

curl -X POST \
  "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["cidade", "count(*) as total_usuarios", "avg(idade) as idade_media"],
    "event_from": "2024-01-01",
    "event_to": "2024-12-31",
    "where": [
      {"field": "idade", "op": "between", "value": [18, 65]}
    ],
    "group_by": ["cidade"],
    "order_by": [
      {"field": "total_usuarios", "direction": "desc"}
    ],
    "limit": 20
  }'

const response = await fetch(
  'https://api.datasnap.cloud/api/v1/schemas/meu-schema/query',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer SEU_TOKEN_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      select: ['nome', 'idade', 'cidade'],
      event_from: '2024-01-01',
      event_to: '2024-12-31',
      where: [
        { field: 'idade', op: '>', value: 18 },
        { field: 'status', op: '=', value: 'ativo' }
      ],
      order_by: [
        { field: 'criado_em', direction: 'desc' }
      ],
      limit: 100
    })
  }
);

const data = await response.json();

import requests
import json

url = "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query"
headers = {
    "Authorization": "Bearer SEU_TOKEN_AQUI",
    "Content-Type": "application/json"
}

payload = {
    "select": ["nome", "idade", "cidade"],
    "event_from": "2024-01-01",
    "event_to": "2024-12-31",
    "where": [
        {"field": "idade", "op": ">", "value": 18},
        {"field": "status", "op": "=", "value": "ativo"}
    ],
    "order_by": [
        {"field": "criado_em", "direction": "desc"}
    ],
    "limit": 100
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()

curl -X POST \
  "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["id", "nome", "criado_em"],
    "order_by": [
      {"field": "criado_em", "direction": "desc"}
    ],
    "limit": 100,
    "page_token": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wOC0xNVQxMDozMDowMFoiLCJpZCI6MTIzZQ=="
  }'

{
  "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
  }
}

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

{"nome":"João Silva","idade":30,"cidade":"São Paulo"}
{"nome":"Maria Santos","idade":25,"cidade":"Rio de Janeiro"}

{
  "error": "Schema sem tabela Datasnap Big Data vinculada."
}

{
  "error": "Select inválido. Utilize colunas específicas; uso de * não é permitido."
}

{
  "error": "Não autenticado."
}

POST

api

schemas

{slug}

query

curl -X POST \
  "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["nome", "idade", "cidade"],
    "event_from": "2024-01-01",
    "event_to": "2024-12-31",
    "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
  }'

curl -X POST \
  "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["cidade", "count(*) as total_usuarios", "avg(idade) as idade_media"],
    "event_from": "2024-01-01",
    "event_to": "2024-12-31",
    "where": [
      {"field": "idade", "op": "between", "value": [18, 65]}
    ],
    "group_by": ["cidade"],
    "order_by": [
      {"field": "total_usuarios", "direction": "desc"}
    ],
    "limit": 20
  }'

const response = await fetch(
  'https://api.datasnap.cloud/api/v1/schemas/meu-schema/query',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer SEU_TOKEN_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      select: ['nome', 'idade', 'cidade'],
      event_from: '2024-01-01',
      event_to: '2024-12-31',
      where: [
        { field: 'idade', op: '>', value: 18 },
        { field: 'status', op: '=', value: 'ativo' }
      ],
      order_by: [
        { field: 'criado_em', direction: 'desc' }
      ],
      limit: 100
    })
  }
);

const data = await response.json();

import requests
import json

url = "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query"
headers = {
    "Authorization": "Bearer SEU_TOKEN_AQUI",
    "Content-Type": "application/json"
}

payload = {
    "select": ["nome", "idade", "cidade"],
    "event_from": "2024-01-01",
    "event_to": "2024-12-31",
    "where": [
        {"field": "idade", "op": ">", "value": 18},
        {"field": "status", "op": "=", "value": "ativo"}
    ],
    "order_by": [
        {"field": "criado_em", "direction": "desc"}
    ],
    "limit": 100
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()

curl -X POST \
  "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["id", "nome", "criado_em"],
    "order_by": [
      {"field": "criado_em", "direction": "desc"}
    ],
    "limit": 100,
    "page_token": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wOC0xNVQxMDozMDowMFoiLCJpZCI6MTIzZQ=="
  }'

{
  "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
  }
}

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

{"nome":"João Silva","idade":30,"cidade":"São Paulo"}
{"nome":"Maria Santos","idade":25,"cidade":"Rio de Janeiro"}

{
  "error": "Schema sem tabela Datasnap Big Data vinculada."
}

{
  "error": "Select inválido. Utilize colunas específicas; uso de * não é permitido."
}

{
  "error": "Não autenticado."
}

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.cloud 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

string

required

O slug do schema

Corpo da Requisição

array

required

Array de nomes de colunas ou expressões para selecionar. O uso de * não é permitido.

Show Exemplos

["nome", "idade", "cidade"]
["cidade", "count(*) as total_usuarios"]
["avg(idade) as idade_media", "max(salario) as salario_max"]

string

required

Data de início para a janela de consulta (obrigatório para performance e particionamento).

string

required

Data de fim para a janela de consulta (obrigatório para performance e particionamento).

array

Array de condições de filtro para aplicar à consulta (além do período obrigatório).

Show Estrutura do Objeto Condição

string

required

Nome do campo para filtrar

string

required

Operador de comparação. Opções: =, !=, >, <, >=, <=, like, not like, in, not in, between, is null, is not null

mixed

Valor para comparar. Para operações in/not in, forneça um array. Para between, forneça array com [de, até]. Para is null/is not null, isso pode ser omitido.

array

Array de nomes de colunas para agrupar

array

Array de especificações de ordenação.

Show Estrutura do Objeto Ordenação

string

required

Nome do campo para ordenar

string

Direção da ordenação. Opções: asc, desc, ASC, DESC (padrão: asc)

integer

default:"100"

Número máximo de registros para retornar (1-10000)

integer

default:"0"

Número de registros para pular (não pode ser usado com page_token)

string

Cursor codificado em Base64 para paginação. Não pode ser usado com offset.

string

default:"json_compact"

Formato da resposta. Opções: json, json_compact, json_compact_strings, jsonl

boolean

default:"true"

Se deve incluir metadados na resposta

Resposta

O formato da resposta depende do parâmetro format:

Formato JSON (`json`)

array

Array de objetos, onde cada objeto representa uma linha com nomes de colunas como chaves

object

Metadados da consulta incluindo informações das colunas

object

Estatísticas de execução da consulta (tempo decorrido, linhas lidas, bytes lidos)

Formato JSON Compacto (`json_compact`)

array

Array de objetos de metadados de colunas com propriedades name e type

array

Array de arrays, onde cada array interno representa uma linha com valores na mesma ordem das colunas meta

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.cloud/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["nome", "idade", "cidade"],
    "event_from": "2024-01-01",
    "event_to": "2024-12-31",
    "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
  }'

curl -X POST \
  "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["cidade", "count(*) as total_usuarios", "avg(idade) as idade_media"],
    "event_from": "2024-01-01",
    "event_to": "2024-12-31",
    "where": [
      {"field": "idade", "op": "between", "value": [18, 65]}
    ],
    "group_by": ["cidade"],
    "order_by": [
      {"field": "total_usuarios", "direction": "desc"}
    ],
    "limit": 20
  }'

const response = await fetch(
  'https://api.datasnap.cloud/api/v1/schemas/meu-schema/query',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer SEU_TOKEN_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      select: ['nome', 'idade', 'cidade'],
      event_from: '2024-01-01',
      event_to: '2024-12-31',
      where: [
        { field: 'idade', op: '>', value: 18 },
        { field: 'status', op: '=', value: 'ativo' }
      ],
      order_by: [
        { field: 'criado_em', direction: 'desc' }
      ],
      limit: 100
    })
  }
);

const data = await response.json();

import requests
import json

url = "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query"
headers = {
    "Authorization": "Bearer SEU_TOKEN_AQUI",
    "Content-Type": "application/json"
}

payload = {
    "select": ["nome", "idade", "cidade"],
    "event_from": "2024-01-01",
    "event_to": "2024-12-31",
    "where": [
        {"field": "idade", "op": ">", "value": 18},
        {"field": "status", "op": "=", "value": "ativo"}
    ],
    "order_by": [
        {"field": "criado_em", "direction": "desc"}
    ],
    "limit": 100
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()

curl -X POST \
  "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["id", "nome", "criado_em"],
    "order_by": [
      {"field": "criado_em", "direction": "desc"}
    ],
    "limit": 100,
    "page_token": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wOC0xNVQxMDozMDowMFoiLCJpZCI6MTIzZQ=="
  }'

{
  "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
  }
}

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

{"nome":"João Silva","idade":30,"cidade":"São Paulo"}
{"nome":"Maria Santos","idade":25,"cidade":"Rio de Janeiro"}

{
  "error": "Schema sem tabela Datasnap Big Data vinculada."
}

{
  "error": "Select inválido. Utilize colunas específicas; uso de * não é permitido."
}

{
  "error": "Não autenticado."
}

Códigos de Erro

Success

Consulta executada com sucesso

Error

Requisição inválida - Schema sem tabela Datasnap Big Data ou credenciais ausentes

Error

Não autorizado - Token de autenticação inválido ou ausente

Error

Erro de validação ou parâmetros de consulta inválidos

Error

Erro interno do servidor

Exemplos de Consulta

Filtragem Básica

{
  "select": ["nome", "email", "criado_em"],
  "event_from": "2024-01-01",
  "event_to": "2024-12-31",
  "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"],
  "event_from": "2024-01-01",
  "event_to": "2024-12-31",
  "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"],
  "event_from": "2024-01-01",
  "event_to": "2024-12-31",
  "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"],
  "event_from": "2024-01-01",
  "event_to": "2024-12-31",
  "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"],
  "event_from": "2024-01-01",
  "event_to": "2024-12-31",
  "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"],
  "event_from": "2024-01-01",
  "event_to": "2024-12-31",
  "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.

Documentação da API

Endpoints

Interface Gráfica Disponível

Autenticação

Parâmetros de Caminho

Corpo da Requisição

Resposta

Formato JSON (`json`)

Formato JSON Compacto (`json_compact`)

Formato JSONL (`jsonl`)

Códigos de Erro

Exemplos de Consulta

Filtragem Básica

Filtragem Avançada com IN e BETWEEN

Agregação com Agrupamento

Consulta Complexa com Múltiplas Condições

Paginação

Paginação Baseada em Offset

Paginação Baseada em Cursor (Recomendado)

Formatos de Resposta

Escolhendo o Formato Certo

Dicas e Melhores Práticas

​Interface Gráfica Disponível

​Autenticação

​Parâmetros de Caminho

​Corpo da Requisição

​Resposta

​Formato JSON (json)

​Formato JSON Compacto (json_compact)

​Formato JSONL (jsonl)

​Códigos de Erro

​Exemplos de Consulta

​Filtragem Básica

​Filtragem Avançada com IN e BETWEEN

​Agregação com Agrupamento

​Consulta Complexa com Múltiplas Condições

​Paginação

​Paginação Baseada em Offset

​Paginação Baseada em Cursor (Recomendado)

​Formatos de Resposta

​Escolhendo o Formato Certo

​Dicas e Melhores Práticas

Interface Gráfica Disponível

Autenticação

Parâmetros de Caminho

Corpo da Requisição

Resposta

Formato JSON (`json`)

Formato JSON Compacto (`json_compact`)

Formato JSONL (`jsonl`)

Códigos de Erro

Exemplos de Consulta

Filtragem Básica

Filtragem Avançada com IN e BETWEEN

Agregação com Agrupamento

Consulta Complexa com Múltiplas Condições

Paginação

Paginação Baseada em Offset

Paginação Baseada em Cursor (Recomendado)

Formatos de Resposta

Escolhendo o Formato Certo

Dicas e Melhores Práticas