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

# Referência Técnica

Esta seção detalha a estrutura técnica do banco de dados PostgreSQL 18 do S.Analytics, incluindo tabelas principais, campos, tipos de dados e índices de performance.

## Tabela Principal: `events`

A tabela `events` é o coração do sistema de rastreamento do Synapside. Cada evento coletado é armazenado como uma linha nesta tabela.

### Estrutura da Tabela

```sql theme={null}
CREATE TABLE events (
  event_uuid UUID PRIMARY KEY,
  user_uuid UUID NOT NULL,
  event_type VARCHAR(50) NOT NULL,
  event_ts TIMESTAMP WITH TIME ZONE NOT NULL,
  recorded_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  data JSONB,
  session_uuid UUID,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
```

### Campos Principais

| Campo          | Tipo                     | Descrição                                                                      |
| -------------- | ------------------------ | ------------------------------------------------------------------------------ |
| `event_uuid`   | UUID                     | Identificador único do evento (chave primária)                                 |
| `user_uuid`    | UUID                     | Identificador único do usuário que gerou o evento                              |
| `event_type`   | VARCHAR(50)              | Tipo do evento (pageview, click, form\_submit, session\_start, ou customizado) |
| `event_ts`     | TIMESTAMP WITH TIME ZONE | Data e hora em que o evento ocorreu (com timezone)                             |
| `recorded_at`  | TIMESTAMP WITH TIME ZONE | Data e hora em que o evento foi registrado no banco                            |
| `data`         | JSONB                    | Campo flexível contendo dados específicos do evento (estrutura varia por tipo) |
| `session_uuid` | UUID                     | Identificador da sessão do usuário                                             |
| `created_at`   | TIMESTAMP WITH TIME ZONE | Timestamp de criação do registro                                               |

### Tipos de Dados

* **UUID:** Identificador único universal de 128 bits, ideal para distribuição e evitar colisões
* **VARCHAR(50):** String de tamanho variável para tipos de eventos
* **TIMESTAMP WITH TIME ZONE:** Permite armazenar timestamps com informação de timezone, essencial para análises globais
* **JSONB:** Formato JSON binário do PostgreSQL, permite armazenamento flexível e consultas eficientes

## Tabela: `user_identities`

A tabela `user_identities` mapeia identidades conhecidas (email, ID de cliente, etc) ao `user_uuid` centralizado.

### Estrutura da Tabela

```sql theme={null}
CREATE TABLE user_identities (
  identity_uuid UUID PRIMARY KEY,
  user_uuid UUID NOT NULL REFERENCES events(user_uuid),
  identity_type VARCHAR(50) NOT NULL,
  identity_value VARCHAR(255) NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
```

### Campos

| Campo            | Tipo                     | Descrição                                                                  |
| ---------------- | ------------------------ | -------------------------------------------------------------------------- |
| `identity_uuid`  | UUID                     | Identificador único da identificação                                       |
| `user_uuid`      | UUID                     | Usuário anônimo que foi identificado (chave de JOIN com events.user\_uuid) |
| `identity_type`  | VARCHAR(50)              | Método de identificação (email, phone, user\_id, etc.)                     |
| `identity_value` | VARCHAR(255)             | Valor do identificador                                                     |
| `event_ts`       | TIMESTAMP WITH TIME ZONE | Momento em que a identificação foi registrada                              |
| `recorded_at`    | TIMESTAMP WITH TIME ZONE | Momento de gravação no banco                                               |
| `data`           | JSONB                    | Campo flexível contendo dados específicos da identificação                 |

## Exemplos de Consultas Úteis

### Contar eventos por tipo (últimos 30 dias)

```sql theme={null}
SELECT
  event_type,
  COUNT(*) as total
FROM events
WHERE event_ts >= NOW() - INTERVAL '30 days'
GROUP BY event_type
ORDER BY total DESC;
```

### Usuários únicos por dia

```sql theme={null}
SELECT
  DATE(event_ts) as data,
  COUNT(DISTINCT user_uuid) as usuarios_unicos
FROM events
WHERE event_ts >= NOW() - INTERVAL '7 days'
GROUP BY DATE(event_ts)
ORDER BY data DESC;
```

### Identificar usuários por email

```sql theme={null}
SELECT DISTINCT
  e.user_uuid,
  ui.identity_value as email,
  COUNT(e.event_uuid) as total_eventos
FROM events e
JOIN user_identities ui ON e.user_uuid = ui.user_uuid
WHERE ui.identity_type = 'email'
  AND ui.identity_value LIKE '%@example.com'
GROUP BY e.user_uuid, ui.identity_value
ORDER BY total_eventos DESC;
```