Update SDK usage SKILL with namespaced API and relationship examples

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

Author: tpellissier

.claude/skills/dataverse-sdk-use/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dataverse-sdk-use
-description: Guidance for using the PowerPlatform Dataverse Client Python SDK. Use when calling the SDK like creating CRUD operations, SQL queries, table metadata management, and upload files.
+description: Guidance for using the PowerPlatform Dataverse Client Python SDK. Use when calling the SDK like creating CRUD operations, SQL queries, table metadata management, relationships, and upload files.
 ---
 
 # PowerPlatform Dataverse SDK Guide
@@ -17,6 +17,11 @@ Use the PowerPlatform Dataverse Client Python SDK to interact with Microsoft Dat
 - Custom columns: include customization prefix (e.g., `"new_Price"`, `"cr123_Status"`)
 - ALWAYS use **schema names** (logical names), NOT display names
 
+### Operation Namespaces
+- `client.records` -- CRUD and OData queries
+- `client.query` -- query and search operations
+- `client.tables` -- table metadata, columns, and relationships
+
 ### Bulk Operations
 The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `update()` for automatic bulk processing, for `delete()`, set `use_bulk_delete` when passing lists to use bulk operation
 
@@ -29,7 +34,7 @@ The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `
 ### Import
 ```python
 from azure.identity import (
-    InteractiveBrowserCredential, 
+    InteractiveBrowserCredential,
     ClientSecretCredential,
     CertificateCredential,
     AzureCliCredential
@@ -56,41 +61,38 @@ client = DataverseClient("https://yourorg.crm.dynamics.com", credential)
 #### Create Records
 ```python
 # Single record
-account_ids = client.create("account", {"name": "Contoso Ltd", "telephone1": "555-0100"})
-account_id = account_ids[0]
+account_id = client.records.create("account", {"name": "Contoso Ltd", "telephone1": "555-0100"})
 
 # Bulk create (uses CreateMultiple API automatically)
 contacts = [
     {"firstname": "John", "lastname": "Doe"},
     {"firstname": "Jane", "lastname": "Smith"}
 ]
-contact_ids = client.create("contact", contacts)
+contact_ids = client.records.create("contact", contacts)
 ```
 
 #### Read Records
 ```python
 # Get single record by ID
-account = client.get("account", account_id, select=["name", "telephone1"])
+account = client.records.get("account", account_id, select=["name", "telephone1"])
 
-# Query with filter
-pages = client.get(
+# Query with filter (paginated)
+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)
-    top=100
-)
-for page in pages:
+    top=100,
+):
     for record in page:
         print(record["name"])
 
 # Query with navigation property expansion (case-sensitive!)
-pages = client.get(
+for page in client.records.get(
     "account",
     select=["name"],
     expand=["primarycontactid"],  # Navigation properties are case-sensitive!
-    filter="statecode eq 0"       # Column names must be lowercase logical names
-)
-for page in pages:
+    filter="statecode eq 0",      # Column names must be lowercase logical names
+):
     for account in page:
         contact = account.get("primarycontactid", {})
         print(f"{account['name']} - {contact.get('fullname', 'N/A')}")
@@ -99,28 +101,27 @@ for page in pages:
 #### Update Records
 ```python
 # Single update
-client.update("account", account_id, {"telephone1": "555-0200"})
+client.records.update("account", account_id, {"telephone1": "555-0200"})
 
 # Bulk update (broadcast same change to multiple records)
-client.update("account", [id1, id2, id3], {"industry": "Technology"})
+client.records.update("account", [id1, id2, id3], {"industry": "Technology"})
 ```
 
 #### Delete Records
 ```python
 # Single delete
-client.delete("account", account_id)
+client.records.delete("account", account_id)
 
 # Bulk delete (uses BulkDelete API)
-client.delete("account", [id1, id2, id3], use_bulk_delete=True)
+client.records.delete("account", [id1, id2, id3], use_bulk_delete=True)
 ```
 
 ### SQL Queries
 
 SQL queries are **read-only** and support limited SQL syntax. A single SELECT statement with optional WHERE, TOP (integer literal), ORDER BY (column names only), and a simple table alias after FROM is supported. But JOIN and subqueries may not be. Refer to the Dataverse documentation for the current feature set.
 
 ```python
-# Basic SQL query
-results = client.query_sql(
+results = client.query.sql(
     "SELECT TOP 10 accountid, name FROM account WHERE statecode = 0"
 )
 for record in results:
@@ -132,22 +133,22 @@ for record in results:
 #### Create Custom Tables
 ```python
 # Create table with columns (include customization prefix!)
-table_info = client.create_table(
-    table_schema_name="new_Product",
-    columns={
+table_info = client.tables.create(
+    "new_Product",
+    {
         "new_Code": "string",
         "new_Price": "decimal",
         "new_Active": "bool",
-        "new_Quantity": "int"
-    }
+        "new_Quantity": "int",
+    },
 )
 
 # With solution assignment and custom primary column
-table_info = client.create_table(
-    table_schema_name="new_Product",
-    columns={"new_Code": "string", "new_Price": "decimal"},
-    solution_unique_name="MyPublisher",
-    primary_column_schema_name="new_ProductCode"
+table_info = client.tables.create(
+    "new_Product",
+    {"new_Code": "string", "new_Price": "decimal"},
+    solution="MyPublisher",
+    primary_column="new_ProductCode",
 )
 ```
 
@@ -165,32 +166,101 @@ Types on the same line map to the same exact format under the hood
 #### Manage Columns
 ```python
 # Add columns to existing table (must include customization prefix!)
-client.create_columns("new_Product", {
+client.tables.add_columns("new_Product", {
     "new_Category": "string",
-    "new_InStock": "bool"
+    "new_InStock": "bool",
 })
 
 # Remove columns
-client.delete_columns("new_Product", ["new_Category"])
+client.tables.remove_columns("new_Product", ["new_Category"])
 ```
 
 #### Inspect Tables
 ```python
 # Get single table information
-table_info = client.get_table_info("new_Product")
+table_info = client.tables.get("new_Product")
 print(f"Logical name: {table_info['table_logical_name']}")
 print(f"Entity set: {table_info['entity_set_name']}")
 
 # List all tables
-tables = client.list_tables()
+tables = client.tables.list()
 for table in tables:
     print(table)
 ```
 
 #### Delete Tables
 ```python
-# Delete custom table
-client.delete_table("new_Product")
+client.tables.delete("new_Product")
+```
+
+### Relationship Management
+
+#### Create One-to-Many Relationship
+```python
+from PowerPlatform.Dataverse.models.metadata import (
+    LookupAttributeMetadata,
+    OneToManyRelationshipMetadata,
+    Label,
+    LocalizedLabel,
+    CascadeConfiguration,
+)
+from PowerPlatform.Dataverse.common.constants import CASCADE_BEHAVIOR_REMOVE_LINK
+
+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",
+    referencing_entity="new_employee",
+    referenced_attribute="new_departmentid",
+    cascade_configuration=CascadeConfiguration(
+        delete=CASCADE_BEHAVIOR_REMOVE_LINK,
+    ),
+)
+
+result = client.tables.create_one_to_many_relationship(lookup, relationship)
+print(f"Created lookup field: {result['lookup_schema_name']}")
+```
+
+#### Create Many-to-Many Relationship
+```python
+from PowerPlatform.Dataverse.models.metadata import ManyToManyRelationshipMetadata
+
+relationship = ManyToManyRelationshipMetadata(
+    schema_name="new_employee_project",
+    entity1_logical_name="new_employee",
+    entity2_logical_name="new_project",
+)
+
+result = client.tables.create_many_to_many_relationship(relationship)
+print(f"Created: {result['relationship_schema_name']}")
+```
+
+#### Convenience Method for Lookup Fields
+```python
+result = client.tables.create_lookup_field(
+    referencing_table="new_order",
+    lookup_field_name="new_AccountId",
+    referenced_table="account",
+    display_name="Account",
+    required=True,
+)
+```
+
+#### Query and Delete Relationships
+```python
+# Get relationship metadata
+rel = client.tables.get_relationship("new_Department_Employee")
+if rel:
+    print(f"Found: {rel['SchemaName']}")
+
+# Delete relationship
+client.tables.delete_relationship(result["relationship_id"])
 ```
 
 ### File Operations
@@ -220,7 +290,7 @@ from PowerPlatform.Dataverse.core.errors import (
 from PowerPlatform.Dataverse.client import DataverseClient
 
 try:
-    client.get("account", "invalid-id")
+    client.records.get("account", "invalid-id")
 except HttpError as e:
     print(f"HTTP {e.status_code}: {e.message}")
     print(f"Error code: {e.code}")
@@ -262,6 +332,7 @@ except ValidationError as e:
 7. **Always include customization prefix** for custom tables/columns
 8. **Use lowercase** - Generally using lowercase input won't go wrong, except for custom table/column naming
 9. **Test in non-production environments** first
+10. **Use named constants** - Import cascade behavior constants from `PowerPlatform.Dataverse.common.constants`
 
 ## Additional Resources