@pythia-software/query-table-core 0.5.0 → 0.7.0

package/README.md

@@ -3,6 +3,10 @@
 Framework-agnostic query state, schema contracts, filtering, sorting,
 aggregation, serialization, and transport/storage interfaces for query-table.
 
+Also exports object property view definitions, normalization/defaults, separate
+property storage adapters, and foreign-key relationship mapping contracts. See
+[object property views](../../docs/object-properties.md).
+
 ## Install
 
 ```bash
@@ -40,6 +44,17 @@ Query state is bounded whenever it crosses the library's URL, storage, or
 server-projection boundaries. SQL expressions remain trusted server-side schema
 configuration; request values are never SQL fragments.
 
+## Compact URLs and query snapshots
+
+`encodeQuery` chooses versioned JSON or raw-DEFLATE tokens, packs intact set
+filters once, and shares identical property layouts. `decodeQueryStrict` reports
+invalid/unsupported/oversized links; `decodeQuery` is the tolerant convenience
+decoder. `createQueryLinkService` keeps fitting views inline and oversized views
+in a bounded FIFO browser cache. Its explicit `durable`/`snapshot` calls promote
+immutable codes through an injected `QuerySnapshotStore`; ordinary `local` calls
+never write to the server. `httpQuerySnapshotStore` implements the host REST
+contract. See [URL state and saved-search links](../../docs/url-state-and-saved-search-design.md).
+
 Text filters include `matches_regex` / `not_matches_regex`. An order term may
 set `extract: { regex: "..." }` to compare the first capture group (or the whole
 match when there is no capture group); non-matches sort as nulls.
@@ -59,3 +74,61 @@ Exports include `ComputedColumnStore`, `httpComputedColumnStore`, `memoryCompute
 For case-sensitive array keys, set `filter: { arrayCaseSensitive: true }` on the
 `textarray` field. The default remains case-insensitive. This setting applies to
 local filtering and metrics and to PostgreSQL array membership.
+
+Datetime comparisons accept signed elapsed offsets such as `-1h`, `+8d2h10m`,
+and `+0s`. Operators and the wire shape are unchanged: values remain relative in
+saved queries and requests, and the server resolves them when compiling. Local
+executors mirror this behavior and accept an optional clock for deterministic
+execution. See [relative datetime operands](https://github.com/Pythia-Software/query-table/blob/main/docs/relative-time.md).
+
+## Local metric resource and precision boundaries
+
+`evaluateMetrics` checks grouping storage before serializing each tuple.
+`maxGroupKeyLength` defaults to 65,536 escaped JSON UTF-16 code units per tuple;
+`maxGroupBytes` defaults to 16,000,000 estimated bytes per metric. The byte
+estimate includes serialized keys, original string payloads (charged per group
+even when shared), tuple slots, map/bucket overhead, and 16 bytes per retained
+row reference. It also reserves a candidate group and serialization scratch
+before lookup, including for duplicate keys. These conservative bounds can
+reject a population below its actual heap limit; they are not heap measurements.
+Ungrouped rows also consume the row-reference budget. Bounds must be nonnegative
+safe integers. Exceeding a bound returns an explicit metric error with no partial
+buckets. Existing row, group-count, operation, and distinct-value budgets remain
+independent. Group limits apply after evaluation and do not bypass these bounds.
+Keys preserve scalar types, and long field values remain valid within the tuple
+and byte limits; field values are never truncated.
+
+Numeric SUM, AVG, MIN, MAX and numeric COUNT_DISTINCT samples must be finite and,
+when integral, within ±9,007,199,254,740,991. SUM and AVG check each accumulation
+step; aggregate results, consumed worker reductions, and final metric expression
+results follow the same boundary. Unsafe samples fail even when cancellation,
+averaging, or selecting an extremum could produce a safe result. COUNT counts
+presence and does not interpret the input's numeric magnitude. Text/date extrema
+keep their existing semantics. Distribution samples, percentile outputs, box
+summary statistics, and histogram boundaries use the same numeric rule. Invalid
+box samples produce group errors; any invalid histogram sample invalidates the
+shared extent. NULL remains an excluded sample, not an error. Lazy IF/COALESCE
+branches do not observe unused reduction failures; IFERROR can recover from a
+numeric failure.
+
+These are IEEE-754 display-arithmetic semantics, **not exact decimal arithmetic**.
+Finite nonintegral values (including small/subnormal values) remain supported;
+floating-point rounding still applies. `coverage: 'exact'` means the complete
+scoped population was processed, not that every arithmetic operation was exact.
+Row-expression arithmetic retains the formula engine's own semantics; these
+checks apply at sample/reduction/result boundaries, not to every intermediate
+formula node.
+
+The Go `qt-postgres-v1` profile requires explicit `ExpressionNumeric` bindings and
+restricts nonzero magnitudes to 1e-300–1e100. Its numeric metric sample/reduction/result guards reject unsafe integers, including AVG/MIN/MAX and distributions. COUNT retains presence semantics. It accumulates SUM/AVG through
+PostgreSQL numeric and also conservatively bounds SUM's absolute population sum.
+Do not claim identical acceptance, intermediate overflow, or bit-for-bit numeric
+parity; negotiate the backend profile and compare supported floating results
+with tolerances. The host must enforce the negotiated profile and execution budgets.
+
+## Cell presentation
+
+`FieldDef.display` accepts the serializable `CellDisplay` union for JSON, temporal,
+duration, numeric, text, and chip presentation. It is independent of `FieldType`
+and backend query capabilities. `loadSchema` validates display options, and
+codegen preserves them in frontend schemas. See the [cell display guide](../../docs/cell-displays.md).