You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spark.apache.org by ya...@apache.org on 2024/05/29 05:31:53 UTC

(spark) branch master updated: [SPARK-48426][SQL][DOCS] Add documentation for SQL operator precedence

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 8bbbde7cb3c3 [SPARK-48426][SQL][DOCS] Add documentation for SQL operator precedence
8bbbde7cb3c3 is described below

commit 8bbbde7cb3c396bc369c06853ed3a2ec021a2530
Author: Kent Yao <ya...@apache.org>
AuthorDate: Wed May 29 13:31:38 2024 +0800

    [SPARK-48426][SQL][DOCS] Add documentation for SQL operator precedence
    
    ### What changes were proposed in this pull request?
    
    This PR adds a doc for SQL operator precedence based on the current definition of `SqlBaseParser.g4`
    
    Not related to this PR, I have found that our `^` and `!` operators have quite different precedences than other modern systems.
    
    https://docs.oracle.com/cd/A58617_01/server.804/a58225/ch3all.htm
    https://learn.microsoft.com/en-us/sql/t-sql/language-elements/operator-precedence-transact-sql?view=sql-server-ver16
    https://dev.mysql.com/doc/refman/8.0/en/operator-precedence.html
    https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-PRECEDENCE
    https://mariadb.com/kb/en/operator-precedence/
    https://docs.databricks.com/en/sql/language-manual/sql-ref-functions-builtin.html#operator-precedence
    
    ### Why are the changes needed?
    
    doc improvement
    
    ### Does this PR introduce _any_ user-facing change?
    
    no
    
    ### How was this patch tested?
     doc build
    
    ![image](https://github.com/apache/spark/assets/8326978/dd612740-dd8a-4dc9-af2c-488938f00dff)
    
    ### Was this patch authored or co-authored using generative AI tooling?
    no
    
    Closes #46757 from yaooqinn/SPARK-48426.
    
    Authored-by: Kent Yao <ya...@apache.org>
    Signed-off-by: Kent Yao <ya...@apache.org>
---
 docs/_data/menu-sql.yaml  |   2 +
 docs/sql-ref-operators.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+)

diff --git a/docs/_data/menu-sql.yaml b/docs/_data/menu-sql.yaml
index 46dc4f3388cb..059a9bdc1af4 100644
--- a/docs/_data/menu-sql.yaml
+++ b/docs/_data/menu-sql.yaml
@@ -85,6 +85,8 @@
       url: sql-ref-datetime-pattern.html
     - text: Number Pattern
       url: sql-ref-number-pattern.html
+    - text: Operators
+      url: sql-ref-operators.html
     - text: Functions
       url: sql-ref-functions.html
     - text: Identifiers
diff --git a/docs/sql-ref-operators.md b/docs/sql-ref-operators.md
new file mode 100644
index 000000000000..102e45fba8d2
--- /dev/null
+++ b/docs/sql-ref-operators.md
@@ -0,0 +1,124 @@
+---
+layout: global
+title: Operators
+displayTitle: Operators
+license: |
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+---
+
+An SQL operator is a symbol specifying an action that is performed on one or more expressions. Operators are represented by special characters or by keywords.
+
+### Operator Precedence
+
+When a complex expression has multiple operators, operator precedence determines the sequence of operations in the expression,
+e.g. in expression `1 + 2 * 3`, `*` has higher precedence than `+`, so the expression is evaluated as `1 + (2 * 3) = 7`.
+The order of execution can significantly affect the resulting value.
+
+Operators have the precedence levels shown in the following table.
+An operator on higher precedence is evaluated before an operator on a lower level.
+In the following table, the operators in descending order of precedence, a.k.a. 1 is the highest level.
+Operators listed on the same table cell have the same precedence and are evaluated from left to right or right to left based on the associativity.
+
+<table>
+  <thead>
+    <tr>
+      <th>Precedence</th>
+      <th>Operator</th>
+      <th>Operation</th>
+      <th>Associativity</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>.<br/>[]<br/>::</td>
+      <td>member access<br/>element access<br/>cast</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>+<br/>-<br/>~</td>
+      <td>unary plus<br/>unary minus<br/>bitwise NOT</td>
+      <td>Right to left</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>*<br/>/<br/>%<br/>DIV</td>
+      <td>multiplication<br/>division, modulo<br/>integral division</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>4</td>
+      <td>+<br/>-<br/>||</td>
+      <td>addition<br/>subtraction<br/>concatenation</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>5</td>
+      <td>&lt;&lt;<br/>&gt;&gt;<br/>&gt;&gt;&gt;</td>
+      <td>bitwise shift left<br/>bitwise shift right<br/>bitwise shift right unsigned</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>6</td>
+      <td>&</td>
+      <td>bitwise AND</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>7</td>
+      <td>^</td>
+      <td>bitwise XOR(exclusive or)</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>8</td>
+      <td>|</td>
+      <td>bitwise OR(inclusive or)</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>9</td>
+      <td>=, ==<br/>&lt;&gt;, !=<br/>&lt;, &lt;=<br/>&gt;, &gt;=</td>
+      <td>comparison operators</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>10</td>
+      <td>NOT, !<br/>EXISTS</td>
+      <td>logical NOT<br/>existence</td>
+      <td>Right to left</td>
+    </tr>
+    <tr>
+      <td>11</td>
+      <td>BETWEEN<br/>IN<br/>RLIKE, REGEXP<br/>ILIKE<br/>LIKE<br/>IS [NULL, TRUE, FALSE]<br/>IS DISTINCT FROM</td>
+      <td>other predicates</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>12</td>
+      <td>AND</td>
+      <td>conjunction</td>
+      <td>Left to right</td>
+    </tr>
+    <tr>
+      <td>13</td>
+      <td>OR</td>
+      <td>disjunction</td>
+      <td>Left to right</td>
+    </tr>
+  </tbody>
+</table>


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