fundamentals_fetch_state.md

fundamentals_fetch_state

Purpose

Tracks active retry state and backoff windows for fundamentals ingestion failures.

Grain

One active failure row per provider_listing_id; no row means the listing is not currently blocked by a fundamentals fetch failure.

Live Stats

• Snapshot source: data/pyvalue.db on 2026-07-28
• Row count: 0
• Table size: 4,096 bytes (4.0 KiB)
• Approximate bytes per row: 0.0

Columns

Column	Type	Null	Key	Notes
provider_listing_id	INTEGER	no	PK, FK	provider listing identity
failed_at	TEXT	no		latest failure timestamp
error	TEXT	no		latest provider error
next_eligible_at	TEXT	no	idx	retry/backoff watermark
attempts	INTEGER	no		retry counter, always positive

Keys And Relationships

• Primary key: provider_listing_id
• Physical foreign keys:
  • provider_listing_id -> provider_listing.provider_listing_id
• Physical references from other tables: none
• Unique constraints beyond the primary key: none
• Main logical refs: provider_listing_id in provider_listing

Secondary Indexes

• None beyond the primary key and unique constraints.

Main Read Paths

• active backoff filtering for ingest planning
• progress and recent-failure reporting

Main Write Paths

• ingest-fundamentals
• retry/backoff updates
• successful raw upserts delete active failure rows
• provider-layer prune: rows die with their provider_listing — the ticker refresh (removed tickers) and the dropped-venue cascade in refresh-supported-exchanges delete them

Sample Rows

• Snapshot source: data/pyvalue.db on 2026-07-28
• Sample window: first 0 rows returned by SQLite ordered by provider_listing_id ASC

[]

Review Notes

• Provider and symbol values are resolved through provider_listing, keeping the state row narrow.
• Successful fetch progress is derived from fundamentals_raw, not duplicated here.