Data Dictionary
Complete reference of data fields and types used across Snowtrail products.
Point-in-Time Columns
Every Snowtrail table, signals, features, events, and backtests, includes three point-in-time columns and a model_version that support reproducible research and audit.
| Column | Type | Description |
|---|---|---|
str_effective_at | date | The date this row became knowable: the business date it describes, plus the source's publication lag where one applies. |
str_observed_at | timestamp | When Snowtrail could first have held this value, derived from the arrival of the raw data that fed it. |
str_ingested_at | timestamp | The UTC timestamp of the pipeline run that last wrote this row. Rewritten on every rebuild, not a first-publication date; used by as_of only as a tiebreaker. |
model_version | string | MAJOR.MINOR version of the model that produced the row. A MAJOR change restates history. |
as_of bounds both str_effective_at and str_observed_at, and per key returns the newest version ordered by MAJOR model_version, then str_observed_at, then str_ingested_at. A query replayed at a historical date returns what Snowtrail held and the market could have seen by then, including values a source has since restated, back to each product's effective as_of start. It reconstructs data under the current model, not earlier models. See Point-in-Time Integrity.
Common API Response Fields
When querying the Snowtrail API, responses include standard envelope fields.
| Field | Type | Description |
|---|---|---|
product_id | string | Identifier for the product (e.g. gbsi_us, glmi) |
count | integer | Number of records returned in this response |
has_more | boolean | Whether additional pages of results exist |
next_cursor | string | Cursor token for retrieving the next page of results |
Signal Columns
Signal schemas are product and dataset-specific. Below is an example using GBSI-US system stress.
Example: GBSI-US System Stress
| Column | Type | Description |
|---|---|---|
week_ending | date | The week-ending date for this observation |
stress_regime | integer (1--5) | Numeric stress regime classification, where 1 is lowest stress and 5 is highest |
stress_regime_label | string | Human-readable label for the stress regime |
confidence_score | float | Confidence in the regime classification |
directional_bias | string | Directional context associated with the current regime |
str_effective_at | date | When the row became publicly knowable |
str_observed_at | timestamp | When Snowtrail could first have held it |
str_ingested_at | timestamp | When this row was processed by Snowtrail |
Other signal datasets (e.g. balance momentum, price context, grid stress) follow similar patterns but with columns specific to their domain.
Feature Columns
Feature schemas vary by product and dataset. Features represent the derived, research-ready inputs that underpin signals and events. Every feature table includes:
| Column | Type | Description |
|---|---|---|
str_effective_at | date | When the row became publicly knowable |
str_observed_at | timestamp | When Snowtrail could first have held it |
str_ingested_at | timestamp | When this row was processed by Snowtrail |
Additional columns are specific to the product and feature dataset. For example, GBSI-US storage features include columns for storage levels, injections, withdrawals, and year-over-year comparisons.
Event Columns
Event schemas vary by product and dataset. Events represent discrete developments that materially affect market conditions. Every event table includes:
| Column | Type | Description |
|---|---|---|
str_effective_at | date | When the row became publicly knowable |
str_observed_at | timestamp | When Snowtrail could first have held it |
str_ingested_at | timestamp | When this row was processed by Snowtrail |
Additional columns describe the event type, severity, status, and other product-specific attributes. GBSI-US, GBSI-EU, GLMI and WSSI-US events carry event_status (ACTIVE or SUPERSEDED); superseded events also carry superseded_by_source and superseded_at.
Schema Discovery
Actual column names and types are product and dataset-specific. To explore the schema for a particular dataset:
- Use the Python SDK to fetch a sample and inspect the resulting DataFrame columns
- Consult the API Reference for endpoint-specific documentation
- Contact support@snowtrail.ai for detailed schema documentation