Refactor SQL query handling and error management in Dataverse SDK

- Updated SQL query examples to use correct field names for ownerid and related entities.
- Removed unsupported SQL validation error code.
- Enhanced parameter handling for OneToMany and ManyToMany relationships.
- Improved test coverage for metadata error handling in entity set resolution.
- Fix integration tests

Author: Samson Gebre

examples/advanced/relationships.py

@@ -42,7 +42,7 @@ def delete_relationship_if_exists(client, schema_name):
     """Delete a relationship by schema name if it exists."""
     rel = client.tables.get_relationship(schema_name)
     if rel:
-        rel_id = rel.get("MetadataId")
+        rel_id = rel.relationship_id
         if rel_id:
             client.tables.delete_relationship(rel_id)
             print(f"   (Cleaned up existing relationship: {schema_name})")
@@ -236,11 +236,11 @@ def _run_example(client):
         )
     )
 
-    print(f"[OK] Created relationship: {result['relationship_schema_name']}")
-    print(f"  Lookup field: {result['lookup_schema_name']}")
-    print(f"  Relationship ID: {result['relationship_id']}")
+    print(f"[OK] Created relationship: {result.relationship_schema_name}")
+    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 (Convenience Method)
@@ -265,10 +265,10 @@ def _run_example(client):
         )
     )
 
-    print(f"[OK] Created lookup using convenience method: {result2['lookup_schema_name']}")
-    print(f"  Relationship: {result2['relationship_schema_name']}")
+    print(f"[OK] Created lookup using convenience method: {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
@@ -292,10 +292,10 @@ def _run_example(client):
         )
     )
 
-    print(f"[OK] Created M:N relationship: {result3['relationship_schema_name']}")
-    print(f"  Relationship ID: {result3['relationship_id']}")
+    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
@@ -308,21 +308,21 @@ def _run_example(client):
 
     rel_metadata = client.tables.get_relationship("new_Department_Employee")
     if rel_metadata:
-        print(f"[OK] Found relationship: {rel_metadata.get('SchemaName')}")
-        print(f"  Type: {rel_metadata.get('@odata.type')}")
-        print(f"  Referenced Entity: {rel_metadata.get('ReferencedEntity')}")
-        print(f"  Referencing Entity: {rel_metadata.get('ReferencingEntity')}")
+        print(f"[OK] Found relationship: {rel_metadata.relationship_schema_name}")
+        print(f"  Type: {rel_metadata.relationship_type}")
+        print(f"  Referenced Entity: {rel_metadata.referenced_entity}")
+        print(f"  Referencing Entity: {rel_metadata.referencing_entity}")
     else:
         print("  Relationship not found")
 
     log_call("Retrieving M:N relationship by schema name")
 
     m2m_metadata = client.tables.get_relationship("new_employee_project")
     if m2m_metadata:
-        print(f"[OK] Found relationship: {m2m_metadata.get('SchemaName')}")
-        print(f"  Type: {m2m_metadata.get('@odata.type')}")
-        print(f"  Entity 1: {m2m_metadata.get('Entity1LogicalName')}")
-        print(f"  Entity 2: {m2m_metadata.get('Entity2LogicalName')}")
+        print(f"[OK] Found relationship: {m2m_metadata.relationship_schema_name}")
+        print(f"  Type: {m2m_metadata.relationship_type}")
+        print(f"  Entity 1: {m2m_metadata.entity1_logical_name}")
+        print(f"  Entity 2: {m2m_metadata.entity2_logical_name}")
     else:
         print("  Relationship not found")
 

examples/advanced/sql_examples.py

@@ -612,7 +612,7 @@ def _run_examples(client):
             lookup_names = sorted(
                 c.get("LogicalName", "")
                 for c in acct_cols
-                if c.get("LogicalName", "").startswith("_") and c.get("LogicalName", "").endswith("_value")
+                if c.get("LogicalName", "")
             )
             print(f"[OK] Lookup columns on account ({len(lookup_names)} found):")
             for ln in lookup_names[:10]:
@@ -626,12 +626,7 @@ def _run_examples(client):
         print("\n-- 23b. Discover which entities a polymorphic lookup targets --")
         log_call("client.tables.list_table_relationships('account', ...)")
         try:
-            acct_rels = backoff(
-                lambda: client.tables.list_table_relationships(
-                    "account",
-                    select=["SchemaName", "ReferencedEntity", "ReferencingEntity", "ReferencingAttribute"],
-                )
-            )
+            acct_rels = backoff(lambda: client.tables.list_table_relationships("account"))
             by_attr = defaultdict(list)
             for rel in acct_rels:
                 attr = rel.get("ReferencingAttribute", "")
@@ -650,23 +645,23 @@ def _run_examples(client):
         print("ownerid is polymorphic (systemuser or team). Use separate\n" "JOINs and combine in a DataFrame.")
         try:
             # Records owned by users
