SNOW-3746497 Snowpark Python SDK: add interval type support for UDFs & Sprocs by sfc-gh-jzhan · Pull Request #4291 · snowflakedb/snowpark-python

sfc-gh-jzhan · 2026-07-21T20:14:02Z

Which Jira issue is this PR addressing? Make sure that there is an accompanying issue to your PR.

Fixes SNOW-3746497
Fill out the following pre-review checklist:
- I am adding a new automated test(s) to verify correctness of my new code
  - If this test skips Local Testing mode, I'm requesting review from @snowflakedb/local-testing
- I am adding new logging messages
- I am adding a new telemetry message
- I am adding new credentials
- I am adding a new dependency
- If this is a new feature/behavior, I'm adding the Local Testing parity changes.
- I acknowledge that I have ensured my changes to be thread-safe. Follow the link for more information: Thread-safe Developer Guidelines
- If adding any arguments to public Snowpark APIs or creating new public Snowpark APIs, I acknowledge that I have ensured my changes include AST support. Follow the link for more information: AST Support Guidelines

Please describe how your code solves the related issue.
Enables DayTimeIntervalType and YearMonthIntervalType as parameter and return types for Python UDFs and stored procedures, gated behind the ENABLE_INTERVAL_TYPES_IN_UDF account parameter.

New user-facing behavior:

DayTimeIntervalType — datetime.timedelta is now a recognized annotation:

# annotation inferred automatically — no explicit return_type/input_types needed
def add_day(d: datetime.timedelta) -> datetime.timedelta:
    return d + datetime.timedelta(days=1)

f = session.udf.register(add_day)
# f._return_type  == DayTimeIntervalType()
# f._input_types  == [DayTimeIntervalType()]

# YearMonthIntervalType — no native Python type exists, so the YearMonthInterval
# TypeVar must be used as the annotation (or return_type/input_types passed
# explicitly). Inside the handler, values are plain int (total months):
def add_year(m: YearMonthInterval) -> YearMonthInterval:
    return m + 12  # m is int at runtime, e.g. 14 for "1 year 2 months"

f = session.udf.register(
     add_year,
     return_type=YearMonthIntervalType(),
     input_types=[YearMonthIntervalType()],
)

SDK changes:

type_utils.py — datetime.timedelta added to PYTHON_TO_SNOW_TYPE_MAPPINGS (→ DayTimeIntervalType); "timedelta" and "YearMonthInterval" string cases added to python_type_str_to_object for register_from_file support.
datatype_mapper.py — to_sql() extended to serialize timedelta → INTERVAL DAY TO SECOND literal and int → INTERVAL YEAR TO MONTH literal, enabling direct sproc calls with Python values (e.g. sp(timedelta(days=3))).
types.py — docstrings updated to reflect UDF/sproc support and correct annotation guidance for both interval types.
mock/_functions.py — cast_column_to extended to pass through DayTimeIntervalType and YearMonthIntervalType columns in Local Testing mode.

github-actions · 2026-07-21T20:14:15Z

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

I have read the CLA Document and I hereby sign the CLA

_{You can retrigger this bot by commenting recheck in this Pull Request.}_{Posted by the CLA Assistant Lite bot.}

codecov-commenter · 2026-07-21T20:59:33Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.19%. Comparing base (b99b89b) to head (3489ae2).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #4291       +/-   ##
===========================================
- Coverage   95.46%   82.19%   -13.28%     
===========================================
  Files         171      172        +1     
  Lines       44720    44807       +87     
  Branches     7676     7689       +13     
===========================================
- Hits        42694    36828     -5866     
- Misses       1253     5943     +4690     
- Partials      773     2036     +1263

☔ View full report in Codecov by Harness.
📢 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.

snowflake-security-bot

Snowflake Security Review

Security grade: A — Passed ✅

No security findings after adjudication. This PR passes the Snowflake Security Review.

📊 3 of 6 files (3 tests skipped) · 4,030 lines reviewed · 3 candidates → 3 kept · retrieval: on

sfc-gh-lshi · 2026-07-29T17:53:24Z

    if isinstance(value, str) and isinstance(datatype, DayTimeIntervalType):
        return f"{str_to_sql_for_day_time_interval(value, datatype)} :: {convert_sp_to_sf_type(datatype)}"

+    if isinstance(value, timedelta) and isinstance(datatype, DayTimeIntervalType):


Can we unit test this conversion to SQL string? The math is pretty complicated so some tests would be ideal

sfc-gh-lshi · 2026-07-29T17:55:38Z

+    assert result[0][0] == datetime.timedelta(days=-3)
+
+
+def test_udf_yearmonth_interval(session):


We can also add a test for negative yearmonth

sfc-gh-lshi · 2026-07-29T18:09:36Z

+def test_sproc_yearmonth_interval(session):
+    """YearMonthIntervalType sproc: int (total months) arg/return round-trips correctly."""
+    if not _interval_udf_flag_enabled(session):
+        pytest.skip("ENABLE_INTERVAL_TYPES_IN_UDF not enabled on this account")


Because of the skip, the test passes if the feature isn't enabled so we need to be careful about syncing the parameter rollout and client release. Otherwise, we might merge the change with tests skipped, then turn on the parameter and have untested code in the release.

