mcpField
A
analyzing-data

analyzing-data

github.com/astronomerData & databases4571.4k installsUpdated 3w ago
Repository

About analyzing-data

A data analysis skill for querying a data warehouse to answer business questions. It combines SQL execution with caches for query strategies, table concepts, and schemas.

Key features

  1. 01Execute SQL through a managed kernel
  2. 02Run independent queries concurrently
  3. 03Cache query strategies and outcomes
  4. 04Look up and store table concepts
  5. 05Cache table schemas

Use cases

  1. 01Answer business questions with warehouse data
  2. 02Reuse a known query strategy
  3. 03Find table mappings when exploring data
  4. 04Run independent queries together

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/astronomer/agents --skill analyzing-data

After installing, type/analyzing-datain Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

reference/
common-patterns.md
discovery-warehouse.md
scripts/
.gitignore
cache.py
cli.py
config.py
connectors.py
kernel.py
pyproject.toml
templates.py
ty.toml
warehouse.py
scripts/tests/
__init__.py
conftest.py
test_cache.py
test_config.py
test_connectors.py
test_kernel.py
test_utils.py
test_warehouse.py
scripts/tests/integration/
__init__.py
conftest.py
test_duckdb_e2e.py
test_kernel_interrupt.py
test_postgres_e2e.py
test_sqlite_e2e.py

Details

From the project README

Data Analysis

Answer business questions by querying the data warehouse. The kernel auto-starts on first exec call.

All CLI commands below are relative to this skill's directory. Before running any scripts/cli.py command, cd to the directory containing this file.

Workflow

  1. Pattern lookup — Check for a cached query strategy:

    uv run scripts/cli.py pattern lookup "<user's question>"

    If a pattern exists, follow its strategy. Record the outcome after executing:

    uv run scripts/cli.py pattern record <name> --success  # or --failure

  2. Concept lookup — Find known table mappings:

    uv run scripts/cli.py concept lookup <concept>

  3. Table discovery — If cache misses, search the codebase (Grep pattern="<concept>" glob="**/*.sql") or query INFORMATION_SCHEMA. See reference/discovery-warehouse.md.

  4. Execute query:

    uv run scripts/cli.py exec "df = run_sql('SELECT ...')"
uv run scripts/cli.py exec "print(df)"

  5. Cache learnings — Always cache before presenting results:

    # Cache concept → table mapping
uv run scripts/cli.py concept learn <concept> <TABLE> -k <KEY_COL>
# Cache query strategy (if discovery was needed)
uv run scripts/cli.py pattern learn <name> -q "question" -s "step" -t "TABLE" -g "gotcha"

  6. Present findings to user.

Kernel Functions

FunctionReturns
run_sql(query, limit=100)Polars DataFrame
run_sql_pandas(query, limit=100)Pandas DataFrame
run_sql_many(queries, limit=100)List of Polars DataFrames (one per query)

pl (Polars) and pd (Pandas) are pre-imported.

Run independent queries together with run_sql_many — they execute concurrently (Snowflake async / connection-pool fan-out) instead of one at a time:

uv run scripts/cli.py exec "dfs = run_sql_many(['SELECT ...', 'SELECT ...']); print(dfs[0])"

run_sql_many is fail-fast: if any query errors, the call raises and the results of the queries that succeeded are discarded. Use separate run_sql calls if you need partial results.

Timeouts: exec waits up to 120s by default, then interrupts the query and returns a "client stopped waiting" message (the query may still finish server-side). Raise it for known long-running queries: uv run scripts/cli.py exec "..." -t 600.

Idle kernel: the kernel self-terminates after 2h idle (preserving state until then). Override with ASTRO_KERNEL_IDLE_TIMEOUT (seconds; 0 disables).

CLI Reference

Kernel
uv run scripts/cli.py warehouse list      # List warehouses
uv run scripts/cli.py start [-w name]     # Start kernel (with optional warehouse)
uv run scripts/cli.py exec "..."          # Execute Python code
uv run scripts/cli.py status              # Kernel status
uv run scripts/cli.py restart             # Restart kernel
uv run scripts/cli.py stop                # Stop kernel
uv run scripts/cli.py install <pkg>       # Install package
Concept Cache
uv run scripts/cli.py concept lookup <name>                     # Look up
uv run scripts/cli.py concept learn <name> <TABLE> -k <KEY_COL> # Learn
uv run scripts/cli.py concept list                               # List all
uv run scripts/cli.py concept import -p /path/to/warehouse.md   # Bulk import
Pattern Cache
uv run scripts/cli.py pattern lookup "question"                                      # Look up
uv run scripts/cli.py pattern learn <name> -q "..." -s "..." -t "TABLE" -g "gotcha"  # Learn
uv run scripts/cli.py pattern record <name> --success                                # Record outcome
uv run scripts/cli.py pattern list                                                   # List all
uv run scripts/cli.py pattern delete <name>                                          # Delete
Table Schema Cache
uv run scripts/cli.py table lookup <TABLE>            # Look up schema
uv run scripts/cli.py table cache <TABLE> -c '[...]'  # Cache schema
uv run scripts/cli.py table list                       # List cached
uv run scripts/cli.py table delete <TABLE>             # Delete
Cache Management
uv run scripts/cli.py cache status                # Stats
uv run scripts/cli.py cache clear [--stale-only]  # Clear

References

Comments

Markdown supported