> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datasnap.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Início Rápido
> Comece a usar o DataSnap em minutos seguindo nosso guia passo a passo
## Primeiros passos com DataSnap
Este guia mostrará como usar o DataSnap em duas etapas simples: fazer upload de dados e realizar consultas.
## Pré-requisitos
Antes de iniciar, você precisa ter:
### 1. Conta na DataSnap
Você precisa ter uma conta ativa na plataforma DataSnap. Se ainda não possui uma, [cadastre-se aqui](https://app.datasnap.cloud).
### 2. Token de Acesso
Um **token de autenticação Bearer** válido para acessar e usar todos os endpoints da API DataSnap. Este token funciona como sua "chave de acesso" pessoal e deve ser incluído no cabeçalho `Authorization` de todas as requisições à API.
**Como obter seu token:**
1. Acesse o [painel de controle da DataSnap](https://app.datasnap.cloud)
2. Navegue até a seção "API" ou "Tokens de Acesso"
3. Clique em "Gerar Novo Token" ou "Criar Token"
4. Copie o token gerado e mantenha-o seguro
**Importante**: Mantenha seu token seguro e nunca o compartilhe. Se comprometido, gere um novo token imediatamente no painel de controle.
### 3. Modelo de Dados (Schema) Criado
Você precisa ter um **schema** criado na plataforma, onde você declara campo a campo que será enviado no arquivo JSONL.
**Criação automática de schema**: Você também pode enviar um arquivo JSON de exemplo que o sistema vai automaticamente identificar os campos enviados e criar a estrutura de forma automática **em 1 segundo**!
**Como criar um schema**: Acesse o painel de controle da DataSnap, vá em "Modelos de Dados" → "Novo Modelo de Dados" e defina a estrutura dos seus dados ou faça upload de um arquivo JSON de exemplo para criação automática.
**Campo de Data Obrigatório**: Para garantir a correta ordenação e busca dos dados, é **obrigatório** definir um campo de data principal no seu modelo (Data do Evento). O sistema utiliza este campo para organizar seus dados temporalmente.
## Passo 1: Upload de Arquivos
**Sistema antigo descontinuado!** O endpoint `POST /api/v1/schemas/{slug}/files` não funciona mais.
Para realizar o upload de arquivos, você deve seguir dois subpassos:
### 1.1 Gerar Token de Upload
Primeiro, solicite uma URL de upload na nuvem fazendo uma requisição POST:
```bash theme={null}
curl -X POST \
"https://api.datasnap.cloud/api/v1/schemas/logs-de-acoes/generate-upload-token" \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-H "Content-Type: application/json" \
-d '{"minutes": 15}'
```
**Resposta:**
```json theme={null}
{
"id": 8,
"upload_url": "{pre_signed_url}",
"expires_at": "2025-10-03T03:29:08.000000Z",
"success": true
}
```
**Importante**: A URL de upload tem validade limitada (15 minutos no exemplo). Após o horário em `expires_at`, a URL expira automaticamente e você deve gerar um novo token.
### 1.2 Fazer Upload do Arquivo
Com a URL de upload obtida, faça o upload do arquivo usando PUT na URL retornada + nome do arquivo:
```bash theme={null}
curl -X PUT \
"{pre_signed_url}/nome-do-arquivo.jsonl" \
-H "Content-Type: application/octet-stream" \
--data-binary "@dados.jsonl"
```
**Regras importantes para o upload:**
* O nome do arquivo deve ser incluído na URL
* Sempre use a extensão `.jsonl` no nome do arquivo
* Cada upload deve ter um nome de arquivo único
* O arquivo deve estar no formato JSONL (um objeto JSON por linha)
* **Tamanho máximo**: 10MB por arquivo para melhor experiência
### Preparando seus dados
Seus arquivos devem estar no formato JSONL (JSON Lines), onde cada linha contém um objeto JSON válido:
```jsonl theme={null}
{"data_evento": "2024-10-01", "nome": "João Silva", "idade": 30, "cidade": "São Paulo"}
{"data_evento": "2024-10-02", "nome": "Maria Santos", "idade": 25, "cidade": "Rio de Janeiro"}
{"data_evento": "2024-10-03", "nome": "Carlos Oliveira", "idade": 35, "cidade": "Belo Horizonte"}
```
## Passo 2: Consultas
Após o upload, você pode realizar consultas nos seus dados imediatamente.
### Consulta simples
```bash cURL theme={null}
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": 25}
],
"order_by": [
{"field": "idade", "direction": "desc"}
],
"limit": 10
}'
```
```python Python theme={null}
import requests
url = "https://api.datasnap.cloud/api/v1/schemas/meu-schema/query"
headers = {
"Authorization": "Bearer SEU_TOKEN_AQUI",
"Content-Type": "application/json"
}
data = {
"select": ["nome", "idade", "cidade"],
"event_from": "2024-01-01",
"event_to": "2024-12-31",
"where": [
{"field": "idade", "op": ">", "value": 25}
],
"order_by": [
{"field": "idade", "direction": "desc"}
],
"limit": 10
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
```
```javascript JavaScript theme={null}
const queryData = {
select: ["nome", "idade", "cidade"],
event_from: "2024-01-01",
event_to: "2024-12-31",
where: [
{field: "idade", op: ">", value: 25}
],
order_by: [
{field: "idade", direction: "desc"}
],
limit: 10
};
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(queryData)
})
.then(response => response.json())
.then(data => console.log(data));
```
### Consulta com agregação
Você também pode realizar consultas mais complexas com agrupamentos e funções de agregação:
```json theme={null}
{
"select": ["cidade", "count(*) as total", "avg(idade) as idade_media"],
"group_by": ["cidade"],
"order_by": [
{"field": "total", "direction": "desc"}
],
"limit": 5
}
```
**Que tal construir suas consultas de forma visual e interativa?**
🎯 **Acesse nossa tela de consultas no painel DataSnap** e construa suas queries selecionando campos, aplicando filtros e visualizando resultados em tempo real!
✨ **Benefícios:**
* ✅ **Interface visual intuitiva** - construa consultas sem escrever SQL
* ✅ **Geração automática do JSON** - copie o código gerado para usar na API
* ✅ **Preview de resultados** - veja os dados antes de executar na API
* ✅ **Histórico de consultas** - salve e reutilize suas consultas favoritas
* ✅ **Construtor de agregações** - crie métricas complexas facilmente
🔗 **Acesse:** [Painel DataSnap](https://app.datasnap.cloud) → Modelo de Dados → Modelo → Consultar Registros
*Dessa forma você acelera o desenvolvimento e evita erros de sintaxe!*
## Próximos passos
Agora que você conhece o fluxo básico, explore recursos mais avançados:
Aprenda a listar, filtrar e gerenciar seus arquivos enviados.
Domine filtros complexos, paginação e formatos de resposta.
Entenda os formatos suportados e melhores práticas para seus dados.
Explore toda a documentação da API com exemplos detalhados.
**Precisa de ajuda?** Entre em contato com nosso [suporte](mailto:support@datasnap.cloud) ou acesse nossa [central de ajuda](https://datasnap.cloud/support).