Cache

O Lens pode cachear arquivos Parquet remotos localmente para que você possa trabalhar offline e evitar cobranças repetidas de egress da nuvem.

Cachear uma tabela

dataspoc-lens cache orders

Caching 'orders'...
Cached 'orders': 4 file(s), 12.3 MB

Isso baixa todos os arquivos Parquet da tabela orders para seu diretório de cache local.

Listar tabelas cacheadas

dataspoc-lens cache --list

┌──────────────┬─────────────────────┬──────────┬────────┐
│ Table        │ Cached At           │ Size     │ Status │
├──────────────┼─────────────────────┼──────────┼────────┤
│ orders       │ 2026-04-15 10:30:00 │ 12.3 MB  │ fresh  │
│ customers    │ 2026-04-14 08:00:00 │ 2.1 MB   │ stale  │
└──────────────┴─────────────────────┴──────────┴────────┘

Para saída em JSON:

dataspoc-lens cache --list --output json

Forçar re-download

dataspoc-lens cache orders --refresh

Baixa os dados mais recentes mesmo que já exista uma cópia local.

Limpar cache

# Clear a specific table
dataspoc-lens cache orders --clear

# Clear all cached data
dataspoc-lens cache --clear

Detecção de frescor

O Lens determina o frescor do cache comparando dois timestamps:

1. cached_at — quando o cache local foi criado
2. last_extraction — o timestamp da última extração no manifest do Pipe

Se o Pipe executou uma extração depois que o cache foi criado, o cache é marcado como stale. Caso contrário, é fresh.

Condição	Status	Comportamento
cached_at > last_extraction	fresh	Queries usam o cache local
cached_at < last_extraction	stale	Queries ainda usam o cache, mas um aviso é exibido
Sem cache	—	Queries leem diretamente do bucket remoto

Uso automático do cache

Quando você executa consultas (via query, shell, ask ou notebooks), o Lens usa automaticamente o cache local para tabelas que possuem uma cópia cacheada e atualizada. Nenhuma configuração é necessária — mount_views() detecta o cache e muda a view DuckDB para ler do caminho local ao invés do bucket remoto.

Estrutura de diretórios

Os arquivos cacheados ficam em ~/.dataspoc-lens/cache/:

~/.dataspoc-lens/
  cache/
    orders/
      part-0001.parquet
      part-0002.parquet
      part-0003.parquet
      part-0004.parquet
    customers/
      part-0001.parquet
    cache_meta.json          # Metadata: cached_at, size, freshness per table

Fluxo de trabalho: análise offline

# 1. Cache the tables you need while online
dataspoc-lens cache orders
dataspoc-lens cache customers
dataspoc-lens cache products

# 2. Verify cache
dataspoc-lens cache --list

# 3. Go offline and query normally
dataspoc-lens query "SELECT * FROM orders JOIN customers USING (customer_id)"
dataspoc-lens shell
dataspoc-lens ask "Top customers by revenue"

Todas as consultas vão ler do cache local de forma transparente.