Quickstart

Este guia mostra como configurar o DataSpoc Lens e executar suas primeiras consultas em um data lake.

1. Instalar o Lens

pip install dataspoc-lens[s3]

Substitua [s3] por [gcs] ou [azure] dependendo do seu provedor de nuvem.

2. Inicializar a configuração

dataspoc-lens init

Initialized DataSpoc Lens in ~/.dataspoc-lens

Isso cria o diretório de configuração em ~/.dataspoc-lens/ com um config.yaml padrão.

3. Registrar um bucket

dataspoc-lens add-bucket s3://my-company-data

Bucket added: s3://my-company-data
Discovering tables...
┌──────────────┬─────────┬──────┬────────────┐
│ Table        │ Columns │ Rows │ Source     │
├──────────────┼─────────┼──────┼────────────┤
│ customers    │ 8       │ 5420 │ postgres   │
│ orders       │ 12      │ 48k  │ postgres   │
│ products     │ 6       │ 312  │ postgres   │
└──────────────┴─────────┴──────┴────────────┘

3 table(s) found.

O Lens lê o manifest escrito pelo DataSpoc Pipe (ou escaneia por arquivos .parquet) e monta cada tabela como uma view DuckDB.

4. Explorar o catálogo

dataspoc-lens catalog

┌──────────────┬─────────┬──────┬────────────┐
│ Table        │ Columns │ Rows │ Source     │
├──────────────┼─────────┼──────┼────────────┤
│ customers    │ 8       │ 5420 │ postgres   │
│ orders       │ 12      │ 48k  │ postgres   │
│ products     │ 6       │ 312  │ postgres   │
└──────────────┴─────────┴──────┴────────────┘

Veja detalhes das colunas de uma tabela específica:

dataspoc-lens catalog --detail orders

┌─────────────────┬───────────┐
│ Column          │ Type      │
├─────────────────┼───────────┤
│ order_id        │ INTEGER   │
│ customer_id     │ INTEGER   │
│ order_date      │ DATE      │
│ total           │ DOUBLE    │
│ status          │ VARCHAR   │
└─────────────────┴───────────┘

5. Executar uma consulta SQL

dataspoc-lens query "SELECT status, COUNT(*) as cnt FROM orders GROUP BY status"

┌───────────┬───────┐
│ status    │ cnt   │
├───────────┼───────┤
│ completed │ 32100 │
│ pending   │ 8450  │
│ cancelled │ 2130  │
└───────────┴───────┘

(3 row(s), 0.142s)

6. Abrir o shell interativo

dataspoc-lens shell

DataSpoc Lens Shell (DuckDB)
Type SQL or .help for commands.

lens> SELECT * FROM customers LIMIT 3;
┌─────┬──────────────┬───────────────────────┐
│ id  │ name         │ email                 │
├─────┼──────────────┼───────────────────────┤
│ 1   │ Alice Smith  │ alice@example.com     │
│ 2   │ Bob Johnson  │ bob@example.com       │
│ 3   │ Carol White  │ carol@example.com     │
└─────┴──────────────┴───────────────────────┘

(3 row(s), 0.008s)

lens> .quit

7. Configurar consultas com IA (opcional)

Para IA local gratuita usando Ollama:

dataspoc-lens setup-ai

Ou configure um provedor na nuvem:

export DATASPOC_LLM_PROVIDER=anthropic
export DATASPOC_LLM_API_KEY=sk-ant-...

8. Fazer perguntas em linguagem natural

dataspoc-lens ask "What are the top 5 customers by total spending?"

SQL: SELECT c.name, SUM(o.total) as total_spent
     FROM customers c JOIN orders o ON c.id = o.customer_id
     GROUP BY c.name ORDER BY total_spent DESC LIMIT 5

┌──────────────┬─────────────┐
│ name         │ total_spent │
├──────────────┼─────────────┤
│ Alice Smith  │ 15420.50    │
│ Bob Johnson  │ 12300.00    │
│ Carol White  │ 9870.25     │
│ Dave Brown   │ 8540.00     │
│ Eve Davis    │ 7210.75     │
└──────────────┴─────────────┘

(5 row(s), 1.230s)

Próximos passos

• Shell Interativo — aprenda dot commands e recursos do shell
• AI Ask — configure provedores de IA e uso avançado
• Notebooks — use Jupyter ou Marimo com seus dados
• Referência de Comandos — referência completa da CLI