Documentation/714 part 2 add smaller feature details (#715)

* Create non-orm multiple example & clean up orm one
* Sync examples to have similar structure
* Add description of caching in SQLAlchemy.

Author: ArBridgeman

doc/changes/unreleased.md

@@ -17,3 +17,4 @@
 * #703: Added ORM examples
 * #706: Added more single and multiple entry ORM examples
 * #712: Added to features information on: autoincremented columns, foreign keys, & automatic indexes
+* #714: Added to features information on: caching + more non-ORM examples

doc/conf.py

@@ -87,5 +87,5 @@
     # All HTTP redirections from the source URI to
     # the canonical URI will be treated as "working".
     r"https://github\.com/.*": r"https://github\.com/login*",
-    r"https://exasol\.my\.site\.com/s/article/.*": r"https://exasol\.my\.site\.com/s/article/.*?language=en_US",
+    r"https://exasol\.my\.site\.com/s/.*": r"https://exasol\.my\.site\.com/s/.*?language=en_US",
 }

doc/user_guide/examples/non_orm/index.rst

@@ -8,3 +8,4 @@ Basic Operations
 
    create_tables
    single_entry
+   multiple_entries

doc/user_guide/examples/non_orm/multiple_entries.rst

@@ -0,0 +1,12 @@
+.. _example_non_orm_multiple_entries:
+
+Working with Multiple Entries
+=============================
+
+This script inserts multiple entries into our two tables in one session & relies
+on in-session auto-incrementing behavior. As mentioned in the :ref:`known_limitations`,
+SQLAlchemy is slower than other drivers at performing multiple entry inserts.
+
+.. literalinclude:: ../../../../examples/features/non_orm/_2_working_with_multiple_entries.py
+       :language: python3
+       :caption: examples/features/non_orm/_2_working_with_multiple_entries.py

doc/user_guide/features/index.rst

@@ -39,6 +39,38 @@ unnecessary but intentionally unsupported to prevent interference with the engin
 optimization algorithms. For more in-depth information, explore the Exasol documentation
 on `indexes <https://docs.exasol.com/db/latest/performance/indexes.htm>`__.
 
+Caching
+-------
+
+Since version 1.4, SQLAlchemy features a "SQL compilation caching" facility designed to
+significantly reduce Python interpreter overhead during query construction. This system
+works by generating a unique cache key that represents the structural state of a Core or
+an ORM SQL construct, including its columns, tables, and JOIN conditions. Once a
+specific query structure is compiled into a string for the first time, SQLAlchemy stores
+the result in an internal cache; subsequent executions with the same structure skip the
+expensive string compilation process and reuse the existing SQL. This is particularly
+beneficial for ORM-heavy applications, as it streamlines the logic for lazy loaders and
+relationship lookups.
+
+For more information, see these pages from SQLAlchemy:
+
+* `Performance <https://docs.sqlalchemy.org/en/21/faq/performance.html>`__
+* `SQL Compilation Caching <https://docs.sqlalchemy.org/en/21/core/connections.html#sql-compilation-caching>`__
+
+Since version 1.4, SQLAlchemy has also streamlined its "Reflection API" by implementing
+an internal metadata cache within the Inspector object. This system is designed to
+minimize the performance cost of querying database system catalogs—such as those in
+Exasol—by ensuring that schema details like columns, foreign keys, and constraints are
+only fetched once per inspector instance. When a method like ``get_foreign_keys()`` is
+called, the result is stored in an internal dictionary; subsequent requests for the same
+table metadata skip the network round-trip and return the cached data immediately.
+This is particularly advantageous for applications that perform heavy reflection
+operations.
+
+For more details, see:
+
+* `Reflecting Database Objects <https://docs.sqlalchemy.org/en/21/core/reflection.html>`__
+
 Foreign Keys
 ------------
 

doc/user_guide/index.rst

@@ -52,6 +52,16 @@ General Tips
 
 Known Limitations
 -----------------
