End-to-end SQL support: schema discovery, SELECT * expansion, DataFrame bridge, guardrails, examples

- Schema discovery APIs: list_columns, list_relationships, list_table_relationships
- SELECT * auto-expansion via list_columns (server blocks SELECT *)
- client.dataframe.sql() for SQL -> DataFrame bridge
- SQL safety guardrails: block writes, auto-inject TOP 5000, warn on
  leading-wildcard LIKE and implicit cross joins
- Comprehensive sql_examples.py (28 sections): JOINs, aggregates, GROUP BY,
  DISTINCT, OFFSET FETCH, polymorphic lookups, audit trail, SQL read ->
  DataFrame transform -> SDK write-back
- Updated query.sql() docstring with accurate SQL capabilities
- 732 tests (was 318), all passing

Author: Saurabh Badenkal

README.md

@@ -269,6 +269,14 @@ client.dataframe.update("account", df, id_column="accountid", clear_nulls=True)
 
 # Delete records by passing a Series of GUIDs
 client.dataframe.delete("account", new_accounts["accountid"])
+
+# SQL query directly to DataFrame (supports JOINs, aggregates, GROUP BY)
+df = client.dataframe.sql(
+    "SELECT a.name, COUNT(c.contactid) as contacts "
+    "FROM account a "
+    "JOIN contact c ON a.accountid = c.parentcustomerid "
+    "GROUP BY a.name"
+)
 ```
 
 ### Query data
@@ -372,14 +380,30 @@ results = (client.query.builder("account")
            .execute())
 ```
 
-**SQL queries** provide an alternative read-only query syntax:
+**SQL queries** provide an alternative read-only query syntax with support for
+JOINs, aggregates, GROUP BY, DISTINCT, and OFFSET FETCH pagination:
 
 ```python
+# Basic query
 results = client.query.sql(
     "SELECT TOP 10 accountid, name FROM account WHERE statecode = 0"
 )
-for record in results:
-    print(record["name"])
+
+# JOINs and aggregates work
+results = client.query.sql(
+    "SELECT a.name, COUNT(c.contactid) as cnt "
+    "FROM account a "
+    "JOIN contact c ON a.accountid = c.parentcustomerid "
+    "GROUP BY a.name"
+)
+
+# SELECT * is auto-expanded by the SDK
+results = client.query.sql("SELECT * FROM account")
+
+# SQL results directly as a DataFrame
+df = client.dataframe.sql(
+    "SELECT name, revenue FROM account ORDER BY revenue DESC"
+)
 ```
 
 **Raw OData queries** are available via `records.get()` for cases where you need direct control over the OData filter string:

examples/README.md

@@ -40,6 +40,19 @@ Deep-dive into production-ready patterns and specialized functionality:
   - Column metadata management and multi-language support  
   - Interactive cleanup and best practices
 
+- **`sql_examples.py`** - **SQL QUERY END-TO-END** 🔍
+  - Schema discovery before writing SQL (list_columns, list_relationships)
+  - Full SQL capabilities: SELECT, WHERE, TOP, ORDER BY, LIKE, IN, BETWEEN
+  - JOINs (INNER, LEFT, multi-table), GROUP BY, DISTINCT, aggregates
+  - OFFSET FETCH for server-side pagination
+  - SELECT * auto-expansion (SDK rewrites for server compatibility)
+  - Polymorphic lookups via SQL (ownerid, customerid, createdby)
+  - SQL read -> DataFrame transform -> SDK write-back (full round-trip)
+  - SQL-driven bulk create, update, and delete patterns
+  - SQL to DataFrame via `client.dataframe.sql()`
+  - Limitations with SDK fallbacks (writes, subqueries, functions)
+  - Complete reference table: SQL vs SDK method mapping
+
 - **`file_upload.py`** - **FILE OPERATIONS** 📎
   - File upload to Dataverse file columns with chunking
   - Advanced file handling patterns
@@ -68,13 +81,17 @@ python examples/basic/functional_testing.py
 ```bash
 # Comprehensive walkthrough with production patterns
 python examples/advanced/walkthrough.py
+
+# SQL queries end-to-end with SDK fallbacks for unsupported operations
+python examples/advanced/sql_examples.py
 ```
 
 ## 🎯 Quick Start Recommendations
 
 - **New to the SDK?** → Start with `examples/basic/installation_example.py`
 - **Need to test/validate?** → Use `examples/basic/functional_testing.py`  
 - **Want to see all features?** → Run `examples/advanced/walkthrough.py`
+- **Using SQL queries?** → Run `examples/advanced/sql_examples.py`
 - **Building production apps?** → Study patterns in `examples/advanced/walkthrough.py`
 
 ## 📋 Prerequisites