> ## Documentation Index
> Fetch the complete documentation index at: https://docs.analytics.synapside.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SQL Livre

O Synapside CDP oferece um endpoint para a execução flexível de comandos SQL diretamente no schema isolado do seu projeto. Esse recurso é voltado para usuários avançados que necessitam de operações complexas que os endpoints estruturados não cobrem.

[Documentação da API >](https://docs.analytics.synapside.com/api-reference/sql/sql-livre)

## O que é possível fazer?

* **Consultas (SELECT):** Realizar buscas complexas ou agregações de dados.
* **Manipulação de Dados (DML):** `INSERT`, `UPDATE` e `DELETE` em massa.
* **Mudanças Estruturais (DDL):** `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE` e `TRUNCATE`.

***

## Como funciona

Ao chamar este endpoint, sua query SQL é executada utilizando a **Role PostgreSQL dedicada** do seu projeto (`cdp_project_{id}`).

### Segurança por Design

O isolamento é garantido nativamente pelo banco de dados:

1. Sua role possui permissões exclusivamente no seu schema (`project_{id}_cdp`).
2. Se você tentar acessar um schema de outro projeto (ex: `SELECT * FROM project_2_cdp.users`), o PostgreSQL retornará um erro `403 Forbidden (Permission Denied)`.
3. Você não precisa se preocupar em qualificar suas tabelas com o nome do schema (ex: `SELECT * FROM leads` funcionará perfeitamente).

***

## Exemplo de Requisição (SELECT)

Busque leads com idade superior a 25 anos:

```json theme={null}
{
  "sql": "SELECT * FROM leads WHERE idade > 25"
}
```

### Exemplo de Resposta (Sucesso)

```json theme={null}
{
  "success": true,
  "type": "SELECT",
  "rows": [
    { "id": "...", "email": "ana@exemplo.com", "idade": 28 },
    { "id": "...", "email": "marcos@exemplo.com", "idade": 32 }
  ],
  "row_count": 2
}
```

***

## Melhores Práticas

* **Uso criterioso:** Embora potente, o endpoint SQL deve ser usado com cuidado para não causar deleções acidentais em massa.
* **Ponto e Vírgula:** Não é necessário finalizar sua query com `;` no payload JSON.
* **Sincronização:** Comandos DDL (`CREATE`, `ALTER`, `DROP`) acionam automaticamente o `sync_schema` no seu painel Metabase.