Imo we should keep this PR open until the parameter is turned on, or turn on the parameter in this client's test account, remove the skip, and merge after testing

I am going to send out a PR for enabling the param in GS and will merge this PR after that PR is merged and the CI passed on this repo.

sfc-gh-yuwang · 2026-07-29T20:14:05Z

+        total_us %= 60_000_000
+        s = total_us // 1_000_000
+        us = total_us % 1_000_000
+        interval_str = f"{sign}{d} {h:02d}:{m:02d}:{s:02d}.{us:06d}"


can you check if we can reuse format_day_time_interval() or format_day_time_interval_for_display() in type_utils.py?
another question I have is do we need :: {convert_sp_to_sf_type(datatype)} like we used when value is a string?

The display functions (format_day_time_interval_for_display, format_year_month_interval_for_display) go in the opposite direction — they take interval strings already returned by Snowflake and reformat them for display. Our new to_sql cases go the other way: Python native values (timedelta, int) → SQL literal. Different input type, different purpose, so they're not reusable here.

For the suffix, you are right. I have added the suffix for consistency.

sfc-gh-yuwang · 2026-07-29T20:15:07Z

+        abs_months = abs(value)
+        years = abs_months // 12
+        months = abs_months % 12
+        interval_str = f"{sign}{years}-{months:02d}"


similar here, is it possible we reuse format_year_month_interval_for_display() ?

replied above: https://github.com/snowflakedb/snowpark-python/pull/4291/changes#r3707481689

snowflake-security-bot

Snowflake Security Review

Security grade: A — Passed ✅

No security findings after adjudication. This PR passes the Snowflake Security Review.

📊 10 files · 16,731 lines reviewed · 3 candidates → 1 kept · retrieval: on

python sdk change draft

d717360

sfc-gh-jzhan added 2 commits July 27, 2026 18:43

add e2e tests

097af22

Merge branch 'main' into jing/interval-udf-sdk

8c7fa69

sfc-gh-jzhan marked this pull request as ready for review July 29, 2026 17:20

sfc-gh-jzhan requested review from a team as code owners July 29, 2026 17:20

sfc-gh-jzhan requested review from sfc-gh-aling, sfc-gh-bkogan and sfc-gh-mayliu July 29, 2026 17:20

snowflake-security-bot Bot reviewed Jul 29, 2026

View reviewed changes

sfc-gh-lshi reviewed Jul 29, 2026

View reviewed changes

sfc-gh-yuwang reviewed Jul 29, 2026

View reviewed changes

sfc-gh-jzhan requested review from sfc-gh-lshi and sfc-gh-yuwang August 3, 2026 20:36

sfc-gh-jzhan added 4 commits August 3, 2026 13:46

test push

1d49078

add tests

d65b524

resolve comments

dba465a

cleanup param setting

3489ae2

github-actions Bot added the local testing Local Testing issues/PRs label Aug 4, 2026

snowflake-security-bot Bot reviewed Aug 4, 2026

View reviewed changes

sfc-gh-yuwang approved these changes Aug 5, 2026

View reviewed changes

Navigation Menu

Uh oh!

SNOW-3746497 Snowpark Python SDK: add interval type support for UDFs & Sprocs - #4291

SNOW-3746497 Snowpark Python SDK: add interval type support for UDFs & Sprocs#4291
sfc-gh-jzhan wants to merge 7 commits into
mainfrom
jing/interval-udf-sdk

sfc-gh-jzhan commented Jul 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 21, 2026

Uh oh!

codecov-commenter commented Jul 21, 2026 •

edited

Loading

Uh oh!

snowflake-security-bot Bot left a comment

Uh oh!

sfc-gh-lshi Jul 29, 2026

Uh oh!

sfc-gh-lshi Jul 29, 2026

Uh oh!

sfc-gh-lshi Jul 29, 2026 •

edited

Loading

Uh oh!

sfc-gh-jzhan Aug 3, 2026

Uh oh!

sfc-gh-yuwang Jul 29, 2026

Uh oh!

sfc-gh-jzhan Aug 3, 2026

Uh oh!

sfc-gh-yuwang Jul 29, 2026

Uh oh!

sfc-gh-jzhan Aug 3, 2026

Uh oh!

snowflake-security-bot Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		assert result[0][0] == datetime.timedelta(days=-3)


		def test_udf_yearmonth_interval(session):

Uh oh!

Conversation

sfc-gh-jzhan commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 21, 2026

Uh oh!

codecov-commenter commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

snowflake-security-bot Bot left a comment

Choose a reason for hiding this comment

Snowflake Security Review

Uh oh!

sfc-gh-lshi Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

sfc-gh-lshi Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

sfc-gh-lshi Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfc-gh-jzhan Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

sfc-gh-yuwang Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

sfc-gh-jzhan Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

sfc-gh-yuwang Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

sfc-gh-jzhan Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

snowflake-security-bot Bot left a comment

Choose a reason for hiding this comment

Snowflake Security Review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sfc-gh-jzhan commented Jul 21, 2026 •

edited

Loading

codecov-commenter commented Jul 21, 2026 •

edited

Loading

sfc-gh-lshi Jul 29, 2026 •

edited

Loading