[spark] branch branch-3.0 updated: [SPARK-31502][SQL][DOCS] Document identifier in SQL Reference

[wenchen]

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

wenchen pushed a commit to branch branch-3.0
in repository https://gitbox.apache.org/repos/asf/spark.git


The following commit(s) were added to refs/heads/branch-3.0 by this push:
     new cec09b0  [SPARK-31502][SQL][DOCS] Document identifier in SQL Reference
cec09b0 is described below

commit cec09b05f822da54bf78a6682fe9c0fba7896ef0
Author: Huaxin Gao <huax...@us.ibm.com>
AuthorDate: Fri Apr 24 08:05:27 2020 +0000

    [SPARK-31502][SQL][DOCS] Document identifier in SQL Reference
    
    ### What changes were proposed in this pull request?
    Document identifier in SQL Reference
    
    ### Why are the changes needed?
    make SQL Reference complete
    
    ### Does this PR introduce any user-facing change?
    Yes
    <img width="1049" alt="Screen Shot 2020-04-23 at 11 14 10 PM" 
src="https://user-images.githubusercontent.com/13592258/80180695-2f2a4f00-85b8-11ea-819b-f96872956d05.png";>
    
    <img width="1050" alt="Screen Shot 2020-04-23 at 11 32 32 PM" 
src="https://user-images.githubusercontent.com/13592258/80182062-e6c06080-85ba-11ea-9502-1c38358c97c9.png";>
    
    ### How was this patch tested?
    Manually build and check
    
    Closes #28277 from huaxingao/identifier.
    
    Authored-by: Huaxin Gao <huax...@us.ibm.com>
    Signed-off-by: Wenchen Fan <wenc...@databricks.com>
    (cherry picked from commit b14b980ab86a5e68e0affa62a875e2db6812ed2e)
    Signed-off-by: Wenchen Fan <wenc...@databricks.com>
---
 docs/_data/menu-sql.yaml   |  2 ++
 docs/sql-ref-identifier.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+)

diff --git a/docs/_data/menu-sql.yaml b/docs/_data/menu-sql.yaml
index 5d8c265..26cca61 100644
--- a/docs/_data/menu-sql.yaml
+++ b/docs/_data/menu-sql.yaml
@@ -78,6 +78,8 @@
   subitems:
     - text: Data Types
       url: sql-ref-datatypes.html
+    - text: Identifiers
+      url: sql-ref-identifier.html
     - text: Literals
       url: sql-ref-literals.html
     - text: Null Semantics
diff --git a/docs/sql-ref-identifier.md b/docs/sql-ref-identifier.md
new file mode 100644
index 0000000..89cde21
--- /dev/null
+++ b/docs/sql-ref-identifier.md
@@ -0,0 +1,80 @@
+---
+layout: global
+title: Identifiers
+displayTitle: Identifiers
+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.
+---
+
+### Description
+
+An identifier is a string used to identify a database object such as a table, 
view, schema, column, etc. Spark SQL has regular identifiers and delimited 
identifiers, which are enclosed within backticks. Both regular identifiers and 
delimited identifiers are case-insensitive.
+
+### Syntax
+
+#### Regular Identifier
+
+{% highlight sql %}
+{ letter | digit | '_' } [ , ... ]
+{% endhighlight %}
+Note: If `spark.sql.ansi.enabled` is set to true, ANSI SQL reserved keywords 
cannot be used as identifiers. For more details, please refer to [ANSI 
Compliance](sql-ref-ansi-compliance.html).
+
+#### Delimited Identifier
+
+{% highlight sql %}
+`c [ ... ]`
+{% endhighlight %}
+
+### Parameters
+
+<dl>
+  <dt><code><em>letter</em></code></dt>
+  <dd>
+    Any letter from A-Z or a-z.
+  </dd>
+</dl>
+<dl>
+  <dt><code><em>digit</em></code></dt>
+  <dd>
+    Any numeral from 0 to 9.
+  </dd>
+</dl>
+<dl>
+  <dt><code><em>c</em></code></dt>
+  <dd>
+    Any character from the character set. Use <code>`</code> to escape special 
characters (e.g., <code>`</code>).
+  </dd>
+</dl>
+
+### Examples
+
+{% highlight sql %}
+-- This CREATE TABLE fails with ParseException because of the illegal 
identifier name a.b
+CREATE TABLE test (a.b int);
+org.apache.spark.sql.catalyst.parser.ParseException:
+no viable alternative at input 'CREATE TABLE test (a.'(line 1, pos 20)
+
+-- This CREATE TABLE works
+CREATE TABLE test (`a.b` int);
+
+-- This CREATE TABLE fails with ParseException because special character ` is 
not escaped
+CREATE TABLE test1 (`a`b` int);
+org.apache.spark.sql.catalyst.parser.ParseException:
+no viable alternative at input 'CREATE TABLE test (`a`b`'(line 1, pos 23)
+
+-- This CREATE TABLE works
+CREATE TABLE test (`a``b` int);
+{% endhighlight %}


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