Merging upstream version 20.9.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 47 insertions, 30 deletions

diff --git a/README.md b/README.md
index 70ce7af..8a779db 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ SQLGlot is a no-dependency SQL parser, transpiler, optimizer, and engine. It can
 
 It is a very comprehensive generic SQL parser with a robust [test suite](https://github.com/tobymao/sqlglot/blob/main/tests/). It is also quite [performant](#benchmarks), while being written purely in Python.
 
-You can easily [customize](#custom-dialects) the parser, [analyze](#metadata) queries, traverse expression trees, and programmatically [build](#build-and-modify-sql) SQL. 
+You can easily [customize](#custom-dialects) the parser, [analyze](#metadata) queries, traverse expression trees, and programmatically [build](#build-and-modify-sql) SQL.
 
 Syntax [errors](#parser-errors) are highlighted and dialect incompatibilities can warn or raise depending on configurations. However, it should be noted that SQL validation is not SQLGlot’s goal, so some syntax errors may go unnoticed.
 
@@ -17,6 +17,7 @@ Contributions are very welcome in SQLGlot; read the [contribution guide](https:/
 * [Install](#install)
 * [Versioning](#versioning)
 * [Get in Touch](#get-in-touch)
+* [FAQ](#faq)
 * [Examples](#examples)
    * [Formatting and Transpiling](#formatting-and-transpiling)
    * [Metadata](#metadata)
@@ -38,8 +39,11 @@ Contributions are very welcome in SQLGlot; read the [contribution guide](https:/
 
 From PyPI:
 
-```
-pip3 install sqlglot
+```bash
+pip3 install "sqlglot[rs]"
+
+# Without Rust tokenizer (slower):
+# pip3 install sqlglot
 ```
 
 Or with a local checkout:
@@ -66,6 +70,20 @@ Given a version number `MAJOR`.`MINOR`.`PATCH`, SQLGlot uses the following versi
 
 We'd love to hear from you. Join our community [Slack channel](https://tobikodata.com/slack)!
 
+## FAQ
+
+I tried to parse SQL that should be valid but it failed, why did that happen?
+  
+* You need to specify the dialect to read the SQL properly, by default it is SQLGlot's dialect which is designed to be a superset of all dialects `parse_one(sql, dialect="spark")`. If you tried specifying the dialect and it still doesn't work, please file an issue.
+
+I tried to output SQL but it's not in the correct dialect!
+  
+* You need to specify the dialect to write the sql properly, by default it is in SQLGlot's dialect `parse_one(sql, dialect="spark").sql(dialect="spark")`.
+
+I tried to parse invalid SQL and it should raise an error but it worked! Why didn't it validate my SQL.
+  
+* SQLGlot is not a validator and designed to be very forgiving, handling things like trailing commas.
+
 ## Examples
 
 ### Formatting and Transpiling
@@ -318,13 +336,14 @@ print(repr(parse_one("SELECT a + 1 AS z")))
 ```
 
 ```python
-(SELECT expressions:
-  (ALIAS this:
-    (ADD this:
-      (COLUMN this:
-        (IDENTIFIER this: a, quoted: False)), expression:
-      (LITERAL this: 1, is_string: False)), alias:
-    (IDENTIFIER this: z, quoted: False)))
+Select(
+  expressions=[
+    Alias(
+      this=Add(
+        this=Column(
+          this=Identifier(this=a, quoted=False)),
+        expression=Literal(this=1, is_string=False)),
+      alias=Identifier(this=z, quoted=False))])
 ```
 
 ### AST Diff
@@ -338,19 +357,17 @@ diff(parse_one("SELECT a + b, c, d"), parse_one("SELECT c, a - b, d"))
 
 ```python
 [
-  Remove(expression=(ADD this:
-    (COLUMN this:
-      (IDENTIFIER this: a, quoted: False)), expression:
-    (COLUMN this:
-      (IDENTIFIER this: b, quoted: False)))),
-  Insert(expression=(SUB this:
-    (COLUMN this:
-      (IDENTIFIER this: a, quoted: False)), expression:
-    (COLUMN this:
-      (IDENTIFIER this: b, quoted: False)))),
-  Move(expression=(COLUMN this:
-    (IDENTIFIER this: c, quoted: False))),
-  Keep(source=(IDENTIFIER this: b, quoted: False), target=(IDENTIFIER this: b, quoted: False)),
+  Remove(expression=Add(
+    this=Column(
+      this=Identifier(this=a, quoted=False)),
+    expression=Column(
+      this=Identifier(this=b, quoted=False)))),
+  Insert(expression=Sub(
+    this=Column(
+      this=Identifier(this=a, quoted=False)),
+    expression=Column(
+      this=Identifier(this=b, quoted=False)))),
+  Keep(source=Identifier(this=d, quoted=False), target=Identifier(this=d, quoted=False)),
   ...
 ]
 ```
@@ -480,14 +497,14 @@ make check  # Full test suite & linter checks
 
 ## Benchmarks
 
-[Benchmarks](https://github.com/tobymao/sqlglot/blob/main/benchmarks/bench.py) run on Python 3.10.5 in seconds.
+[Benchmarks](https://github.com/tobymao/sqlglot/blob/main/benchmarks/bench.py) run on Python 3.10.12 in seconds.
 
-|           Query |         sqlglot |        sqlfluff |         sqltree |        sqlparse |  moz_sql_parser |        sqloxide |
-| --------------- | --------------- | --------------- | --------------- | --------------- | --------------- | --------------- |
-|            tpch |   0.01308 (1.0) | 1.60626 (122.7) | 0.01168 (0.893) | 0.04958 (3.791) | 0.08543 (6.531) | 0.00136 (0.104) |
-|           short |   0.00109 (1.0) | 0.14134 (129.2) | 0.00099 (0.906) | 0.00342 (3.131) | 0.00652 (5.970) | 8.76E-5 (0.080) |
-|            long |   0.01399 (1.0) | 2.12632 (151.9) | 0.01126 (0.805) | 0.04410 (3.151) | 0.06671 (4.767) | 0.00107 (0.076) |
-|           crazy |   0.03969 (1.0) | 24.3777 (614.1) | 0.03917 (0.987) | 11.7043 (294.8) | 1.03280 (26.02) | 0.00625 (0.157) |
+|           Query |         sqlglot |       sqlglotrs |        sqlfluff |         sqltree |        sqlparse |  moz_sql_parser |        sqloxide |
+| --------------- | --------------- | --------------- | --------------- | --------------- | --------------- | --------------- | --------------- |
+|            tpch |   0.00944 (1.0) | 0.00590 (0.625) | 0.32116 (33.98) | 0.00693 (0.734) | 0.02858 (3.025) | 0.03337 (3.532) | 0.00073 (0.077) |
+|           short |   0.00065 (1.0) | 0.00044 (0.687) | 0.03511 (53.82) | 0.00049 (0.759) | 0.00163 (2.506) | 0.00234 (3.601) | 0.00005 (0.073) |
+|            long |   0.00889 (1.0) | 0.00572 (0.643) | 0.36982 (41.56) | 0.00614 (0.690) | 0.02530 (2.844) | 0.02931 (3.294) | 0.00059 (0.066) |
+|           crazy |   0.02918 (1.0) | 0.01991 (0.682) | 1.88695 (64.66) | 0.02003 (0.686) | 7.46894 (255.9) | 0.64994 (22.27) | 0.00327 (0.112) |
 
 
 ## Optional Dependencies