Merging upstream version 10.1.3.

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

1 files changed, 73 insertions, 3 deletions

diff --git a/README.md b/README.md
index 2ceadfb..218d86c 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ Contributions are very welcome in SQLGlot; read the [contribution guide](https:/
    * [AST Introspection](#ast-introspection)
    * [AST Diff](#ast-diff)
    * [Custom Dialects](#custom-dialects)
+   * [SQL Execution](#sql-execution)
 * [Benchmarks](#benchmarks)
 * [Optional Dependencies](#optional-dependencies)
 
@@ -147,9 +148,9 @@ print(sqlglot.transpile(sql, read='mysql', pretty=True)[0])
 */
 SELECT
   tbl.cola /* comment 1 */ + tbl.colb /* comment 2 */,
-  CAST(x AS INT), -- comment 3
-  y -- comment 4
-FROM bar /* comment 5 */, tbl /*          comment 6*/
+  CAST(x AS INT), /* comment 3 */
+  y /* comment 4 */
+FROM bar /* comment 5 */, tbl /*          comment 6 */
 ```
 
 
@@ -189,6 +190,28 @@ sqlglot.errors.ParseError: Expecting ). Line 1, Col: 13.
               ~~~~
 ```
 
+Structured syntax errors are accessible for programmatic use:
+
+```python
+import sqlglot
+try:
+    sqlglot.transpile("SELECT foo( FROM bar")
+except sqlglot.errors.ParseError as e:
+    print(e.errors)
+```
+
+Output:
+```python
+[{
+  'description': 'Expecting )',
+  'line': 1,
+  'col': 13,
+  'start_context': 'SELECT foo( ',
+  'highlight': 'FROM',
+  'end_context': ' bar'
+}]
+```
+
 ### Unsupported Errors
 
 Presto `APPROX_DISTINCT` supports the accuracy argument which is not supported in Hive:
@@ -372,6 +395,53 @@ print(Dialect["custom"])
 <class '__main__.Custom'>
 ```
 
+### SQL Execution
+
+One can even interpret SQL queries using SQLGlot, where the tables are represented as Python dictionaries. Although the engine is not very fast (it's not supposed to be) and is in a relatively early stage of development, it can be useful for unit testing and running SQL natively across Python objects. Additionally, the foundation can be easily integrated with fast compute kernels (arrow, pandas). Below is an example showcasing the execution of a SELECT expression that involves aggregations and JOINs:
+
+```python
+from sqlglot.executor import execute
+
+tables = {
+    "sushi": [
+        {"id": 1, "price": 1.0},
+        {"id": 2, "price": 2.0},
+        {"id": 3, "price": 3.0},
+    ],
+    "order_items": [
+        {"sushi_id": 1, "order_id": 1},
+        {"sushi_id": 1, "order_id": 1},
+        {"sushi_id": 2, "order_id": 1},
+        {"sushi_id": 3, "order_id": 2},
+    ],
+    "orders": [
+        {"id": 1, "user_id": 1},
+        {"id": 2, "user_id": 2},
+    ],
+}
+
+execute(
+    """
+    SELECT
+      o.user_id,
+      SUM(s.price) AS price
+    FROM orders o
+    JOIN order_items i
+      ON o.id = i.order_id
+    JOIN sushi s
+      ON i.sushi_id = s.id
+    GROUP BY o.user_id
+    """,
+    tables=tables
+)
+```
+
+```python
+user_id price
+      1   4.0
+      2   3.0
+```
+
 ## Benchmarks
 
 [Benchmarks](benchmarks) run on Python 3.10.5 in seconds.