Designated timestamp

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.

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.

Why it matters​

The designated timestamp is not just metadata - it determines how QuestDB physically organizes and queries your data. These features require it:

If your data has a time dimension - and for time-series workloads it always does - define a designated timestamp.

note

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) function at table creation:

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 (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.

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.
note

There are two timestamp resolutions available: microseconds and nanoseconds. See Timestamps in QuestDB for details.

Checking designated timestamp settings​

The meta functions tables() and 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.