Add QueryBuilder examples to walkthrough and README

- README: Promote QueryBuilder as primary query method with fluent, expression
  tree, and filter_in/between examples; demote raw OData to fallback
- Walkthrough: Add Section 7 with 5 QueryBuilder demos (basic fluent,
  filter_in, filter_between, where() expression tree, combined + paging)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tpellissier

README.md

@@ -24,7 +24,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
   - [Basic CRUD operations](#basic-crud-operations)
   - [Bulk operations](#bulk-operations)
   - [Upsert operations](#upsert-operations)
-  - [Query data](#query-data)
+  - [Query data](#query-data) *(QueryBuilder, SQL, raw OData)*
   - [Table management](#table-management)
   - [Relationship management](#relationship-management)
   - [File operations](#file-operations)
@@ -36,7 +36,8 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
 
 - **🔄 CRUD Operations**: Create, read, update, and delete records with support for bulk operations and automatic retry
 - **⚡ True Bulk Operations**: Automatically uses Dataverse's native `CreateMultiple`, `UpdateMultiple`, `UpsertMultiple`, and `BulkDelete` Web API operations for maximum performance and transactional integrity
-- **📊 SQL Queries**: Execute read-only SQL queries via the Dataverse Web API `?sql=` parameter  
+- **🔍 Fluent QueryBuilder**: Type-safe query construction with method chaining, composable filter expressions, and automatic OData generation
+- **📊 SQL Queries**: Execute read-only SQL queries via the Dataverse Web API `?sql=` parameter
 - **🏗️ Table Management**: Create, inspect, and delete custom tables and columns programmatically
 - **🔗 Relationship Management**: Create one-to-many and many-to-many relationships between tables with full metadata control
 - **📎 File Operations**: Upload files to Dataverse file columns with automatic chunking for large files
@@ -113,7 +114,7 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 | Concept | Description |
 |---------|-------------|
 | **DataverseClient** | Main entry point; provides `records`, `query`, `tables`, and `files` namespaces |
-| **Namespaces** | Operations are organized into `client.records` (CRUD & OData queries), `client.query` (query & search), `client.tables` (metadata), and `client.files` (file uploads) |
+| **Namespaces** | Operations are organized into `client.records` (CRUD), `client.query` (QueryBuilder & SQL), `client.tables` (metadata), and `client.files` (file uploads) |
 | **Records** | Dataverse records represented as Python dictionaries with column schema names |
 | **Schema names** | Use table schema names (`"account"`, `"new_MyTestTable"`) and column schema names (`"name"`, `"new_MyTestColumn"`). See: [Table definitions in Microsoft Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/entity-metadata) |
 | **Bulk Operations** | Efficient bulk processing for multiple records with automatic optimization |
@@ -232,42 +233,83 @@ client.records.upsert("account", [
 
 ### Query data
 
+The **QueryBuilder** is the recommended way to query records. It provides a fluent, type-safe interface that generates correct OData queries automatically — no need to remember OData filter syntax.
+
+```python
+# Fluent query builder (recommended)
+for page in (client.query.builder("account")
+             .select("name", "revenue")
+             .filter_eq("statecode", 0)
+             .filter_gt("revenue", 1000000)
+             .order_by("revenue", descending=True)
+             .top(100)
+             .page_size(50)
+             .execute()):
+    for record in page:
+        print(f"{record['name']}: {record['revenue']}")
+```
+
+The QueryBuilder handles value formatting, column name casing, and OData syntax automatically. All filter methods are discoverable via IDE autocomplete:
+
+```python
+# Comparison filters
+query = (client.query.builder("contact")
+         .filter_eq("statecode", 0)          # statecode eq 0
+         .filter_gt("revenue", 1000000)      # revenue gt 1000000
+         .filter_contains("name", "Corp")    # contains(name, 'Corp')
+         .filter_in("statecode", [0, 1])     # statecode in (0, 1)
+         .filter_between("revenue", 100000, 500000)  # (revenue ge 100000 and revenue le 500000)
+         .filter_null("telephone1")          # telephone1 eq null
+         )
+```
+
+For complex logic (OR, NOT, grouping), use the composable expression tree with `where()`:
+
+```python
+from PowerPlatform.Dataverse.models.filters import eq, gt, filter_in, between
+
+# OR conditions: (statecode = 0 OR statecode = 1) AND revenue > 100k
+for page in (client.query.builder("account")
+             .select("name", "revenue")
+             .where((eq("statecode", 0) | eq("statecode", 1))
+                    & gt("revenue", 100000))
+             .execute()):
+    for record in page:
+        print(record["name"])
+
+# NOT, between, and in operators
+for page in (client.query.builder("account")
+             .where(~eq("statecode", 2))                  # NOT inactive
+             .where(between("revenue", 100000, 500000))    # revenue in range
+             .execute()):
+    for record in page:
+        print(record["name"])
+```
+
+**SQL queries** provide an alternative read-only query syntax:
+
 ```python
-# SQL query (read-only)
 results = client.query.sql(
     "SELECT TOP 10 accountid, name FROM account WHERE statecode = 0"
 )
 for record in results:
     print(record["name"])
+```
+
+**Raw OData queries** are available via `records.get()` for cases where you need direct control over the OData filter string:
 
-# OData query with paging
-# Note: filter and expand parameters are case sensitive
+```python
 for page in client.records.get(
     "account",
-    select=["accountid", "name"],  # select is case-insensitive (automatically lowercased)
-    filter="statecode eq 0",       # filter must use lowercase logical names (not transformed)
+    select=["name"],
+    filter="statecode eq 0",  # Raw OData: column names must be lowercase
+    expand=["primarycontactid"],  # Navigation properties are case-sensitive
     top=100,
 ):
     for record in page:
         print(record["name"])
-
-# Query with navigation property expansion (case-sensitive!)
-for page in client.records.get(
-    "account",
-    select=["name"],
-    expand=["primarycontactid"],  # Navigation property names are case-sensitive
-    filter="statecode eq 0",      # Column names must be lowercase logical names
-):
-    for account in page:
-        contact = account.get("primarycontactid", {})
-        print(f"{account['name']} - Contact: {contact.get('fullname', 'N/A')}")
 ```
 
-> **Important**: When using `filter` and `expand` parameters:
-> - **`filter`**: Column names must use exact lowercase logical names (e.g., `"statecode eq 0"`, not `"StateCode eq 0"`)
-> - **`expand`**: Navigation property names are case-sensitive and must match the exact server names
-> - **`select`** and **`orderby`**: Case-insensitive; automatically converted to lowercase
-
 ### Table management
 
 ```python

examples/advanced/walkthrough.py

@@ -7,7 +7,7 @@
 This example shows:
 - Table creation with various column types including enums
 - Single and multiple record CRUD operations
-- Querying with filtering, paging, and SQL
+- Querying with filtering, paging, QueryBuilder, and SQL
 - Picklist label-to-value conversion
 - Column management
 - Cleanup
@@ -24,6 +24,7 @@
 from azure.identity import InteractiveBrowserCredential
 from PowerPlatform.Dataverse.client import DataverseClient
 from PowerPlatform.Dataverse.core.errors import MetadataError
+from PowerPlatform.Dataverse.models.filters import eq, gt, between
 import requests
 
 
@@ -251,10 +252,107 @@ def main():
         print(f"  Page {page_num}: {len(page)} records - IDs: {record_ids}")
 
     # ============================================================================
-    # 7. SQL QUERY
+    # 7. QUERYBUILDER - FLUENT QUERIES
     # ============================================================================
     print("\n" + "=" * 80)
-    print("7. SQL Query")
+    print("7. QueryBuilder - Fluent Queries")
+    print("=" * 80)
+
+    # Basic fluent query: active records sorted by amount
+    log_call("client.query.builder(...).select().filter_eq().order_by().execute()")
+    print("Querying incomplete records ordered by amount (fluent builder)...")
+    qb_records = []
+    for page in backoff(
+        lambda: client.query.builder(table_name)
+        .select("new_Title", "new_Amount", "new_Priority")
+        .filter_eq("new_Completed", False)
+        .order_by("new_Amount", descending=True)
+        .top(10)
+        .execute()
+    ):
+        qb_records.extend(page)
+    print(f"[OK] QueryBuilder found {len(qb_records)} incomplete records:")
+    for rec in qb_records[:5]:
+        print(f"  - '{rec.get('new_title')}' Amount={rec.get('new_amount')}")
+
+    # filter_in: records with specific priorities
+    log_call("client.query.builder(...).filter_in('new_Priority', [HIGH, LOW]).execute()")
+    print("Querying records with HIGH or LOW priority (filter_in)...")
+    priority_records = []
+    for page in backoff(
+        lambda: client.query.builder(table_name)
+        .select("new_Title", "new_Priority")
+        .filter_in("new_Priority", [Priority.HIGH, Priority.LOW])
+        .execute()
+    ):
+        priority_records.extend(page)
+    print(f"[OK] Found {len(priority_records)} records with HIGH or LOW priority")
+    for rec in priority_records[:5]:
+        print(f"  - '{rec.get('new_title')}' Priority={rec.get('new_priority')}")
+
+    # filter_between: amount in a range
+    log_call("client.query.builder(...).filter_between('new_Amount', 500, 1500).execute()")
+    print("Querying records with amount between 500 and 1500 (filter_between)...")
+    range_records = []
+    for page in backoff(
+        lambda: client.query.builder(table_name)
+        .select("new_Title", "new_Amount")
+        .filter_between("new_Amount", 500, 1500)
+        .execute()
+    ):
+        range_records.extend(page)
+    print(f"[OK] Found {len(range_records)} records with amount in [500, 1500]")
+    for rec in range_records:
+        print(f"  - '{rec.get('new_title')}' Amount={rec.get('new_amount')}")
+
+    # Composable expression tree with where()
+    log_call("client.query.builder(...).where((eq(...) | eq(...)) & gt(...)).execute()")
+    print("Querying with composable expression tree (where)...")
+    expr_records = []
+    for page in backoff(
+        lambda: client.query.builder(table_name)
+        .select("new_Title", "new_Amount", "new_Quantity")
+        .where(
+            (eq("new_Completed", False) & gt("new_Amount", 100))
+        )
+        .order_by("new_Amount", descending=True)
+        .top(5)
+        .execute()
+    ):
+        expr_records.extend(page)
+    print(f"[OK] Expression tree query found {len(expr_records)} records:")
+    for rec in expr_records:
+        print(
+            f"  - '{rec.get('new_title')}' Amount={rec.get('new_amount')} Qty={rec.get('new_quantity')}"
+        )
+
+    # Combined: fluent filters + expression tree + paging
+    log_call("client.query.builder(...).filter_eq().where(between()).page_size().execute()")
+    print("Querying with combined fluent + expression filters and paging...")
+    combined_page_count = 0
+    combined_record_count = 0
+    for page in backoff(
+        lambda: client.query.builder(table_name)
+        .select("new_Title", "new_Quantity")
+        .filter_eq("new_Completed", False)
+        .where(between("new_Quantity", 1, 15))
+        .order_by("new_Quantity")
+        .page_size(3)
+        .execute()
+    ):
+        combined_page_count += 1
+        combined_record_count += len(page)
+        titles = [r.get("new_title", "?") for r in page]
+        print(f"  Page {combined_page_count}: {len(page)} records - {titles}")
+    print(
+        f"[OK] Combined query: {combined_record_count} records across {combined_page_count} page(s)"
+    )
+
+    # ============================================================================
+    # 8. SQL QUERY
+    # ============================================================================
+    print("\n" + "=" * 80)
+    print("8. SQL Query")
     print("=" * 80)
 
     log_call(f"client.query.sql('SELECT new_title, new_quantity FROM {table_name} WHERE new_completed = 1')")
@@ -268,10 +366,10 @@ def main():
         print(f"[WARN] SQL query failed (known server-side bug): {str(e)}")
 
     # ============================================================================
-    # 8. PICKLIST LABEL CONVERSION
+    # 9. PICKLIST LABEL CONVERSION
     # ============================================================================
     print("\n" + "=" * 80)
-    print("8. Picklist Label Conversion")
+    print("9. Picklist Label Conversion")
     print("=" * 80)
 
     log_call(f"client.records.create('{table_name}', {{'new_Priority': 'High'}})")
@@ -289,10 +387,10 @@ def main():
     print(f"  new_Priority@FormattedValue: {retrieved.get('new_priority@OData.Community.Display.V1.FormattedValue')}")
 
     # ============================================================================
-    # 9. COLUMN MANAGEMENT
+    # 10. COLUMN MANAGEMENT
     # ============================================================================
     print("\n" + "=" * 80)
-    print("9. Column Management")
+    print("10. Column Management")
     print("=" * 80)
 
     log_call(f"client.tables.add_columns('{table_name}', {{'new_Notes': 'string'}})")
@@ -305,10 +403,10 @@ def main():
     print(f"[OK] Deleted column: new_Notes")
 
     # ============================================================================
-    # 10. DELETE OPERATIONS
+    # 11. DELETE OPERATIONS
     # ============================================================================
     print("\n" + "=" * 80)
-    print("10. Delete Operations")
+    print("11. Delete Operations")
     print("=" * 80)
 
     # Single delete
@@ -323,10 +421,10 @@ def main():
     print(f"  (Deleting {len(paging_ids)} paging demo records)")
 
     # ============================================================================
-    # 11. CLEANUP
+    # 12. CLEANUP
     # ============================================================================
     print("\n" + "=" * 80)
-    print("11. Cleanup")
+    print("12. Cleanup")
     print("=" * 80)
 
     log_call(f"client.tables.delete('{table_name}')")
@@ -352,6 +450,7 @@ def main():
     print("  [OK] Reading records by ID and with filters")
     print("  [OK] Single and multiple record updates")
     print("  [OK] Paging through large result sets")
+    print("  [OK] QueryBuilder fluent queries (filter_eq, filter_in, filter_between, where)")
     print("  [OK] SQL queries")
     print("  [OK] Picklist label-to-value conversion")
     print("  [OK] Column management")