List all tables with their column names and types.

Call this first to understand what data is available before querying.

Show the first few rows of a table to understand its structure.

Use this after list_tables to see what the actual data looks like.

List utilities, optionally filtered by two-letter state code (e.g. 'CO', 'TX').

Returns utility and parent names, EIA/FERC1 IDs, RMI utility type, and — when a state is given — the capacity that utility owns in that state (MW), largest first. name_contains additionally filters on utility or parent name (case-insensitive substring). Use this to find the right utility name before pulling emissions or generation data.

Get yearly CO2 emissions and 1.5°C pathway comparison for a utility.

Returns historical CO2 (MMT), emissions implied by the utility's stated targets, its IRP projection, and RMI's 1.5°C benchmark — plus generation (TWh) and emissions intensity (metric tons/MWh).

basis selects the accounting boundary and MUST be one of: "delivered" (default) — emissions behind the power the utility sells "owned" — emissions from generation the utility owns "all" — both, distinguished by the owned_delivered column The two bases are separate row sets; never sum across them. The search is case-insensitive and supports partial names.

Get electricity generation breakdown by technology for a utility.

Shows capacity (GW), net generation (TWh), capacity factor, and CO2 emissions (MMT) by RMI technology group (Coal, Gas, Wind, Solar, Nuclear, Hydro, Storage, ...).

By default this covers only generation the utility OWNS. The underlying table also carries non-owned energy_source rows — wholesale power purchases, net exchanges, wheeled power, energy efficiency, demand response, and negative transmission losses. Those are supply, not generation, and summing them together with owned output overstates the fleet and mixes in negative rows. Set include_purchases=True to get them as separate rows, split by the energy_source and owned_energy_source columns.

The search is case-insensitive and supports partial names. Optionally filter to a single year; defaults to all years (2005-2024).

Compare a utility's emissions to RMI's 1.5°C pathway, year by year.

Adds a gap column (CO2 minus the 1.5°C benchmark: positive = above the pathway) and a status label. Historical years use reported CO2; future years fall back to the utility's stated target, then its IRP projection.

basis is "delivered" (default), "owned", or "all" — see get_emissions_trend. The search is case-insensitive and supports partial names.

Run a read-only SQL query against the database. DuckDB SQL syntax.

Call list_tables() first to see available tables and columns. One SELECT statement per call (a leading WITH ... CTE is fine).

There is no single join key across all tables: utility_id_eia — utility_information, utility_state_map, operations_emissions_by_tech / _by_fuel, reliability utility_id_ferc1 — utility_information, customers_sales, revenue_by_tech, assets_earnings_investments, debt_equity_returns, net_plant_balance respondent_id — expenditure_bills_burden, housing_units_income only emissions_targets has NO id column; join it on utility_name_irp / parent_name. utility_name and parent_name appear in most tables directly.

Two traps worth knowing: emissions_targets holds separate 'owned' and 'delivered' row sets — filter owned_delivered or you double-count. operations_emissions_by_tech mixes owned generation with purchased power, exchanges, EE/DR, and negative transmission losses — filter owned_energy_source for generation only.

Example: SELECT utility_name_irp, year, emissions_co2_historical, emissions_co2_1point5c FROM emissions_targets WHERE year >= 2015 AND owned_delivered = 'delivered' ORDER BY emissions_co2_historical DESC LIMIT 20