SNOW-898383: snowflake.snowpark.functions.datediff documentation does not match implementation

[zaramzamzam]

I skipped the first few questions, since I think they might not be important to this issue.

4. What did you do?

I tested the example code for the datediff function.

>>> # year difference between two date columns
>>> import datetime
>>> date_df = session.create_dataframe([[datetime.date(2020, 1, 1), datetime.date(2021, 1, 1)]], schema=["date_col1", "date_col2"])
>>> date_df.select(datediff("year", col("date_col1"), col("date_col2")).alias("year_diff")).show()
---------------
|"YEAR_DIFF"  |
---------------
|1            |
---------------

5. What did you expect to see?

As the documentation describes the datedifffunction parameters are defined as the following:

Parameters:
part – The time part to use for calculating the difference

col1 – The first timestamp column or minuend in the datediff

col2 – The second timestamp column or the subtrahend in the datediff

Therefore I would have expected to see a difference of -1 instead of 1.
Since col2 should have been subtracted from col1 according to the documentation.

The opposite happens, which is in line with the documentation of the SQL functionality as described in Snowflake Datediff SQL.

[zaramzamzam]

If this is seen as an issue I would be happy to contribute.

[sfc-gh-aalam]

I'm not sure if this is a bug. Based on the documentation you provided, I ran the same example on snowflake using sql and the results align when the results generated by the snowpark client

select DATEDIFF(year, '2020-01-01'::DATE, '2021-01-01'::DATE) as YEAR_DIFF;

--output
YEAR_DIFF
1

Do you see a difference between snowflake server and the client?

edit: This is a documentation bug. I'll update the documentation to match the behavior

[zaramzamzam]

Not a difference in the result, but as you said a bug in the documentation which should be fixed in the linked PR.