[jasperblues]

Port of liberation-data/drivine4j#509 (drivine4j's #508), with liberation-data/drivine-cypher-spec#44, which the spec at v0.19.0 already holds. The compiler follows Drivine for TypeScript's port, liberation-data/drivine#503.

What changes

• date(), localtime(), time(), localdatetime() and datetime() take a map with date, time or datetime, which is another temporal value. The map's other fields are laid over that value's own: SqlCypherCompiler._from_temporal checks the map, and Temporals.over builds the SQL.
  • A year, month and day replace the value's together. The date is read as a date first, so the store fails where they make no date (Oracle included).
  • A week, ordinalDay or dayOfQuarter goes through of_calendar. A quarter alone or a dayOfWeek alone moves the date. Beside a dayOfWeek, a year moves the date by that many years.
  • A fraction given makes the whole fraction.
  • A zoned value keeps the offset of whatever gives its time. A timezone given moves a zoned value there and names a local value's offset.
• Where the statement doesn't tell the value's kind (a property, an unwound item), a runtime CASE over the possible kinds reads it. A kind known to be wrong is refused when compiling.
• A value or zone from an expression that is null or of the wrong kind fails when the statement runs, on day 0, as Neo4j fails.
• The compiler refuses, with drivine4j's messages:
  • a field the kind doesn't have;
  • a datetime beside a date or a time;
  • a value that isn't a temporal value, or is of the wrong kind;
  • fields of two calendars;
  • a date that isn't whole beside a value that gives only the time;
  • a field of the time without the one above it;
  • a number that isn't whole or is past its range (Java's year bounds for a whole date written beside a time);
  • a time zone that is null or isn't an offset.
• A zone given by name, 'UTC' included, is now refused in any temporal map, not only one with calendar fields. That includes the constructor of a value given to another, as drivine4j does.
• Shared helpers rather than parallel ones:
  • _whole_field, the whole-number and range check, is shared by truncation and from-temporal, as drivine #503's review had it.
  • _zone_text is shared with truncation.
  • _calendars_of, _calendar_date and Temporals._dated / _date_of are reused from Make a date or a moment from a week, an ordinal day or a quarter, and filter a grouping WITH by an aggregate in its WHERE, as drivine4j does, at Cypher spec v0.19.0 #318's calendar helpers.
  • TRUNCATION_FIELD_NAMES becomes FIELD_NOUNS.

Tests

• The Cypher on SQL stores: make a date, a time or a moment from another temporal value, as {date: d, week: 2} or {datetime: dt, timezone: '+05:00'} #317 holds come out of HELD:
  • temporal.yaml: "Dates, times and moments from another temporal value", "Zoned times and moments from another temporal value", and steps 2–4 of "Temporal values from another an expression gives";
  • refusals.yaml: "Temporal map from another temporal value Neo4j does not take", and steps 1 and 4 of "Temporal map not compiled yet".
• The holds for Compiled Cypher: a null in a map and a missing key group, de-duplicate and sort apart on the SQL stores (port of drivine4j#500) #314 and Compiled Cypher: a grouping key read in an order term's body fails, and one in any(y IN … WHERE y = e) groups by its variable (port of drivine4j#505) #316 stay.
• drivine4j's and drivine #503's refusal and compile cases that the spec doesn't hold are ported in tests/unit/test_cypher_refusals.py.

SQL comparison. Every statement of the spec at v0.19.0 (1,494) and of the openCypher TCK's features (4,119) was compiled for Postgres and Oracle, on main and on this branch:

• 176 statements per store that main refused as "… of a map with date/time/datetime … not compiled to SQL yet" now compile.
• 84 per store go from that refusal to one of the new refusals.
• 19 per store go from compiled to "The time zone 'Europe/Stockholm' is Cypher, and is not compiled to SQL yet." These are maps with a named zone, which gave null before (datetime({…, timezone: 'Europe/Stockholm'}), TCK Temporal1 [10], Temporal3, Temporal5, Temporal6 and Temporal10 [8]). drivine4j#509 refuses them the same way.
• Nothing else changed.

The 176 newly compiled statements were also compiled with drivine #503:

• Postgres: the SQL is identical on all 176.
• Oracle: the SQL is identical apart from this library's existing outer JSON_TRANSFORM(…, KEEP '$').

Against Neo4j. drivine #503's reviewer built a grid of 3,015 statements: 10 source values × 5 targets × each variant, run as a WITH, a stored property, an UNWIND, and a filtered UNWIND, plus the null cases. It was run here on Postgres and Oracle and compared with that grid's Neo4j answers (errors as errors, fractions to the microsecond): 0 differences on either store.

Fixes #317