-
Notifications
You must be signed in to change notification settings - Fork 894
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: atovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox <iain@timescale.com> Signed-off-by: Fabrízio de Royes Mello <fabriziomello@gmail.com> Signed-off-by: Ramon Guiu <ramon@timescale.com> Co-authored-by: Fabrízio de Royes Mello <fabriziomello@gmail.com> Co-authored-by: Iain Cox <iain@timescale.com> Co-authored-by: Pallavi Sontakke <pallavi@timescale.com> Co-authored-by: Ramon Guiu <ramon@timescale.com>
- Loading branch information
5 people
authored
Dec 19, 2024
1 parent
155efa1
commit 9a85dd9
Showing
1 changed file
with
153 additions
and
127 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,178 +1,204 @@ | ||
| |Linux/macOS|Linux i386|Windows|Coverity|Code Coverage|OpenSSF| | ||
| |:---:|:---:|:---:|:---:|:---:|:---:| | ||
| |[](https://github.com/timescale/timescaledb/actions/workflows/linux-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[](https://github.com/timescale/timescaledb/actions/workflows/linux-32bit-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[](https://github.com/timescale/timescaledb/actions/workflows/windows-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[](https://scan.coverity.com/projects/timescale-timescaledb)|[](https://codecov.io/gh/timescale/timescaledb)|[](https://www.bestpractices.dev/projects/8012)| | ||
|
|
||
| <div align=center> | ||
| <picture align=center> | ||
| <source media="(prefers-color-scheme: dark)" srcset="https://assets.timescale.com/docs/images/timescale-logo-dark-mode.svg"> | ||
| <source media="(prefers-color-scheme: light)" srcset="https://assets.timescale.com/docs/images/timescale-logo-light-mode.svg"> | ||
| <img alt="Timescale logo" > | ||
| </picture> | ||
| </div> | ||
|
|
||
| ## TimescaleDB | ||
| <div align=center> | ||
|
|
||
| TimescaleDB is an open-source database designed to make SQL scalable for | ||
| time-series data. It is engineered up from PostgreSQL and packaged as a | ||
| PostgreSQL extension, providing automatic partitioning across time and space | ||
| (partitioning key), as well as full SQL support. | ||
| <h3>TimescaleDB is a PostgreSQL extension for high-performance real-time analytics on time-series and event data</h3> | ||
|
|
||
| If you prefer not to install or administer your instance of TimescaleDB, try the | ||
| 30 day free trial of [Timescale Cloud](https://console.cloud.timescale.com/signup), our fully managed cloud offering. | ||
| Timescale is pay-as-you-go. We don't charge for storage you dont use, backups, snapshots, ingress or egress. | ||
| [](https://docs.timescale.com/) | ||
| [](https://timescaledb.slack.com/archives/C4GT3N90X) | ||
| [](https://console.cloud.timescale.com/signup) | ||
|
|
||
| To determine which option is best for you, see [Timescale Products](https://tsdb.co/GitHubTimescaleProducts) | ||
| for more information about our Apache-2 version, TimescaleDB Community (self-hosted), and Timescale | ||
| Cloud (hosted), including: feature comparisons, FAQ, documentation, and support. | ||
| </div> | ||
|
|
||
| Below is an introduction to TimescaleDB. For more information, please check out | ||
| these other resources: | ||
| - [Developer Documentation](https://docs.timescale.com/getting-started/latest/services/) | ||
| - [Slack Channel](https://slack-login.timescale.com) | ||
| - [Timescale Community Forum](https://www.timescale.com/forum/) | ||
| - [Timescale Release Notes & Future Plans](https://tsdb.co/GitHubTimescaleDocsReleaseNotes) | ||
| ## Install TimescaleDB | ||
|
|
||
| For reference and clarity, all code files in this repository reference | ||
| licensing in their header (either the Apache-2-open-source license | ||
| or [Timescale License (TSL)](https://github.com/timescale/timescaledb/blob/main/tsl/LICENSE-TIMESCALE) | ||
| ). Apache-2 licensed binaries can be built by passing `-DAPACHE_ONLY=1` to `bootstrap`. | ||
| Install from a Docker container: | ||
|
|
||
| [Contributors welcome.](https://github.com/timescale/timescaledb/blob/main/CONTRIBUTING.md) | ||
| 1. Run the TimescaleDB container: | ||
|
|
||
| (To build TimescaleDB from source, see instructions in [_Building from source_](https://github.com/timescale/timescaledb/blob/main/docs/BuildSource.md).) | ||
| ```bash | ||
| docker run -d --name timescaledb -p 5432:5432 -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg17 | ||
| ``` | ||
|
|
||
| ### Using TimescaleDB | ||
| 1. Connect to a database: | ||
|
|
||
| TimescaleDB scales PostgreSQL for time-series data via automatic | ||
| partitioning across time and space (partitioning key), yet retains | ||
| the standard PostgreSQL interface. | ||
| ```bash | ||
| docker exec -it timescaledb psql -d "postgres://postgres:password@localhost/postgres" | ||
| ``` | ||
|
|
||
| In other words, TimescaleDB exposes what look like regular tables, but | ||
| are actually only an | ||
| abstraction (or a virtual view) of many individual tables comprising the | ||
| actual data. This single-table view, which we call a | ||
| [hypertable](https://tsdb.co/GitHubTimescaleHypertable), | ||
| is comprised of many chunks, which are created by partitioning | ||
| the hypertable's data in either one or two dimensions: by a time | ||
| interval, and by an (optional) "partition key" such as | ||
| device id, location, user id, etc. | ||
| See [other installation options](https://docs.timescale.com/self-hosted/latest/install/) or try [Timescale Cloud](https://docs.timescale.com/getting-started/latest/) for free. | ||
|
|
||
| Virtually all user interactions with TimescaleDB are with | ||
| hypertables. Creating tables and indexes, altering tables, inserting | ||
| data, selecting data, etc., can (and should) all be executed on the | ||
| hypertable. | ||
| ## Create a hypertable | ||
|
|
||
| From the perspective of both use and management, TimescaleDB just | ||
| looks and feels like PostgreSQL, and can be managed and queried as | ||
| such. | ||
|
|
||
| #### Before you start | ||
|
|
||
| PostgreSQL's out-of-the-box settings are typically too conservative for modern | ||
| servers and TimescaleDB. You should make sure your `postgresql.conf` | ||
| settings are tuned, either by using [timescaledb-tune](https://github.com/timescale/timescaledb-tune) | ||
| or doing it manually. | ||
|
|
||
| #### Creating a hypertable | ||
| You create a regular table and then convert it into a hypertable. A hypertable automatically partitions data into chunks based on your configuration. | ||
|
|
||
| ```sql | ||
| -- Do not forget to create timescaledb extension | ||
| -- Create timescaledb extension | ||
| CREATE EXTENSION timescaledb; | ||
| -- We start by creating a regular SQL table | ||
| -- Create a regular SQL table | ||
| CREATE TABLE conditions ( | ||
| time TIMESTAMPTZ NOT NULL, | ||
| location TEXT NOT NULL, | ||
| temperature DOUBLE PRECISION NULL, | ||
| humidity DOUBLE PRECISION NULL | ||
| ); | ||
| -- Then we convert it into a hypertable that is partitioned by time | ||
| SELECT create_hypertable('conditions', 'time'); | ||
| -- Convert the table into a hypertable that is partitioned by time | ||
| SELECT create_hypertable('conditions', by_range('time')); | ||
| ``` | ||
|
|
||
| - [Quick start: Creating hypertables](https://docs.timescale.com/use-timescale/latest/hypertables/create/) | ||
| - [Reference examples](https://tsdb.co/GitHubTimescaleHypertableReference) | ||
| See more: | ||
|
|
||
| #### Inserting and querying data | ||
| - [About hypertables](https://docs.timescale.com/use-timescale/latest/hypertables/) | ||
| - [API reference](https://docs.timescale.com/api/latest/hypertable/) | ||
|
|
||
| Inserting data into the hypertable is done via normal SQL commands: | ||
| ## Enable columnstore | ||
|
|
||
| ```sql | ||
| INSERT INTO conditions(time, location, temperature, humidity) | ||
| VALUES (NOW(), 'office', 70.0, 50.0); | ||
|
|
||
| SELECT * FROM conditions ORDER BY time DESC LIMIT 100; | ||
|
|
||
| SELECT time_bucket('15 minutes', time) AS fifteen_min, | ||
| location, COUNT(*), | ||
| MAX(temperature) AS max_temp, | ||
| MAX(humidity) AS max_hum | ||
| FROM conditions | ||
| WHERE time > NOW() - interval '3 hours' | ||
| GROUP BY fifteen_min, location | ||
| ORDER BY fifteen_min DESC, max_temp DESC; | ||
| ``` | ||
| TimescaleDB's hypercore is a hybrid row-columnar store that boosts analytical query performance on your time-series and event data, while reducing data size by more than 90%. This keeps your queries operating at lightning speed and ensures low storage costs as you scale. Data is inserted in row format in the rowstore and converted to columnar format in the columnstore based on your configuration. | ||
| - Configure the columnstore on a hypertable: | ||
| ```sql | ||
| ALTER TABLE conditions SET ( | ||
| timescaledb.compress, | ||
| timescaledb.compress_segmentby = 'device_id' | ||
| ); | ||
| ``` | ||
| - Create a policy to automatically convert chunks in row format that are older than seven days to chunks in the columnar format: | ||
| ```sql | ||
| SELECT add_compression_policy('conditions', INTERVAL '7 days'); | ||
| ``` | ||
| See more: | ||
| - [About columnstore](https://docs.timescale.com/use-timescale/latest/compression/about-compression/) | ||
| - [Enable columnstore manually](https://docs.timescale.com/use-timescale/latest/compression/manual-compression/) | ||
| - [API reference](https://docs.timescale.com/api/latest/compression/) | ||
| In addition, TimescaleDB includes additional functions for time-series | ||
| analysis that are not present in vanilla PostgreSQL. (For example, the `time_bucket` function above.) | ||
| ## Insert and query data | ||
| - [Quick start: Basic operations](https://tsdb.co/GitHubTimescaleBasicOperations) | ||
| - [Reference examples](https://tsdb.co/GitHubTimescaleWriteData) | ||
| - [TimescaleDB API](https://tsdb.co/GitHubTimescaleAPI) | ||
| Insert and query data in a hypertable via regular SQL commands. For example: | ||
| ### Installation | ||
| - Insert data into a hypertable named `conditions`: | ||
| Installation options are: | ||
| ```sql | ||
| INSERT INTO conditions | ||
| VALUES | ||
| (NOW(), 'office', 70.0, 50.0), | ||
| (NOW(), 'basement', 66.5, 60.0), | ||
| (NOW(), 'garage', 77.0, 65.2); | ||
| ``` | ||
| - **[Timescale Cloud](https://tsdb.co/GitHubTimescale)**: A fully-managed TimescaleDB in the cloud, is | ||
| available via a free trial. Create a PostgreSQL database in the cloud with TimescaleDB pre-installed | ||
| so you can power your application with TimescaleDB without the management overhead. | ||
| - Return the number of entries written to the table conditions in the last 12 hours: | ||
| - **Platform packages**: TimescaleDB is also available pre-packaged for several platforms such as | ||
| Linux, Windows, MacOS, Docker, and Kubernetes. For more information, see [Install TimescaleDB](https://docs.timescale.com/self-hosted/latest/install/). | ||
| ```sql | ||
| SELECT | ||
| COUNT(*) | ||
| FROM | ||
| conditions | ||
| WHERE | ||
| time > NOW() - INTERVAL '12 hours'; | ||
| ``` | ||
| - **Build from source**: See [Building from source](https://github.com/timescale/timescaledb/blob/main/docs/BuildSource.md). | ||
| See more: | ||
| We recommend not using TimescaleDB with PostgreSQL 17.1, 16.5, 15.9, 14.14, 13.17, 12.21. | ||
| These minor versions [introduced a breaking binary interface change][postgres-breaking-change] that, | ||
| once identified, was reverted in subsequent minor PostgreSQL versions 17.2, 16.6, 15.10, 14.15, 13.18, and 12.22. | ||
| When you build from source, best practice is to build with PostgreSQL 17.2, 16.6, etc and higher. | ||
| Users of [Timescale Cloud](https://console.cloud.timescale.com/) and Platform packages built and | ||
| distributed by Timescale are unaffected. | ||
| - [Query data](https://docs.timescale.com/use-timescale/latest/query-data/) | ||
| - [Write data](https://docs.timescale.com/use-timescale/latest/write-data/) | ||
| ## Resources | ||
| ## Create time buckets | ||
| ### Architecture documents | ||
| Time buckets enable you to aggregate data in hypertables by time interval and calculate summary values. | ||
| - [Basic TimescaleDB Features](tsl/README.md) | ||
| - [Advanced TimescaleDB Features](tsl/README.md) | ||
| - [Testing TimescaleDB](test/README.md) | ||
| For example, calculate the average daily temperature in a table named `conditions`. The table has a `time` and `temperature` columns: | ||
| ### Useful tools | ||
| ```sql | ||
| SELECT | ||
| time_bucket('1 day', time) AS bucket, | ||
| AVG(temperature) AS avg_temp | ||
| FROM | ||
| conditions | ||
| GROUP BY | ||
| bucket | ||
| ORDER BY | ||
| bucket ASC; | ||
| ``` | ||
| See more: | ||
| - [About time buckets](https://docs.timescale.com/use-timescale/latest/time-buckets/about-time-buckets/) | ||
| - [API reference](https://docs.timescale.com/api/latest/hyperfunctions/time_bucket/) | ||
| - [All TimescaleDB features](https://docs.timescale.com/use-timescale/latest/) | ||
| - [Tutorials](https://docs.timescale.com/tutorials/latest/) | ||
| ## Create continuous aggregates | ||
| Continuous aggregates are designed to make queries on very large datasets run faster. They continuously and incrementally refresh a query in the background, so that when you run such query, only the data that has changed needs to be computed, not the entire dataset. This is what makes them different from regular PostgreSQL [materialized views](https://www.postgresql.org/docs/current/rules-materializedviews.html), which cannot be incrementally materialized and have to be rebuilt from scratch every time you want to refresh it. | ||
| For example, create a continuous aggregate view for daily weather data in two simple steps: | ||
| 1. Create a materialized view: | ||
| - [timescaledb-tune](https://github.com/timescale/timescaledb-tune): Helps | ||
| set your PostgreSQL configuration settings based on your system's resources. | ||
| - [timescaledb-parallel-copy](https://github.com/timescale/timescaledb-parallel-copy): | ||
| Parallelize your initial bulk loading by using PostgreSQL's `COPY` across | ||
| multiple workers. | ||
| ```sql | ||
| CREATE MATERIALIZED VIEW conditions_summary_daily | ||
| WITH (timescaledb.continuous) AS | ||
| SELECT | ||
| device, | ||
| time_bucket(INTERVAL '1 day', time) AS bucket, | ||
| AVG(temperature), | ||
| MAX(temperature), | ||
| MIN(temperature) | ||
| FROM | ||
| conditions | ||
| GROUP BY | ||
| device, | ||
| bucket; | ||
| ``` | ||
| ### Additional documentation | ||
| 1. Create a policy to refresh the view every hour: | ||
| - [Why use TimescaleDB?](https://tsdb.co/GitHubTimescaleIntro) | ||
| - [Migrating from PostgreSQL](https://docs.timescale.com/migrate/latest/) | ||
| - [Writing data](https://tsdb.co/GitHubTimescaleWriteData) | ||
| - [Querying and data analytics](https://tsdb.co/GitHubTimescaleReadData) | ||
| - [Tutorials and sample data](https://tsdb.co/GitHubTimescaleTutorials) | ||
| ```sql | ||
| SELECT | ||
| add_continuous_aggregate_policy( | ||
| 'conditions_summary_daily', | ||
| start_offset => INTERVAL '1 month', | ||
| end_offset => INTERVAL '1 day', | ||
| schedule_interval => INTERVAL '1 hour' | ||
| ); | ||
| ``` | ||
| See more: | ||
| ### Community & help | ||
| - [About continuous aggregates](https://docs.timescale.com/use-timescale/latest/continuous-aggregates/) | ||
| - [API reference](https://docs.timescale.com/api/latest/continuous-aggregates/create_materialized_view/) | ||
| - [Slack Channel](https://slack.timescale.com) | ||
| - [Github Issues](https://github.com/timescale/timescaledb/issues) | ||
| - [Timescale Support](https://tsdb.co/GitHubTimescaleSupport): see support options (community & subscription) | ||
| ## Want TimescaleDB hosted and managed for you? Try Timescale Cloud | ||
| [Timescale Cloud](https://docs.timescale.com/getting-started/latest/) is a cloud-based PostgreSQL platform for resource-intensive workloads. We help you build faster, scale further, and stay under budget. A Timescale Cloud service is a single optimized 100% PostgreSQL database instance that you use as is, or extend with capabilities specific to your business needs. The available capabilities are: | ||
| - **Time-series and analytics**: PostgreSQL with TimescaleDB. The PostgreSQL you know and love, supercharged with functionality for storing and querying time-series data at scale for analytics and other use cases. Get faster time-based queries with hypertables, continuous aggregates, and columnar storage. Save on storage with native compression, data retention policies, and bottomless data tiering to Amazon S3. | ||
| - **AI and vector**: PostgreSQL with vector extensions. Use PostgreSQL as a vector database with purpose built extensions for building AI applications from start to scale. Get fast and accurate similarity search with the pgvector and pgvectorscale extensions. Create vector embeddings and perform LLM reasoning on your data with the pgai extension. | ||
| - **PostgreSQL**: the trusted industry-standard RDBMS. Ideal for applications requiring strong data consistency, complex relationships, and advanced querying capabilities. Get ACID compliance, extensive SQL support, JSON handling, and extensibility through custom functions, data types, and extensions. | ||
| All services include all the cloud tooling you'd expect for production use: [automatic backups](https://docs.timescale.com/use-timescale/latest/backup-restore/backup-restore-cloud/), [high availability](https://docs.timescale.com/use-timescale/latest/ha-replicas/), [read replicas](https://docs.timescale.com/use-timescale/latest/ha-replicas/read-scaling/), [data forking](https://docs.timescale.com/use-timescale/latest/services/service-management/#fork-a-service), [connection pooling](https://docs.timescale.com/use-timescale/latest/services/connection-pooling/), [tiered storage](https://docs.timescale.com/use-timescale/latest/data-tiering/), [usage-based storage](https://docs.timescale.com/about/latest/pricing-and-account-management/), and much more. | ||
|
|
||
| ## Check build status | ||
|
|
||
| |Linux/macOS|Linux i386|Windows|Coverity|Code Coverage|OpenSSF| | ||
| |:---:|:---:|:---:|:---:|:---:|:---:| | ||
| |[](https://github.com/timescale/timescaledb/actions/workflows/linux-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[](https://github.com/timescale/timescaledb/actions/workflows/linux-32bit-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[](https://github.com/timescale/timescaledb/actions/workflows/windows-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[](https://scan.coverity.com/projects/timescale-timescaledb)|[](https://codecov.io/gh/timescale/timescaledb)|[](https://www.bestpractices.dev/projects/8012)| | ||
|
|
||
| ### Releases & updates | ||
| ## Get involved | ||
|
|
||
| - [Timescale Release Notes](https://tsdb.co/GitHubTimescaleDocsReleaseNotes): see detailed information about current and past | ||
| versions and subscribe to get | ||
| notified about new releases, fixes, and early access/beta programs. | ||
| We welcome contributions to TimescaleDB! See [Contributing](https://github.com/timescale/timescaledb/blob/main/CONTRIBUTING.md) and [Code style guide](https://github.com/timescale/timescaledb/blob/main/docs/StyleGuide.md) for details. | ||
|
|
||
| ### Contributing | ||
| ## Learn about Timescale | ||
|
|
||
| - [Contributor instructions](https://github.com/timescale/timescaledb/blob/main/CONTRIBUTING.md) | ||
| - [Code style guide](https://github.com/timescale/timescaledb/blob/main/docs/StyleGuide.md) | ||
| Timescale is PostgreSQL made powerful. To learn more about the company and its products, visit [timescale.com](https://www.timescale.com). | ||
|
|
||
| [postgres-breaking-change]: https://www.postgresql.org/about/news/postgresql-172-166-1510-1415-1318-and-1222-released-2965/ |