Add offset/origin params to time_bucket_gapfill

[tjgreen42]

Summary

Adds offset and origin parameters to time_bucket_gapfill() using named parameters with defaults.

Fixes #1304

Function Signatures

All existing parameters remain in place. New optional parameters are added at the end with NULL defaults.

Integer Variants (5 args)

time_bucket_gapfill(
    bucket_width SMALLINT,
    ts SMALLINT,
    start SMALLINT = NULL,
    finish SMALLINT = NULL,
    "offset" SMALLINT = NULL
) RETURNS SMALLINT

-- Same pattern for INT and BIGINT

Timestamp Variants (6 args)

time_bucket_gapfill(
    bucket_width INTERVAL,
    ts TIMESTAMPTZ,
    start TIMESTAMPTZ = NULL,
    finish TIMESTAMPTZ = NULL,
    origin TIMESTAMPTZ = NULL,
    "offset" INTERVAL = NULL
) RETURNS TIMESTAMPTZ

-- Same pattern for DATE and TIMESTAMP

Timezone Variant (7 args)

time_bucket_gapfill(
    bucket_width INTERVAL,
    ts TIMESTAMPTZ,
    timezone TEXT,
    start TIMESTAMPTZ = NULL,
    finish TIMESTAMPTZ = NULL,
    origin TIMESTAMPTZ = NULL,
    "offset" INTERVAL = NULL
) RETURNS TIMESTAMPTZ

Examples

Offset: Business Day at 6 AM

SELECT time_bucket_gapfill('1 day'::interval, sale_time,
           start => '2024-01-01 06:00'::timestamptz,
           finish => '2024-01-10 06:00'::timestamptz,
           "offset" => '6 hours'::interval) AS business_day,
       coalesce(sum(amount), 0) AS total
FROM sales
GROUP BY 1 ORDER BY 1;

Origin: Fiscal Months Starting April 1st

SELECT time_bucket_gapfill('1 month'::interval, event_time,
           start => '2024-01-01'::timestamptz,
           finish => '2024-12-01'::timestamptz,
           origin => '2024-04-01'::timestamptz) AS fiscal_month,
       count(*) AS events
FROM events
GROUP BY 1 ORDER BY 1;

Timezone with Offset

SELECT time_bucket_gapfill('1 day'::interval, event_time,
           'America/New_York',
           start => '2024-01-01'::timestamptz,
           finish => '2024-01-05'::timestamptz,
           "offset" => '6 hours'::interval) AS day,
       count(*)
FROM events
GROUP BY 1 ORDER BY 1;

Constraints

• offset and origin are mutually exclusive (same as time_bucket)
• All existing function calls remain unchanged (full backward compatibility)

Testing

• Added tests for offset/origin variants in tsl/test/shared/sql/gapfill.sql.in
• Verified all variants work correctly with locf() and interpolate()

Disable-check: commit-count

[codecov]

Codecov Report

❌ Patch coverage is 42.37288% with 68 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.14%. Comparing base (1236a1a) to head (8f5bcaf).

Files with missing lines	Patch %	Lines
tsl/src/nodes/gapfill/gapfill_exec.c	54.21%	35 Missing and 3 partials ⚠️
tsl/src/nodes/gapfill/gapfill_functions.c	0.00%	19 Missing and 6 partials ⚠️
src/func_cache.c	28.57%	1 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9123      +/-   ##
==========================================
- Coverage   82.42%   82.14%   -0.29%     
==========================================
  Files         243      243              
  Lines       47911    46914     -997     
  Branches    12228    12241      +13     
==========================================
- Hits        39492    38536     -956     
- Misses       3550     3564      +14     
+ Partials     4869     4814      -55     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.