TimeDB Quickstart

Get started with TimeDB in 5 minutes. Learn how to store and query time series data with forecast revisions.

1. Setup

Import TimeDB and create a client.

from timedb import TimeDataClient
import pandas as pd
from datetime import datetime, timedelta, timezone
from dotenv import load_dotenv
load_dotenv()

td = TimeDataClient()
td.delete()
td.create()

Creating database schema...
✓ Schema created successfully

2. Create a Series

A series is identified by its name and optional labels. Since this is forecast data, we set overlapping=True.

series_id = td.create_series(
    name='wind_power',
    unit='MW',
    labels={'site': 'offshore_1', 'type': 'forecast'},
    overlapping=True
)

# See what was created
for s in td.series('wind_power').list_series():
    print(f"  id={s['series_id']}  name={s['name']}  unit={s['unit']}  labels={s['labels']}  overlapping={s['overlapping']}")

  id=1  name=wind_power  unit=MW  labels={'site': 'offshore_1', 'type': 'forecast'}  overlapping=True

3. Insert Data

Insert time series data with a DataFrame. The known_time indicates when the forecast was made.

# Create forecast data
start = datetime(2025, 1, 1, 0, 0, tzinfo=timezone.utc)
times = [start + timedelta(hours=i) for i in range(24)]
values = [100 + i * 2 for i in range(24)]  # Simple increasing pattern

df = pd.DataFrame({
    'valid_time': times,
    'value': values
})

# Insert with known_time (when forecast was made)
td.series('wind_power').where(site='offshore_1', type='forecast').insert(
    df=df,
    known_time=start
)

InsertResult(batch_id=1, workflow_id='sdk-workflow', series_id=1)

4. Insert a Revised Forecast

Insert an updated forecast for the same time period with a new known_time.

# Create revised forecast (made 6 hours later)
revised_known = start + timedelta(hours=6)
revised_values = [105 + i * 2 for i in range(24)]  # Slightly different values

df_revised = pd.DataFrame({
    'valid_time': times,
    'value': revised_values
})

td.series('wind_power').where(site='offshore_1', type='forecast').insert(
    df=df_revised,
    known_time=revised_known
)

InsertResult(batch_id=2, workflow_id='sdk-workflow', series_id=1)

5. Read Latest Values

Get the most recent forecast for each time point.

# Read latest forecast values
df_latest = td.series('wind_power').where(site='offshore_1', type='forecast').read(
    start_valid=start,
    end_valid=start + timedelta(hours=24)
)
df_latest.head(10)

	value
valid_time
2025-01-01 00:00:00+00:00	105.0
2025-01-01 01:00:00+00:00	107.0
2025-01-01 02:00:00+00:00	109.0
2025-01-01 03:00:00+00:00	111.0
2025-01-01 04:00:00+00:00	113.0
2025-01-01 05:00:00+00:00	115.0
2025-01-01 06:00:00+00:00	117.0
2025-01-01 07:00:00+00:00	119.0
2025-01-01 08:00:00+00:00	121.0
2025-01-01 09:00:00+00:00	123.0

6. Read All Forecast Revisions

Get all forecast versions to see how predictions changed over time.

# Read all forecast revisions
df_all = td.series('wind_power').where(site='offshore_1', type='forecast').read(
    start_valid=start,
    end_valid=start + timedelta(hours=24),
    versions=True
)
print(f"All revisions (multi-index: known_time, valid_time):")
df_all.head(10)

All revisions (multi-index: known_time, valid_time):

		value
known_time	valid_time
2025-01-01 00:00:00+00:00	2025-01-01 00:00:00+00:00	100.0
	2025-01-01 01:00:00+00:00	102.0
	2025-01-01 02:00:00+00:00	104.0
	2025-01-01 03:00:00+00:00	106.0
	2025-01-01 04:00:00+00:00	108.0
	2025-01-01 05:00:00+00:00	110.0
	2025-01-01 06:00:00+00:00	112.0
	2025-01-01 07:00:00+00:00	114.0
	2025-01-01 08:00:00+00:00	116.0
	2025-01-01 09:00:00+00:00	118.0

7. Compare Forecasts

Visualize how the forecast changed between revisions.

import matplotlib.pyplot as plt

plt.figure(figsize=(12, 6))

for known_time, data in df_all.groupby(level='known_time'):
    plt.plot(data.index.get_level_values('valid_time'), data['value'].values, marker='o', label=f'Forecast at {known_time.strftime("%H:%M")}')

plt.xlabel('Valid Time')
plt.ylabel('Wind Power (MW)')
plt.title('Forecast Revisions')
plt.legend()
plt.grid(True, alpha=0.3)
plt.xticks(rotation=45)
plt.tight_layout()
plt.show()

Summary

You’ve learned the basics of TimeDB:

1. Create series - Define your time series with name, unit, labels, and overlapping=True for versioned data

2. Insert data - Store forecasts with known_time using insert()

3. Read latest - Get the most recent forecast for each time point using read()

4. Read revisions - Access all forecast versions using read(versions=True) to analyze changes

Key Concepts

• ``valid_time``: The time period being forecasted

• ``known_time``: When the forecast was made

• ``overlapping``: False (default) for immutable facts, True for versioned forecasts

• Series Collection: Use .series().where() to filter by name and labels

• Forecast Revisions: Multiple forecasts for the same valid_time with different known_time

Next Steps

• Check out nb_03_forecast_revisions.ipynb for more detailed examples

• Explore other notebooks for advanced features