Update README to match pgai docs

README.md

@@ -1,185 +1,192 @@
-|Linux/macOS|Linux i386|Windows|Coverity|Code Coverage|OpenSSF|
-|:---:|:---:|:---:|:---:|:---:|:---:|
-|[![Build Status Linux/macOS](https://github.com/timescale/timescaledb/actions/workflows/linux-build-and-test.yaml/badge.svg?branch=main&event=schedule)](https://github.com/timescale/timescaledb/actions/workflows/linux-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[![Build Status Linux i386](https://github.com/timescale/timescaledb/actions/workflows/linux-32bit-build-and-test.yaml/badge.svg?branch=main&event=schedule)](https://github.com/timescale/timescaledb/actions/workflows/linux-32bit-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[![Windows build status](https://github.com/timescale/timescaledb/actions/workflows/windows-build-and-test.yaml/badge.svg?branch=main&event=schedule)](https://github.com/timescale/timescaledb/actions/workflows/windows-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[![Coverity Scan Build Status](https://scan.coverity.com/projects/timescale-timescaledb/badge.svg)](https://scan.coverity.com/projects/timescale-timescaledb)|[![Code Coverage](https://codecov.io/gh/timescale/timescaledb/branch/main/graphs/badge.svg?branch=main)](https://codecov.io/gh/timescale/timescaledb)|[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8012/badge)](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>
+
+<div align=center>
+
+<h3>TimescaleDB is an extension for PostgreSQL that enables time-series workloads while increasing ingest, query, storage, and analytics performance</h3>
 
+[![Docs](https://img.shields.io/badge/Read_the_Timescale_docs-black?style=for-the-badge&logo=readthedocs&logoColor=white)](https://docs.timescale.com/)
+[![SLACK](https://img.shields.io/badge/Ask_the_Timescale_community-black?style=for-the-badge&logo=slack&logoColor=white)](https://timescaledb.slack.com/archives/C4GT3N90X)
+[![Try TimescaleDB for free](https://img.shields.io/badge/Try_Timescale_for_free-black?style=for-the-badge&logo=timescale&logoColor=white)](https://console.cloud.timescale.com/signup)
 
-## TimescaleDB
+</div>
 
-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.
+TimescaleDB scales PostgreSQL for time-series data with the help of [hypertables](https://docs.timescale.com/use-timescale/latest/hypertables/about-hypertables/). Hypertables are PostgreSQL tables that automatically partition your data by time and space. You interact with a hypertable in the same way as regular PostgreSQL table. Behind the scenes, the database performs the work of setting up and maintaining the hypertable's partitions.
+
+From the perspective of both use and management, TimescaleDB looks and feels like PostgreSQL, and can be managed and queried as
+such. However, it provides a range of features and optimizations that make managing your time-series data easier and more efficient.
 
 > [!WARNING]
 >
->  The latest Postgres minor releases (17.1, 16.5, 15.9, 14.14, 13.17, 12.21), released 2024-11-14, have an unexpected
+>  The latest Postgres minor releases (17.1, 16.5, 15.9, 14.14, 13.17, 12.21), released on 2024-11-14, have an unexpected
 >  breaking ABI change that may crash existing deployments of TimescaleDB, unless used with a TimescaleDB binary explicitly built against those new minor PG versions.
->  
->  
+>
+>
 >  Status and recommendations:
 >  - **Users of [Timescale Cloud](https://console.cloud.timescale.com/) are unaffected**. We are currently not upgrading cloud databases to these latest minor PG releases. But regardless, Timescale Cloud recompiles TimescaleDB against each new minor Postgres version, which would prevent any such incompatibility.
 >  - **Users to Timescale's [k8s docker image](https://github.com/timescale/timescaledb-docker-ha) are unaffected**.  We are currently not building a new release against these latest minor PG releases. But regardless, our docker image build process recompiles TimescaleDB against each new minor Postgres version, which would prevent any such incompatibility.
 >  - Users of other managed clouds (using TimescaleDB Apache-2 Edition) are recommended to not upgrade to these latest minor PG releases at this time, or discuss with their cloud provider how they build TimescaleDB with new minor releases.
 >  - Users who self-manage TimescaleDB are recommended to not upgrade to these latest minor PG releases at this time.
-> 
+>
 >  We are working with the PG community about how best to address this issue.  See [this thread on pgsql-hackers](https://www.postgresql.org/message-id/flat/CABOikdNmVBC1LL6pY26dyxAS2f%2BgLZvTsNt%3D2XbcyG7WxXVBBQ%40mail.gmail.com) for more info.
 >
 >  Thanks for your understanding! 🙏
 
+**Learn more about TimescaleDB**:
 
-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.
-
-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.
-
-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)
+- [Developer documentation](https://docs.timescale.com/)
+- [Release notes](https://tsdb.co/GitHubTimescaleDocsReleaseNotes)
+- [Testing TimescaleDB](test/README.md)
+- [Timescale community forum](https://www.timescale.com/forum/)
+- [GitHub issues](https://github.com/timescale/timescaledb/issues)
+- [Timescale support](https://tsdb.co/GitHubTimescaleSupport)
 
-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 TimescaleDB
 
-[Contributors welcome.](https://github.com/timescale/timescaledb/blob/main/CONTRIBUTING.md)
+TimescaleDB is available as a self-hosted solution or a managed cloud offering. Get TimescaleDB in either of the following ways:
 
-(To build TimescaleDB from source, see instructions in [_Building from source_](https://github.com/timescale/timescaledb/blob/main/docs/BuildSource.md).)
+- As a cloud solution:
 
-### Using TimescaleDB
+    - Get a free trial of [Timescale Cloud](https://console.cloud.timescale.com/signup) - TimescaleDB hosted on AWS and fully managed by Timescale.
+    - Get a free trial of [Managed Service for TimescaleDB](https://docs.timescale.com/mst/latest/) - TimescaleDB hosted on Azure and GCP and offered in partnership with [Aiven](https://aiven.io/).
 
-TimescaleDB scales PostgreSQL for time-series data via automatic
-partitioning across time and space (partitioning key), yet retains
-the standard PostgreSQL interface.
+- As a self-hosted solution:
 
-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.
+    - Install the [platform-specific package](https://docs.timescale.com/self-hosted/latest/install/).
+    - [Build from source](https://docs.timescale.com/self-hosted/latest/install/installation-source/).
 
-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.
+  The self-hosted TimescaleDB comes in the following editions: Apache 2 and Community. See the [documentation](https://docs.timescale.com/about/latest/timescaledb-editions/) for differences between the editions.
 
-From the perspective of both use and management, TimescaleDB just
-looks and feels like PostgreSQL, and can be managed and queried as
-such.
+  For reference and clarity, all code files in this repository reference [licensing](https://github.com/timescale/timescaledb/blob/main/tsl/LICENSE-TIMESCALE) in their header. Apache-2 licensed binaries can be built by passing `-DAPACHE_ONLY=1` to `bootstrap`.
 
-#### Before you start
+  PostgreSQL's out-of-the-box settings are typically too conservative for modern
+  servers and TimescaleDB. Make sure your `postgresql.conf`
+  settings are tuned, by either using [timescaledb-tune](https://github.com/timescale/timescaledb-tune)
+  or doing it manually.
 
-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.
+# Create a hypertable
 
-#### Creating a hypertable
+You create a regular table and then convert it into a hypertable.
 
 ```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:
+
+- [About hypertables](https://docs.timescale.com/use-timescale/latest/hypertables/)
+- [API reference](https://docs.timescale.com/api/latest/hypertable/)
+
+# Insert and query data
+
+Insert and query data in a hypertable via regular SQL commands.
+
+- Insert data into a hypertable named `conditions`:
+
+    ```sql
+    INSERT INTO conditions
+      VALUES
+        (NOW(), 'office', 70.0, 50.0),
+        (NOW(), 'basement', 66.5, 60.0),
+        (NOW(), 'garage', 77.0, 65.2);
+    ```
 
-#### Inserting and querying data
+- Return the number of entries written to the table conditions in the last 12 hours:
 
-Inserting data into the hypertable is done via normal SQL commands:
+    ```sql
+    SELECT COUNT(*) FROM conditions
+      WHERE time > NOW() - INTERVAL '12 hours';
+    ```
+
+See more:
+
+- [Query data](https://docs.timescale.com/use-timescale/latest/query-data/)
+- [Write data](https://docs.timescale.com/use-timescale/latest/write-data/)
+
+# Create time buckets
+
+Time buckets enable you to aggregate data in hypertables by time interval and calculate summary values.
+
+For example, calculate the average daily temperature in a table named `weather_conditions`. The table has a `time` and `temperature` columns:
 
 ```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;
+SELECT time_bucket('1 day', time) AS bucket,
+  avg(temperature) AS avg_temp
+FROM weather_conditions
+GROUP BY bucket
+ORDER BY bucket ASC;
 ```
 
-In addition, TimescaleDB includes additional functions for time-series
-analysis that are not present in vanilla PostgreSQL. (For example, the `time_bucket` function above.)
+See more:
 
-- [Quick start: Basic operations](https://tsdb.co/GitHubTimescaleBasicOperations)
-- [Reference examples](https://tsdb.co/GitHubTimescaleWriteData)
-- [TimescaleDB API](https://tsdb.co/GitHubTimescaleAPI)
+- [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/)
 
-### Installation
+# Create continuous aggregates
 
-[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.
+Continuous aggregates are designed to make queries on very large datasets run faster. They use PostgreSQL [materialized views](https://www.postgresql.org/docs/current/rules-materializedviews.html) to continuously and incrementally refresh a query in the background, so that when you run the query, only the data that has changed needs to be computed, not the entire dataset.
 
-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/).
+See more:
 
-To build from source, see [Building from source](https://github.com/timescale/timescaledb/blob/main/docs/BuildSource.md).
+- [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/)
 
-## Resources
+# Tier data
 
-### Architecture documents
+TimescaleDB tiered storage architecture includes a standard high-performance storage tier and a low-cost object storage tier. You can migrate rarely used data to the object storage to cut costs. Data is tiered on the level of chunks, that is, individual parts of tables. This means that a single table can be spread among storage tiers for ultimate cost optimization.
 
-- [Basic TimescaleDB Features](tsl/README.md)
-- [Advanced TimescaleDB Features](tsl/README.md)
-- [Testing TimescaleDB](test/README.md)
+<img src="https://assets.timescale.com/docs/images/tiered-storage.png" alt="tiered-storage"/>
+
+See more:
+
+- [About tiered storage](https://docs.timescale.com/use-timescale/latest/data-tiering/)
 
-### Useful tools
+# Ensure high availability
 
-- [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.
+For services with different downtime tolerance, TimescaleDB offers high-availability (HA) and read replicas. HA replicas are exact, up-to-date copies of your database. They automatically take over operations if the original primary data node becomes unavailable. Read replicas are read-only copies of the primary data instance. Queries on read replicas have minimal impact on the performance of the primary data instance.
+
+<img src="https://assets.timescale.com/docs/images/high-availability.png" alt="high availability"/>
+
+See more:
+
+- [About high availability and read replication](https://docs.timescale.com/use-timescale/latest/ha-replicas/)
+
+# Check build status
+
+|Linux/macOS|Linux i386|Windows|Coverity|Code Coverage|OpenSSF|
+|:---:|:---:|:---:|:---:|:---:|:---:|
+|[![Build Status Linux/macOS](https://github.com/timescale/timescaledb/actions/workflows/linux-build-and-test.yaml/badge.svg?branch=main&event=schedule)](https://github.com/timescale/timescaledb/actions/workflows/linux-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[![Build Status Linux i386](https://github.com/timescale/timescaledb/actions/workflows/linux-32bit-build-and-test.yaml/badge.svg?branch=main&event=schedule)](https://github.com/timescale/timescaledb/actions/workflows/linux-32bit-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[![Windows build status](https://github.com/timescale/timescaledb/actions/workflows/windows-build-and-test.yaml/badge.svg?branch=main&event=schedule)](https://github.com/timescale/timescaledb/actions/workflows/windows-build-and-test.yaml?query=workflow%3ARegression+branch%3Amain+event%3Aschedule)|[![Coverity Scan Build Status](https://scan.coverity.com/projects/timescale-timescaledb/badge.svg)](https://scan.coverity.com/projects/timescale-timescaledb)|[![Code Coverage](https://codecov.io/gh/timescale/timescaledb/branch/main/graphs/badge.svg?branch=main)](https://codecov.io/gh/timescale/timescaledb)|[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8012/badge)](https://www.bestpractices.dev/projects/8012)|
 
-### Additional documentation
 
-- [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)
+# Get involved
 
-### Community & help
+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.
 
-- [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)
+# Learn about Timescale
 
-### Releases & updates
+Timescale is a PostgreSQL database company. To learn more, visit [timescale.com](https://www.timescale.com).
 
- - [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.
+Timescale Cloud is a high-performance, developer focused, cloud platform that provides PostgreSQL services
+for the most demanding AI, time-series, analytics, and event workloads. Timescale Cloud is ideal for production applications and provides high availability, streaming backups, upgrades over time, roles and permissions, and great security.
 
-### Contributing
 
-- [Contributor instructions](https://github.com/timescale/timescaledb/blob/main/CONTRIBUTING.md)
-- [Code style guide](https://github.com/timescale/timescaledb/blob/main/docs/StyleGuide.md)