Update documentation to mention PARAMETRIC_DATETIME client capabilities header

[alec-heif]

The following query

SELECT cast(TIMESTAMP '2020-09-01 12:00:00.123456789' as TIMESTAMP(9))

gives the following result when run against the <coordinator_host>/v1/statement endpoint:

"2020-09-01 12:00:00.123"

on prestosql 340

This is in contrast to the documentation here which states that the result should be

"2020-09-01 12:00:00.123456789"

FWIW the presto CLI handles this query correctly:

presto> SELECT cast(TIMESTAMP '2020-09-01 12:00:00.123456789' as TIMESTAMP(9));
             _col0
-------------------------------
 2020-09-01 12:00:00.123456789

and even handles the non-parameterized version correctly as well:

presto> SELECT TIMESTAMP '2020-09-01 12:00:00.123456789';
             _col0
-------------------------------
 2020-09-01 12:00:00.123456789
(1 row)

[martint]

When we added this feature, we had to preserve backward compatibility for old clients that did not support arbitrary precision. In order to get the new behaviors, client have to declare they support the PARAMETRIC_DATETIME capability via the X-Presto-Client-Capabilities header.

[alec-heif]

ah I see, thanks for the clarification.

do you think it makes sense to add this advice to either https://prestosql.io/docs/current/functions/datetime.html or https://prestosql.io/docs/current/language/timestamp.html?highlight=timestamp? or will this be a non-issue in 341 now that the PR breaking backcompat with legacy semantics is landed?

[alec-heif]

to close the loop I can confirm that the full results are returned when -H "X-Presto-Client-Capabilities: PARAMETRIC_DATETIME" is included so going to retitle this issue as a documentation update :)

[martint]

do you think it makes sense to add this advice to either https://prestosql.io/docs/current/functions/datetime.html or https://prestosql.io/docs/current/language/timestamp.html?highlight=timestamp

No, that should be mentioned in the Clients or Developer section. It's something users shouldn't be concerned with, as it's an implementation detail of the client itself. We don't have any place for that information right now, so we'll have to create something. cc @mosabua

[findepi]

@alec-heif curious, do you use a client library or interact with REST API directly?

[alec-heif]

@findepi I use the pyhive client library

[findepi]

@alec-heif i created dropbox/PyHive#363 as a follow up to this discussion.
thanks for reminding about this.