Time Series Declarations¶

Energy research datasets often contain hourly time arrays — for example, 8,760 rows per year for each combination of region, fuel type, and metric. These arrays frequently have issues that are hard to catch with generic quality checks:

• missing hours from incomplete data ingestion
• DST spring-forward gaps (a missing hour when clocks jump ahead)
• DST fall-back duplicates (a repeated hour when clocks fall back)
• leap-year inconsistencies (some groups include February 29, others do not)

time_series.yaml lets you declare the temporal structure of your tables so datasight can check completeness automatically.

How It Works¶

1. You create a time_series.yaml file in your project directory.
2. datasight quality runs temporal completeness checks against the declarations — no LLM needed.
3. The AI agent receives the declarations as context, so it understands the timestamp column, expected frequency, and group structure when answering time-series questions.

time_series.yaml¶

The file lives in the project root alongside measures.yaml and queries.yaml.

Minimal example¶

- table: generation_hourly
  timestamp_column: datetime_utc
  frequency: PT1H

Full example¶

- table: generation_hourly
  timestamp_column: datetime_utc
  frequency: PT1H
  group_columns: [region, energy_source_code]
  time_zone: UTC

- table: load_forecast
  timestamp_column: forecast_hour
  frequency: PT1H
  group_columns: [zone_id]
  time_zone: America/New_York

Required fields¶

Optional fields¶

Frequency values¶

Frequencies use the ISO 8601 duration format:

Quality checks¶

When time_series.yaml exists, datasight quality adds two new sections to its output:

Time Series¶

A summary of each declared time series showing row count, frequency, and date range.

Temporal Completeness¶

Issues found in the data:

• gap — an interval between consecutive timestamps that is larger than the declared frequency. This catches missing hours, dropped days, and DST spring-forward gaps.
• duplicate — a timestamp that appears more than once within a group. This catches DST fall-back duplicates and accidental re-ingestion.

datasight quality
datasight quality --table generation_hourly
datasight quality --format json -o quality.json

Creating the file¶

With datasight generate¶

datasight generate automatically scaffolds time_series.yaml alongside schema_description.md, queries.yaml, and measures.yaml. It detects tables with timestamp columns and creates entries with a default PT1H frequency.

datasight generate

Review and edit the generated file — you will likely need to adjust the frequency, add group columns, and set the correct time zone.

With datasight init¶

datasight init copies a commented template:

datasight init my-project

Manually¶

Create time_series.yaml in the project root:

- table: generation_hourly
  timestamp_column: datetime_utc
  frequency: PT1H
  group_columns: [region, energy_source_code]
  time_zone: UTC

How it helps the AI¶

When you use datasight ask or the web UI, the time series declarations are included in the system prompt. This means the AI already knows:

• which column is the time axis
• the expected frequency
• which columns define independent groups
• the time zone

So when you ask "are there any gaps in the wind generation data?", the agent can write targeted SQL using the correct timestamp column and group structure without guessing.

Which file should you edit?¶