Problem
The POST /api/v2/search endpoint (added in [hyperdxio/hyperdx#2258](#2258)) uses LIMIT/OFFSET pagination with results ordered by Timestamp. When multiple rows share the same timestamp, pagination becomes non-deterministic -- rows near a page boundary can be duplicated or skipped across pages.
Example: If rows 90-110 all have the same Timestamp value and the client requests maxResults=100, offset=0 followed by maxResults=100, offset=100, ClickHouse arbitrarily assigns which rows fall on which page. The client may see some rows twice and miss others entirely.
Why this happens in practice
While Timestamp is DateTime64(9) (nanosecond precision), duplicate timestamps are common in real-world OTEL pipelines:
- Collector-assigned timestamps: When logs arrive at the OTEL collector without a timestamp, the collector assigns one. An entire batch receives the same timestamp.
- Limited source precision: Many language runtimes only produce microsecond or millisecond precision. The remaining digits are zero-padded, reducing the effective keyspace.
- High-throughput services: Multiple log lines from the same flush, HTTP request, or function call naturally share the same wall-clock time.
Adding search predicates reduces the likelihood (fewer matching rows means fewer ties), but the issue is still possible in any high-volume deployment.
Proposed solution
For tables with enable_block_number_column = 1 and enable_block_offset_column = 1 (which ClickStack already enables on otel_logs), add _block_number and _block_offset as tiebreaker columns in the ORDER BY clause:
ORDER BY Timestamp DESC, _block_number DESC, _block_offset DESC
LIMIT {maxResults} OFFSET {offset}This produces a deterministic total ordering since (_block_number, _block_offset) uniquely identifies each row within a part. The additional columns should have negligible performance impact when using read_in_order.
Alternatives considered
- Cursor-based pagination (filter by
WHERE Timestamp < :last_seen): Avoids offset entirely but still non-deterministic when ties exist at the cursor boundary. Would also require a tiebreaker.
- Nanosecond precision alone: Reduces probability but does not eliminate the issue, especially for collector-assigned timestamps.
Problem
The
POST /api/v2/searchendpoint (added in [hyperdxio/hyperdx#2258](#2258)) usesLIMIT/OFFSETpagination with results ordered byTimestamp. When multiple rows share the same timestamp, pagination becomes non-deterministic -- rows near a page boundary can be duplicated or skipped across pages.Example: If rows 90-110 all have the same
Timestampvalue and the client requestsmaxResults=100, offset=0followed bymaxResults=100, offset=100, ClickHouse arbitrarily assigns which rows fall on which page. The client may see some rows twice and miss others entirely.Why this happens in practice
While
TimestampisDateTime64(9)(nanosecond precision), duplicate timestamps are common in real-world OTEL pipelines:Adding search predicates reduces the likelihood (fewer matching rows means fewer ties), but the issue is still possible in any high-volume deployment.
Proposed solution
For tables with
enable_block_number_column = 1andenable_block_offset_column = 1(which ClickStack already enables onotel_logs), add_block_numberand_block_offsetas tiebreaker columns in theORDER BYclause:This produces a deterministic total ordering since
(_block_number, _block_offset)uniquely identifies each row within a part. The additional columns should have negligible performance impact when usingread_in_order.Alternatives considered
WHERE Timestamp < :last_seen): Avoids offset entirely but still non-deterministic when ties exist at the cursor boundary. Would also require a tiebreaker.