{
"cells": [
{
"cell_type": "markdown",
"id": "81365e4d",
"metadata": {},
"source": [
"# TimeDB Quickstart\n",
"\n",
"Get started with TimeDB in 5 minutes. Learn how to store and query time series data with forecast revisions."
]
},
{
"cell_type": "markdown",
"id": "727d20ab",
"metadata": {},
"source": [
"## 1. Setup\n",
"\n",
"Import TimeDB and create a client."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "86225072",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Creating database schema...\n",
"✓ Schema created successfully\n"
]
}
],
"source": [
"from timedb import TimeDataClient\n",
"import pandas as pd\n",
"from datetime import datetime, timedelta, timezone\n",
"from dotenv import load_dotenv\n",
"load_dotenv()\n",
"\n",
"td = TimeDataClient()\n",
"td.delete()\n",
"td.create()"
]
},
{
"cell_type": "markdown",
"id": "9b575168",
"metadata": {},
"source": [
"## 2. Create a Series\n",
"\n",
"A series is identified by its name and optional labels. Since this is forecast data, we set `overlapping=True`."
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "5d16c90e",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" id=1 name=wind_power unit=MW labels={'site': 'offshore_1', 'type': 'forecast'} overlapping=True\n"
]
}
],
"source": [
"series_id = td.create_series(\n",
" name='wind_power',\n",
" unit='MW',\n",
" labels={'site': 'offshore_1', 'type': 'forecast'},\n",
" overlapping=True\n",
")\n",
"\n",
"# See what was created\n",
"for s in td.series('wind_power').list_series():\n",
" print(f\" id={s['series_id']} name={s['name']} unit={s['unit']} labels={s['labels']} overlapping={s['overlapping']}\")"
]
},
{
"cell_type": "markdown",
"id": "bfe4742f",
"metadata": {},
"source": [
"## 3. Insert Data\n",
"\n",
"Insert time series data with a DataFrame. The `known_time` indicates when the forecast was made."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "fd33e96b",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"InsertResult(batch_id=1, workflow_id='sdk-workflow', series_id=1)"
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Create forecast data\n",
"start = datetime(2025, 1, 1, 0, 0, tzinfo=timezone.utc)\n",
"times = [start + timedelta(hours=i) for i in range(24)]\n",
"values = [100 + i * 2 for i in range(24)] # Simple increasing pattern\n",
"\n",
"df = pd.DataFrame({\n",
" 'valid_time': times,\n",
" 'value': values\n",
"})\n",
"\n",
"# Insert with known_time (when forecast was made)\n",
"td.series('wind_power').where(site='offshore_1', type='forecast').insert(\n",
" df=df,\n",
" known_time=start\n",
")"
]
},
{
"cell_type": "markdown",
"id": "27fbffd7",
"metadata": {},
"source": [
"## 4. Insert a Revised Forecast\n",
"\n",
"Insert an updated forecast for the same time period with a new `known_time`."
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "8427abfb",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"InsertResult(batch_id=2, workflow_id='sdk-workflow', series_id=1)"
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Create revised forecast (made 6 hours later)\n",
"revised_known = start + timedelta(hours=6)\n",
"revised_values = [105 + i * 2 for i in range(24)] # Slightly different values\n",
"\n",
"df_revised = pd.DataFrame({\n",
" 'valid_time': times,\n",
" 'value': revised_values\n",
"})\n",
"\n",
"td.series('wind_power').where(site='offshore_1', type='forecast').insert(\n",
" df=df_revised,\n",
" known_time=revised_known\n",
")"
]
},
{
"cell_type": "markdown",
"id": "8caf881c",
"metadata": {},
"source": [
"## 5. Read Latest Values\n",
"\n",
"Get the most recent forecast for each time point."
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "d96d7e5e",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" value | \n",
"
\n",
" \n",
" | valid_time | \n",
" | \n",
"
\n",
" \n",
" \n",
" \n",
" | 2025-01-01 00:00:00+00:00 | \n",
" 105.0 | \n",
"
\n",
" \n",
" | 2025-01-01 01:00:00+00:00 | \n",
" 107.0 | \n",
"
\n",
" \n",
" | 2025-01-01 02:00:00+00:00 | \n",
" 109.0 | \n",
"
\n",
" \n",
" | 2025-01-01 03:00:00+00:00 | \n",
" 111.0 | \n",
"
\n",
" \n",
" | 2025-01-01 04:00:00+00:00 | \n",
" 113.0 | \n",
"
\n",
" \n",
" | 2025-01-01 05:00:00+00:00 | \n",
" 115.0 | \n",
"
\n",
" \n",
" | 2025-01-01 06:00:00+00:00 | \n",
" 117.0 | \n",
"
\n",
" \n",
" | 2025-01-01 07:00:00+00:00 | \n",
" 119.0 | \n",
"
\n",
" \n",
" | 2025-01-01 08:00:00+00:00 | \n",
" 121.0 | \n",
"
\n",
" \n",
" | 2025-01-01 09:00:00+00:00 | \n",
" 123.0 | \n",
"
\n",
" \n",
"
\n",
"
\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" | \n",
" value | \n",
"
\n",
" \n",
" | known_time | \n",
" valid_time | \n",
" | \n",
"
\n",
" \n",
" \n",
" \n",
" | 2025-01-01 00:00:00+00:00 | \n",
" 2025-01-01 00:00:00+00:00 | \n",
" 100.0 | \n",
"
\n",
" \n",
" | 2025-01-01 01:00:00+00:00 | \n",
" 102.0 | \n",
"
\n",
" \n",
" | 2025-01-01 02:00:00+00:00 | \n",
" 104.0 | \n",
"
\n",
" \n",
" | 2025-01-01 03:00:00+00:00 | \n",
" 106.0 | \n",
"
\n",
" \n",
" | 2025-01-01 04:00:00+00:00 | \n",
" 108.0 | \n",
"
\n",
" \n",
" | 2025-01-01 05:00:00+00:00 | \n",
" 110.0 | \n",
"
\n",
" \n",
" | 2025-01-01 06:00:00+00:00 | \n",
" 112.0 | \n",
"
\n",
" \n",
" | 2025-01-01 07:00:00+00:00 | \n",
" 114.0 | \n",
"
\n",
" \n",
" | 2025-01-01 08:00:00+00:00 | \n",
" 116.0 | \n",
"
\n",
" \n",
" | 2025-01-01 09:00:00+00:00 | \n",
" 118.0 | \n",
"
\n",
" \n",
"
\n",
"