+.. note::
+    * Running into an error with a specific SQLAlchemy example? Our Exasol dialect may
+      already be handling that for you! Check out our :ref:`features` for a full breakdown
+      of what is automated.
+    * In some cases, we might be able to provide new features or solutions for these
+      limitations. Please feel free to reach out by creating a
+      `GitHub issue <https://github.com/exasol/sqlalchemy-exasol/issues>`__.
+    * For technical difficulties, please submit a request
+      via the `Exasol Support Portal <https://exasol.my.site.com/s/create-new-case>`__.
+
 * Insert
 
   - SQLAlchemy is slower than other drivers at performing multiple entry inserts.

examples/features/non_orm/_0_create_tables.py

@@ -1,10 +1,13 @@
+from __future__ import annotations
+
 from sqlalchemy import (
     Column,
     ForeignKey,
     Integer,
     MetaData,
     String,
     Table,
+    text,
 )
 
 from examples.config import (
@@ -13,13 +16,15 @@
     SQL_ALCHEMY,
 )
 
+# For more information on table definitions, check out:
+#    https://docs.sqlalchemy.org/en/21/tutorial/metadata.html
+
 # 1. Ensure that the schema exists
 SQL_ALCHEMY.create_schema(engine=ENGINE, schema=DEFAULT_SCHEMA_NAME)
 
 # 2. Use the schema to define the metadata_obj, which is used in the `Base` class
 metadata_obj = MetaData(schema=DEFAULT_SCHEMA_NAME)
 
-
 metadata = MetaData()
 
 # 3. Define tables
@@ -42,3 +47,17 @@
 # 4. Create all tables
 with ENGINE.begin() as conn:
     metadata.create_all(conn)
+
+# 5. Verify that the tables have been created
+query = f"""
+SELECT TABLE_NAME
+FROM SYS.EXA_ALL_TABLES
+WHERE TABLE_SCHEMA = '{DEFAULT_SCHEMA_NAME}'
+ORDER BY TABLE_NAME
+"""
+
+with ENGINE.connect() as con:
+    results = con.execute(text(query)).fetchall()
+
+if __name__ == "__main__":
+    print(f"Tables in schema={DEFAULT_SCHEMA_NAME}: {results}")

examples/features/non_orm/_1_working_with_single_entry.py

@@ -52,22 +52,22 @@ def select_all_entries():
 
 select_all_entries()
 
-# 3. Update (Atomic execution)
+# 3. Update the entry
 with ENGINE.begin() as conn:
     # a. Update User
     conn.execute(
         update(user_table)
         .where(user_table.c.first_name == "Jax")
         .values(first_name="Paris")
     )
-    # b. Update Email (using a subquery or join-like syntax depending on logic)
+    # b. Update EmailAddress
     conn.execute(
         update(email_address_table)
         .where(email_address_table.c.email_address == "[email protected]")
         .values(email_address="[email protected]")
     )
 
-# 4. Delete
+# 4. Delete the entry
 with ENGINE.begin() as conn:
     # a. Get the IDs of the users you want to delete
     user_ids_stmt = select(user_table.c.id).where(user_table.c.first_name == "Paris")
@@ -81,5 +81,5 @@ def select_all_entries():
             )
         )
 
-        # c. Now delete the user
+        # c. Delete the user
         conn.execute(delete(user_table).where(user_table.c.id.in_(user_ids)))

examples/features/non_orm/_2_working_with_multiple_entries.py

