From 8bbbde7cb3c396bc369c06853ed3a2ec021a2530 Mon Sep 17 00:00:00 2001 From: Kent Yao Date: Wed, 29 May 2024 13:31:38 +0800 Subject: [PATCH] [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 Signed-off-by: Kent Yao --- docs/_data/menu-sql.yaml | 2 + docs/sql-ref-operators.md | 124 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+) create mode 100644 docs/sql-ref-operators.md diff --git a/docs/_data/menu-sql.yaml b/docs/_data/menu-sql.yaml index 46dc4f3388cbd..059a9bdc1af43 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 0000000000000..102e45fba8d20 --- /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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrecedenceOperatorOperationAssociativity
1.
[]
::		member access
element access
cast		Left to right
2+
-
~		unary plus
unary minus
bitwise NOT		Right to left
3*
/
%
DIV		multiplication
division, modulo
integral division		Left to right
4+
-
||		addition
subtraction
concatenation		Left to right
5<<
>>
>>>		bitwise shift left
bitwise shift right
bitwise shift right unsigned		Left to right
6&bitwise ANDLeft to right
7^bitwise XOR(exclusive or)Left to right
8|bitwise OR(inclusive or)Left to right
9=, ==
<>, !=
<, <=
>, >=		comparison operatorsLeft to right
10NOT, !
EXISTS		logical NOT
existence		Right to left
11BETWEEN
IN
RLIKE, REGEXP
ILIKE
LIKE
IS [NULL, TRUE, FALSE]
IS DISTINCT FROM		other predicatesLeft to right
12ANDconjunctionLeft to right
13ORdisjunctionLeft to right