# Varve Fundamentals schema reference (v0.1.0)

US company fundamentals, as first filed. Generated from the shipped files on 2026-10-08.

## How the tables join

Every table joins on `cik` (SEC Central Index Key; tickers change, CIKs don't). `accession` links a value to its filing; `cusip` links 13F holdings to companies. Diagram: `join_diagram.svg` / `.png`.

```mermaid
erDiagram
    COMPANIES["varve_fundamentals_companies"] ||--o{ QUARTERLY["varve_fundamentals_quarterly"] : cik
    COMPANIES ||--o{ ANNUAL["varve_fundamentals_annual"] : cik
    COMPANIES ||--o{ FACTS["varve_fundamentals_facts"] : cik
    COMPANIES ||--o{ FILINGS["varve_fundamentals_filings"] : cik
    FILINGS ||--o{ FACTS : accession
    ENTITIES["varve_events_entities"] ||--o| COMPANIES : "cik (superset)"
    COMPANIES ||--o{ FILING_EVENTS["filing events (6 tables)"] : cik
    COMPANIES ||--o{ OWNERSHIP["ownership_filings / insider_sale_notices"] : "cik (subject)"
    ENTITIES ||--o{ OWNERSHIP : filer_ciks
    COMPANIES ||--o{ INSIDER["varve_events_insider_transactions"] : issuer_cik
    ENTITIES ||--o{ INSIDER : owner_cik
    ENTITIES ||--o{ FORMD["varve_events_private_placements"] : cik
    ENTITIES ||--o{ F13["varve_events_13f_filings"] : filer_cik
    F13 ||--o{ POS["varve_events_13f_positions"] : accession
    CMAP["varve_events_13f_cusip_map"] ||--o{ POS : cusip
    CMAP ||--o{ IQ["varve_events_13f_issuer_quarterly"] : cusip
    COMPANIES ||--o{ CMAP : cik
```

## Tables

| table | grain | rows | formats | use for |
|---|---|---:|---|---|
| `varve_fundamentals_quarterly` | One row per company × fiscal quarter-end | 491,263 | parquet, csv.gz | Most backtests, screens and charts. |
| `varve_fundamentals_annual` | One row per company × fiscal year-end | 126,277 | parquet, csv.gz | Annual analysis; longer history per company. |
| `varve_fundamentals_facts` | One row per company × field × period × duration | 9,204,226 | parquet, csv.gz | Auditing a number, restatement research, building your own tables. |
| `varve_fundamentals_fact_versions` | One row per company × field × period × duration × version | 8,314,926 | parquet, csv.gz | Full restatement history; exact as-of values on any date. |
| `varve_fundamentals_ticker_history` | One row per company × ticker × interval | 49,073 | parquet, csv.gz | Point-in-time ticker ↔ CIK mapping for joining prices. |
| `varve_fundamentals_company_names` | One row per company × registrant name × interval | 22,119 | parquet, csv.gz | Point-in-time company names. |
| `varve_fundamentals_companies` | One row per company (CIK) | 16,545 | parquet, csv.gz | Names, symbols, industry, and whether a company still files. |
| `varve_fundamentals_filings` | One row per periodic filing (10-K, 10-Q, 20-F, 40-F and amendments) | 414,329 | parquet, csv.gz | Filing calendars, earnings-release timing, joining a value to its filing. |

## `varve_fundamentals_quarterly`

First-reported values only, pivoted wide: each quarter's flow fields (Q) alongside the balance sheet at that quarter-end (I).

Primary key: `cik, period_end`

| column | type | description |
|---|---|---|
| `cik` | integer | SEC Central Index Key: the permanent company identifier. Tickers change and get recycled; CIKs never do. Join on this. |
| `ticker` | string | Display ticker: the company's current symbol if it still has one, otherwise the earliest symbol recovered for it. NOT point-in-time; for every known symbol see companies.tickers_all. |
| `name` | string | Company name (latest). |
| `period_end` | date | Fiscal period end, normalised to month-end by the SEC (a 52/53-week year ending Saturday 30 Dec 2023 appears as 2023-12-31). |
| `fiscal_year` | integer | The company's own fiscal-year label for the period, from the filing that reported it. |
| `fiscal_period` | string (categorical) | Fiscal quarter label: Q1–Q4. |
| `filed` | date | Latest `filed` date across the row's values: the first date on which the WHOLE row was public. Use this for point-in-time joins. |
| *27 field columns* | float | One column per field; see Fields below. |

## `varve_fundamentals_annual`

First-reported fiscal-year flow values (FY) with the year-end balance sheet (I).

Primary key: `cik, period_end`

| column | type | description |
|---|---|---|
| `cik` | integer | SEC Central Index Key: the permanent company identifier. Tickers change and get recycled; CIKs never do. Join on this. |
| `ticker` | string | Display ticker: the company's current symbol if it still has one, otherwise the earliest symbol recovered for it. NOT point-in-time; for every known symbol see companies.tickers_all. |
| `name` | string | Company name (latest). |
| `period_end` | date | Fiscal period end, normalised to month-end by the SEC (a 52/53-week year ending Saturday 30 Dec 2023 appears as 2023-12-31). |
| `fiscal_year` | integer | The company's own fiscal-year label for the period, from the filing that reported it. |
| `filed` | date | Latest `filed` date across the row's values: the first date on which the WHOLE row was public. Use this for point-in-time joins. |
| *27 field columns* | float | One column per field; see Fields below. |

## `varve_fundamentals_facts`

The long, fully-provenanced table every other table is derived from.

Primary key: `cik, field, duration, period_end`

| column | type | description |
|---|---|---|
| `cik` | integer | SEC Central Index Key: the permanent company identifier. Tickers change and get recycled; CIKs never do. Join on this. |
| `field` | string (categorical) | Field name; see the field dictionary. |
| `duration` | string (categorical) | Q = fiscal quarter, FY = fiscal year (both for flow fields), I = instant (balance-sheet fields). |
| `period_end` | date | Fiscal period end, normalised to month-end by the SEC (a 52/53-week year ending Saturday 30 Dec 2023 appears as 2023-12-31). |
| `fiscal_year` | integer | The company's own fiscal-year label for the period, from the filing that reported it. |
| `fiscal_period` | string (categorical) | Q1–Q4 for quarters and balance sheets, FY for fiscal years. |
| `value` | float | The value AS FIRST REPORTED, in the field's unit. |
| `source` | string (categorical) | How the value was obtained: reported, ytd_derived, q4_derived or q4_ratio_derived (see Derivations). |
| `filed` | date | Date the value became public: the filing date, or for a derived value the latest filing date among its inputs. |
| `accepted` | date | EDGAR acceptance timestamp of that filing (Eastern time). Filings accepted after 17:30 are dated the next business day. |
| `accession` | string | EDGAR accession number of the filing, e.g. 0000320193-23-000106. Filing index: sec.gov/Archives/edgar/data/{cik}/{accession without dashes}/. |
| `value_latest` | float | The most recent value reported for the same company, field and period (after any restatements). |
| `filed_latest` | date | Filing date of value_latest. |
| `accession_latest` | string | Accession number of the filing that reported value_latest. |
| `restated` | boolean | True when value_latest differs from value. |

## `varve_fundamentals_fact_versions`

Every distinct value a company reported for a period, with the interval during which it was the current number. Repeats of the same number in later filings extend a version; a change in precision only (4,843,000 vs 4,843,349) is not a new version. Covers values filers report directly (Q, FY, I); derived Q4 and year-to-date values are in facts.

Primary key: `cik, field, duration, period_end, version`

| column | type | description |
|---|---|---|
| `cik` | integer | SEC Central Index Key: the permanent company identifier. Tickers change and get recycled; CIKs never do. Join on this. |
| `field` | string (categorical) | Field name; see the field dictionary. |
| `duration` | string (categorical) | Q = fiscal quarter, FY = fiscal year, I = instant (balance sheet). |
| `period_end` | date | Fiscal period end, normalised to month-end by the SEC (a 52/53-week year ending Saturday 30 Dec 2023 appears as 2023-12-31). |
| `version` | integer | 1 = first reported, 2 = first restatement, ... |
| `n_versions` | integer | How many distinct values this company-field-period has had. |
| `value` | float | The value as reported in this version. |
| `known_from` | date | Filing date from which this value was the current public number. |
| `known_to` | date | Filing date of the next version (exclusive); null while this version is current. |
| `accepted` | date | EDGAR acceptance timestamp of the filing that introduced this version. |
| `accession` | string | Accession number of the filing that introduced this version. |
| `n_reports` | integer | How many filings reported this exact value (originals plus comparatives). |
| `last_reported` | date | Filing date of the last filing that reported this value. |

## `varve_fundamentals_ticker_history`

When each company traded under each symbol, observed from SEC filings: the issuer symbol on every Form 3/4/5 (2006+) and archived SEC ticker lists (2017+). Dates are first/last observation, not official listing dates. A company can hold several tickers at once (share classes) and a symbol can pass between companies (recycled tickers).

Primary key: `cik, ticker, valid_from`

| column | type | description |
|---|---|---|
| `cik` | integer | SEC Central Index Key: the permanent company identifier. Tickers change and get recycled; CIKs never do. Join on this. |
| `ticker` | string | Ticker symbol. |
| `valid_from` | date | First date the company was observed under this symbol. |
| `valid_to` | date | Last date observed (null while the symbol is current). When the company's insider filings switch symbols, the old interval ends at the switch. |
| `current` | boolean | True if the symbol is in SEC's current ticker list for this company. |
| `last_seen` | date | Last observation date, also for current symbols. |
| `superseded_by` | string | The symbol the company switched to, when the interval ended in a rename. |
| `sources` | string | insider (Form 3/4/5 issuer symbol), sec_list (SEC ticker list), or both. |
| `n_observations` | integer | Number of filings / list snapshots supporting the interval. |

## `varve_fundamentals_company_names`

The registrant name printed on each periodic filing, collapsed into intervals (2009+).

Primary key: `cik, valid_from`

| column | type | description |
|---|---|---|
| `cik` | integer | SEC Central Index Key: the permanent company identifier. Tickers change and get recycled; CIKs never do. Join on this. |
| `name` | string | Registrant name as filed. |
| `valid_from` | date | Filing date of the first filing under this name. |
| `valid_to` | date | Filing date of the first filing under the next name (null = current name). |
| `last_seen` | date | Filing date of the last filing under this name. |
| `n_filings` | integer | Number of periodic filings under this name. |

## `varve_fundamentals_companies`

Every company with at least one value in the dataset, active or not.

Primary key: `cik`

| column | type | description |
|---|---|---|
| `cik` | integer | SEC Central Index Key: the permanent company identifier. Tickers change and get recycled; CIKs never do. Join on this. |
| `ticker` | string | Display ticker: the company's current symbol if it still has one, otherwise the earliest symbol recovered for it. NOT point-in-time; for every known symbol see companies.tickers_all. |
| `ticker_current` | string | Symbol in SEC's current ticker file; empty if the company no longer has one. |
| `tickers_all` | string | Every symbol ever recovered for this company, pipe-separated (e.g. BKNG|PCLN). |
| `name` | string | Latest registered company name. |
| `former_names` | string | Earlier names reported to the SEC, pipe-separated. |
| `sic` | integer | Standard Industrial Classification code assigned by the SEC. |
| `country_inc` | string | Country of incorporation (ISO code). |
| `state_inc` | string | State of incorporation, for US companies. |
| `fiscal_year_end_mmdd` | string | Fiscal year end as MMDD (e.g. 0930). |
| `first_filed` | date | Date of the company's first 10-K/10-Q/20-F/40-F in the source. |
| `last_filed` | date | Date of its most recent one. A date well in the past means the company stopped filing (delisted, acquired, bankrupt, deregistered). |
| `n_filings` | integer | Number of periodic filings in the source. |

## `varve_fundamentals_filings`

Index of every filing the dataset draws on.

Primary key: `accession`

| column | type | description |
|---|---|---|
| `accession` | string | EDGAR accession number (primary key). |
| `cik` | integer | SEC Central Index Key: the permanent company identifier. Tickers change and get recycled; CIKs never do. Join on this. |
| `form` | string | Form type: 10-K, 10-Q, 20-F, 40-F, or an amendment (/A). |
| `period_end` | date | Balance-sheet date of the report, normalised to month-end. |
| `fiscal_year` | integer | Fiscal year the filer assigned to the report. |
| `fiscal_period` | string | Fiscal period the filer assigned: Q1–Q3, FY (annual report). |
| `filed` | date | Filing date. |
| `accepted` | date | EDGAR acceptance timestamp (Eastern time). |
| `superseded` | boolean | True if the filer later amended this submission. |

## Fields

| field | statement | unit | Q4 method | companies | definition | XBRL tags, priority order |
|---|---|---|---|---:|---|---|
| `revenue` | income statement | USD | subtraction | 13,377 | Total revenue / net sales. For banks and insurers, which report no single revenue line, the closest top-line tag is used (interest and dividend income, net interest income, premiums earned); see tag priority. | RevenueFromContractWithCustomerExcludingAssessedTax, RevenueFromContractWithCustomerIncludingAssessedTax, Revenues, SalesRevenueNet, SalesRevenueGoodsNet, RevenuesNetOfInterestExpense, InterestAndDividendIncomeOperating, InterestIncomeExpenseNet, PremiumsEarnedNet |
| `cost_of_revenue` | income statement | USD | subtraction | 8,478 | Cost of goods and/or services sold. | CostOfRevenue, CostOfGoodsAndServicesSold, CostOfGoodsSold, CostOfServices |
| `gross_profit` | income statement | USD | subtraction | 7,105 | Gross profit as reported by the filer, never computed. Many service companies and financials do not report it; compute revenue − cost_of_revenue yourself where you need it. | GrossProfit |
| `sga` | income statement | USD | subtraction | 5,068 | Selling, general and administrative expense. | SellingGeneralAndAdministrativeExpense |
| `rnd` | income statement | USD | subtraction | 5,231 | Research and development expense. | ResearchAndDevelopmentExpense, ResearchAndDevelopmentExpenseExcludingAcquiredInProcessCost |
| `operating_income` | income statement | USD | subtraction | 12,880 | Operating income (loss). | OperatingIncomeLoss |
| `interest_expense` | income statement | USD | subtraction | 10,874 | Interest expense. Positive = expense. | InterestExpense, InterestExpenseNonoperating |
| `income_tax` | income statement | USD | subtraction | 11,660 | Income tax expense (benefit). Positive = expense, negative = benefit. | IncomeTaxExpenseBenefit |
| `net_income` | income statement | USD | subtraction | 16,370 | Net income (loss) attributable to the parent company. Falls back to consolidated profit including noncontrolling interests, then to income available to common shareholders. | NetIncomeLoss, ProfitLoss, NetIncomeLossAvailableToCommonStockholdersBasic |
| `eps_diluted` | income statement | USD/shares | ratio | 13,914 | Diluted earnings per share, USD per share. Includes filers that report a single combined basic-and-diluted figure. | EarningsPerShareDiluted, EarningsPerShareBasicAndDiluted |
| `eps_basic` | income statement | USD/shares | ratio | 11,495 | Basic earnings per share, USD per share. | EarningsPerShareBasic |
| `shares_diluted` | income statement | shares | ratio | 12,905 | Weighted-average diluted shares outstanding over the period: the denominator for per-share maths, not for market cap. | WeightedAverageNumberOfDilutedSharesOutstanding, WeightedAverageNumberOfShareOutstandingBasicAndDiluted |
| `shares_basic` | income statement | shares | ratio | 11,464 | Weighted-average basic shares outstanding over the period. | WeightedAverageNumberOfSharesOutstandingBasic |
| `operating_cash_flow` | cash flow | USD | ytd | 15,510 | Net cash provided by (used in) operating activities. | NetCashProvidedByUsedInOperatingActivities, NetCashProvidedByUsedInOperatingActivitiesContinuingOperations |
| `capex` | cash flow | USD | ytd | 11,250 | Payments to acquire property, plant and equipment. A positive number is a cash outflow. Free cash flow = operating_cash_flow − capex. | PaymentsToAcquirePropertyPlantAndEquipment, PaymentsToAcquireProductiveAssets, PaymentsForCapitalImprovements |
| `depreciation_amortization` | cash flow | USD | ytd | 10,078 | Depreciation, depletion and amortization, from the cash-flow statement. | DepreciationDepletionAndAmortization, DepreciationAndAmortization, DepreciationAmortizationAndAccretionNet |
| `stock_comp` | cash flow | USD | ytd | 10,789 | Share-based compensation: the non-cash add-back in the cash-flow statement. | ShareBasedCompensation |
| `dividends_paid` | cash flow | USD | ytd | 4,489 | Cash dividends paid. A positive number is a cash outflow. | PaymentsOfDividends, PaymentsOfDividendsCommonStock |
| `buybacks` | cash flow | USD | ytd | 6,246 | Payments for repurchase of common stock. A positive number is a cash outflow. | PaymentsForRepurchaseOfCommonStock |
| `cash` | balance sheet | USD | — | 15,886 | Cash and cash equivalents. Where only the fallback tag exists, includes restricted cash (the presentation required after ASU 2016-18). | CashAndCashEquivalentsAtCarryingValue, CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents, Cash |
| `current_assets` | balance sheet | USD | — | 13,147 | Total current assets. | AssetsCurrent |
| `total_assets` | balance sheet | USD | — | 16,324 | Total assets. | Assets |
| `current_liabilities` | balance sheet | USD | — | 13,105 | Total current liabilities. | LiabilitiesCurrent |
| `total_liabilities` | balance sheet | USD | — | 14,431 | Total liabilities. Many filers never tag this total (they report only liabilities-and-equity), so coverage is lower than total_assets. | Liabilities |
| `long_term_debt` | balance sheet | USD | — | 7,029 | Long-term debt, non-current portion where tagged; the fallback tags may include current maturities. | LongTermDebtNoncurrent, LongTermDebt, LongTermDebtAndCapitalLeaseObligations |
| `equity` | balance sheet | USD | — | 15,413 | Stockholders' equity attributable to the parent; falls back to total equity including noncontrolling interests. | StockholdersEquity, StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest |
| `shares_outstanding` | balance sheet | shares | — | 13,719 | Common shares outstanding at the balance-sheet date. Falls back to shares issued (which includes treasury shares). Use for market cap with a price dated on or after `filed`. | CommonStockSharesOutstanding, CommonStockSharesIssued |