From bc3bf1e265308c4c08c12ceff87191871ad05f2b Mon Sep 17 00:00:00 2001 From: Jaromir Hamala Date: Sat, 6 Dec 2025 13:35:30 +0100 Subject: [PATCH 1/5] docs: recommend designated timestamps as essential, not optional Reframe designated timestamp documentation to reflect their importance for time-series workloads. Add capability table showing dependent features, code example, and note about lookup table exceptions. --- documentation/concept/designated-timestamp.md | 94 ++++++++++++------- 1 file changed, 60 insertions(+), 34 deletions(-) diff --git a/documentation/concept/designated-timestamp.md b/documentation/concept/designated-timestamp.md index 844ceb00d..24aacf258 100644 --- a/documentation/concept/designated-timestamp.md +++ b/documentation/concept/designated-timestamp.md @@ -2,56 +2,82 @@ title: Designated timestamp sidebar_label: Designated timestamp description: - How designated timestamps are implemented and why it is an important - functionality for time series. + Why every QuestDB table should have a designated timestamp and how to set one. --- -QuestDB offers the option to elect a column as a _designated timestamp_. This -allows you to specify which column the tables will be indexed by in order to -leverage time-oriented language features and high-performance functionalities. +Every table in QuestDB should have a designated timestamp. This column defines +the time axis for your data and unlocks QuestDB's core time-series capabilities +including partitioning, time-series joins, and optimized interval scans. -A designated timestamp is elected by using the -[`timestamp(columnName)`](/docs/reference/function/timestamp/) function: +Without a designated timestamp, a table behaves like a generic append-only +store - you lose partitioning, efficient time-range queries, and most +time-series SQL features. -- during a [CREATE TABLE](/docs/reference/sql/create-table/#designated-timestamp) operation -- during a [SELECT](/docs/reference/sql/select/#timestamp) operation - (`dynamic timestamp`) -- when ingesting data via InfluxDB Line Protocol, for tables that do not already - exist in QuestDB, partitions are applied automatically by day by default with - a `timestamp` column +## Why it matters + +The designated timestamp is not just metadata - it determines how QuestDB +physically organizes and queries your data: + +| Capability | Requires designated timestamp | +| --------------------------------------- | ----------------------------- | +| Partitioning | ✓ Required | +| Time-series joins (ASOF, LT, SPLICE) | ✓ Required | +| Interval scan optimization | ✓ Required | +| SAMPLE BY queries | ✓ Required | +| LATEST ON optimization | ✓ Required | +| TTL (via partitioning) | ✓ Required | +| Deduplication | ✓ Required | + +If your data has a time dimension - and for time-series workloads it always +does - define a designated timestamp. :::note -- There are two timestamp resolutions available in QuestDB: microseconds and nanoseconds. See - [Timestamps in QuestDB](/docs/guides/working-with-timestamps-timezones/#timestamps-in-questdb) - for more details. +Static lookup or reference tables with no time dimension are the exception. +These can be created without a designated timestamp. ::: +## How to set it + +Use the [`timestamp(columnName)`](/docs/reference/function/timestamp/) function +at table creation: + +```questdb-sql +CREATE TABLE readings ( + ts TIMESTAMP, + sensor_id SYMBOL, + value DOUBLE +) TIMESTAMP(ts) PARTITION BY DAY; +``` + +If you have multiple timestamp columns, designate the one you'll filter and +aggregate by most often. + +Other ways to set a designated timestamp: + +- On query results: see [SELECT](/docs/reference/sql/select/#timestamp) + (`dynamic timestamp`) +- Via InfluxDB Line Protocol: tables created automatically include a `timestamp` + column as the designated timestamp, partitioned by day by default + +For full CREATE TABLE syntax, see the +[reference documentation](/docs/reference/sql/create-table/#designated-timestamp). + ## Properties - Only a column of type `timestamp` or `timestamp_ns` can be elected as a designated timestamp. - Only one column can be elected for a given table. -## Checking the designated timestamp settings - -The [meta functions](/docs/reference/function/meta/), `tables()` and -`table_columns()`, are designed to show the designated timestamp settings of the -selected table. - -## Advantages of electing a designated timestamp +:::note -Electing a designated timestamp allows you to: +There are two timestamp resolutions available: microseconds and nanoseconds. See +[Timestamps in QuestDB](/docs/guides/working-with-timestamps-timezones/#timestamps-in-questdb) +for details. -- Partition tables by time range. For more information, see the - [partitions reference](/docs/concept/partitions/). -- Use time series joins such as `ASOF JOIN`. For more information, see the - [ASOF JOIN reference](/docs/reference/sql/asof-join/) or the more general - [JOIN reference](/docs/reference/sql/join/). -- Optimize queries with [Interval scan](/docs/concept/interval-scan) +::: -## Out-of-order policy +## Checking designated timestamp settings -As of version 6.0.0, QuestDB supports the ingestion of records that are -out-of-order (O3) by time. QuestDB detects and adjusts data ingestion for O3 -data automatically and no manual configuration is required. +The [meta functions](/docs/reference/function/meta/) `tables()` and +`table_columns()` show the designated timestamp settings for a table. \ No newline at end of file From 7c6a6399cdb4623d64b11eeae3db05d6209b0bbe Mon Sep 17 00:00:00 2001 From: Jaromir Hamala Date: Sat, 6 Dec 2025 13:42:11 +0100 Subject: [PATCH 2/5] o3 note --- documentation/concept/designated-timestamp.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/documentation/concept/designated-timestamp.md b/documentation/concept/designated-timestamp.md index 24aacf258..26cd6afd1 100644 --- a/documentation/concept/designated-timestamp.md +++ b/documentation/concept/designated-timestamp.md @@ -64,6 +64,8 @@ Other ways to set a designated timestamp: For full CREATE TABLE syntax, see the [reference documentation](/docs/reference/sql/create-table/#designated-timestamp). +QuestDB handles out-of-order data automatically during ingestion. + ## Properties - Only a column of type `timestamp` or `timestamp_ns` can be elected as a designated timestamp. From 0075a58b29dfc31de75eadd2dbcf4dea38eb268f Mon Sep 17 00:00:00 2001 From: Jaromir Hamala Date: Sat, 6 Dec 2025 13:51:28 +0100 Subject: [PATCH 3/5] faq --- documentation/concept/designated-timestamp.md | 27 ++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/documentation/concept/designated-timestamp.md b/documentation/concept/designated-timestamp.md index 26cd6afd1..c14ba7b26 100644 --- a/documentation/concept/designated-timestamp.md +++ b/documentation/concept/designated-timestamp.md @@ -64,8 +64,6 @@ Other ways to set a designated timestamp: For full CREATE TABLE syntax, see the [reference documentation](/docs/reference/sql/create-table/#designated-timestamp). -QuestDB handles out-of-order data automatically during ingestion. - ## Properties - Only a column of type `timestamp` or `timestamp_ns` can be elected as a designated timestamp. @@ -82,4 +80,27 @@ for details. ## Checking designated timestamp settings The [meta functions](/docs/reference/function/meta/) `tables()` and -`table_columns()` show the designated timestamp settings for a table. \ No newline at end of file +`table_columns()` show the designated timestamp settings for a table. + +## FAQ + +**What if my data arrives out of order?** + +QuestDB handles out-of-order data automatically during ingestion. No special +configuration is required. + +**Can I change the designated timestamp later?** + +No. The designated timestamp is set at table creation and cannot be changed. +To use a different column, create a new table and migrate your data. + +**Can I add a designated timestamp to an existing table?** + +No. You must define the designated timestamp when creating the table. If you +have an existing table without one, create a new table with the designated +timestamp and use `INSERT INTO ... SELECT` to migrate your data. + +**Can the designated timestamp contain NULL values?** + +No. The designated timestamp column cannot contain NULL values. Every row must +have a valid timestamp. \ No newline at end of file From 9586758fa664dbe2eb2e5f07f8d6559734a4d7a0 Mon Sep 17 00:00:00 2001 From: Jaromir Hamala Date: Sat, 6 Dec 2025 16:08:17 +0100 Subject: [PATCH 4/5] table -> list --- documentation/concept/designated-timestamp.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/documentation/concept/designated-timestamp.md b/documentation/concept/designated-timestamp.md index c14ba7b26..779d14823 100644 --- a/documentation/concept/designated-timestamp.md +++ b/documentation/concept/designated-timestamp.md @@ -16,17 +16,16 @@ time-series SQL features. ## Why it matters The designated timestamp is not just metadata - it determines how QuestDB -physically organizes and queries your data: - -| Capability | Requires designated timestamp | -| --------------------------------------- | ----------------------------- | -| Partitioning | ✓ Required | -| Time-series joins (ASOF, LT, SPLICE) | ✓ Required | -| Interval scan optimization | ✓ Required | -| SAMPLE BY queries | ✓ Required | -| LATEST ON optimization | ✓ Required | -| TTL (via partitioning) | ✓ Required | -| Deduplication | ✓ Required | +physically organizes and queries your data. These features require it: + +- Partitioning +- Time-series joins (ASOF, LT, SPLICE) +- Interval scan optimization +- SAMPLE BY queries +- LATEST ON optimization +- TTL +- Deduplication +- Replication If your data has a time dimension - and for time-series workloads it always does - define a designated timestamp. From 4a850d86388792673d98bf1bbff250fb2a18493b Mon Sep 17 00:00:00 2001 From: Jaromir Hamala Date: Sat, 6 Dec 2025 16:11:08 +0100 Subject: [PATCH 5/5] links --- documentation/concept/designated-timestamp.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/documentation/concept/designated-timestamp.md b/documentation/concept/designated-timestamp.md index 779d14823..38087a518 100644 --- a/documentation/concept/designated-timestamp.md +++ b/documentation/concept/designated-timestamp.md @@ -18,14 +18,14 @@ time-series SQL features. The designated timestamp is not just metadata - it determines how QuestDB physically organizes and queries your data. These features require it: -- Partitioning -- Time-series joins (ASOF, LT, SPLICE) -- Interval scan optimization -- SAMPLE BY queries -- LATEST ON optimization -- TTL -- Deduplication -- Replication +- [Partitioning](/docs/concept/partitions/) +- [Time-series joins](/docs/reference/sql/join/) (ASOF, LT, SPLICE) +- [Interval scan](/docs/concept/interval-scan/) optimization +- [SAMPLE BY](/docs/reference/sql/sample-by/) queries +- [LATEST ON](/docs/reference/sql/latest-on/) optimization +- [TTL](/docs/concept/ttl/) +- [Deduplication](/docs/concept/deduplication/) +- [Replication](/docs/operations/replication/) If your data has a time dimension - and for time-series workloads it always does - define a designated timestamp.