@@ -0,0 +1,139 @@
+from sqlalchemy import (
+    and_,
+    delete,
+    insert,
+    or_,
+    select,
+    update,
+)
+
+from examples.config import ENGINE
+
+# Import the Table objects (not classes) from your metadata
+from examples.features.non_orm._0_create_tables import (
+    email_address_table,
+    user_table,
+)
+
+# 0. Clean tables
+with ENGINE.begin() as conn:
+    conn.execute(delete(email_address_table))
+    conn.execute(delete(user_table))
+
+# 1. Insert multiple entries
+data = [
+    {
+        "first_name": "Lux",
+        "last_name": "Noceda",
+        "email_addresses": ["[email protected]", "[email protected]"],
+    },
+    {
+        "first_name": "Eda",
+        "last_name": "Clawthorne",
+        "email_addresses": ["[email protected]"],
+    },
+    {
+        "first_name": "Raine",
+        "last_name": "Whispers",
+        "email_addresses": ["[email protected]"],
+    },
+    {
+        "first_name": "Amity",
+        "last_name": "Blight",
+        "email_addresses": ["[email protected]"],
+    },
+    {
+        "first_name": "Willow",
+        "last_name": "Park",
+        "email_addresses": ["[email protected]"],
+    },
+]
+
+with ENGINE.begin() as conn:
+    # a. Insert Users
+    user_payload = [
+        {"first_name": d["first_name"], "last_name": d["last_name"]} for d in data
+    ]
+    conn.execute(insert(user_table), user_payload)
+
+    # b. Retrieve user ids
+    stmt = select(user_table.c.id, user_table.c.first_name, user_table.c.last_name)
+    user_map = {(row.first_name, row.last_name): row.id for row in conn.execute(stmt)}
+
+    # c. Insert EmailAddresses
+    email_payload = []
+    for entry in data:
+        u_id = user_map.get((entry["first_name"], entry["last_name"]))
+        for email in entry["email_addresses"]:
+            email_payload.append({"user_id": u_id, "email_address": email})
+    conn.execute(insert(email_address_table), email_payload)
+
+
+# 2. Display results
+def select_all_entries():
+    with ENGINE.connect() as conn:
+        # Join user_table and email_address_table explicitly
+        stmt = select(
+            user_table.c.id,
+            user_table.c.first_name,
+            user_table.c.last_name,
+            email_address_table.c.email_address,
+        ).select_from(user_table.join(email_address_table, isouter=True))
+        results = conn.execute(stmt).fetchall()
+
+        # Grouping manually since Core doesn't have ORM's unique().all() object deduplication
+        grouped = {}
+        for row in results:
+            key = (row.id, row.first_name, row.last_name)
+            if key not in grouped:
+                grouped[key] = []
+            if row.email_address:
+                grouped[key].append(row.email_address)
+
+        for (u_id, f_name, l_name), emails in grouped.items():
+            print(f"{u_id} {f_name} {l_name} {emails}")
+
+
+select_all_entries()
+
+# 3. Update multiple entries
+with ENGINE.begin() as conn:
+    # a. Update the last_name of Users
+    new_last_name = "Clawthorne-Whispers"
+    conn.execute(
+        update(user_table)
+        .where(user_table.c.last_name.in_(["Whispers", "Clawthorne"]))
+        .values(last_name=new_last_name)
+    )
+
+    # b. Update the EmailAddress
+    eda_id_subq = (
+        select(user_table.c.id)
+        .where(user_table.c.first_name == "Eda")
+        .scalar_subquery()
+    )
+    conn.execute(
+        update(email_address_table)
+        .where(email_address_table.c.user_id == eda_id_subq)
+        .values(email_address="[email protected]")
+    )
+
+# 4. Delete multiple entries
+with ENGINE.begin() as conn:
+    # a. Define the selection criteria for the users you want to target
+    target_criteria = or_(
+        and_(user_table.c.first_name == "Amity", user_table.c.last_name == "Blight"),
+        and_(user_table.c.first_name == "Willow", user_table.c.last_name == "Park"),
+        and_(user_table.c.first_name == "Lux", user_table.c.last_name == "Noceda"),
+    )
+    stmt = select(user_table.c.id).where(target_criteria)
+    users_ids = conn.execute(stmt).scalars().all()
+
+    # b. Delete EmailAddresses associated with these Users, as they graduated
+    for uid in users_ids:
+        email_delete_stmt = delete(email_address_table).where(
+            email_address_table.c.user_id == uid
+        )
+        conn.execute(email_delete_stmt)
+
+select_all_entries()

examples/features/orm/_0_create_tables.py

@@ -20,7 +20,7 @@
     SQL_ALCHEMY,
 )
 
-# For more information on ORM table definition, check out:
+# For more information on ORM table definitions, check out:
 #    https://docs.sqlalchemy.org/en/20/orm/quickstart.html#orm-quick-start
 
 # 1. Ensure that the schema exists