Skip to content

feat(bindings): bins(span | spanset, vsize, vorigin) table function#62

Closed
estebanzimanyi wants to merge 1 commit into
mainfrom
feat/table-fn-bins
Closed

feat(bindings): bins(span | spanset, vsize, vorigin) table function#62
estebanzimanyi wants to merge 1 commit into
mainfrom
feat/table-fn-bins

Conversation

@estebanzimanyi

Copy link
Copy Markdown
Member

Summary

Adds the first MobilityDuck TableFunction registration: `bins()` that partitions a span (or spanset) into uniformly-sized bins anchored at a given origin and emits one row per bin.

```sql
SELECT bin FROM bins(intspan '[1, 10)', 2, 0);
-- [0, 2)
-- [2, 4)
-- [4, 6)
-- [6, 8)
-- [8, 10)

SELECT bin FROM bins(tstzspan '[2000-01-01, 2000-01-04)',
INTERVAL '1 day',
TIMESTAMPTZ '2000-01-01');
-- [2000-01-01, 2000-01-02)
-- [2000-01-02, 2000-01-03)
-- [2000-01-03, 2000-01-04)
```

Coverage

10 overloads — every span / spanset base type:

Input vsize vorigin
`intspan` / `intspanset` `INTEGER` `INTEGER`
`bigintspan` / `bigintspanset` `BIGINT` `BIGINT`
`floatspan` / `floatspanset` `DOUBLE` `DOUBLE`
`datespan` / `datespanset` `INTERVAL` `DATE`
`tstzspan` / `tstzspanset` `INTERVAL` `TIMESTAMP_TZ`

Each overload returns a one-column relation `(bin )` matching the input's base type.

Implementation

Component What it does
`BinsKind` enum 10-way tag dispatching to the right MEOS `*_bins` function.
`BinsBindData` (`FunctionData`) Captures the three constant arguments at bind time and the chosen output span type.
`BinsInitGlobal` Allocates the MEOS-managed `Span bins` array via the appropriate MEOS `_bins(s, vsize, vorigin, &count)` call.
`BinsExecute` Emits up to `STANDARD_VECTOR_SIZE` rows per chunk; advances state offset.
`~BinsGlobalState` Frees the MEOS-allocated array.

Date and timestamptz inputs are converted from DuckDB's 1970 epoch to MEOS's 2000 epoch via the existing `time_util.hpp` helpers. Output bins are stored in MEOS-native epoch form, which round-trips correctly through the span in/out functions.

This establishes the `bind` / `init_global` / `execute` scaffolding that follow-up table functions (`tsample`, `tprecision`, `similarityPath`, `tspatial_value/time_split`) can reuse.

Test plan

  • All 10 overloads emit the expected bins for representative inputs
  • Date / timestamptz round-trip correctly across the epoch boundary
  • Chunk boundary handled (output stops at `STANDARD_VECTOR_SIZE`, advances offset for next chunk)
  • Destructor frees the MEOS array

Adds the first MobilityDuck TableFunction registration: bins() that
partitions a span (or spanset) into uniformly-sized bins anchored at a
given origin and emits one row per bin.

10 overloads — every span / spanset base type:

  bins(intspan,    INTEGER,  INTEGER)      -> TABLE(bin intspan)
  bins(bigintspan, BIGINT,   BIGINT)       -> TABLE(bin bigintspan)
  bins(floatspan,  DOUBLE,   DOUBLE)       -> TABLE(bin floatspan)
  bins(datespan,   INTERVAL, DATE)         -> TABLE(bin datespan)
  bins(tstzspan,   INTERVAL, TIMESTAMP_TZ) -> TABLE(bin tstzspan)
  bins(<spanset>,  ... )                   -> TABLE(bin <span>)

Each overload gets its own templated bind via BinsKind dispatch.
BinsBindData captures the three constant arguments at bind time and
BinsInitGlobal materialises the MEOS bin array on first row of
execution. BinsExecute emits up to STANDARD_VECTOR_SIZE rows per
chunk. The destructor on BinsGlobalState frees the MEOS-allocated
array.

Date and timestamptz inputs are converted from DuckDB's 1970 epoch
to MEOS's 2000 epoch via the existing time_util.hpp helpers
(ToMeosDate, DuckDBToMeosTimestamp). Output bins are stored in
MEOS-native epoch form, which round-trips correctly through the span
in/out functions.

This establishes the bind / init_global / execute scaffolding that
follow-up table functions (tsample, tprecision, similarityPath,
tspatial value/time split) can reuse.
@estebanzimanyi

Copy link
Copy Markdown
Member Author

Superseded by the consolidated PR branch consolidate/tiles-bins-parity. All changes from this PR are included in that branch as a single squashed commit. Please review and merge the consolidated branch instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant