query_dataset

com.twmarketdata/tw-market-data · Verify this server

Query rows with built-in look-ahead protection. ★ POINT-IN-TIME: pass `as_of` (YYYY-MM-DD) for backtesting/agent-learning. For non-point-in-time-safe datasets (fundamentals, monthly_revenue, dividend_policy…) rows are filtered by DISCLOSURE date <= as_of, so the agent only sees what was public at that moment. Omit as_of only for present-day lookups (warned). ★ IF A VALUE IS IN `coverage.missing`, IT IS NOT AVAILABLE. Say it is not available. **Never estimate it, interpolate it, infer it from a neighbouring period, or carry the last known value forward.** `coverage.missing` lists exactly what was requested and not returned, with a reason (e.g. "9999 在 as_of 當日未上市"). An empty `data` array alongside a populated `missing` list is a complete and correct answer to "what do you have" — not an invitation to fill the gap. ★ EVERY VALUE IS ATTRIBUTABLE. `provenance` carries {source, source_role, ingested_at, revision, provenance_uri}; `meta.query_id` names this exact question. Quote the query_id when reporting a number — `replay_query(query_id)` returns the bytes that were served, so the claim can be checked later. `freshness.is_stale` is computed server-side against the dataset's own cadence budget; `null` means it could not be determined, which is NOT the same as fresh. Args: dataset_id: see list_datasets. tickers: e.g. ['2330','2317']. start/end: 'YYYY-MM-DD' range. as_of: knowledge-time cutoff 'YYYY-MM-DD' (use for backtests). limit: <=5000. Returns: {meta:{table,coverage,row_count,as_of_applied,point_in_time_safe,warnings,query_id}, data:[...], provenance:{...}, coverage:{requested,returned,missing,reason}, freshness:{status,latest_available,expected_lag,is_stale}} Example: query_dataset('fundamental_income', tickers=['2330'], as_of='2023-06-30')