Skip to main content

Django timescaledb

A database backend and tooling for Timescaledb.

This is a maintained fork of django-timescaledb, released on PyPI as django-timescaledb-ng. The original has had no PyPI release since 0.2.13 (February 2023). This fork is tested on Django 4.2 to 6.0 and Python 3.9 to 3.13. The import name is still timescale, so it replaces the original and the two cannot be installed together.

Based on gist from WeRiot.

Quick start

  1. Install via pip

pip install django-timescaledb-ng
  1. Use as DATABASE engine in settings.py:

Standard PostgreSQL

DATABASES = {
    'default': {
        'ENGINE': 'timescale.db.backends.postgresql',
        ...
    },
}

PostGIS

DATABASES = {
    'default': {
        'ENGINE': 'timescale.db.backends.postgis',
        ...
    },
}

If you already make use of a custom PostgreSQL db backend you can set the path in settings.py.

TIMESCALE_DB_BACKEND_BASE = "django.contrib.gis.db.backends.postgis"
  1. Inherit from the TimescaleModel. A hypertable will automatically be created.

class TimescaleModel(models.Model):
  """
  A helper class for using Timescale within Django, has the TimescaleManager and
  TimescaleDateTimeField already present. This is an abstract class it should
  be inheritted by another class for use.
  """
  time = TimescaleDateTimeField(interval="1 day")

  objects = TimescaleManager()

  class Meta:
      abstract = True

Implementation would look like this

from timescale.db.models.models import TimescaleModel

class Metric(TimescaleModel):
   temperature = models.FloatField()

If you already have a table, you can either add time field of type TimescaleDateTimeField to your model or rename (if not already named time) and change type of existing DateTimeField (rename first then run makemigrations and then change the type, so that makemigrations considers it as change in same field instead of removing and adding new field). This also triggers the creation of a hypertable.

from timescale.db.models.fields import TimescaleDateTimeField
from timescale.db.models.managers import TimescaleManager

class Metric(models.Model):
  time = TimescaleDateTimeField(interval="1 day")

  objects = models.Manager()
  timescale = TimescaleManager()

The name of the field is important as Timescale specific feratures require this as a property of their functions. ### Reading Data

“TimescaleDB hypertables are designed to behave in the same manner as PostgreSQL database tables for reading data, using standard SQL commands.”

As such the use of the Django’s ORM is perfectally suited to this type of data. By leveraging a custom model manager and queryset we can extend the queryset methods to include Timescale functions.

Time Bucket More Info

Metric.timescale.filter(time__range=date_range).time_bucket('time', '1 hour')

# expected output

<TimescaleQuerySet [{'bucket': datetime.datetime(2020, 12, 22, 11, 0, tzinfo=<UTC>)}, ... ]>

Time Bucket Gap Fill More Info

from metrics.models import *
from django.db.models import Count, Avg
from django.utils import timezone
from datetime import timedelta

ranges = (timezone.now() - timedelta(days=2), timezone.now())

(Metric.timescale
  .filter(time__range=ranges)
  .time_bucket_gapfill('time', '1 day', ranges[0], ranges[1], datapoints=240)
  .annotate(Avg('temperature')))

# expected output

<TimescaleQuerySet [{'bucket': datetime.datetime(2020, 12, 21, 21, 24, tzinfo=<UTC>), 'temperature__avg': None}, ...]>

Histogram More Info

from metrics.models import *
from django.db.models import Count
from django.utils import timezone
from datetime import timedelta

ranges = (timezone.now() - timedelta(days=3), timezone.now())

(Metric.timescale
  .filter(time__range=ranges)
  .values('device')
  .histogram(field='temperature', min_value=50.0, max_value=55.0, num_of_buckets=10)
  .annotate(Count('device')))

# expected output

<TimescaleQuerySet [{'histogram': [0, 0, 0, 87, 93, 125, 99, 59, 0, 0, 0, 0], 'device__count': 463}]>

Metadata

Release files for django-timescaledb-ng 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-timescaledb-ng 0.3.1
File Size Uploaded Provenance Actions
django_timescaledb_ng-0.3.1.tar.gz 13.9 kB Without provenance Details for django_timescaledb_ng-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-timescaledb-ng 0.3.1
File Interpreter ABI Platform Actions
django_timescaledb_ng-0.3.1-py3-none-any.whl Python 3 none any Details for django_timescaledb_ng-0.3.1-py3-none-any.whl

Total release size: 33.8 kB

Release files / django_timescaledb_ng-0.3.1.tar.gz

Download URL django_timescaledb_ng-0.3.1.tar.gz
Size 13.9 kB
Tags Source
SHA-256 checksum
How to use checksums
2a1095927c9a6bae177b437067498336b1444fc2bf283e265c4f688d71f00b21
BLAKE2b-256 checksum
How to use checksums
dfedb9e88bf55e61dbcec38394606fad36d04f643ee40a50a158d62f16e27466
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / django_timescaledb_ng-0.3.1-py3-none-any.whl

Download URL django_timescaledb_ng-0.3.1-py3-none-any.whl
Size 19.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1e7cad9ca904a502f744beb6830527dcf924dc7ad315264825076df8f4ddfcb0
BLAKE2b-256 checksum
How to use checksums
29dace44ca68db95476992e0976d4f4010759ff77eaad25d9e528f66fd7512f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for django-timescaledb-ng 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page