📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Módulo 08: Bancos de Dados SQL e NoSQL. Recomendado revisar antes de começar.

🌾 Séries Temporais IoT em Alta Escala no Apache Cassandra

v1.0 — Modelagem Query-Driven, Chaves Compostas e Expiração Nativa com TTL

Trilha de Engenharia de Dados & Bancos de Dados — Projeto 6 de 10

• v1: Modelagem Relacional 3FN · PostgreSQL 16
• v2: Modelagem NoSQL · MongoDB 7.0
• v3: Estratégias de Cache · Redis 7.2
• v4: DBA Enterprise · Particionamento & RLS · PostgreSQL 16
• v5: Modelagem Visual EER & Stored Procedures · MySQL 8.0
• ➡️ v6 (este): Séries Temporais IoT · Apache Cassandra 5.0
• v7: Prontuário Objeto-Relacional & JSONB · PostgreSQL 16
• v8: Rastreamento de Fraudes em Grafos · Neo4j 5.x
• v9: Data Warehouse & Consultas OLAP · PostgreSQL 16
• v10: Persistência Poliglota Integrada · Postgres + Mongo + Redis

🎓 Nível Profissional Simulado: Data Engineer / Distributed Systems Specialist. Em sistemas de telemetria agroindustrial com dezenas de milhares de sensores emitindo dados a cada 5 segundos, a arquitetura distribuída do Cassandra (LSM Trees sem master) garante vazão massiva de escrita e consultas rápidas por partição.

🎯 Objetivo

Desenvolver um modelo de dados colunar orientado a consultas (Query-Driven Modeling) no Apache Cassandra 5.0 para monitoramento de sensores ambientais em silos de grãos, utilizando Chave de Partição Composta ((silo_id, data_leitura), horario), ordenação física em disco (Clustering Order) e expiração de dados com TTL de 60 dias.

🏗️ Diagrama de Particionamento Colunar no Cassandra

graph TD
    classDef ring fill:#1A365D,stroke:#63B3ED,stroke-width:2px,color:#fff;
    classDef part fill:#2A4365,stroke:#90CDF4,stroke-width:1px,color:#fff;
    classDef row fill:#2C5282,stroke:#BEE3F8,stroke-width:1px,color:#fff;

    Ring["🪐 Cassandra Ring (Cluster Distribuído)"]:::ring

    Ring --> P1["📦 Partição: (silo_1, '2026-08-27')"]:::part
    Ring --> P2["📦 Partição: (silo_1, '2026-08-28')"]:::part
    Ring --> P3["📦 Partição: (silo_2, '2026-08-27')"]:::part

    P1 --> R1["🕒 23:59:00 | 24.5°C | 13.2% | CO2: 410 (TTL: 60d)"]:::row
    P1 --> R2["🕒 23:58:00 | 24.6°C | 13.1% | CO2: 412 (TTL: 60d)"]:::row

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Diretor de Operações de Cooperativa Agrícola)

“Nossos 200 silos armazenam milhões de toneladas de soja e milho. Se a umidade subir ou a temperatura passar de 28°C, os grãos fermentam e o prejuízo é milionário. Temos sensores de temperatura, umidade e CO2 enviando dados sem parar. O banco antigo travava na hora de gravar tantos registros. Precisamos de um banco que suporte milhares de gravações por segundo e que delete automaticamente os dados antigos após 60 dias sem precisar de rotinas pesadas de limpeza.”

Requisitos Funcionais (RF) e Não-Funcionais (RNF)

📋 Fase 2 — Backlog & User Stories

🌿 Fase 3 — Engenharia em Equipe (Git Flow & Setup)

# Branch da funcionalidade
git checkout -b feature/US01-cassandra-timeseries

# Subir o Cassandra isolado via Docker
docker-compose up -d

# Conectar no console cqlsh
docker exec -it db_cassandra_agro cqlsh -u cassandra -p cassandra

🛠️ Fase 4 — Implementação Passo a Passo (cql/01_schema_keyspace.cql)

CREATE KEYSPACE IF NOT EXISTS agrosense 
WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};

CREATE TABLE IF NOT EXISTS agrosense.telemetria_silo (
    silo_id uuid,
    data_leitura date,
    horario timestamp,
    temperatura_graos double,
    umidade_relativa double,
    nivel_co2 double,
    status_alerta text,
    PRIMARY KEY ((silo_id, data_leitura), horario)
) WITH CLUSTERING ORDER BY (horario DESC);

🧭 Decisões Técnicas (ADRs)

• ADR 001: Adoção de chave de partição composta e TTL nativo no Cassandra para ingestão maciça de telemetria IoT.

🚀 Como Executar no Laboratório

1. Abra o terminal na pasta deste projeto

No seu editor/IDE, abra a pasta deste projeto (File > Open Folder) ou navegue via terminal:

cd db_nosql_06_cassandra_timeseries

2. Execute a aplicação ou testes

docker-compose up -d
# Executar a suíte de testes automatizados:
python -m unittest tests/test_cassandra_timeseries.py

[!TIP] Dica para execução a partir da raiz do repositório: Se você abriu o repositório completo no VS Code, basta navegar até a pasta antes de executar: cd catalogo_projetos/db_nosql_06_cassandra_timeseries

🧪 Testes de Validação & Asserções

-- Inserir telemetria com TTL
INSERT INTO agrosense.telemetria_silo (
    silo_id, data_leitura, horario, temperatura_graos, umidade_relativa, nivel_co2
) VALUES (
    550e8400-e29b-41d4-a716-446655440000,
    '2026-08-27',
    toTimestamp(now()),
    24.5, 13.2, 410.0
) USING TTL 5184000;

-- Consultar exatamente a partição do dia
SELECT horario, temperatura_graos, umidade_relativa 
FROM agrosense.telemetria_silo 
WHERE silo_id = 550e8400-e29b-41d4-a716-446655440000 
  AND data_leitura = '2026-08-27';

🏛️ Arquitetura Visual & Engenharia de Dados

A arquitetura abaixo demonstra o fluxo de persistência, otimização e isolamento dos componentes na subpasta cql/:

flowchart TD
    subgraph DDL["Modelagem & Schema (DDL)"]
        S1["Tabelas / Coleções"] --> S2["Constraints & Índices"]
    end
    subgraph DML["Regras & Automação (DML / PL)"]
        R1["Triggers / Aggregations"] --> R2["Procedimentos Transacionais"]
    end
    subgraph Perf["Otimização & Armazenamento"]
        P1["Planos EXPLAIN / Partições"] --> P2["Garantia de ACID / TTL"]
    end
    subgraph Homolog["Homologação & Qualidade"]
        Q1["Docker Compose & Scripts"] --> Q2["Checkpoints CP-01..05 PASS"]
    end

    DDL --> DML
    DML --> Perf
    Perf --> Homolog

    style DDL fill:#e3f2fd,stroke:#1976d2,stroke-width:1.5px
    style DML fill:#fffde7,stroke:#fbc02d,stroke-width:1.5px
    style Perf fill:#e8f5e9,stroke:#388e3c,stroke-width:1.5px
    style Homolog fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px

🎯 Engenharia de Requisitos & Modelagem Formal

👤 User Stories (Histórias de Usuário)

⚙️ Requisitos Funcionais (RF)

🛡️ Requisitos Não-Funcionais (RNF)

🔗 Matriz de Rastreabilidade (RTM)

🏁 Checkpoints de Qualidade & Homologação