-            log_call("SQL: account JOIN systemuser ON _ownerid_value")
+            log_call("SQL: account JOIN systemuser ON ownerid")
             df_user_owned = backoff(
                 lambda: client.dataframe.sql(
                     "SELECT TOP 5 a.name, su.fullname as owner_name "
                     "FROM account a "
-                    "INNER JOIN systemuser su ON a._ownerid_value = su.systemuserid"
+                    "INNER JOIN systemuser su ON a.ownerid = su.systemuserid"
                 )
             )
             df_user_owned["owner_type"] = "User"
 
             # Records owned by teams
-            log_call("SQL: account JOIN team ON _ownerid_value")
+            log_call("SQL: account JOIN team ON ownerid")
             df_team_owned = backoff(
                 lambda: client.dataframe.sql(
                     "SELECT TOP 5 a.name, t.name as owner_name "
                     "FROM account a "
-                    "INNER JOIN team t ON a._ownerid_value = t.teamid"
+                    "INNER JOIN team t ON a.ownerid = t.teamid"
                 )
             )
             df_team_owned["owner_type"] = "Team"
@@ -690,8 +685,8 @@ def _run_examples(client):
                     "creator.fullname as created_by, "
                     "modifier.fullname as modified_by "
                     "FROM account a "
-                    "JOIN systemuser creator ON a._createdby_value = creator.systemuserid "
-                    "JOIN systemuser modifier ON a._modifiedby_value = modifier.systemuserid"
+                    "JOIN systemuser creator ON a.createdby = creator.systemuserid "
+                    "JOIN systemuser modifier ON a.modifiedby = modifier.systemuserid"
                 )
             )
             print(f"[OK] Audit trail: {len(results)} rows")

src/PowerPlatform/Dataverse/core/_error_codes.py

@@ -44,7 +44,6 @@
 VALIDATION_SQL_NOT_STRING = "validation_sql_not_string"
 VALIDATION_SQL_EMPTY = "validation_sql_empty"
 VALIDATION_SQL_WRITE_BLOCKED = "validation_sql_write_blocked"
-VALIDATION_SQL_CROSS_JOIN_BLOCKED = "validation_sql_cross_join_blocked"
 VALIDATION_SQL_UNSUPPORTED_SYNTAX = "validation_sql_unsupported_syntax"
 VALIDATION_ENUM_NO_MEMBERS = "validation_enum_no_members"
 VALIDATION_ENUM_NON_INT_VALUE = "validation_enum_non_int_value"

src/PowerPlatform/Dataverse/data/_odata.py

@@ -976,20 +976,9 @@ def _query_sql(self, sql: str) -> list[dict[str, Any]]:
             raise ValidationError("sql must be a non-empty string", subcode=VALIDATION_SQL_EMPTY)
         sql = sql.strip()
 
-        # Block write statements FIRST (before table extraction, since
-        # UPDATE/INSERT/DELETE don't have FROM clauses).
-        # Strip SQL comments to catch e.g. /**/DELETE or --\\nDELETE.
-        sql_no_comments = self._SQL_COMMENT_RE.sub(" ", sql).strip()
-        if self._SQL_WRITE_RE.search(sql_no_comments):
-            raise ValidationError(
-                "SQL endpoint is read-only. Use client.records or "
-                "client.dataframe for write operations "
-                "(INSERT/UPDATE/DELETE are not supported).",
-                subcode=VALIDATION_SQL_WRITE_BLOCKED,
-            )
-
-        # Apply safety guardrails (block unsupported syntax, warn on risky patterns).
-        # SELECT * raises ValidationError here before any table resolution.
+        # Apply safety guardrails (block unsupported syntax including writes,
+        # warn on risky patterns). SELECT * raises ValidationError here before
+        # any table resolution.
         sql = self._sql_guardrails(sql)
 
         r = self._execute_raw(self._build_sql(sql))

src/PowerPlatform/Dataverse/data/_relationships.py

@@ -218,19 +218,28 @@ def _list_table_relationships(
             )
 
         metadata_id = ent["MetadataId"]
-        params: Dict[str, str] = {}
+        # OneToMany/ManyToOne share the same property surface (ReferencedEntity,
+        # ReferencingEntity, etc.).  ManyToManyRelationshipMetadata has a
+        # different schema -- it only exposes SchemaName plus Entity1/Entity2
+        # fields, not ReferencedEntity or ReferencingEntity.  Sending a $select
+        # that includes those properties to the ManyToMany endpoint causes a
+        # 400: "Could not find a property named 'ReferencedEntity' on type
+        # 'ManyToManyRelationshipMetadata'".  Use separate param dicts.
+        one_to_many_params: Dict[str, str] = {}
+        many_to_many_params: Dict[str, str] = {}
         if filter:
-            params["$filter"] = filter
+            one_to_many_params["$filter"] = filter
+            many_to_many_params["$filter"] = filter
         if select:
-            params["$select"] = ",".join(select)
+            one_to_many_params["$select"] = ",".join(select)
 
         one_to_many_url = f"{self.api}/EntityDefinitions({metadata_id})/OneToManyRelationships"
         many_to_one_url = f"{self.api}/EntityDefinitions({metadata_id})/ManyToOneRelationships"
         many_to_many_url = f"{self.api}/EntityDefinitions({metadata_id})/ManyToManyRelationships"
 
