Examples

TimeDB includes interactive Jupyter notebooks that demonstrate key features and usage patterns.

Before running the examples locally, ensure you have:

1. PostgreSQL Database: A PostgreSQL database (version 12+) with TimescaleDB

2. Environment Variables: Set your database connection string:

   export TIMEDB_DSN="postgresql://user:password@host:port/database"
   

3. Jupyter: Install Jupyter to run the notebooks interactively:

   pip install jupyter
   

Available Notebooks

• TimeDB Quickstart
• Writing and Reading Time Series with TimeDB
• Unit Validation and Conversion with TimeDB
• Forecast Revisions with TimeDB
• Summary
• Time Series Changes and Versioning with TimeDB
• Summary
• Using the TimeDB REST API
• 3.1: Insert Data via POST /values
• 3.2: List and Filter Series via GET /series
• 4.1: Read with versions=true
• Summary

Notebook Descriptions

Quickstart: Get up and running in 5 minutes with basic insert, read, and versioning operations.

nb_01_write_read_pandas: Demonstrates the fluent API with label-based filtering and broad vs. targeted operations on multiple series.

nb_02_units_validation: Shows how TimeDB handles unit conversion and validation with Pint.

nb_03_forecast_revisions: Deep dive into overlapping series (versioned forecasts) with multiple revisions and historical tracking.

nb_04_timeseries_changes: Demonstrates updating records in-place for flat series and tracking changes over time.

nb_05_api_usage: Examples of using the REST API for reading and writing time series data.