timescaledb-ts

  

Welcome to the Timescale Typescript library. This library is a collection of packages that help you work with TimescaleDB in a Typescript environment.

If you are looking to setup this project locally, you can follow the instructions in the CONTRIBUTING.md file.

Packages

- @timescaledb/typeorm - Official TimescaleDB integration for TypeORM.
- @timescaledb/core - Migration and query helpers
- @timescaledb/schemas - TimescaleDB object schemas
- @timescaledb/utils - utilities and helpers

Examples

- Node Sequelize Example - Using TimescaleDB with Node.js and Sequelize
- Node TypeORM Example - Using TimescaleDB with Node.js and TypeORM

Guides

- Getting Started - A guide to getting started with TimescaleDB and this library.
- Working with Energy Data - A guide to working with energy data in TimescaleDB.
- Working with Candlesticks - A guide to working with candlestick data in TimescaleDB.

Feature Compatibility

| Feature | Core | TypeORM | Sequelize |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------- | -------------------- |
| Core Functions | | | |
| Create Hypertable | ✅ | ✅ Auto | ✅ Manual (via Core) |
| Add Compression | ✅ | ✅ Auto | ✅ Manual (via Core) |
| Add Compression Policy | ✅ | ✅ Auto | ✅ Manual (via Core) |
| Add Retention Policy | ❌ | ❌ | ❌ |
| Continuous Aggregates | ✅ | ✅ Auto | ✅ Manual (via Core) |
| Hyperfunctions | | | |
| Time Bucket | ✅ | ✅ | ✅ Manual (via Core) |
| Candlestick Aggregates | ✅ | ✅ | ✅ Manual (via Core) |
| Stats Aggregates | ❌ | ❌ | ❌ |
| Percentile Approximation | ❌ | ❌ | ❌ |
| Info Views | | | |
| Chunks | ❌ | ❌ | ❌ |
| User Defined Actions | ❌ | ❌ | ❌ |
| Compression Settings | ✅ | ✅ | ✅ Manual (via Core) |
| Continuous Aggregates | ✅ | ✅ | ✅ Manual (via Core) |
| Hierarchical continuous aggregates | ✅ | ✅ | ✅ Manual (via Core) |

Legend:

- ✅ Supported
- ❌ Not Supported at this time
- Auto = Automatic integration with ORM
- Manual = Manual integration using Core package

Getting Started

- TypeORM: README

To get started with TypeORM simply install the package:

``bash
npm install typeorm @timescaledb/typeorm
`

Then you can use the @Hypertable decorator to define your hypertables:

`diff
import { Entity, PrimaryColumn } from 'typeorm';
+ import { Hypertable, TimeColumn } from '@timescaledb/typeorm';

+ @Hypertable({ ... })
@Entity('page_loads')
export class PageLoad {
@PrimaryColumn({ type: 'varchar' })
user_agent!: string;

+ @TimeColumn()
time!: Date;
}
`

Then you can query a Hypertable using the attached methods:

`typescript
import { AppDataSource } from './data-source';
import { PageLoad } from './models/PageLoad';

const repository = AppDataSource.getRepository(PageLoad);
const stats = await repository.getTimeBucket({
timeRange: {
start: new Date('2025-01-01'),
end: new Date('2025-01-02'),
},
where: {
user_agent: 'Chrome',
},
bucket: {
interval: '1 hour',
metrics: [{ type: 'distinct_count', column: 'user_agent', alias: 'unique_users' }],
},
});

console.log(stats);
// [
// { time: '2021-01-01T00:00:00.000Z', unique_users: 5 },
// { time: '2021-01-01T01:00:00.000Z', unique_users: 10 },
// { time: '2021-01-01T02:00:00.000Z', unique_users: 15 },
// ...
// ]
``

License

The library is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Timescale project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.