Use when you need structured rows from financial/market/altdata tables.
For SEC filing narrative use sec_report_search instead. For company qualitative
discovery use company_search instead. For recent news + market events use
signal_list instead.
Execute a read-only PostgreSQL SELECT query on financial and alternative-data tables.
Call `get_table_schema` first to look up columns for a specific table. For alternative-data categories, call `list_tables(categories=[...])` to see tables + columns.
SQL constraints:
- No CTE (`WITH ... AS`) — use subqueries instead.
- Date columns are TEXT — use plain string comparison (`period_end >= '2024-01'`). Never use `::date` cast or `INTERVAL` arithmetic.
- No `ROUND(float8, int)` — use `CAST(value AS DECIMAL(10,2))` if rounding is needed.
- Structured-data queries: always filter by ticker (`WHERE ticker IN ('A','B','C')`; screening: `ticker NOT LIKE '%-%'` to exclude preferred stock). Alternative data is macro/industry/patent — no ticker filter required.
Structured data (tables grouped by domain):
## Market Data
- price_volume_history: Historical OHLCV price data, ~32M rows. MUST filter by ticker AND time_frame ('daily'|'weekly'|'monthly') to avoid timeout. Columns: ticker, period_end, time_frame, open, high, low, close, adj_close, volume, turnover, vwap, change, change_percent.
Ticker conventions:
* STOCK / ETF — bare 1–5 letters (AAPL, MSFT, SPY, QQQ, VOO, TLT). Foreign listings use exchange suffix: 1557.T (JP), 310960.KS (KR).
* INDEX — leading "^" (^GSPC=S&P 500, ^DJI, ^IXIC=NASDAQ Composite, ^NDX=NASDAQ 100, ^RUT=Russell 2000, ^VIX). Foreign indices: ^FTSE, ^GDAXI, ^N225, 000001.SS (Shanghai Composite), FTSEMIB.MI.
* COMMODITY — [code]+USD or +USX (CLUSD=WTI futures, BZUSD=Brent, NGUSD=natgas, GCUSD=gold, SIUSD=silver, HGUSD=copper, ZCUSX=corn, CTUSX=cotton). Suffix USX = priced in cents.
* FOREX — 6 letters base+quote, no separator (EURUSD, USDJPY, GBPUSD, USDCNY).
* CRYPTO — [token]+USD (BTCUSD, ETHUSD, SOLUSD, DOGEUSD, USDTUSD, USDCUSD).
Pitfalls:
1. Same asset, different tickers: NASDAQ 100 → index ^NDX (~26000) vs ETF QQQ (~640). Pick the one matching user intent.
2. WTI spot ≠ futures. CLUSD here is NYMEX futures, NOT spot (FRED has spot via DCOILWTICO).
3. Tickers with "." or "^" MUST be quoted in SQL: `WHERE ticker = '^NDX'`.
- index_price: Real-time price snapshot for 3 major US indices: S&P 500 (^GSPC), Dow Jones (^DJI), NASDAQ 100 (^NDX).
- equity_extended_rt: Extended-hours snapshot, one row per ticker (~6.1K US equities; PK=ticker; refreshed every few minutes — see extended_updated_at). Use ONLY for pre-market / after-hours / overnight quotes. Columns: ticker, company_name, market, price_current (last regular-session close), then three parallel blocks pre_* / after_* / overnight_* (price, change_val, change_rate, high, low, volume, turnover), plus extended_updated_at. For regular-session OHLCV history use price_volume_history; for valuation / fundamentals use company_snapshot. Japan tickers are NOT in this view yet — extended-hours data is US-only.
## Fundamentals
- financial_statements: Quarterly and annual financial data covering income statement, balance sheet, and cash flow statement. Filter by ticker + fiscal_period ('FY' annual, 'Q1'..'Q4' quarterly).
- company_snapshot: Real-time company snapshot, one row per company. Pre-computed metrics (ratios, percentages, per-share figures, growth rates) only — NOT raw statement line items. For raw statements use financial_statements; for qualitative discovery use company_search.
## Earnings
- earning_call_summary: Earnings call data with AI-structured summaries (management_highlights, guidance, risks, segment_performance, q_and_a). Filter by ticker + period_end (yyyy-mm). NOT for structured financial numbers.
- earning_call_calendar: Earnings conference call schedule with EPS and revenue estimates vs actuals. `date` column is the scheduled earnings call datetime (UTC timestamptz) — NOT the press-release / 10-Q filing date (the filing typically lands the same day or shortly after). Use eps_actual IS NULL for upcoming calls, IS NOT NULL for reported.
## Analyst Coverage
- analyst_ratings: Individual analyst rating events — every re-rating is a separate row. ~565K rows, 519 firms. Filter by ticker; `date` is TEXT (string comparison, no ::date cast). importance >= 4 for high-impact calls.
- analyst_ratings_consensus: Per-ticker analyst consensus rollup — one row per ticker, refreshed daily. Columns: strong_buy/buy/hold/sell/strong_sell counts, total_analysts, consensus, pt_consensus/high/low.
## Ownership & Insider Activity
- insider_and_institution_activities: Insider trades (Form 3/4/5) and institutional holding changes (13D/G/F, 13F-HR) from SEC EDGAR. Filter by ticker + source ('insider' vs 'institution'). For institutions, filer_name is the holder; shares/market_value give position size.
## Corporate Events (8-K)
- executive_change: 8-K executive change events — appointments, departures, reasons, successors, effective dates. Filter by ticker + event_type.
- company_deal_events: Single source of truth for corporate deal activity (8-K 1.01/1.02/2.01, S-4, press releases). M&A, financing, material agreements as event-based rows (announced/signed/amended/closed/terminated/waived). Filter by ticker only — do NOT filter by deal_type. One deal may span multiple rows linked via deal_fingerprint.
- debt_issuance: 8-K debt issuance events — principal amount, interest rate, maturity, lender, use of proceeds. Use is_current = true for latest version when amendments exist.
- securities_offering: 8-K securities offering events — shares, price per share, total proceeds, investors, lock-up. Use is_current = true for latest version when amendments exist.
## Executive Profiles & Compensation
- executive_profile: Key executive profiles — name, title, compensation, gender, birth year. One row per executive per company.
- executive_compensation: Annual executive compensation breakdown — salary, bonus, stock awards, option awards, total. Filter by ticker + year.
## Alternative Data
For alternative-data tables, call list_tables(categories=[...]) first.
Connector