The emission_factor_value table

One value of a factor: the headline number, its gas splits, the vintage it was characterised under, and everything needed to judge whether it fits. A pending row holds the place of a number withheld from every caller.

Fields#

field type required example meaning
id uuid yes The row's own identifier. Consumers address a factor by its slug, not by this.
source_key text yes 'efv1-'+H(publisher, release, factor source parts + value discriminators); recipe version lives in the prefix. UNIQUE is a collision-detection net: never silently deduped.
content_hash text 'ch1-'+H(raw fields); source-edit detector
emission_factor_id uuid yes re-linkable: corrections move membership, not identity
publisher_id uuid yes identity self-contained even if re-linked
release_id uuid yes release fixes the system_model (dim 3)
source_row_id uuid The raw line this value came from (E: traceability).
data_type text How specific the number is to the thing you bought, and nothing else (dim 9). CHECK-closed at three words: specific is the ILCD "specific dataset" - ONE product from one named plant, which a supplier link alone never implies; generic is a default standing in for a measurement, with no producer attached; average is a mean over several producers, which is where a market, national, sector or operator-wide figure lands. The publisher's own word survives verbatim in source_row.raw.
reference_year integer yes The year the value DESCRIBES: the publisher's data or activity year: Ember 2019 is electricity generated in 2019. Where the publisher states no data year, the edition year stands in; each library's basis is recorded in its own file under docs/ef-libraries/. Use it to judge how old a number is, and to pick a vintage out of a multi-year series. It is not when we ingested the row (updated_at) and not when the publisher shipped it (release.released_on).
publisher_valid_from date Start of a validity window the PUBLISHER states. Populated only where the publisher prints one: today essentially the CBAM regulatory schedule. NULL is the normal case and does not mean 'not valid'. Never derived from reference_year. Use it only to honour a publisher's forward schedule: to choose a value use is_latest, to date the data use reference_year. It is not on factors_flat: read it through the view's value_id. It is not the view's applies_from_year, which we derive from reference_year and never cap with this date.
publisher_valid_to date The date the PUBLISHER withdraws the value: ÖKOBAUDAT's dataSetValidUntil, co2emissiefactoren.be's 'Geldig tot'. Use it to detect a retirement: a factor the publisher did not republish in its newest edition. NULL means the publisher stated no end, not 'current forever'. A value past its publisher_valid_to still serves, by design; the audit flags it advisory rather than dropping it. It is not on factors_flat: read it through the view's value_id. It does not cap the view's applies_to_year.
is_latest boolean yes Marks the value currently served for its lineage. Exactly one per lineage.
is_default_indicator boolean yes Marks the one value served when the caller does not pick a characterization. Exactly one per factor per release, which is what makes the served view a single row per factor.
is_latest_reference_year boolean yes The mechanical year-vintage pick: true on the row(s) at MAX(reference_year) within (factor, release, approach, radiative_forcing): maintained by the loader (_refresh_is_latest_reference_year), never adapter-supplied. Orthogonal to is_default_indicator (methodology) and to is_latest (release/lineage currency): a consumer that does not name a year reads is_latest AND is_default_indicator AND is_latest_reference_year. Not enforced by a unique index: parallel co-current siblings tied at the same top year (EXIOBASE's 7 GHG characterizations) all carry it true, same as is_latest.
value_status text yes Whether the row carries the publisher's numbers (published) or only the factor, its release and everything that describes it (pending), its value withheld from every caller, entitled or not (ecoinvent today). On a pending row every value column is NULL: not a zero and not a gap. A published row always carries both headlines. The serving view carries it too; the library coverage counts published rows only, and a browse value count reads a pending row like a licence-withheld value.
value_co2e_native double precision NULL only on a pending row (the CHECK below): a published row always carries it.
co2e_origin text yes Which shape the headline came from, closed by CHECK: source = the publisher printed the total; computed_from_gases = it printed a per-gas vector and we summed that vector under the stated GWP set; summed_from_children = nobody printed a total and open_ef summed an exact cover of this factor's own slices (emission_factor.is_derived; an estimated total too, which emission_factor.is_estimated tells apart); estimated_from_reference = nobody printed this leg and open-climate.ai estimated it by a rule from published figures, most often the publisher's own value times a reference ratio (emission_factor.is_estimated); differenced_from_parent = nobody printed this part, but the publisher printed its parent total and every sibling, and open-climate.ai subtracted them: ICM's input-output tail is its hybrid total minus its process total (emission_factor.is_derived, MOD-0049); apportioned_from_parent = nobody printed this part, but the publisher printed its parent total and the share this part takes of it, and open-climate.ai multiplied them: Boavizta's use and embodied parts of a device's lifecycle total (emission_factor.is_derived, MOD-0071).
co2e_basis text Which CO2e the headline counts: whether biogenic carbon and land use are inside. Two factors on different bases are not comparable however close the numbers look. NULL on a pending row, which has no headline yet.
value_co2_native double precision CO2 component, native vintage.
value_co2_fossil_native double precision Fossil-origin CO2e. CO2 alone, unless characterization_model is EF 3.x (ef_3.0, ef_3.1): then the method's whole fossil-origin group, multi-gas (fossil CH4 and N2O inside), so not a CO2 leg (MOD-0075).
value_ch4_native double precision Methane component, native vintage.
value_ch4_biogenic_native double precision Biogenic methane component, native vintage.
value_n2o_native double precision Nitrous oxide component, native vintage.
value_hfcs_native double precision HFC basket component, native vintage.
value_pfcs_native double precision PFC basket component, native vintage.
value_sf6_native double precision Sulphur hexafluoride component, native vintage.
value_nf3_native double precision Nitrogen trifluoride component, native vintage.
value_other_native double precision Remaining greenhouse gases the publisher groups together, native vintage.
value_co2_biogenic_native double precision Biogenic-origin CO2e. CO2 alone, unless characterization_model is EF 3.x (ef_3.0, ef_3.1): then the method's whole biogenic-origin group, multi-gas (biogenic CH4, enteric methane among it, inside), so not a CO2 leg (MOD-0075).
value_co2_luluc_native double precision Land-use-change CO2e: dLUC, sLUC or iLUC; see the value's luc_method qualifier (MOD-0096 D15). Whether a headline includes it is co2e_basis.
value_removals_native double precision Removals the publisher accounts for, native vintage. Negative by convention.
value_non_kyoto_native double precision The one value column BESIDE the headline, never inside it (MOD-0063): the CO2e of the gases outside the Kyoto basket (CFCs, HCFCs, halons and the other Montreal-Protocol substances), which a GHG Protocol inventory reports separately from its scope totals. DESNZ prints a refrigerant's Kyoto part, its non-Kyoto part and their total; the headline is the Kyoto part and this column the other, so the two add up to the printed total. NULL where the publisher states no such part. Additive across slices like a gas leg, and a basket (no single GWP): a row carrying it is never re-characterized, so its twin below is a verbatim copy.
value_flag_luc_native double precision SBTi FLAG land-use change
value_flag_land_management_native double precision SBTi FLAG land-management CO2e: the farm's non-LUC land emissions, every gas (soil and manure N2O included, which EF 3.1 files as fossil).
value_non_flag_native double precision The non-FLAG rest of the CO2e: energy, fertiliser manufacture, transport and other off-farm inputs.
value_co2_normalized double precision The _normalized twin of each gas leg (rev 13), on exactly the rule the headline follows: re-characterized where gwp_normalization_basis says 'recharacterized', and otherwise a verbatim copy of the native leg. NULL only where the publisher ships no such leg at all, so a consumer reading the _normalized set alone never has to fall back to the native one.
value_co2_fossil_normalized double precision Fossil CO2 component, moved to the target vintage.
value_ch4_normalized double precision Methane component, moved to the target vintage.
value_ch4_biogenic_normalized double precision Biogenic methane component, moved to the target vintage.
value_n2o_normalized double precision Nitrous oxide component, moved to the target vintage.
value_hfcs_normalized double precision HFC basket component, moved to the target vintage.
value_pfcs_normalized double precision PFC basket component, moved to the target vintage.
value_sf6_normalized double precision Sulphur hexafluoride component, moved to the target vintage.
value_nf3_normalized double precision Nitrogen trifluoride component, moved to the target vintage.
value_other_normalized double precision Remaining greenhouse gases the publisher groups together, moved to the target vintage.
value_co2_biogenic_normalized double precision Biogenic CO2 component, moved to the target vintage.
value_co2_luluc_normalized double precision Land-use and land-use-change CO2 component, moved to the target vintage.
value_removals_normalized double precision Removals the publisher accounts for, moved to the target vintage. Negative by convention.
value_non_kyoto_normalized double precision
value_flag_luc_normalized double precision The FLAG legs' twins (MOD-0113). A FLAG leg mixes gases in CO2e, so it cannot be re-characterized: each twin is a verbatim copy of its native leg where the headline's twin is not re-characterized either (gwp_normalization_basis native, invariant or unconverted), and NULL where the headline moved to another GWP vintage.
value_flag_land_management_normalized double precision
value_non_flag_normalized double precision
gwp_method_native text yes ar2 / ar4 / ar5 / ar6 / wmo2022 / mixed / unknown / none (none = pure-CO2, no GWP)
gwp_horizon_years integer yes 20/100/500
characterization_model text named LCIA method, snake_case; else NULL
gwp_origin text yes source / assigned / inferred
value_co2e_normalized double precision The same headline, moved to the one target vintage so it can be added to another library's. Populated on every published row and NULL on a pending one (value_status): where the move is not exactly derivable the native number is copied through and labelled unconverted, so this is the only headline column a consumer needs to read. Sum it only across published rows where gwp_normalization_basis is not unconverted.
gwp_method_normalized text yes The vintage these numbers are ACTUALLY on: 'ar6' for every converted basis, and the row's own gwp_method_native for 'unconverted'.
gwp_normalization_basis text yes HOW the measure was obtained, and the ONE column that says whether it may be summed across libraries: native (already the target vintage: a verbatim copy) / invariant (pure-CO2 value, GWP=1 in every vintage) / recharacterized (per-gas legs divided by the native GWP, re-multiplied by the target) / unconverted (not derivable: the native number, native vintage). The cross-library-comparable set is WHERE gwp_normalization_basis <> 'unconverted': not gwp_method_normalized = 'ar6', which an AR6 row on a GWP20/GWP500 horizon also satisfies while answering a different question.
calculation_approach text location_based / market_based / NULL
radiative_forcing text with / without / NULL (n/a)
grid_mix text Grid or network accounting mix (refines calculation_approach). Location: production (the mix of the plants generating in the territory), consumption (the mix of what is consumed in the territory, imports in and exports out) and marginal (a margin construct, such as the CDM Tool 07 operating margin; MOD-0096 D3, D4). Market: residual / total_supplier_mix (every supplier of a region combined) / supplier_specific (one supplier's product) / green. NULL where the carrier publishes no location/market duality of its own, which is most non-electricity - but NOT all of it: japan_moe's statutory basic (kiso) / adjusted (chouseigo) pair is published for city gas and district heat as well as electricity, and this axis is what separates a menu's two legs. Pair-enforced with calculation_approach, so a supplier-specific gas coefficient cannot be typed market_based without it. In value_discriminators; is_default marks the sensible default per method (consumption for location, residual for market).
grid_mix_origin text Who put the grid_mix there (MOD-0042, D5): 'source' when the publisher printed a value for that mix, 'assigned' when open-climate.ai added the value under rule G (the green zero on a residual's factor: AIB's 31 greens, then green_e, nve, nga_australia). NULL exactly when grid_mix is NULL, so a filter on the axis never has to special-case a value the axis does not apply to. A green zero keeps co2e_origin = 'source': it is the factor a wind, solar or hydro certificate carries under the Protocol, not an estimate (a biomass certificate is not 0).
currency_year integer For a monetary factor, the price level the value is expressed in, bounded [1990, 2100]. A monetary factor is only meaningful with it: use it to deflate or inflate spend before applying the factor. It is a price year, not a publisher date, and it is independent of reference_year.
price_basis text producer / purchaser / basic
value_qualifiers jsonb Library-family-specific value discriminators that are NOT a cross-library typed axis: a single jsonb bag, keys validated by the loader against the declared VALUE_QUALIFIER_KEYS registry (no dumping ground). First occupant: EN 15804 EPD scenarios, {"scenario": "S2"}. Any value_discriminators input to the source_key hash MUST be readable from a typed column or here: never only from inside the hash or source_record (queryability contract).
uncertainty_pct double precision The publisher's stated uncertainty, as a percentage of the value.
data_quality_rating_native double precision The publisher's OWN rating, on the publisher's OWN scale. Meaningless without data_quality_scheme_native: 'lower is better' on one scheme and the number of axes both vary, so two ratings from different publishers must NOT be compared. Cross-library comparison is what data_quality_normalized below is for.
data_quality_scheme_native text Which scheme the rating on this row is expressed in. A rating never travels without it.
data_quality_detail_native jsonb scores on registered axes only, e.g. {TeR,GR,TiR,P}; NULL if none
data_quality_normalized text yes The one quality ordinal that is comparable across publishers. Values at the problematic floor are excluded from the serving view.
data_quality_reason_normalized text Why the tier is what it is, or why a 0 is real: 'structural_zero', 'green_electricity_zero', 'rounded_to_zero', 'context_dependent_basis', 'tiny_denominator_extreme'; the loader stamps 'library_prior' / 'no_native_signal' when nothing else explains the tier. Every 0 on a servable factor carries one, so the read path can exclude it by reason. A reason never forces a tier: only an adapter override floors, and a correct zero keeps its derived tier (MOD-0015). NULL when a native quality signal set the tier. See ingest.loader.
unit_conversion_factor double precision yes What the source's number was multiplied by to reach the canonical unit.
activity_raw text The activity string exactly as the source wrote it.
region_raw text NULL when the source ships no region
unit_raw text The unit label exactly as the source wrote it, before canonicalisation.
source_native_id text publisher's own id when present
source_native_id_kind text e.g. 'ademe_identifiant'
source_status text e.g. ademe 'valide_generique' / 'archive'
source_link text The publisher's own link for this record.
source_record jsonb yes Adapter-authored per-value provenance: a selected + renamed + lightly cleaned subset of source fields (+ derived fields, e.g. the resolved system_boundary); feeds content_hash for edit detection. The full, untouched line lives in source_row.raw (one per artifact line, shared by sibling values): that is the ALL-fields-verbatim archive, not this.
ingested_at timestamp yes When we loaded the row.
updated_at timestamp yes OUR pipeline bookkeeping, not a publisher date: when we last wrote this row. Use it for cache invalidation (WHERE updated_at > :last_sync) and for nothing else. When the number was dated is reference_year; when the publisher shipped it is release.released_on.

Referenced by#

unit_conversion.value_id.

Notes#

Every stored measure is native: as the publisher published it, under the publisher's own global-warming-potential vintage. Beside it sits a _normalized twin of the headline and of all thirteen gas legs, moved to a single target vintage. The twin is populated on every published row: where the move is not exactly derivable the native numbers are copied through and the row is labelled unconverted, so a consumer reads one set of columns and never falls back to the native set by hand. gwp_normalization_basis is what to filter on: an unconverted row is one you cannot honestly add to another library's.

The serving view answers now: exactly one current value per factor. Superseded vintages are not lost: they stay in this table, off the served surface, keyed by reference_year, and that is how a consumer answers which value applies to my 2019 inventory. Query this table directly for that and order by reference_year yourself, since is_default_indicator is elected once per factor per release, so it only ever marks the newest year.

A row is published or pending (value_status). A pending row is a factor of a served release whose numbers open-climate.ai does not load yet, typically under a licence it does not hold: every value column and co2e_basis are NULL, while the GWP fields name the method the edition scores on (for ecoinvent: AR6 GWP100 from 3.9, AR5 GWP100 for 3.2 to 3.8). That NULL is neither a zero nor a gap, so filter value_status = 'published' before you sum, convert or rank. Only a library flagged for it may hold one, and the release's real-values ingest replaces its pending rows in the same transaction.