semantic-link-labs 0.10.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

sempy_labs/tom/_model.py

@@ -2,8 +2,10 @@ import sempy
 import sempy.fabric as fabric
 import pandas as pd
 import re
+import os
 import json
 from datetime import datetime
+from decimal import Decimal
 from sempy_labs._helper_functions import (
     format_dax_object_name,
     generate_guid,
@@ -14,17 +16,19 @@ from sempy_labs._helper_functions import (
     resolve_workspace_id,
     resolve_item_id,
     resolve_lakehouse_id,
+    _validate_weight,
 )
 from sempy_labs._list_functions import list_relationships
 from sempy_labs._refresh_semantic_model import refresh_semantic_model
 from sempy_labs.directlake._dl_helper import check_fallback_reason
 from contextlib import contextmanager
-from typing import List, Iterator, Optional, Union, TYPE_CHECKING
+from typing import List, Iterator, Optional, Union, TYPE_CHECKING, Literal
 from sempy._utils._log import log
 import sempy_labs._icons as icons
 import ast
 from uuid import UUID
 import sempy_labs._authentication as auth
+from sempy_labs.lakehouse._lakehouse import lakehouse_attached
 
 
 if TYPE_CHECKING:
@@ -784,7 +788,11 @@ class TOMWrapper:
             self.model.Roles[role_name].TablePermissions.Add(tp)
 
     def set_ols(
-        self, role_name: str, table_name: str, column_name: str, permission: str
+        self,
+        role_name: str,
+        table_name: str,
+        column_name: Optional[str] = None,
+        permission: Literal["Default", "None", "Read"] = "Default",
     ):
         """
         Sets the object level security permissions for a column within a role.
@@ -795,9 +803,9 @@ class TOMWrapper:
             Name of the role.
         table_name : str
             Name of the table.
-        column_name : str
-            Name of the column.
-        permission : str
+        column_name : str, default=None
+            Name of the column. Defaults to None which sets object level security for the entire table.
+        permission : Literal["Default", "None", "Read"], default="Default"
             The object level security permission for the column.
             `Permission valid values <https://learn.microsoft.com/dotnet/api/microsoft.analysisservices.tabular.metadatapermission?view=analysisservices-dotnet>`_
         """
@@ -817,19 +825,29 @@ class TOMWrapper:
             tp.Table = self.model.Tables[table_name]
             r.TablePermissions.Add(tp)
         columns = [c.Name for c in r.TablePermissions[table_name].ColumnPermissions]
-        # Add column permission if it does not exist
-        if column_name not in columns:
-            cp = TOM.ColumnPermission()
-            cp.Column = self.model.Tables[table_name].Columns[column_name]
-            cp.MetadataPermission = System.Enum.Parse(
+
+        # Set column level security if column is specified
+        if column_name:
+            # Add column permission if it does not exist
+            if column_name not in columns:
+                cp = TOM.ColumnPermission()
+                cp.Column = self.model.Tables[table_name].Columns[column_name]
+                cp.MetadataPermission = System.Enum.Parse(
+                    TOM.MetadataPermission, permission
+                )
+                r.TablePermissions[table_name].ColumnPermissions.Add(cp)
+            # Set column permission if it already exists
+            else:
+                r.TablePermissions[table_name].ColumnPermissions[
+                    column_name
+                ].MetadataPermission = System.Enum.Parse(
+                    TOM.MetadataPermission, permission
+                )
+        # Set table level security if column is not specified
+        else:
+            r.TablePermissions[table_name].MetadataPermission = System.Enum.Parse(
                 TOM.MetadataPermission, permission
             )
-            r.TablePermissions[table_name].ColumnPermissions.Add(cp)
-        # Set column permission if it already exists
-        else:
-            r.TablePermissions[table_name].ColumnPermissions[
-                column_name
-            ].MetadataPermission = System.Enum.Parse(TOM.MetadataPermission, permission)
 
     def add_hierarchy(
         self,
@@ -911,11 +929,15 @@ class TOMWrapper:
         from_column: str,
         to_table: str,
         to_column: str,
-        from_cardinality: str,
-        to_cardinality: str,
-        cross_filtering_behavior: Optional[str] = None,
+        from_cardinality: Literal["Many", "One", "None"],
+        to_cardinality: Literal["Many", "One", "None"],
+        cross_filtering_behavior: Literal[
+            "Automatic", "OneDirection", "BothDirections"
+        ] = "Automatic",
         is_active: bool = True,
-        security_filtering_behavior: Optional[str] = None,
+        security_filtering_behavior: Optional[
+            Literal["None", "OneDirection", "BothDirections"]
+        ] = None,
         rely_on_referential_integrity: bool = False,
     ):
         """
@@ -931,29 +953,22 @@ class TOMWrapper:
             Name of the table on the 'to' side of the relationship.
         to_column : str
             Name of the column on the 'to' side of the relationship.
-        from_cardinality : str
-            The cardinality of the 'from' side of the relationship. Options: ['Many', 'One', 'None'].
-        to_cardinality : str
-                The cardinality of the 'to' side of the relationship. Options: ['Many', 'One', 'None'].
-        cross_filtering_behavior : str, default=None
+        from_cardinality : Literal["Many", "One", "None"]
+            The cardinality of the 'from' side of the relationship.
+        to_cardinality : Literal["Many", "One", "None"]
+                The cardinality of the 'to' side of the relationship.
+        cross_filtering_behavior : Literal["Automatic", "OneDirection", "BothDirections"], default="Automatic"
             Setting for the cross filtering behavior of the relationship. Options: ('Automatic', 'OneDirection', 'BothDirections').
-            Defaults to None which resolves to 'Automatic'.
         is_active : bool, default=True
             Setting for whether the relationship is active or not.
-        security_filtering_behavior : str, default=None
-            Setting for the security filtering behavior of the relationship. Options: ('None', 'OneDirection', 'BothDirections').
-            Defaults to None which resolves to 'OneDirection'.
+        security_filtering_behavior : Literal["None, "OneDirection", "BothDirections"], default="OneDirection"
+            Setting for the security filtering behavior of the relationship.
         rely_on_referential_integrity : bool, default=False
             Setting for the rely on referential integrity of the relationship.
         """
         import Microsoft.AnalysisServices.Tabular as TOM
         import System
 
-        if not cross_filtering_behavior:
-            cross_filtering_behavior = "Automatic"
-        if not security_filtering_behavior:
-            security_filtering_behavior = "OneDirection"
-
         for var_name in [
             "from_cardinality",
             "to_cardinality",
@@ -4822,6 +4837,47 @@ class TOMWrapper:
 
         return bim
 
+    def clear_linguistic_schema(self, culture: str):
+        """
+        Clears the linguistic schema for a given culture.
+
+        Parameters
+        ----------
+        culture : str
+            The culture name.
+        """
+
+        empty_schema = f'{{"Version":"1.0.0","Language":"{culture}"}}'
+
+        self.model.Cultures[culture].LinguisticMetadata.Content = json.dumps(
+            empty_schema, indent=4
+        )
+
+    def get_linguistic_schema(self, culture: str) -> dict:
+        """
+        Obtains the linguistic schema for a given culture.
+
+        Parameters
+        ----------
+        culture : str
+            The culture name.
+
+        Returns
+        -------
+        dict
+            The .bim file.
+        """
+
+        import Microsoft.AnalysisServices.Tabular as TOM
+
+        bim = (
+            json.loads(TOM.JsonScripter.ScriptCreate(self.model.Database))
+            .get("create")
+            .get("database")
+        )
+
+        return bim
+
     def _reduce_model(self, perspective_name: str):
         """
         Reduces a model's objects based on a perspective. Adds the dependent objects within a perspective to that perspective.
@@ -5261,6 +5317,425 @@ class TOMWrapper:
                 f"{icons.red_dot} The '{str(object.ObjectType)}' object type is not supported for DAX formatting."
             )
 
+    def get_linguistic_schema(self, culture: str) -> dict:
+        """
+        Obtains the linguistic schema for a given culture.
+        Parameters
+        ----------
+        culture : str
+            The culture name.
+        Returns
+        -------
+        dict
+            The linguistic schema for the given culture.
+        """
+
+        c = self.model.Cultures[culture]
+        if c.LinguisticMetadata is not None:
+            return json.loads(c.LinguisticMetadata.Content)
+        else:
+            print(
+                f"{icons.info} The '{culture}' culture does not have a linguistic schema."
+            )
+            return None
+
+    def _add_linguistic_schema(self, culture: str):
+
+        import Microsoft.AnalysisServices.Tabular as TOM
+
+        # TODO: if LinguisticMetadata is None
+        # TODO: check if lower() is good enough
+        # TODO: 'in' vs 'has' in relationships
+        # TODO: 'SemanticSlots' in relationships
+
+        c = self.model.Cultures[culture]
+        if c.LinguisticMetadata is not None:
+            lm = json.loads(c.LinguisticMetadata.Content)
+
+            def add_entity(entity, conecptual_entity, conceptual_property):
+                lm["Entities"][entity] = {
+                    "Definition": {
+                        "Binding": {
+                            "ConceptualEntity": conecptual_entity,
+                            "ConceptualProperty": conceptual_property,
+                        }
+                    },
+                    "State": "Generated",
+                    "Terms": [],
+                }
+
+            def add_relationship(rel_key, table_name, t_name, o_name):
+                lm["Relationships"][rel_key] = {
+                    "Binding": {"ConceptualEntity": table_name},
+                    "State": "Generated",
+                    "Roles": {
+                        t_name: {"Target": {"Entity": t_name}},
+                        f"{t_name}.{o_name}": {
+                            "Target": {"Entity": f"{t_name}.{o_name}"}
+                        },
+                    },
+                    "Phrasings": [
+                        {
+                            "Attribute": {
+                                "Subject": {"Role": t_name},
+                                "Object": {"Role": f"{t_name}.{o_name}"},
+                            },
+                            "State": "Generated",
+                            "Weight": 0.99,
+                            "ID": f"{t_name}_have_{o_name}",
+                        }
+                    ],
+                }
+
+            if "Entities" not in lm:
+                lm["Entities"] = {}
+                for t in self.model.Tables:
+                    t_lower = t.Name.lower()
+                    lm["Entities"][t_lower] = {
+                        "Definition": {"Binding": {"ConceptualEntity": t.Name}},
+                        "State": "Generated",
+                        "Terms": [],
+                    }
+                    for c in t.Columns:
+                        if c.Type != TOM.ColumnType.RowNumber:
+                            c_lower = f"{t_lower}.{c.Name.lower()}"
+                            add_entity(c_lower, t.Name, c.Name)
+                    for m in t.Measures:
+                        m_lower = f"{t_lower}.{m.Name.lower()}"
+                        add_entity(m_lower, t.Name, m.Name)
+                    for h in t.Hierarchies:
+                        h_lower = f"{t_lower}.{h.Name.lower()}"
+                        add_entity(h_lower, t.Name, h.Name)
+            # if "Relationships" not in lm:
+            #    lm["Relationships"] = {}
+            #    for c in self.all_columns():
+            #        table_name = c.Parent.Name
+            #        t_name = table_name.lower()
+            #        object_name = c.Name
+            #        o_name = object_name.lower()
+            #        rel_key = f"{t_name}_has_{o_name}"
+            #        add_relationship(rel_key, table_name, t_name, o_name)
+            #    for m in self.all_measures():
+            #        table_name = c.Parent.Name
+            #        t_name = table_name.lower()
+            #        object_name = m.Name
+            #        o_name = object_name.lower()
+            #        rel_key = f"{t_name}_has_{o_name}"
+            #        add_relationship(rel_key, table_name, t_name, o_name)
+
+            self.model.Cultures[culture].LinguisticMetadata.Content = json.dumps(lm)
+
+    @staticmethod
+    def _get_synonym_info(
+        lm: dict,
+        object: Union["TOM.Table", "TOM.Column", "TOM.Measure", "TOM.Hierarchy"],
+        synonym_name: str,
+    ):
+
+        import Microsoft.AnalysisServices.Tabular as TOM
+
+        object_type = object.ObjectType
+        obj = None
+        syn_exists = False
+
+        for key, v in lm.get("Entities", []).items():
+            binding = v.get("Definition", {}).get("Binding", {})
+            t_name = binding.get("ConceptualEntity")
+            o_name = binding.get("ConceptualProperty")
+
+            if (
+                object_type == TOM.ObjectType.Table
+                and t_name == object.Name
+                and o_name is None
+            ) or (
+                object_type
+                in [
+                    TOM.ObjectType.Column,
+                    TOM.ObjectType.Measure,
+                    TOM.ObjectType.Hierarchy,
+                ]
+                and t_name == object.Parent.Name
+                and o_name == object.Name
+            ):
+                obj = key
+                terms = v.get("Terms", [])
+                syn_exists = any(synonym_name in term for term in terms)
+                # optionally break early if match is found
+                break
+
+        return obj, syn_exists
+
+    def set_synonym(
+        self,
+        culture: str,
+        object: Union["TOM.Table", "TOM.Column", "TOM.Measure", "TOM.Hierarchy"],
+        synonym_name: str,
+        weight: Optional[Decimal] = None,
+    ):
+        """
+        Sets a synonym for a table/column/measure/hierarchy in the linguistic schema of the semantic model. This function is currently in preview.
+
+        Parameters
+        ----------
+        culture : str
+            The culture name for which the synonym is being set. Example: 'en-US'.
+        object : TOM Object
+            The TOM object for which the synonym is being set. This can be a table, column, measure, or hierarchy.
+        synonym_name : str
+            The name of the synonym to be set.
+        weight : Decimal, default=None
+            The weight of the synonym. If None, the default weight is used. The weight must be a Decimal value between 0 and 1.
+        """
+
+        import Microsoft.AnalysisServices.Tabular as TOM
+
+        object_type = object.ObjectType
+
+        if object_type not in [
+            TOM.ObjectType.Table,
+            TOM.ObjectType.Column,
+            TOM.ObjectType.Measure,
+            TOM.ObjectType.Hierarchy,
+        ]:
+            raise ValueError(
+                f"{icons.red_dot} This function only supports adding synonyms for tables/columns/measures/hierarchies."
+            )
+
+        # Add base linguistic schema in case it does not yet exist
+        self._add_linguistic_schema(culture=culture)
+
+        # Extract linguistic metadata content
+        lm = json.loads(self.model.Cultures[culture].LinguisticMetadata.Content)
+
+        # Generate synonym dictionary
+        _validate_weight(weight)
+        now = datetime.now().isoformat(timespec="milliseconds") + "Z"
+        syn_dict = {"Type": "Noun", "State": "Authored", "LastModified": now}
+        if weight is not None:
+            syn_dict["Weight"] = weight
+
+        updated = False
+
+        (obj, syn_exists) = self._get_synonym_info(
+            lm=lm, object=object, synonym_name=synonym_name
+        )
+
+        entities = lm.get("Entities", {})
+
+        def get_unique_entity_key(object, object_type, entities):
+
+            if object_type == TOM.ObjectType.Table:
+                base_obj = object.Name.lower().replace(" ", "_")
+            else:
+                base_obj = f"{object.Parent.Name}.{object.Name}".lower().replace(
+                    " ", "_"
+                )
+
+            obj = base_obj
+            counter = 1
+            existing_keys = set(entities.keys())
+
+            # Make sure the object name is unique
+            while obj in existing_keys:
+                obj = f"{base_obj}_{counter}"
+                counter += 1
+
+            return obj
+
+        # Update linguistic metadata content
+        if obj is None:
+            obj = get_unique_entity_key(object, object_type, entities)
+            lm["Entities"][obj] = {
+                "Definition": {"Binding": {}},
+                "State": "Authored",
+                "Terms": [
+                    {synonym_name: syn_dict},
+                ],
+            }
+            if object_type == TOM.ObjectType.Table:
+                lm["Entities"][obj]["Definition"]["Binding"][
+                    "ConceptualEntity"
+                ] = object.Name
+            else:
+                lm["Entities"][obj]["Definition"]["Binding"][
+                    "ConceptualEntity"
+                ] = object.Parent.Name
+                lm["Entities"][obj]["Definition"]["Binding"][
+                    "ConceptualProperty"
+                ] = object.Name
+            updated = True
+        elif not syn_exists:
+            lm["Entities"][obj]["Terms"].append({synonym_name: syn_dict})
+            updated = True
+        else:
+            for term in lm["Entities"][obj]["Terms"]:
+                if term == synonym_name:
+                    lm["Entities"][obj]["Terms"][term] = syn_dict
+            updated = True
+
+        if "State" in lm["Entities"][obj]:
+            del lm["Entities"][obj]["State"]
+
+        if updated:
+            self.model.Cultures[culture].LinguisticMetadata.Content = json.dumps(
+                lm, indent=4
+            )
+            if object_type == TOM.ObjectType.Table:
+                print(
+                    f"{icons.green_dot} The '{synonym_name}' synonym was set for the '{object.Name}' table."
+                )
+            else:
+                print(
+                    f"{icons.green_dot} The '{synonym_name}' synonym was set for the '{object.Parent.Name}'[{object.Name}] column."
+                )
+
+    def delete_synonym(
+        self,
+        culture: str,
+        object: Union["TOM.Table", "TOM.Column", "TOM.Measure", "TOM.Hierarchy"],
+        synonym_name: str,
+    ):
+        """
+        Deletes a synonym for a table/column/measure/hierarchy in the linguistic schema of the semantic model. This function is currently in preview.
+
+        Parameters
+        ----------
+        culture : str
+            The culture name for which the synonym is being deleted. Example: 'en-US'.
+        object : TOM Object
+            The TOM object for which the synonym is being deleted. This can be a table, column, measure, or hierarchy.
+        synonym_name : str
+            The name of the synonym to be deleted.
+        """
+
+        import Microsoft.AnalysisServices.Tabular as TOM
+
+        if not any(c.Name == culture for c in self.model.Cultures):
+            raise ValueError(
+                f"{icons.red_dot} The '{culture}' culture does not exist within the semantic model."
+            )
+
+        if object.ObjectType not in [
+            TOM.ObjectType.Table,
+            TOM.ObjectType.Column,
+            TOM.ObjectType.Measure,
+            TOM.ObjectType.Hierarchy,
+        ]:
+            raise ValueError(
+                f"{icons.red_dot} This function only supports tables/columns/measures/hierarchies."
+            )
+
+        lm = json.loads(self.model.Cultures[culture].LinguisticMetadata.Content)
+
+        if "Entities" not in lm:
+            print(
+                f"{icons.warning} There is no linguistic schema for the '{culture}' culture."
+            )
+            return
+
+        (obj, syn_exists) = self._get_synonym_info(
+            lm=lm, object=object, synonym_name=synonym_name
+        )
+
+        # Mark the synonym as deleted if it exists
+        if obj is not None and syn_exists:
+            data = lm["Entities"][obj]["Terms"]
+            next(
+                (
+                    item[synonym_name].update({"State": "Deleted"})
+                    for item in data
+                    if synonym_name in item
+                ),
+                None,
+            )
+
+            self.model.Cultures[culture].LinguisticMetadata.Content = json.dumps(
+                lm, indent=4
+            )
+            print(
+                f"{icons.green_dot} The '{synonym_name}' synonym was marked as status 'Deleted' for the '{object.Name}' object."
+            )
+        else:
+            print(
+                f"{icons.info} The '{synonym_name}' synonym does not exist for the '{object.Name}' object."
+            )
+
+    def _lock_linguistic_schema(self, culture: str):
+
+        c = self.model.Cultures[culture]
+        if c.LinguisticMetadata is not None:
+            lm = json.loads(c.LinguisticMetadata.Content)
+            if "DynamicImprovement" not in lm:
+                lm["DynamicImprovement"] = {}
+            lm["DynamicImprovement"]["Schema"] = None
+
+            c.LinguisticMetadata.Content = json.dumps(lm, indent=4)
+
+    def _unlock_linguistic_schema(self, culture: str):
+
+        c = self.model.Cultures[culture]
+        if c.LinguisticMetadata is not None:
+            lm = json.loads(c.LinguisticMetadata.Content)
+            if "DynamicImprovement" in lm:
+                del lm["DynamicImprovement"]["Schema"]
+
+            c.LinguisticMetadata.Content = json.dumps(lm, indent=4)
+
+    def _export_linguistic_schema(self, culture: str, file_path: str):
+
+        if not lakehouse_attached():
+            raise ValueError(
+                f"{icons.red_dot} A lakehouse must be attached to the notebook in order to export a linguistic schema."
+            )
+
+        if not any(c.Name == culture for c in self.model.Cultures):
+            raise ValueError(
+                f"{icons.red_dot} The '{culture}' culture does not exist within the semantic model."
+            )
+
+        folderPath = "/lakehouse/default/Files"
+        fileExt = ".json"
+        if not file_path.endswith(fileExt):
+            file_path = f"{file_path}{fileExt}"
+
+        for c in self.model.Cultures:
+            if c.Name == culture:
+                lm = json.loads(c.LinguisticMetadata.Content)
+                filePath = os.path.join(folderPath, file_path)
+                with open(filePath, "w") as json_file:
+                    json.dump(lm, json_file, indent=4)
+
+                print(
+                    f"{icons.green_dot} The linguistic schema for the '{culture}' culture was saved as the '{file_path}' file within the lakehouse attached to this notebook."
+                )
+
+    def _import_linguistic_schema(self, file_path: str):
+
+        if not file_path.endswith(".json"):
+            raise ValueError(f"{icons.red_dot} The 'file_path' must be a .json file.")
+
+        with open(file_path, "r") as json_file:
+            schema_file = json.load(json_file)
+
+            # Validate structure
+            required_keys = ["Version", "Language", "Entities", "Relationships"]
+            if not all(key in schema_file for key in required_keys):
+                raise ValueError(
+                    f"{icons.red_dot} The 'schema_file' is not in the proper format."
+                )
+
+            culture_name = schema_file["Language"]
+
+            # Validate culture
+            if not any(c.Name == culture_name for c in self.model.Cultures):
+                raise ValueError(
+                    f"{icons.red_dot} The culture of the schema_file is not a valid culture within the semantic model."
+                )
+
+            self.model.Cultures[culture_name].LinguisticMetadata.Content = json.dumps(
+                schema_file, indent=4
+            )
+
     def close(self):
 
         # DAX Formatting