Add PostgreSQL-compatible EXTRACT units

[alexey-milovidov]

Add PostgreSQL-compatible units to the EXTRACT operator: EPOCH, DOW, DOY, ISODOW, ISOYEAR, WEEK, CENTURY, DECADE, MILLENNIUM.

These are parsed as extract-only units (not interval kinds) and mapped to existing ClickHouse functions:

• EPOCH → toUnixTimestamp
• DOW → toDayOfWeek(expr, 2) (0 = Sunday, 6 = Saturday)
• DOY → toDayOfYear
• ISODOW → toDayOfWeek(expr) (1 = Monday, 7 = Sunday)
• ISOYEAR → toISOYear
• WEEK → toISOWeek (previously threw an error)
• CENTURY → intDiv(toYear(expr) - 1, 100) + 1
• DECADE → intDiv(toYear(expr), 10)
• MILLENNIUM → intDiv(toYear(expr) - 1, 1000) + 1

Changelog category (leave one):

• New Feature

Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):

Add PostgreSQL-compatible units to the EXTRACT operator: EPOCH, DOW, DOY, ISODOW, ISOYEAR, WEEK, CENTURY, DECADE, MILLENNIUM. Also fix EXTRACT(WEEK FROM date) which previously threw an error.

Documentation entry for user-facing changes

• Documentation is written (mandatory for new features)

The EXTRACT operator now supports additional PostgreSQL-compatible units:

• EXTRACT(EPOCH FROM expr) — seconds since 1970-01-01 00:00:00 UTC
• EXTRACT(DOW FROM expr) — day of week (0 = Sunday, 6 = Saturday)
• EXTRACT(DOY FROM expr) — day of year (1–366)
• EXTRACT(ISODOW FROM expr) — ISO day of week (1 = Monday, 7 = Sunday)
• EXTRACT(ISOYEAR FROM expr) — ISO 8601 week-numbering year
• EXTRACT(WEEK FROM expr) — ISO 8601 week number (1–53)
• EXTRACT(CENTURY FROM expr) — century
• EXTRACT(DECADE FROM expr) — decade (year / 10)
• EXTRACT(MILLENNIUM FROM expr) — millennium

Example:

SELECT EXTRACT(EPOCH FROM now());
SELECT EXTRACT(DOW FROM toDate('2024-01-15')); -- 1 (Monday)
SELECT EXTRACT(CENTURY FROM toDate('2024-01-01')); -- 21

[clickhouse-gh]

Workflow [PR], commit [6661f10]

Summary: ✅

---

AI Review

Summary

This PR adds PostgreSQL-style EXTRACT units and maps them to existing functions, including enabling EXTRACT(WEEK FROM ...) via toISOWeek. The main correctness gap is EPOCH: mapping to toUnixTimestamp does not preserve PostgreSQL-compatible semantics for DateTime64 (fractional seconds are lost and the return type/range semantics differ). Overall verdict: request changes until EPOCH behavior is aligned (or clearly scoped as intentionally different).

Findings

❌ Blockers

• [src/Parsers/ExpressionListParsers.cpp:1640] EXTRACT(EPOCH FROM ...) is implemented as toUnixTimestamp(expr), which is not PostgreSQL-compatible for DateTime64 because subsecond precision is truncated and unsigned-second conversion semantics differ from PostgreSQL double precision epoch extraction.
  • Suggested fix: route EPOCH through a path that preserves fractional seconds for DateTime64 (e.g., toUnixTimestamp64* + scale to Float64, while keeping integer behavior for non-fractional types if desired), and ensure behavior for pre-epoch timestamps is explicitly defined and tested.

ClickHouse Rules

Item	Status	Notes
Deletion logging	➖
Serialization versioning	➖
Core-area scrutiny	✅
No test removal	✅
Experimental gate	➖
No magic constants	✅
Backward compatibility	✅
SettingsChangesHistory.cpp	➖
PR metadata quality	✅
Safe rollout	✅
Compilation time	✅

Performance & Safety

• EPOCH currently takes a lossy conversion path for DateTime64; this is a semantic correctness issue rather than a runtime performance issue, but it can silently drop precision in user queries.

Final Verdict

• Status: ⚠️ Request changes
• Minimum required actions:
  • Fix EXTRACT(EPOCH FROM DateTime64) to preserve PostgreSQL-compatible epoch semantics (fractional seconds and well-defined behavior across full supported timestamp range), or explicitly narrow/document non-compatibility and adjust naming/claims accordingly.

[clickhouse-gh]

Please add a coverage case for EXTRACT(EPOCH FROM toDateTime64(...)).

Right now the new test checks only Date/DateTime, so it does not lock the intended behavior for fractional seconds. This is especially important because the implementation currently routes through toUnixTimestamp.

[alexey-milovidov]

The code is good.

[clickhouse-gh]

LLVM Coverage Report

Metric	Baseline	Current	Δ
Lines	83.80%	83.80%	+0.00%
Functions	24.60%	24.60%	+0.00%
Branches	76.50%	76.40%	-0.10%

PR changed lines: PR changed-lines coverage: 97.54% (119/122, 1 noise lines excluded)
Diff coverage report
Uncovered code