-        r1 = self._request("get", one_to_many_url, headers=self._headers(), params=params)
-        r2 = self._request("get", many_to_one_url, headers=self._headers(), params=params)
-        r3 = self._request("get", many_to_many_url, headers=self._headers(), params=params)
+        r1 = self._request("get", one_to_many_url, headers=self._headers(), params=one_to_many_params)
+        r2 = self._request("get", many_to_one_url, headers=self._headers(), params=one_to_many_params)
+        r3 = self._request("get", many_to_many_url, headers=self._headers(), params=many_to_many_params)
 
         return r1.json().get("value", []) + r2.json().get("value", []) + r3.json().get("value", [])
 

src/PowerPlatform/Dataverse/operations/query.py

@@ -7,8 +7,8 @@
 
 from typing import Any, Dict, List, Optional, TYPE_CHECKING
 
+from ..core.errors import MetadataError
 from ..models.record import Record
-
 from ..models.query_builder import QueryBuilder
 
 if TYPE_CHECKING:
@@ -484,7 +484,7 @@ def odata_expands(
             try:
                 with self._client._scoped_odata() as od:
                     target_set = od._entity_set_from_schema_name(target)
-            except (KeyError, AttributeError, ValueError):
+            except (KeyError, AttributeError, ValueError, MetadataError):
                 pass  # Entity set resolution failed; target_set stays empty
 
             result.append(

tests/unit/data/test_relationships.py

@@ -478,20 +478,30 @@ def test_filter_param_is_forwarded(self):
             params = call[1].get("params", {})
             self.assertEqual(params["$filter"], "IsManaged eq false")
 
-    def test_select_param_is_forwarded(self):
-        """Test that $select is sent to all three sub-requests."""
+    def test_select_param_forwarded_to_one_to_many_only(self):
+        """$select is sent to OneToMany and ManyToOne but NOT ManyToMany.
+
+        ManyToManyRelationshipMetadata has a different property surface --
+        it does not expose ReferencedEntity or ReferencingEntity.  Sending a
+        $select with those names to the ManyToMany endpoint causes a 400 from
+        the server.
+        """
         self.client._mock_request.side_effect = [
             self._make_response([]),
             self._make_response([]),
             self._make_response([]),
         ]
 
-        self.client._list_table_relationships("account", select=["SchemaName", "MetadataId"])
+        self.client._list_table_relationships("account", select=["SchemaName", "ReferencedEntity"])
 
         calls = self.client._mock_request.call_args_list
-        for call in calls:
-            params = call[1].get("params", {})
-            self.assertEqual(params["$select"], "SchemaName,MetadataId")
+        self.assertEqual(len(calls), 3)
+        one_to_many_params = calls[0][1].get("params", {})
+        many_to_one_params = calls[1][1].get("params", {})
+        many_to_many_params = calls[2][1].get("params", {})
+        self.assertEqual(one_to_many_params["$select"], "SchemaName,ReferencedEntity")
+        self.assertEqual(many_to_one_params["$select"], "SchemaName,ReferencedEntity")
+        self.assertNotIn("$select", many_to_many_params)
 
     def test_raises_metadata_error_when_table_not_found(self):
         """Test that MetadataError is raised when entity is not found."""

tests/unit/test_query_operations.py

@@ -7,6 +7,7 @@
 from azure.core.credentials import TokenCredential
 
 from PowerPlatform.Dataverse.client import DataverseClient
+from PowerPlatform.Dataverse.core.errors import MetadataError
 from PowerPlatform.Dataverse.models.record import Record
 from PowerPlatform.Dataverse.operations.query import QueryOperations
 
@@ -837,6 +838,28 @@ def test_polymorphic_returns_multiple(self):
         nav_props = {e["nav_property"] for e in expands}
         self.assertEqual(nav_props, {"customerid_account", "customerid_contact"})
 
+    def test_metadata_error_on_entity_set_resolution_is_swallowed(self):
+        """MetadataError from entity-set resolution must not propagate -- target_entity_set stays empty."""
+        self._mock_rels(
+            [
+                {
+                    "ReferencingEntity": "contact",
+                    "ReferencingAttribute": "parentcustomerid",
+                    "ReferencedEntity": "account",
+                    "ReferencedAttribute": "accountid",
+                    "ReferencingEntityNavigationPropertyName": "parentcustomerid_account",
+                    "SchemaName": "contact_customer_accounts",
+                },
+            ]
+        )
+        self.client._odata._entity_set_from_schema_name.side_effect = MetadataError(
+            "Unable to resolve entity set for 'account'.",
+            subcode="metadata_entityset_not_found",
+        )
+        expands = self.client.query.odata_expands("contact")
+        self.assertEqual(len(expands), 1)
+        self.assertEqual(expands[0]["target_entity_set"], "")
+
 
 class TestOdataExpand(unittest.TestCase):
     """Tests for client.query.odata_expand()."""