Add SQL helper functions: sql_columns, sql_select, sql_joins, sql_join

New methods on client.query for SQL-first developers:
- sql_columns(table) -> simplified column metadata list
- sql_select(table) -> comma-separated column list for SELECT
- sql_joins(table) -> all possible JOINs with ready-to-use clauses
- sql_join(from, to) -> auto-generated JOIN clause between tables

Key finding from live testing: SQL JOINs use the raw attribute name
(e.g. parentcustomerid), NOT the _value suffix. The ReferencingAttribute
from relationship metadata matches exactly.

13 new unit tests, 745 total passing.

Author: Saurabh Badenkal

README.md

@@ -404,6 +404,20 @@ results = client.query.sql("SELECT * FROM account")
 df = client.dataframe.sql(
     "SELECT name, revenue FROM account ORDER BY revenue DESC"
 )
+
+# SQL helpers: discover columns and JOINs from metadata
+cols = client.query.sql_select("account")  # "accountid, name, revenue, ..."
+join = client.query.sql_join("contact", "account", from_alias="c", to_alias="a")
+# Returns: "JOIN account a ON c.parentcustomerid = a.accountid"
+
+# Build queries using helpers -- no OData knowledge needed
+sql = f"SELECT TOP 10 c.fullname, a.name FROM contact c {join}"
+df = client.dataframe.sql(sql)
+
+# Discover all possible JOINs from a table (including polymorphic)
+joins = client.query.sql_joins("opportunity")
+for j in joins:
+    print(f"{j['column']:30s} -> {j['target']}.{j['target_pk']}")
 ```
 
 **Raw OData queries** are available via `records.get()` for cases where you need direct control over the OData filter string:

src/PowerPlatform/Dataverse/operations/query.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-from typing import List, TYPE_CHECKING
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
 
 from ..models.record import Record
 
@@ -149,3 +149,229 @@ def sql(self, sql: str) -> List[Record]:
         with self._client._scoped_odata() as od:
             rows = od._query_sql(sql)
             return [Record.from_api_response("", row) for row in rows]
+
+    # --------------------------------------------------------------- sql_columns
+
+    def sql_columns(
+        self,
+        table: str,
+        *,
+        include_system: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """Return a simplified list of SQL-usable columns for a table.
+
+        Each dict contains ``name`` (logical name for SQL), ``type``
+        (Dataverse attribute type), ``is_pk`` (primary key flag), and
+        ``label`` (display name).  Virtual columns are always excluded
+        because the SQL endpoint cannot query them.
+
+        :param table: Schema name of the table (e.g. ``"account"``).
+        :type table: :class:`str`
+        :param include_system: When ``False`` (default), columns that end
+            with common system suffixes (``_base``, ``versionnumber``,
+            ``timezoneruleversionnumber``, ``utcconversiontimezonecode``,
+            ``importsequencenumber``, ``overriddencreatedon``) are excluded.
+        :type include_system: :class:`bool`
+
+        :return: List of column metadata dicts.
+        :rtype: list[dict[str, typing.Any]]
+
+        Example::
+
+            cols = client.query.sql_columns("account")
+            for c in cols:
+                print(f"{c['name']:30s} {c['type']:20s} PK={c['is_pk']}")
+        """
+        _SYSTEM_SUFFIXES = (
+            "_base",
+            "versionnumber",
+            "timezoneruleversionnumber",
+            "utcconversiontimezonecode",
+            "importsequencenumber",
+            "overriddencreatedon",
+        )
+
+        raw = self._client.tables.list_columns(
+            table,
+            select=["LogicalName", "SchemaName", "AttributeType", "IsPrimaryId", "IsPrimaryName", "DisplayName"],
+            filter="AttributeType ne 'Virtual'",
+        )
+        result: List[Dict[str, Any]] = []
+        for c in raw:
+            name = c.get("LogicalName", "")
+            if not name:
+                continue
+            if not include_system and any(name.endswith(s) for s in _SYSTEM_SUFFIXES):
+                continue
+            # Extract display label
+            label = ""
+            dn = c.get("DisplayName")
+            if isinstance(dn, dict):
+                ul = dn.get("UserLocalizedLabel")
+                if isinstance(ul, dict):
+                    label = ul.get("Label", "")
+            result.append(
+                {
+                    "name": name,
+                    "type": c.get("AttributeType", ""),
+                    "is_pk": bool(c.get("IsPrimaryId")),
+                    "is_name": bool(c.get("IsPrimaryName")),
+                    "label": label,
+                }
+            )
+        result.sort(key=lambda x: (not x["is_pk"], not x["is_name"], x["name"]))
+        return result
+
+    # --------------------------------------------------------------- sql_select
+
+    def sql_select(
+        self,
+        table: str,
+        *,
+        include_system: bool = False,
+    ) -> str:
+        """Return a comma-separated column list for use in SQL SELECT.
+
+        Excludes virtual columns and optionally system columns. The result
+        can be embedded directly in a SQL query string.
+
+        :param table: Schema name of the table (e.g. ``"account"``).
+        :type table: :class:`str`
+        :param include_system: Include system columns (default ``False``).
+        :type include_system: :class:`bool`
+
+        :return: Comma-separated column names.
+        :rtype: :class:`str`
+
+        Example::
+
+            cols = client.query.sql_select("account")
+            sql = f"SELECT TOP 10 {cols} FROM account"
+            df = client.dataframe.sql(sql)
+        """
+        columns = self.sql_columns(table, include_system=include_system)
+        return ", ".join(c["name"] for c in columns)
+
+    # --------------------------------------------------------------- sql_joins
+
+    def sql_joins(
+        self,
+        table: str,
+    ) -> List[Dict[str, Any]]:
+        """Discover all possible SQL JOINs from a table.
+
+        Returns one entry per outgoing lookup relationship, with the
+        exact column names needed for SQL ``JOIN ... ON`` clauses.
+
+        For **polymorphic** lookups (e.g. ``customerid`` targeting both
+        ``account`` and ``contact``), multiple entries are returned with
+        the same ``column`` but different ``target`` values.
+
+        :param table: Schema name of the table (e.g. ``"contact"``).
+        :type table: :class:`str`
+
+        :return: List of JOIN metadata dicts, each containing:
+
+            - ``column`` -- the lookup attribute on this table (use in ON clause)
+            - ``target`` -- the referenced entity name
+            - ``target_pk`` -- the referenced entity's primary key column
+            - ``relationship`` -- the schema name of the relationship
+            - ``join_clause`` -- a ready-to-use ``JOIN ... ON ...`` fragment
+
+        :rtype: list[dict[str, typing.Any]]
+
+        Example::
+
+            joins = client.query.sql_joins("contact")
+            for j in joins:
+                print(f"{j['column']:30s} -> {j['target']}.{j['target_pk']}")
+                print(f"  {j['join_clause']}")
+
+            # Use in a query
+            j = next(j for j in joins if j['target'] == 'account')
+            sql = f"SELECT TOP 10 c.fullname, a.name FROM contact c {j['join_clause']}"
+        """
+        table_lower = table.lower()
+        rels = self._client.tables.list_table_relationships(table)
+
+        result: List[Dict[str, Any]] = []
+        for r in rels:
+            ref_entity = (r.get("ReferencingEntity") or "").lower()
+            if ref_entity != table_lower:
+                continue
+            col = r.get("ReferencingAttribute", "")
+            target = r.get("ReferencedEntity", "")
+            target_pk = r.get("ReferencedAttribute", "")
+            schema = r.get("SchemaName", "")
+            if not all([col, target, target_pk]):
+                continue
+
+            # Generate a short alias for the target table
+            alias = target[0] if target else "j"
+            join_clause = f"JOIN {target} {alias} " f"ON {table_lower}.{col} = {alias}.{target_pk}"
+
+            result.append(
+                {
+                    "column": col,
+                    "target": target,
+                    "target_pk": target_pk,
+                    "relationship": schema,
+                    "join_clause": join_clause,
+                }
+            )
+
+        result.sort(key=lambda x: (x["target"], x["column"]))
+        return result
+
+    # --------------------------------------------------------------- sql_join
+
+    def sql_join(
+        self,
+        from_table: str,
+        to_table: str,
+        *,
+        from_alias: Optional[str] = None,
+        to_alias: Optional[str] = None,
+    ) -> str:
+        """Generate a SQL JOIN clause between two tables.
+
+        Discovers the relationship automatically via metadata. If multiple
+        relationships exist (e.g. polymorphic lookups), picks the first
+        match. Use :meth:`sql_joins` to see all options.
+
+        :param from_table: Schema name of the FROM table (e.g. ``"contact"``).
+        :type from_table: :class:`str`
+        :param to_table: Schema name of the target table (e.g. ``"account"``).
+        :type to_table: :class:`str`
+        :param from_alias: Optional alias for the FROM table in the JOIN
+            clause. If ``None``, uses the full table name.
+        :type from_alias: :class:`str` or None
+        :param to_alias: Optional alias for the target table. If ``None``,
+            uses the first letter of the target table name.
+        :type to_alias: :class:`str` or None
+
+        :return: A ready-to-use ``JOIN ... ON ...`` clause.
+        :rtype: :class:`str`
+
+        :raises ValueError: If no relationship is found between the tables.
+
+        Example::
+
+            j = client.query.sql_join("contact", "account", from_alias="c", to_alias="a")
+            # Returns: "JOIN account a ON c.parentcustomerid = a.accountid"
+            sql = f"SELECT TOP 10 c.fullname, a.name FROM contact c {j}"
+            df = client.dataframe.sql(sql)
+        """
+        to_lower = to_table.lower()
+        joins = self.sql_joins(from_table)
+        match = [j for j in joins if j["target"].lower() == to_lower]
+        if not match:
+            raise ValueError(
+                f"No relationship found from '{from_table}' to '{to_table}'. "
+                f"Use client.query.sql_joins('{from_table}') to see available targets."
+            )
+
+        j = match[0]
+        src = from_alias or from_table.lower()
+        tgt = to_alias or to_lower[0]
+        return f"JOIN {to_lower} {tgt} " f"ON {src}.{j['column']} = {tgt}.{j['target_pk']}"