Interactive Shell

The interactive shell is a SQL REPL that gives you direct access to your data lake with syntax highlighting, autocomplete, and special dot commands.

Launch

dataspoc-lens shell

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

lens>

Features

• Syntax highlighting — SQL keywords, strings, and numbers are color-coded via Pygments
• Autocomplete — table names, column names, and SQL keywords with Tab completion
• Command history — persistent across sessions, stored in ~/.dataspoc-lens/history
• Multi-line queries — queries run when you type ; at the end
• Rich output — results displayed as formatted tables

Dot commands

Dot commands are special shell commands that start with . and provide quick access to metadata and utilities.

Command	Description
.tables	List all mounted tables
.schema <table>	Show column names and types for a table
.buckets	List all registered buckets
.cache [table]	Cache a table locally for offline use
.export <format> <path>	Export the last query result to a file
.help	Show available dot commands
.quit	Exit the shell

Example session

lens> .tables
  customers
  orders
  products

lens> .schema orders
  order_id     INTEGER
  customer_id  INTEGER
  order_date   DATE
  total        DOUBLE
  status       VARCHAR

lens> SELECT status, COUNT(*) as cnt, AVG(total) as avg_total
   ...> FROM orders
   ...> GROUP BY status;
┌───────────┬───────┬───────────┐
│ status    │ cnt   │ avg_total │
├───────────┼───────┼───────────┤
│ completed │ 32100 │ 85.40     │
│ pending   │ 8450  │ 72.15     │
│ cancelled │ 2130  │ 45.20     │
└───────────┴───────┴───────────┘

(3 row(s), 0.089s)

lens> .export csv /tmp/order_stats.csv
Exported 3 row(s) to /tmp/order_stats.csv

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

lens> .buckets
  s3://my-company-data

lens> .quit

Using AI inside the shell

If you have configured an AI provider (via setup-ai or environment variables), you can ask natural language questions directly in the shell by prefixing your input with ask:

lens> ask What is the average order value by month?

SQL: SELECT DATE_TRUNC('month', order_date) as month,
     AVG(total) as avg_order_value
     FROM orders GROUP BY month ORDER BY month

┌────────────┬─────────────────┐
│ month      │ avg_order_value │
├────────────┼─────────────────┤
│ 2024-01-01 │ 78.50           │
│ 2024-02-01 │ 82.30           │
│ 2024-03-01 │ 91.20           │
└────────────┴─────────────────┘

(3 row(s), 1.150s)

Keyboard shortcuts

Shortcut	Action
Tab	Autocomplete
Up / Down	Navigate command history
Ctrl+C	Cancel current input
Ctrl+D	Exit the shell