Address PR review feedback: fix security issue, update README

tpellissier · claude · tpellissier · commit c9d77f14d08d · 2026-01-21T10:23:05.000-08:00
- Fix OData filter injection vulnerability in _get_relationship by using
  _escape_odata_quotes() to sanitize schema_name input
- Fix late binding closure bug in relationships.py cleanup loop
- Remove unused imports (HttpError, MetadataError, pytest)
- Initialize relationship IDs to None for cleanup safety
- Add relationship management section to README with examples
- Update docstring examples to use intuitive Department/Employee/Project
  scenario with helpful comments

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -25,6 +25,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
   - [Bulk operations](#bulk-operations)
   - [Query data](#query-data)
   - [Table management](#table-management)
+  - [Relationship management](#relationship-management)
   - [File operations](#file-operations)
 - [Next steps](#next-steps)
 - [Troubleshooting](#troubleshooting)
@@ -36,6 +37,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
 - **⚡ True Bulk Operations**: Automatically uses Dataverse's native `CreateMultiple`, `UpdateMultiple`, 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  
 - **🏗️ 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
 - **🔐 Azure Identity**: Built-in authentication using Azure Identity credential providers with comprehensive support
 - **🛡️ Error Handling**: Structured exception hierarchy with detailed error context and retry guidance
@@ -235,9 +237,74 @@ client.delete_columns("new_Product", ["new_Category"])
 client.delete_table("new_Product")
 ```
 
-> **Important**: All custom column names must include the customization prefix value (e.g., `"new_"`). 
+> **Important**: All custom column names must include the customization prefix value (e.g., `"new_"`).
 > This ensures explicit, predictable naming and aligns with Dataverse metadata requirements.
 
+### Relationship management
+
+Create relationships between tables using the relationship API. For a complete working example, see [examples/advanced/relationships.py](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/relationships.py).
+
+```python
+from PowerPlatform.Dataverse.models.metadata import (
+    LookupAttributeMetadata,
+    OneToManyRelationshipMetadata,
+    ManyToManyRelationshipMetadata,
+    Label,
+    LocalizedLabel,
+)
+
+# Create a one-to-many relationship: Department (1) -> Employee (N)
+# This adds a "Department" lookup field to the Employee table
+lookup = LookupAttributeMetadata(
+    schema_name="new_DepartmentId",
+    display_name=Label(localized_labels=[LocalizedLabel(label="Department", language_code=1033)]),
+)
+
+relationship = OneToManyRelationshipMetadata(
+    schema_name="new_Department_Employee",
+    referenced_entity="new_department",   # Parent table (the "one" side)
+    referencing_entity="new_employee",    # Child table (the "many" side)
+    referenced_attribute="new_departmentid",
+)
+
+result = client.create_one_to_many_relationship(lookup, relationship)
+print(f"Created lookup field: {result['lookup_schema_name']}")
+
+# Create a many-to-many relationship: Employee (N) <-> Project (N)
+# Employees work on multiple projects; projects have multiple team members
+m2m_relationship = ManyToManyRelationshipMetadata(
+    schema_name="new_employee_project",
+    entity1_logical_name="new_employee",
+    entity2_logical_name="new_project",
+)
+
+result = client.create_many_to_many_relationship(m2m_relationship)
+print(f"Created M:N relationship: {result['relationship_schema_name']}")
+
+# Query relationship metadata
+rel = client.get_relationship("new_Department_Employee")
+if rel:
+    print(f"Found: {rel['SchemaName']}")
+
+# Delete a relationship
+client.delete_relationship(result['relationship_id'])
+```
+
+For simpler scenarios, use the extension helper:
+
+```python
+from PowerPlatform.Dataverse.extensions.relationships import create_lookup_field
+
+# Quick way to create a lookup field with sensible defaults
+result = create_lookup_field(
+    client,
+    referencing_table="contact",       # Child table gets the lookup field
+    lookup_field_name="new_AccountId",
+    referenced_table="account",        # Parent table being referenced
+    display_name="Account",
+)
+```
+
 ### File operations
 
 ```python
@@ -261,7 +328,8 @@ Explore our comprehensive examples in the [`examples/`](https://github.com/micro
 - **[Functional Testing](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/basic/functional_testing.py)** - Test core functionality in your environment
 
 **🚀 Advanced Usage:**
-- **[Complete Walkthrough](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/walkthrough.py)** - Full feature demonstration with production patterns  
+- **[Complete Walkthrough](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/walkthrough.py)** - Full feature demonstration with production patterns
+- **[Relationship Management](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/relationships.py)** - Create and manage table relationships
 - **[File Upload](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/file_upload.py)** - Upload files to Dataverse file columns
 
 📖 See the [examples README](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/README.md) for detailed guidance and learning progression.
@@ -323,8 +391,7 @@ For optimal performance in production environments:
 ### Limitations
 
 - SQL queries are **read-only** and support a limited subset of SQL syntax
-- Create Table supports a limited number of column types. Lookup columns are not yet supported.
-- Creating relationships between tables is not yet supported.
+- Create Table supports a limited number of column types (string, int, decimal, bool, datetime, picklist)
 - File uploads are limited by Dataverse file size restrictions (default 128MB per file)
 
 ## Contributing
diff --git a/examples/advanced/relationships.py b/examples/advanced/relationships.py
@@ -30,7 +30,6 @@
     AssociatedMenuConfiguration,
 )
 from PowerPlatform.Dataverse.extensions.relationships import create_lookup_field
-from PowerPlatform.Dataverse.core.errors import HttpError, MetadataError
 
 
 # Simple logging helper
@@ -95,23 +94,24 @@ def backoff(op, *, delays=(0, 2, 5, 10, 20, 20)):
             result = op()
             if attempts > 1:
                 retry_count = attempts - 1
-                print(
-                    f"   * Backoff succeeded after {retry_count} retry(s); waited {total_delay}s total."
-                )
+                print(f"   * Backoff succeeded after {retry_count} retry(s); waited {total_delay}s total.")
             return result
         except Exception as ex:  # noqa: BLE001
             last = ex
             continue
     if last:
         if attempts:
             retry_count = max(attempts - 1, 0)
-            print(
-                f"   [WARN] Backoff exhausted after {retry_count} retry(s); waited {total_delay}s total."
-            )
+            print(f"   [WARN] Backoff exhausted after {retry_count} retry(s); waited {total_delay}s total.")
         raise last
 
 
 def main():
+    # Initialize relationship IDs to None for cleanup safety
+    rel_id_1 = None
+    rel_id_2 = None
+    rel_id_3 = None
+
     print("=" * 80)
     print("Dataverse SDK - Relationship Management Example")
     print("=" * 80)
@@ -207,11 +207,7 @@ def main():
     # Define the lookup attribute metadata
     lookup = LookupAttributeMetadata(
         schema_name="new_DepartmentId",
-        display_name=Label(
-            localized_labels=[
-                LocalizedLabel(label="Department", language_code=1033)
-            ]
-        ),
+        display_name=Label(localized_labels=[LocalizedLabel(label="Department", language_code=1033)]),
         required_level="None",
     )
 
@@ -229,11 +225,7 @@ def main():
         associated_menu_configuration=AssociatedMenuConfiguration(
             behavior="UseLabel",
             group="Details",
-            label=Label(
-                localized_labels=[
-                    LocalizedLabel(label="Employees", language_code=1033)
-                ]
-            ),
+            label=Label(localized_labels=[LocalizedLabel(label="Employees", language_code=1033)]),
             order=10000,
         ),
     )
@@ -250,7 +242,7 @@ def main():
     print(f"  Lookup field: {result['lookup_schema_name']}")
     print(f"  Relationship ID: {result['relationship_id']}")
 
-    rel_id_1 = result['relationship_id']
+    rel_id_1 = result["relationship_id"]
 
     # ============================================================================
     # 5. CREATE LOOKUP FIELD (Extension Helper)
@@ -279,7 +271,7 @@ def main():
     print(f"[OK] Created lookup using helper: {result2['lookup_schema_name']}")
     print(f"  Relationship: {result2['relationship_schema_name']}")
 
-    rel_id_2 = result2['relationship_id']
+    rel_id_2 = result2["relationship_id"]
 
     # ============================================================================
     # 6. CREATE MANY-TO-MANY RELATIONSHIP
@@ -298,20 +290,12 @@ def main():
         entity1_associated_menu_configuration=AssociatedMenuConfiguration(
             behavior="UseLabel",
             group="Details",
-            label=Label(
-                localized_labels=[
-                    LocalizedLabel(label="Projects", language_code=1033)
-                ]
-            ),
+            label=Label(localized_labels=[LocalizedLabel(label="Projects", language_code=1033)]),
         ),
         entity2_associated_menu_configuration=AssociatedMenuConfiguration(
             behavior="UseLabel",
             group="Details",
-            label=Label(
-                localized_labels=[
-                    LocalizedLabel(label="Team Members", language_code=1033)
-                ]
-            ),
+            label=Label(localized_labels=[LocalizedLabel(label="Team Members", language_code=1033)]),
         ),
     )
 
@@ -324,7 +308,7 @@ def main():
     print(f"[OK] Created M:N relationship: {result3['relationship_schema_name']}")
     print(f"  Relationship ID: {result3['relationship_id']}")
 
-    rel_id_3 = result3['relationship_id']
+    rel_id_3 = result3["relationship_id"]
 
     # ============================================================================
     # 7. QUERY RELATIONSHIP METADATA
@@ -381,7 +365,7 @@ def main():
         log_call("Deleting tables")
         for table_name in ["new_Employee", "new_Department", "new_Project"]:
             try:
-                backoff(lambda: client.delete_table(table_name))
+                backoff(lambda name=table_name: client.delete_table(name))
                 print(f"  [OK] Deleted table: {table_name}")
             except Exception as e:
                 print(f"  [WARN] Error deleting {table_name}: {e}")
@@ -406,5 +390,6 @@ def main():
     except Exception as e:
         print(f"\n\nError: {e}")
         import traceback
+
         traceback.print_exc()
         sys.exit(1)
diff --git a/src/PowerPlatform/Dataverse/client.py b/src/PowerPlatform/Dataverse/client.py
@@ -725,7 +725,7 @@ def create_one_to_many_relationship(
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError: If the Web API request fails.
 
         Example:
-            Create a one-to-many relationship with full control::
+            Create a one-to-many relationship: Department (1) -> Employee (N)::
 
                 from PowerPlatform.Dataverse.models.metadata import (
                     LookupAttributeMetadata,
@@ -735,29 +735,28 @@ def create_one_to_many_relationship(
                     CascadeConfiguration,
                 )
 
-                # Define the lookup attribute
+                # Define the lookup attribute (added to Employee table)
                 lookup = LookupAttributeMetadata(
                     schema_name="new_DepartmentId",
                     display_name=Label(
                         localized_labels=[
                             LocalizedLabel(label="Department", language_code=1033)
                         ]
                     ),
-                    required_level="None"
                 )
 
                 # Define the relationship
                 relationship = OneToManyRelationshipMetadata(
                     schema_name="new_Department_Employee",
-                    referenced_entity="new_department",
-                    referencing_entity="new_employee",
+                    referenced_entity="new_department",   # Parent table (the "one" side)
+                    referencing_entity="new_employee",    # Child table (the "many" side)
                     referenced_attribute="new_departmentid",
-                    cascade_configuration=CascadeConfiguration(delete="RemoveLink")
+                    cascade_configuration=CascadeConfiguration(
+                        delete="RemoveLink",  # When department deleted, unlink employees
+                    ),
                 )
 
-                # Create the relationship
                 result = client.create_one_to_many_relationship(lookup, relationship)
-                print(f"Created relationship: {result['relationship_schema_name']}")
                 print(f"Created lookup field: {result['lookup_schema_name']}")
         """
         with self._scoped_odata() as od:
@@ -790,12 +789,13 @@ def create_many_to_many_relationship(
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError: If the Web API request fails.
 
         Example:
-            Create a many-to-many relationship::
+            Create a many-to-many relationship: Employee (N) <-> Project (N)::
 
                 from PowerPlatform.Dataverse.models.metadata import (
                     ManyToManyRelationshipMetadata,
                 )
 
+                # Employees work on multiple projects; projects have multiple team members
                 relationship = ManyToManyRelationshipMetadata(
                     schema_name="new_employee_project",
                     entity1_logical_name="new_employee",
diff --git a/src/PowerPlatform/Dataverse/data/_relationships.py b/src/PowerPlatform/Dataverse/data/_relationships.py
@@ -139,7 +139,7 @@ def _get_relationship(self, schema_name: str) -> Optional[Dict[str, Any]]:
         :raises HttpError: If the Web API request fails.
         """
         url = f"{self.api}/RelationshipDefinitions"
-        params = {"$filter": f"SchemaName eq '{schema_name}'"}
+        params = {"$filter": f"SchemaName eq '{self._escape_odata_quotes(schema_name)}'"}
         r = self._request("get", url, headers=self._headers(), params=params)
         data = r.json()
         results = data.get("value", [])
diff --git a/tests/unit/models/test_metadata.py b/tests/unit/models/test_metadata.py
@@ -3,7 +3,6 @@
 
 """Tests for metadata entity types."""
 
-import pytest
 from PowerPlatform.Dataverse.models.metadata import (
     LocalizedLabel,
     Label,
