Duck Plot CLI

A command-line tool for visualizing SQL query results using DuckDB and Altair charts.

Installation

Install this tool using pip:

pip install duck-plot

or run the cli with uvx in a temporary virtual environment:

uvx duck-plot ...

Features

• Execute SQL queries against DuckDB databases or in-memory data
• Create line or bar charts from query results
• Display query results in a rich formatted table
• Support for piped input and command-line arguments
• Interactive visualizations in the browser

Usage

Basic Query Visualization

Create a line chart from query results:

duck-plot "SELECT date, sales FROM 'sales.csv'" -x date -y sales

Create a bar chart:

duck-plot "SELECT category, count(*) as total FROM 'sales.csv' GROUP BY 1" -x category -y total --type bar

Using a DuckDB Database

Query an existing DuckDB database:

duck-plot "SELECT * FROM monthly_sales" -x month -y revenue --db sales.duckdb

Piping Queries

Use heredoc for complex queries:

cat << EOF | duck-plot -x month -y total_sales --type bar
SELECT 
    date_trunc('month', date) as month,
    sum(sales) as total_sales 
FROM sales 
GROUP BY 1 
ORDER BY 1
EOF

Query-Only Mode

You have the option to only display results without creating a chart:

duck-plot "SELECT * FROM sales LIMIT 5" --query-only

or use a pipe:

echo "SELECT * FROM 'sales.parquet'" | duck-plot --query-only --db sales.duckdb

Options

Arguments:
  query                  SQL query to execute [optional if piping input]

Options:
  -x, --x TEXT          Column name for X-axis
  -y, --y TEXT          Column name for Y-axis
  -t, --type TEXT       Type of chart (line or bar) [default: line]
  -d, --db TEXT         Path to DuckDB database file [optional]
  -q, --query-only      Output query results to stdout and skip chart creation
  --help                Show this message and exit

Examples

Analyzing Time Series Data

duck-plot "
SELECT 
    date,
    moving_average(price, 7) as price_ma
FROM 'stock_prices.csv'
WHERE symbol = 'AAPL'
ORDER BY date
" -x date -y price_ma

Comparing Categories

duck-plot "
SELECT 
    category,
    sum(revenue) as total_revenue
FROM 'sales.csv'
GROUP BY category
ORDER BY total_revenue DESC
LIMIT 10
" -x category -y total_revenue --type bar

Interactive Data Exploration

# First view the available columns
duck-plot "FROM dataset LIMIT 1" --query-only

# Then create visualizations based on the columns
duck-plot "FROM dataset" -x timestamp -y temperature

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development

To contribute to this tool, first checkout the code. Then create a new virtual environment:

cd duck-plot
python -m venv venv
source venv/bin/activate

Now install the dependencies and test dependencies:

pip install -e '.[test]'

To run the tests:

python -m pytest