(spark) branch master updated: [MINOR][DOCS] Clarify docs on default fractional numeric literals in SQL

[ya...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

yao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/spark.git


The following commit(s) were added to refs/heads/master by this push:
     new 614a0c7d0ce3 [MINOR][DOCS] Clarify docs on default fractional numeric literals in SQL
614a0c7d0ce3 is described below

commit 614a0c7d0ce377fc22de44ec936bcfbf8f483148
Author: Nicholas Chammas <ni...@gmail.com>
AuthorDate: Tue Feb 6 12:46:48 2024 +0800

    [MINOR][DOCS] Clarify docs on default fractional numeric literals in SQL
    
    ### What changes were proposed in this pull request?
    
    Provide examples showing what type literals like `123.456` and `123.456E0` have in SQL.
    
    ### Why are the changes needed?
    
    In Python (and I think Java too) fractional numeric literals are typically floats. To get decimals, you need to provide an explicit postfix or use an explicit class. In Spark, it's the other way around. I found this surprising and couldn't find documentation about it.
    
    I discovered this after reading [SPARK-45786](https://issues.apache.org/jira/browse/SPARK-45786). I did a little searching and came across https://github.com/apache/spark/pull/10796, which shows that we used to default to floats as the fractional numeric literal, but then switched to decimals.
    
    There is an additional wrinkle I discovered in #45003. If the fractional literal has an exponent, then it's a double, not a decimal.
    
    The existing syntax documents this, but that alone is not user-friendly. The new examples make this clearer.
    
    ### Does this PR introduce _any_ user-facing change?
    
    Yes, it clarifies the user-facing documentation about fractional numeric literals.
    
    ### How was this patch tested?
    
    No testing.
    
    ### Was this patch authored or co-authored using generative AI tooling?
    
    No.
    
    Closes #45027 from nchammas/fractional-literal-take2.
    
    Authored-by: Nicholas Chammas <ni...@gmail.com>
    Signed-off-by: Kent Yao <ya...@apache.org>
---
 docs/sql-ref-literals.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md
index 2a02a22bd6f0..141f985b0bea 100644
--- a/docs/sql-ref-literals.md
+++ b/docs/sql-ref-literals.md
@@ -278,12 +278,19 @@ E [ + | - ] digit [ ... ]
 #### Fractional Literals Examples
 
 ```sql
-SELECT 12.578 AS col;
-+------+
-|   col|
-+------+
-|12.578|
-+------+
+SELECT 12.578 AS col, TYPEOF(12.578) AS type;
++------+------------+
+|   col|        type|
++------+------------+
+|12.578|decimal(5,3)|
++------+------------+
+
+SELECT 12.578E0 AS col, TYPEOF(12.578E0) AS type;
++------+------+
+|   col|  type|
++------+------+
+|12.578|double|
++------+------+
 
 SELECT -0.1234567 AS col;
 +----------+


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org