Translate standard DateTime members and methods (#55)

[alex-clickhouse]

Fixes #55.

Stacked on #63. The base branch is fix/issue-53-datetimeoffset, not main. Review #63 first,
and read this diff as the second commit only. The stack matters: #63 supplies the DateTimeOffset
store mapping, which is what lets these translators cover DateTimeOffset as the issue asked.

Problem

The provider registered no date/time member translator. EF Core's base
RelationalMemberTranslatorProvider adds none of its own, so only a direct comparison worked and
every member and method threw The LINQ expression ... could not be translated. Subtracting one date
from another was worse: it failed with an internal cast or coercion error naming CLR types the user
never wrote.

Solution

One shared translator serves DateTime, DateTimeOffset and DateOnly, because the ClickHouse
function is the same for each. RegisterInstanceMembers registers only the members a given type
declares, so DateOnly gets the date components alone.

.NET	ClickHouse
.Year .Month .Day	toYear toMonth toDayOfMonth
.Hour .Minute .Second .Millisecond	toHour toMinute toSecond toMillisecond
.DayOfYear	toDayOfYear
.DayOfWeek	toDayOfWeek(x, 2)
.Date	toStartOfDay
.TimeOfDay	toTime64(x, 7)
.AddYears(n) .AddMonths(n)	addYears addMonths
.AddDays(n) … .AddMilliseconds(n)	addDays … (see below)
DateTime.UtcNow / .Now / .Today	now64(7, 'UTC') / now64(7) / toStartOfDay(now())

Every design decision below was measured against a real ClickHouse 26.7.1 server, and .NET behaviour
was measured on .NET 10 rather than taken from the documentation.

.DayOfWeek needs no arithmetic. Week mode 2 agrees with System.DayOfWeek exactly (Sunday 0
through Saturday 6). The mode argument is always sent, because the default mode 0 starts the week on
Monday.

.DayOfWeek carries a number-backed enum mapping. This provider maps a C# enum to a ClickHouse
string, so the default mapping would render x.DayOfWeek == DayOfWeek.Sunday as a comparison against
'Sunday' while the function returns a number. An EnumToNumberConverter over the Int32 mapping
fixes both sides. Verified against a server for projection, WHERE, parameters, GROUP BY,
HAVING, ORDER BY, DISTINCT and IN.

.TimeOfDay uses toTime64(x, 7), not toTime. One .NET tick is 100 ns, which is Time64
precision 7, so the fraction survives; toTime drops it.

Add* is exact or is not translated. This is the subtle part. AddDays and the other time-based
methods take a double, which .NET scales to whole ticks — AddSeconds(0.1234567) adds exactly
1 234 567 ticks. The matching ClickHouse function takes a whole number of its own unit and discards
the rest, so addDays(x, 1.5) would add only one day. A constant is therefore folded to ticks and
expressed in the coarsest unit that holds it exactly:

e.Timestamp.AddDays(1)             // addDays(ts, 1)
e.Timestamp.AddDays(1.5)           // addMilliseconds(ts, 129600000)
e.Timestamp.AddMilliseconds(0.5)   // not translated — 5 000 ticks is below millisecond resolution
e.Timestamp.AddDays(someVariable)  // not translated — cannot be checked for exactness

Preferring the natural function keeps the store type of the source, and it is the only form that
works on a Date/Date32 column — ClickHouse rejects addMilliseconds on those with
ILLEGAL_TYPE_OF_ARGUMENT.

Anything that cannot be expressed exactly is left untranslated rather than rounded to fit. Three
cases: a sub-millisecond offset, a non-constant offset, and a value outside the DateTime range. An
untranslated call still gives the correct .NET value through client evaluation in a projection, and
reports a clear reason in a predicate.

Milliseconds are as fine as this goes deliberately. addNanoseconds would express a tick exactly,
but promotes the result to DateTime64(9), whose Int64 nanosecond count cannot span the
DateTime64 range — that would trade a rounding error for a silently wrong date. Server-side
rounding was also rejected: ClickHouse round() is banker's rounding (round(2.5) is 2), so it
disagrees with .NET.

Date/time arithmetic now reports a reason. ClickHouse has no operator matching the .NET result
for any of these shapes, and each failed differently before:

• one date minus another gives a TimeSpan, whereas dateDiff counts whole units;
• one time of day minus another gives a TimeSpan, whereas Time64 subtraction gives a Decimal
  of seconds;
• a date plus a TimeSpan keeps the date type in .NET, whereas ClickHouse rejects the mixed
  operands.

VisitBinary now reports these through EF Core's translation-error channel instead of throwing, so
a projection falls back to the client and returns the correct value, and a predicate explains why.

Tests

DateTimeMemberTranslationTests — 60 tests. Integration tests run against a real ClickHouse through
Testcontainers, as AGENTS.md prefers, with a small offline class for SQL-shape assertions.

Coverage worth calling out: sub-millisecond Add* values, a parameterised offset, an out-of-range
offset, AddMonths day clamping, .DayOfWeek compared against a .NET constant, .TimeOfDay to one
tick, Date32 columns, TimeSpan arithmetic falling back to the client, and the DateTimeOffset
equivalents.

Also in this PR

A previously-unsupported Northwind query, GroupJoin_aggregate_anonymous_key_selectors2, now
translates. Its provider-specific override asserted InvalidOperationException, so the override is
removed and the base test runs. The functional suite goes from 321 passed + 2 failed to 323 passed.

Behaviour change

DateTime.Now and DateTime.Today in a projection used to be evaluated on the client; they now
read the server clock. The value therefore follows the server's timezone rather than the
client's, and comes back with DateTimeKind.Unspecified instead of Local. Use DateTime.UtcNow
for an instant that does not depend on server configuration. In a predicate all three were
untranslatable before, so nothing changes there.

This matches how other EF Core providers translate these members (GETDATE(), now()), but it is a
semantic shift and worth a second opinion.

Known limits

• .Date uses toStartOfDay, which returns a DateTime spanning 1970–2106. ClickHouse wraps a
  value outside that window instead of reporting it, so .Date on a DateTime64 column holding a
  pre-1970 date reads back wrong. Enabling
  enable_extended_results_for_datetime_functions gives a range-preserving DateTime64 result —
  measured. This is the same caveat that already applies to EF.Functions.ToStartOfDay, and it is
  now documented for both.
• Not translated: .Ticks, .AddTicks, .Microsecond/.Nanosecond, and DateTimeOffset's
  .UtcDateTime/.LocalDateTime/.Offset.
• The ClickHouse-specific functions (dateDiff, dateTrunc) stay in Add EF.Functions translations for the remaining ClickHouse date/time functions #58.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds standard .NET date/time translation support to the ClickHouse EF Core query pipeline.

Changes:

• Translates date/time components, clocks, and Add* methods.
• Improves unsupported date/time arithmetic handling.
• Adds integration coverage and user documentation.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
ClickHouseDateTimeMemberTranslator.cs	Translates date/time members and clocks.
ClickHouseDateTimeMethodTranslator.cs	Translates Add* methods.
ClickHouseMemberTranslatorProvider.cs	Registers the member translator.
ClickHouseSqlTranslatingExpressionVisitor.cs	Handles unsupported date/time arithmetic.
DateTimeMemberTranslationTests.cs	Adds translation and integration tests.
NorthwindJoinQueryClickHouseTest.cs	Re-enables a formerly unsupported query.
README.md	Documents supported translations and limits.
CHANGELOG.md	Records the feature and behavior changes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/EFCore.ClickHouse/Query/ExpressionTranslators/Internal/ClickHouseDateTimeMethodTranslator.cs:199

• Integral additions bypass all range validation, so constants such as DateTime.AddYears(int.MaxValue) or AddMonths(int.MaxValue) are always sent to ClickHouse. .NET deterministically rejects these arguments (AddYears: ±10,000; AddMonths: ±120,000), whereas the translated query can fail with a server error or different behavior instead of preserving client semantics. Reject out-of-range constants here and report them through the same unsupported-translation path used by fractional additions.

            if (IntegralAddMethods.TryGetValue(method, out var integralFunction))
            {
                return AddFunction(integralFunction, instance, arguments[0], method.ReturnType);

src/EFCore.ClickHouse/Storage/Internal/Mapping/ClickHouseDateTimeOffsetTypeMapping.cs:106

• HasFixedOffset also accepts fixed zones that DateTimeOffset cannot represent, such as Fixed/UTC+14:00:30 or offsets beyond ±14 hours. This mapping materializes those values at +00:00 (lines 180–186), but the translated AddMonths/AddYears still runs in the column's wall clock; around month-end, its clamping can therefore differ by a day from calling .NET on the materialized UTC value. Only treat parsed offsets that pass IsRepresentableOffset as eligible for server-side DateTimeOffset.Add*; leave the others client-side.

    internal bool HasFixedOffset
        => Timezone == DefaultTimezone
           || Timezone is not null && FixedOffsetRegex.IsMatch(Timezone);