acryl-datahub-cloud 0.3.12rc4__py3-none-any.whl → 0.3.12rc6__py3-none-any.whl

acryl_datahub_cloud/sdk/assertions_client.py

@@ -4,13 +4,17 @@ import logging
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any, Optional, Union
 
-from acryl_datahub_cloud.sdk.assertion import (
+from acryl_datahub_cloud.sdk.assertion.assertion_base import (
     AssertionMode,
     FreshnessAssertion,
     SmartFreshnessAssertion,
     SmartVolumeAssertion,
+    SqlAssertion,
     _AssertionPublic,
 )
+from acryl_datahub_cloud.sdk.assertion.smart_column_metric_assertion import (
+    SmartColumnMetricAssertion,
+)
 from acryl_datahub_cloud.sdk.assertion_input.assertion_input import (
     AssertionIncidentBehavior,
     DetectionMechanismInputTypes,
@@ -24,6 +28,19 @@ from acryl_datahub_cloud.sdk.assertion_input.assertion_input import (
 from acryl_datahub_cloud.sdk.assertion_input.freshness_assertion_input import (
     _FreshnessAssertionInput,
 )
+from acryl_datahub_cloud.sdk.assertion_input.smart_column_metric_assertion_input import (
+    MetricInputType,
+    OperatorInputType,
+    RangeInputType,
+    RangeTypeInputType,
+    ValueInputType,
+    ValueTypeInputType,
+    _SmartColumnMetricAssertionInput,
+)
+from acryl_datahub_cloud.sdk.assertion_input.sql_assertion_input import (
+    SqlAssertionCriteria,
+    _SqlAssertionInput,
+)
 from acryl_datahub_cloud.sdk.entities.assertion import Assertion, TagsInputType
 from acryl_datahub_cloud.sdk.entities.monitor import Monitor
 from acryl_datahub_cloud.sdk.errors import SDKUsageError
@@ -477,6 +494,87 @@ class AssertionsClient:
 
         return merged_assertion_input
 
+    def _retrieve_and_merge_sql_assertion_and_monitor(
+        self,
+        assertion_input: _SqlAssertionInput,
+        dataset_urn: Union[str, DatasetUrn],
+        urn: Union[str, AssertionUrn],
+        display_name: Optional[str],
+        enabled: Optional[bool],
+        criteria: SqlAssertionCriteria,
+        statement: str,
+        incident_behavior: Optional[
+            Union[AssertionIncidentBehavior, list[AssertionIncidentBehavior]]
+        ],
+        tags: Optional[TagsInputType],
+        updated_by: Optional[Union[str, CorpUserUrn]],
+        now_utc: datetime,
+        schedule: Optional[Union[str, models.CronScheduleClass]],
+    ) -> Union[SqlAssertion, _SqlAssertionInput]:
+        # 1. Retrieve any existing assertion and monitor entities:
+        maybe_assertion_entity, monitor_urn, maybe_monitor_entity = (
+            self._retrieve_assertion_and_monitor(assertion_input)
+        )
+
+        # 2.1 If the assertion and monitor entities exist, create an assertion object from them:
+        if maybe_assertion_entity and maybe_monitor_entity:
+            existing_assertion = SqlAssertion._from_entities(
+                maybe_assertion_entity, maybe_monitor_entity
+            )
+        # 2.2 If the assertion exists but the monitor does not, create a placeholder monitor entity to be able to create the assertion:
+        elif maybe_assertion_entity and not maybe_monitor_entity:
+            monitor_mode = (
+                "ACTIVE" if enabled else "INACTIVE" if enabled is not None else "ACTIVE"
+            )
+            existing_assertion = SqlAssertion._from_entities(
+                maybe_assertion_entity,
+                Monitor(id=monitor_urn, info=("ASSERTION", monitor_mode)),
+            )
+        # 2.3 If the assertion does not exist, create a new assertion with a generated urn and return the assertion input:
+        elif not maybe_assertion_entity:
+            logger.info(
+                f"No existing assertion entity found for assertion urn {urn}, creating a new assertion with a generated urn"
+            )
+            return self._create_sql_assertion(
+                dataset_urn=dataset_urn,
+                display_name=display_name,
+                criteria=criteria,
+                statement=statement,
+                incident_behavior=incident_behavior,
+                tags=tags,
+                created_by=updated_by,
+                schedule=schedule,
+            )
+
+        # 3. Check for any issues e.g. different dataset urns
+        if (
+            existing_assertion
+            and hasattr(existing_assertion, "dataset_urn")
+            and existing_assertion.dataset_urn != assertion_input.dataset_urn
+        ):
+            raise SDKUsageError(
+                f"Dataset URN mismatch, existing assertion: {existing_assertion.dataset_urn} != new assertion: {dataset_urn}"
+            )
+
+        # 4. Merge the existing assertion with the validated input:
+        merged_assertion_input = self._merge_sql_input(
+            dataset_urn=dataset_urn,
+            urn=urn,
+            display_name=display_name,
+            enabled=enabled,
+            criteria=criteria,
+            statement=statement,
+            incident_behavior=incident_behavior,
+            tags=tags,
+            now_utc=now_utc,
+            assertion_input=assertion_input,
+            maybe_assertion_entity=maybe_assertion_entity,
+            existing_assertion=existing_assertion,
+            schedule=schedule,
+        )
+
+        return merged_assertion_input
+
     def _retrieve_assertion_and_monitor(
         self,
         assertion_input: _AssertionInput,
@@ -769,6 +867,112 @@ class AssertionsClient:
         )
         return merged_assertion_input
 
+    def _merge_sql_input(
+        self,
+        dataset_urn: Union[str, DatasetUrn],
+        urn: Union[str, AssertionUrn],
+        display_name: Optional[str],
+        enabled: Optional[bool],
+        criteria: SqlAssertionCriteria,
+        statement: str,
+        incident_behavior: Optional[
+            Union[AssertionIncidentBehavior, list[AssertionIncidentBehavior]]
+        ],
+        tags: Optional[TagsInputType],
+        now_utc: datetime,
+        assertion_input: _SqlAssertionInput,
+        maybe_assertion_entity: Optional[Assertion],
+        # not used: maybe_monitor_entity: Optional[Monitor], as schedule is already set in existing_assertion
+        existing_assertion: SqlAssertion,
+        schedule: Optional[Union[str, models.CronScheduleClass]],
+    ) -> _SqlAssertionInput:
+        """Merge the input with the existing assertion and monitor entities.
+
+        Args:
+            dataset_urn: The urn of the dataset to be monitored.
+            urn: The urn of the assertion.
+            display_name: The display name of the assertion.
+            enabled: Whether the assertion is enabled.
+            criteria: The criteria of the assertion.
+            statement: The statement of the assertion.
+            incident_behavior: The incident behavior to be applied to the assertion.
+            tags: The tags to be applied to the assertion.
+            now_utc: The current UTC time from when the function is called.
+            assertion_input: The validated input to the function.
+            maybe_assertion_entity: The existing assertion entity from the DataHub instance.
+            existing_assertion: The existing assertion from the DataHub instance.
+            schedule: The schedule to be applied to the assertion.
+
+        Returns:
+            The merged assertion input.
+        """
+        merged_assertion_input = _SqlAssertionInput(
+            urn=urn,
+            entity_client=self.client.entities,
+            dataset_urn=dataset_urn,
+            display_name=_merge_field(
+                display_name,
+                "display_name",
+                assertion_input,
+                existing_assertion,
+                maybe_assertion_entity.description if maybe_assertion_entity else None,
+            ),
+            enabled=_merge_field(
+                enabled,
+                "enabled",
+                assertion_input,
+                existing_assertion,
+                existing_assertion.mode == AssertionMode.ACTIVE
+                if existing_assertion
+                else None,
+            ),
+            schedule=_merge_field(
+                schedule,
+                "schedule",
+                assertion_input,
+                existing_assertion,
+                # TODO should this use maybe_monitor_entity.schedule?
+                existing_assertion.schedule if existing_assertion else None,
+            ),
+            criteria=_merge_field(
+                criteria,
+                "criteria",
+                assertion_input,
+                existing_assertion,
+                existing_assertion.criteria if existing_assertion else None,
+            ),
+            statement=_merge_field(
+                statement,
+                "statement",
+                assertion_input,
+                existing_assertion,
+                existing_assertion.statement if existing_assertion else None,
+            ),
+            incident_behavior=_merge_field(
+                incident_behavior,
+                "incident_behavior",
+                assertion_input,
+                existing_assertion,
+                SqlAssertion._get_incident_behavior(maybe_assertion_entity)
+                if maybe_assertion_entity
+                else None,
+            ),
+            tags=_merge_field(
+                tags,
+                "tags",
+                assertion_input,
+                existing_assertion,
+                maybe_assertion_entity.tags if maybe_assertion_entity else None,
+            ),
+            created_by=existing_assertion.created_by
+            or DEFAULT_CREATED_BY,  # Override with the existing assertion's created_by or the default created_by if not set
+            created_at=existing_assertion.created_at
+            or now_utc,  # Override with the existing assertion's created_at or now if not set
+            updated_by=assertion_input.updated_by,  # Override with the input's updated_by
+            updated_at=assertion_input.updated_at,  # Override with the input's updated_at (now)
+        )
+        return merged_assertion_input
+
     def _merge_smart_volume_input(
         self,
         dataset_urn: Union[str, DatasetUrn],
@@ -1240,6 +1444,103 @@ class AssertionsClient:
         #     raise e
         return FreshnessAssertion._from_entities(assertion_entity, monitor_entity)
 
+    def _create_sql_assertion(
+        self,
+        *,
+        dataset_urn: Union[str, DatasetUrn],
+        display_name: Optional[str] = None,
+        enabled: bool = True,
+        criteria: SqlAssertionCriteria,
+        statement: str,
+        incident_behavior: Optional[
+            Union[AssertionIncidentBehavior, list[AssertionIncidentBehavior]]
+        ],
+        tags: Optional[TagsInputType],
+        created_by: Optional[Union[str, CorpUserUrn]] = None,
+        schedule: Optional[Union[str, models.CronScheduleClass]] = None,
+    ) -> SqlAssertion:
+        """Create a sql assertion.
+
+        Args:
+            dataset_urn: The urn of the dataset to be monitored.
+            display_name: The display name of the assertion. If not provided, a random display
+                name will be generated.
+            enabled: Whether the assertion is enabled. Defaults to True.
+            criteria: The criteria to be used for the assertion. This is of type SqlAssertionCriteria. It has the following fields:
+                - type: The type of sql assertion. Valid values are:
+                    - "METRIC" -> Looks at the current value of the metric.
+                    - "METRIC_CHANGE" -> Looks at the change in the metric between the current and previous run.
+                - change_type: The change type of the assertion, if the type is "METRIC_CHANGE". Valid values are:
+                    - "ABSOLUTE" -> Looks at the absolute change in the metric.
+                    - "PERCENTAGE" -> Looks at the percentage change in the metric.
+                - operator: The operator to be used for the assertion. Valid values are:
+                    - "GREATER_THAN" -> The metric value is greater than the threshold.
+                    - "LESS_THAN" -> The metric value is less than the threshold.
+                    - "GREATER_THAN_OR_EQUAL_TO" -> The metric value is greater than or equal to the threshold.
+                    - "LESS_THAN_OR_EQUAL_TO" -> The metric value is less than or equal to the threshold.
+                    - "EQUAL_TO" -> The metric value is equal to the threshold.
+                    - "NOT_EQUAL_TO" -> The metric value is not equal to the threshold.
+                    - "BETWEEN" -> The metric value is between the two thresholds.
+                - parameters: The parameters to be used for the assertion. This is of type SqlAssertionParameters. It has the following fields:
+                    - value: The value of the metric. This can be a single value or a tuple range.
+                        - If the operator is "BETWEEN", the value is a tuple of two values, with format min, max.
+                        - If the operator is not "BETWEEN", the value is a single value.
+            statement: The statement to be used for the assertion.
+            incident_behavior: The incident behavior to be applied to the assertion. Valid values are:
+                - "raise_on_fail" or AssertionIncidentBehavior.RAISE_ON_FAIL
+                - "resolve_on_pass" or AssertionIncidentBehavior.RESOLVE_ON_PASS
+            tags: The tags to be applied to the assertion. Valid values are:
+                - a list of strings (strings will be converted to TagUrn objects)
+                - a list of TagUrn objects
+                - a list of TagAssociationClass objects
+            created_by: Optional urn of the user who created the assertion. The format is
+                "urn:li:corpuser:<username>", which you can find on the Users & Groups page.
+            schedule: Optional cron formatted schedule for the assertion. If not provided, a default
+                schedule will be used. The schedule determines when the assertion will be evaluated.
+                The format is a cron expression, e.g. "0 * * * *" for every hour using UTC timezone.
+                Alternatively, a models.CronScheduleClass object can be provided with string parameters
+                cron and timezone. Use `from datahub.metadata import schema_classes as models` to import the class.
+
+        Returns:
+            SqlAssertion: The created assertion.
+        """
+        _print_experimental_warning()
+        now_utc = datetime.now(timezone.utc)
+        if created_by is None:
+            logger.warning(
+                f"Created by is not set, using {DEFAULT_CREATED_BY} as a placeholder"
+            )
+            created_by = DEFAULT_CREATED_BY
+        assertion_input = _SqlAssertionInput(
+            urn=None,
+            entity_client=self.client.entities,
+            dataset_urn=dataset_urn,
+            display_name=display_name,
+            enabled=enabled,
+            criteria=criteria,
+            statement=statement,
+            incident_behavior=incident_behavior,
+            tags=tags,
+            created_by=created_by,
+            created_at=now_utc,
+            updated_by=created_by,
+            updated_at=now_utc,
+            schedule=schedule,
+        )
+        assertion_entity, monitor_entity = (
+            assertion_input.to_assertion_and_monitor_entities()
+        )
+        # If assertion creation fails, we won't try to create the monitor
+        self.client.entities.create(assertion_entity)
+        # TODO: Wrap monitor creation in a try-except and delete the assertion if monitor creation fails (once delete is implemented https://linear.app/acryl-data/issue/OBS-1350/add-delete-method-to-entity-clientpy)
+        # try:
+        self.client.entities.create(monitor_entity)
+        # except Exception as e:
+        #     logger.error(f"Error creating monitor: {e}")
+        #     self.client.entities.delete(assertion_entity)
+        #     raise e
+        return SqlAssertion._from_entities(assertion_entity, monitor_entity)
+
     def sync_smart_volume_assertion(
         self,
         *,
@@ -1427,60 +1728,773 @@ class AssertionsClient:
 
         return SmartVolumeAssertion._from_entities(assertion_entity, monitor_entity)
 
-    def sync_freshness_assertion(
+    def sync_smart_column_metric_assertion(
         self,
         *,
         dataset_urn: Union[str, DatasetUrn],
+        column_name: str,
+        metric_type: MetricInputType,
+        operator: OperatorInputType,
+        value: Optional[ValueInputType] = None,
+        value_type: Optional[ValueTypeInputType] = None,
+        range: Optional[RangeInputType] = None,
+        range_type: Optional[RangeTypeInputType] = None,
         urn: Optional[Union[str, AssertionUrn]] = None,
         display_name: Optional[str] = None,
         enabled: Optional[bool] = None,
         detection_mechanism: DetectionMechanismInputTypes = None,
+        sensitivity: Optional[Union[str, InferenceSensitivity]] = None,
+        exclusion_windows: Optional[ExclusionWindowInputTypes] = None,
+        training_data_lookback_days: Optional[int] = None,
         incident_behavior: Optional[
             Union[AssertionIncidentBehavior, list[AssertionIncidentBehavior]]
         ] = None,
         tags: Optional[TagsInputType] = None,
         updated_by: Optional[Union[str, CorpUserUrn]] = None,
-        freshness_schedule_check_type: Optional[
-            Union[str, models.FreshnessAssertionScheduleTypeClass]
-        ] = None,
         schedule: Optional[Union[str, models.CronScheduleClass]] = None,
-        lookback_window: Optional[TimeWindowSizeInputTypes] = None,
-    ) -> FreshnessAssertion:
-        """Upsert and merge a freshness assertion.
+    ) -> SmartColumnMetricAssertion:
+        """Upsert and merge a smart column metric assertion.
 
         Note: keyword arguments are required.
 
         Upsert and merge is a combination of create and update. If the assertion does not exist,
-        it will be created. If it does exist, it will be updated. Existing assertion fields will
-        be updated if the input value is not None. If the input value is None, the existing value
+        it will be created. If it does exist, it will be updated.
+
+        Existing assertion fields will be updated if the input value is not None. If the input value is None, the existing value
         will be preserved. If the input value can be un-set e.g. by passing an empty list or
         empty string.
 
-        Schedule behavior:
-        - Create case: Uses default daily schedule (\"0 0 * * *\") or provided schedule
-        - Update case: Uses existing schedule or provided schedule.
-
         Args:
-            dataset_urn: The urn of the dataset to be monitored.
+            dataset_urn: The urn of the dataset to be monitored. (Required)
+            column_name: The name of the column to be monitored. (Required)
+            metric_type: The type of the metric to be monitored. (Required)
+            operator: The operator to be used for the assertion. (Required)
+            value: The value to be used for the assertion. (Required if operator requires a value)
+            value_type: The type of the value to be used for the assertion. (Required if operator requires a value)
+            range: The range to be used for the assertion. (Required if operator requires a range)
+            range_type: The type of the range to be used for the assertion. (Required if operator requires a range)
             urn: The urn of the assertion. If not provided, a urn will be generated and the assertion
                 will be _created_ in the DataHub instance.
             display_name: The display name of the assertion. If not provided, a random display name
                 will be generated.
             enabled: Whether the assertion is enabled. If not provided, the existing value
                 will be preserved.
-            detection_mechanism: The detection mechanism to be used for the assertion. Information
-                schema is recommended. Valid values are:
-                - "information_schema" or DetectionMechanism.INFORMATION_SCHEMA
-                - "audit_log" or DetectionMechanism.AUDIT_LOG
-                - {
-                    "type": "last_modified_column",
+            detection_mechanism: The detection mechanism to be used for the assertion. Valid values are:
+                - All rows query datahub dataset profile:
+                - "all_rows_query_datahub_dataset_profile" or DetectionMechanism.ALL_ROWS_QUERY_DATAHUB_DATASET_PROFILE
+
+                - All rows query:
+                - "all_rows_query" or DetectionMechanism.ALL_ROWS_QUERY
+                - with optional additional filter: DetectionMechanism.ALL_ROWS_QUERY(additional_filter='last_modified > 2021-01-01')
+                - Or as a dict: {
+                    "type": "all_rows_query",
+                    "additional_filter": "last_modified > '2021-01-01'", # optional
+                }
+
+                - Changed rows query:
+                - For changed rows query, you need to pass a supported column type (Number, Date or Time)
+                - DetectionMechanism.CHANGED_ROWS_QUERY(column_name='last_modified')
+                - With optional additional filter: DetectionMechanism.CHANGED_ROWS_QUERY(column_name='last_modified', additional_filter='last_modified > 2021-01-01')
+                - Or as a dict: {
+                    "type": "changed_rows_query",
                     "column_name": "last_modified",
-                    "additional_filter": "last_modified > '2021-01-01'",
-                } or DetectionMechanism.LAST_MODIFIED_COLUMN(column_name='last_modified',
-                additional_filter='last_modified > 2021-01-01')
-                - {
-                    "type": "high_watermark_column",
-                    "column_name": "id",
+                    "additional_filter": "last_modified > '2021-01-01'", # optional
+                }
+
+            sensitivity: The sensitivity to be applied to the assertion. Valid values are:
+                - "low" or InferenceSensitivity.LOW
+                - "medium" or InferenceSensitivity.MEDIUM
+                - "high" or InferenceSensitivity.HIGH
+            exclusion_windows: The exclusion windows to be applied to the assertion, currently only
+                fixed range exclusion windows are supported. Valid values are:
+                - from datetime.datetime objects: {
+                    "start": "datetime(2025, 1, 1, 0, 0, 0)",
+                    "end": "datetime(2025, 1, 2, 0, 0, 0)",
+                }
+                - from string datetimes: {
+                    "start": "2025-01-01T00:00:00",
+                    "end": "2025-01-02T00:00:00",
+                }
+                - from FixedRangeExclusionWindow objects: FixedRangeExclusionWindow(
+                    start=datetime(2025, 1, 1, 0, 0, 0),
+                    end=datetime(2025, 1, 2, 0, 0, 0)
+                )
+            training_data_lookback_days: The training data lookback days to be applied to the
+                assertion as an integer.
+            incident_behavior: The incident behavior to be applied to the assertion. Valid values are:
+                - "raise_on_fail" or AssertionIncidentBehavior.RAISE_ON_FAIL
+                - "resolve_on_pass" or AssertionIncidentBehavior.RESOLVE_ON_PASS
+            tags: The tags to be applied to the assertion. Valid values are:
+                - a list of strings (strings will be converted to TagUrn objects)
+                - a list of TagUrn objects
+                - a list of TagAssociationClass objects
+            updated_by: Optional urn of the user who updated the assertion. The format is
+                "urn:li:corpuser:<username>", which you can find on the Users & Groups page.
+                The default is the datahub system user.
+                TODO: Retrieve the SDK user as the default instead of the datahub system user.
+            schedule: Optional cron formatted schedule for the assertion. If not provided, a default
+                schedule of every 6 hours will be used. The schedule determines when the assertion will be evaluated.
+                The format is a cron expression, e.g. "0 * * * *" for every hour using UTC timezone.
+                Alternatively, a models.CronScheduleClass object can be provided with string parameters
+                cron and timezone. Use `from datahub.metadata import schema_classes as models` to import the class.
+
+        Returns:
+            SmartColumnMetricAssertion: The created or updated assertion.
+        """
+        _print_experimental_warning()
+        now_utc = datetime.now(timezone.utc)
+
+        if updated_by is None:
+            logger.warning(
+                f"updated_by is not set, using {DEFAULT_CREATED_BY} as a placeholder"
+            )
+            updated_by = DEFAULT_CREATED_BY
+
+        # 1. If urn is not set, create a new assertion
+        if urn is None:
+            logger.info("URN is not set, creating a new assertion")
+            return self._create_smart_column_metric_assertion(
+                dataset_urn=dataset_urn,
+                column_name=column_name,
+                metric_type=metric_type,
+                operator=operator,
+                value=value,
+                value_type=value_type,
+                range=range,
+                range_type=range_type,
+                display_name=display_name,
+                enabled=enabled if enabled is not None else True,
+                detection_mechanism=detection_mechanism,
+                sensitivity=sensitivity,
+                exclusion_windows=exclusion_windows,
+                training_data_lookback_days=training_data_lookback_days,
+                incident_behavior=incident_behavior,
+                tags=tags,
+                created_by=updated_by,
+                schedule=schedule,
+            )
+
+        # 2. If urn is set, first validate the input:
+        assertion_input = _SmartColumnMetricAssertionInput(
+            urn=urn,
+            entity_client=self.client.entities,
+            dataset_urn=dataset_urn,
+            column_name=column_name,
+            metric_type=metric_type,
+            operator=operator,
+            value=value,
+            value_type=value_type,
+            range=range,
+            range_type=range_type,
+            display_name=display_name,
+            detection_mechanism=detection_mechanism,
+            sensitivity=sensitivity,
+            exclusion_windows=exclusion_windows,
+            training_data_lookback_days=training_data_lookback_days,
+            incident_behavior=incident_behavior,
+            tags=tags,
+            created_by=updated_by,  # This will be overridden by the actual created_by
+            created_at=now_utc,  # This will be overridden by the actual created_at
+            updated_by=updated_by,
+            updated_at=now_utc,
+            schedule=schedule,
+        )
+
+        # 3. Merge the assertion input with the existing assertion and monitor entities or create a new assertion
+        # if the assertion does not exist:
+        merged_assertion_input_or_created_assertion = (
+            self._retrieve_and_merge_smart_column_metric_assertion_and_monitor(
+                assertion_input=assertion_input,
+                dataset_urn=dataset_urn,
+                column_name=column_name,
+                metric_type=metric_type,
+                operator=operator,
+                value=value,
+                value_type=value_type,
+                range=range,
+                range_type=range_type,
+                urn=urn,
+                display_name=display_name,
+                enabled=enabled,
+                detection_mechanism=detection_mechanism,
+                sensitivity=sensitivity,
+                exclusion_windows=exclusion_windows,
+                training_data_lookback_days=training_data_lookback_days,
+                incident_behavior=incident_behavior,
+                tags=tags,
+                updated_by=updated_by,
+                now_utc=now_utc,
+                schedule=schedule,
+            )
+        )
+
+        # Return early if we created a new assertion in the merge:
+        if isinstance(merged_assertion_input_or_created_assertion, _AssertionPublic):
+            # We know this is the correct type because we passed the assertion_class parameter
+            assert isinstance(
+                merged_assertion_input_or_created_assertion, SmartColumnMetricAssertion
+            )
+            return merged_assertion_input_or_created_assertion
+
+        # 4. Upsert the assertion and monitor entities:
+        assertion_entity, monitor_entity = (
+            merged_assertion_input_or_created_assertion.to_assertion_and_monitor_entities()
+        )
+        # If assertion upsert fails, we won't try to upsert the monitor
+        self.client.entities.upsert(assertion_entity)
+        # TODO: Wrap monitor upsert in a try-except and delete the assertion if monitor upsert fails (once delete is implemented https://linear.app/acryl-data/issue/OBS-1350/add-delete-method-to-entity-clientpy)
+        # try:
+        self.client.entities.upsert(monitor_entity)
+        # except Exception as e:
+        #     logger.error(f"Error upserting monitor: {e}")
+        #     self.client.entities.delete(assertion_entity)
+        #     raise e
+
+        return SmartColumnMetricAssertion._from_entities(
+            assertion_entity, monitor_entity
+        )
+
+    def _create_smart_column_metric_assertion(
+        self,
+        *,
+        dataset_urn: Union[str, DatasetUrn],
+        column_name: str,
+        metric_type: MetricInputType,
+        operator: OperatorInputType,
+        value: Optional[ValueInputType] = None,
+        value_type: Optional[ValueTypeInputType] = None,
+        range: Optional[RangeInputType] = None,
+        range_type: Optional[RangeTypeInputType] = None,
+        display_name: Optional[str] = None,
+        enabled: bool = True,
+        detection_mechanism: DetectionMechanismInputTypes = None,
+        sensitivity: Optional[Union[str, InferenceSensitivity]] = None,
+        exclusion_windows: Optional[ExclusionWindowInputTypes] = None,
+        training_data_lookback_days: Optional[int] = None,
+        incident_behavior: Optional[
+            Union[AssertionIncidentBehavior, list[AssertionIncidentBehavior]]
+        ] = None,
+        tags: Optional[TagsInputType] = None,
+        created_by: Optional[Union[str, CorpUserUrn]] = None,
+        schedule: Optional[Union[str, models.CronScheduleClass]] = None,
+    ) -> SmartColumnMetricAssertion:
+        """Create a smart column metric assertion.
+
+        Note: keyword arguments are required.
+
+        Args:
+            dataset_urn: The urn of the dataset to be monitored. (Required)
+            column_name: The name of the column to be monitored. (Required)
+            metric_type: The type of the metric to be monitored. (Required)
+            operator: The operator to be used for the assertion. (Required)
+            value: The value to be used for the assertion. (Required if operator requires a value)
+            value_type: The type of the value to be used for the assertion. (Required if operator requires a value)
+            range: The range to be used for the assertion. (Required if operator requires a range)
+            range_type: The type of the range to be used for the assertion. (Required if operator requires a range)
+            display_name: The display name of the assertion. If not provided, a random display
+                name will be generated.
+            enabled: Whether the assertion is enabled. Defaults to True.
+            detection_mechanism: The detection mechanism to be used for the assertion. Information
+                schema is recommended. Valid values are:
+                - "information_schema" or DetectionMechanism.INFORMATION_SCHEMA
+                - "audit_log" or DetectionMechanism.AUDIT_LOG
+                - {
+                    "type": "last_modified_column",
+                    "column_name": "last_modified",
+                    "additional_filter": "last_modified > '2021-01-01'",
+                } or DetectionMechanism.LAST_MODIFIED_COLUMN(column_name='last_modified',
+                additional_filter='last_modified > 2021-01-01')
+                - {
+                    "type": "high_watermark_column",
+                    "column_name": "id",
+                    "additional_filter": "id > 1000",
+                } or DetectionMechanism.HIGH_WATERMARK_COLUMN(column_name='id',
+                additional_filter='id > 1000')
+                - "datahub_operation" or DetectionMechanism.DATAHUB_OPERATION
+            sensitivity: The sensitivity to be applied to the assertion. Valid values are:
+                - "low" or InferenceSensitivity.LOW
+                - "medium" or InferenceSensitivity.MEDIUM
+                - "high" or InferenceSensitivity.HIGH
+            exclusion_windows: The exclusion windows to be applied to the assertion, currently only
+                fixed range exclusion windows are supported. Valid values are:
+                - from datetime.datetime objects: {
+                    "start": "datetime(2025, 1, 1, 0, 0, 0)",
+                    "end": "datetime(2025, 1, 2, 0, 0, 0)",
+                }
+                - from string datetimes: {
+                    "start": "2025-01-01T00:00:00",
+                    "end": "2025-01-02T00:00:00",
+                }
+                - from FixedRangeExclusionWindow objects: FixedRangeExclusionWindow(
+                    start=datetime(2025, 1, 1, 0, 0, 0),
+                    end=datetime(2025, 1, 2, 0, 0, 0)
+                )
+            training_data_lookback_days: The training data lookback days to be applied to the
+                assertion as an integer.
+            incident_behavior: The incident behavior to be applied to the assertion. Valid values are:
+                - "raise_on_fail" or AssertionIncidentBehavior.RAISE_ON_FAIL
+                - "resolve_on_pass" or AssertionIncidentBehavior.RESOLVE_ON_PASS
+            tags: The tags to be applied to the assertion. Valid values are:
+                - a list of strings (strings will be converted to TagUrn objects)
+                - a list of TagUrn objects
+                - a list of TagAssociationClass objects
+            created_by: Optional urn of the user who created the assertion. The format is
+                "urn:li:corpuser:<username>", which you can find on the Users & Groups page.
+                The default is the datahub system user.
+                TODO: Retrieve the SDK user as the default instead of the datahub system user.
+            schedule: Optional cron formatted schedule for the assertion. If not provided, a default
+                schedule will be used. The schedule determines when the assertion will be evaluated.
+                The format is a cron expression, e.g. "0 * * * *" for every hour using UTC timezone.
+                Alternatively, a models.CronScheduleClass object can be provided with string parameters
+                cron and timezone. Use `from datahub.metadata import schema_classes as models` to import the class.
+
+        Returns:
+            SmartVolumeAssertion: The created assertion.
+        """
+        _print_experimental_warning()
+        now_utc = datetime.now(timezone.utc)
+        if created_by is None:
+            logger.warning(
+                f"Created by is not set, using {DEFAULT_CREATED_BY} as a placeholder"
+            )
+            created_by = DEFAULT_CREATED_BY
+        assertion_input = _SmartColumnMetricAssertionInput(
+            urn=None,
+            entity_client=self.client.entities,
+            dataset_urn=dataset_urn,
+            column_name=column_name,
+            metric_type=metric_type,
+            operator=operator,
+            value=value,
+            value_type=value_type,
+            range=range,
+            range_type=range_type,
+            display_name=display_name,
+            enabled=enabled,
+            detection_mechanism=detection_mechanism,
+            sensitivity=sensitivity,
+            exclusion_windows=exclusion_windows,
+            training_data_lookback_days=training_data_lookback_days,
+            incident_behavior=incident_behavior,
+            tags=tags,
+            created_by=created_by,
+            created_at=now_utc,
+            updated_by=created_by,
+            updated_at=now_utc,
+            schedule=schedule,
+        )
+        assertion_entity, monitor_entity = (
+            assertion_input.to_assertion_and_monitor_entities()
+        )
+        # If assertion creation fails, we won't try to create the monitor
+        self.client.entities.create(assertion_entity)
+        # TODO: Wrap monitor creation in a try-except and delete the assertion if monitor creation fails (once delete is implemented https://linear.app/acryl-data/issue/OBS-1350/add-delete-method-to-entity-clientpy)
+        # try:
+        self.client.entities.create(monitor_entity)
+        # except Exception as e:
+        #     logger.error(f"Error creating monitor: {e}")
+        #     self.client.entities.delete(assertion_entity)
+        #     raise e
+        return SmartColumnMetricAssertion._from_entities(
+            assertion_entity, monitor_entity
+        )
+
+    def _retrieve_and_merge_smart_column_metric_assertion_and_monitor(
+        self,
+        assertion_input: _SmartColumnMetricAssertionInput,
+        dataset_urn: Union[str, DatasetUrn],
+        column_name: str,
+        metric_type: MetricInputType,
+        operator: OperatorInputType,
+        value: Optional[ValueInputType],
+        value_type: Optional[ValueTypeInputType],
+        range: Optional[RangeInputType],
+        range_type: Optional[RangeTypeInputType],
+        urn: Union[str, AssertionUrn],
+        display_name: Optional[str],
+        enabled: Optional[bool],
+        detection_mechanism: DetectionMechanismInputTypes,
+        sensitivity: Optional[Union[str, InferenceSensitivity]],
+        exclusion_windows: Optional[ExclusionWindowInputTypes],
+        training_data_lookback_days: Optional[int],
+        incident_behavior: Optional[
+            Union[AssertionIncidentBehavior, list[AssertionIncidentBehavior]]
+        ],
+        tags: Optional[TagsInputType],
+        updated_by: Optional[Union[str, CorpUserUrn]],
+        now_utc: datetime,
+        schedule: Optional[Union[str, models.CronScheduleClass]],
+    ) -> Union[SmartColumnMetricAssertion, _SmartColumnMetricAssertionInput]:
+        # 1. Retrieve any existing assertion and monitor entities:
+        maybe_assertion_entity, monitor_urn, maybe_monitor_entity = (
+            self._retrieve_assertion_and_monitor(assertion_input)
+        )
+
+        # 2.1 If the assertion and monitor entities exist, create an assertion object from them:
+        if maybe_assertion_entity and maybe_monitor_entity:
+            existing_assertion = SmartColumnMetricAssertion._from_entities(
+                maybe_assertion_entity, maybe_monitor_entity
+            )
+        # 2.2 If the assertion exists but the monitor does not, create a placeholder monitor entity to be able to create the assertion:
+        elif maybe_assertion_entity and not maybe_monitor_entity:
+            monitor_mode = (
+                "ACTIVE" if enabled else "INACTIVE" if enabled is not None else "ACTIVE"
+            )
+            existing_assertion = SmartColumnMetricAssertion._from_entities(
+                maybe_assertion_entity,
+                Monitor(id=monitor_urn, info=("ASSERTION", monitor_mode)),
+            )
+        # 2.3 If the assertion does not exist, create a new assertion with a generated urn and return the assertion input:
+        elif not maybe_assertion_entity:
+            logger.info(
+                f"No existing assertion entity found for assertion urn {urn}, creating a new assertion with a generated urn"
+            )
+            return self._create_smart_column_metric_assertion(
+                dataset_urn=dataset_urn,
+                column_name=column_name,
+                metric_type=metric_type,
+                operator=operator,
+                value=value,
+                value_type=value_type,
+                range=range,
+                range_type=range_type,
+                schedule=schedule,
+                display_name=display_name,
+                detection_mechanism=detection_mechanism,
+                sensitivity=sensitivity,
+                exclusion_windows=exclusion_windows,
+                training_data_lookback_days=training_data_lookback_days,
+                incident_behavior=incident_behavior,
+                tags=tags,
+                created_by=updated_by,
+            )
+
+        # 3. Check for any issues e.g. different dataset urns
+        if (
+            existing_assertion
+            and hasattr(existing_assertion, "dataset_urn")
+            and existing_assertion.dataset_urn != assertion_input.dataset_urn
+        ):
+            raise SDKUsageError(
+                f"Dataset URN mismatch, existing assertion: {existing_assertion.dataset_urn} != new assertion: {dataset_urn}"
+            )
+
+        # 4. Merge the existing assertion with the validated input:
+        merged_assertion_input = self._merge_smart_column_metric_input(
+            dataset_urn=dataset_urn,
+            column_name=column_name,
+            metric_type=metric_type,
+            operator=operator,
+            value=value,
+            value_type=value_type,
+            range=range,
+            range_type=range_type,
+            urn=urn,
+            display_name=display_name,
+            enabled=enabled,
+            schedule=schedule,
+            detection_mechanism=detection_mechanism,
+            sensitivity=sensitivity,
+            exclusion_windows=exclusion_windows,
+            training_data_lookback_days=training_data_lookback_days,
+            incident_behavior=incident_behavior,
+            tags=tags,
+            now_utc=now_utc,
+            assertion_input=assertion_input,
+            maybe_assertion_entity=maybe_assertion_entity,
+            maybe_monitor_entity=maybe_monitor_entity,
+            existing_assertion=existing_assertion,
+        )
+
+        return merged_assertion_input
+
+    def _merge_smart_column_metric_input(
+        self,
+        dataset_urn: Union[str, DatasetUrn],
+        column_name: str,
+        metric_type: MetricInputType,
+        operator: OperatorInputType,
+        value: Optional[ValueInputType],
+        value_type: Optional[ValueTypeInputType],
+        range: Optional[RangeInputType],
+        range_type: Optional[RangeTypeInputType],
+        urn: Union[str, AssertionUrn],
+        display_name: Optional[str],
+        enabled: Optional[bool],
+        detection_mechanism: DetectionMechanismInputTypes,
+        sensitivity: Optional[Union[str, InferenceSensitivity]],
+        exclusion_windows: Optional[ExclusionWindowInputTypes],
+        training_data_lookback_days: Optional[int],
+        incident_behavior: Optional[
+            Union[AssertionIncidentBehavior, list[AssertionIncidentBehavior]]
+        ],
+        tags: Optional[TagsInputType],
+        schedule: Optional[Union[str, models.CronScheduleClass]],
+        now_utc: datetime,
+        assertion_input: _SmartColumnMetricAssertionInput,
+        maybe_assertion_entity: Optional[Assertion],
+        maybe_monitor_entity: Optional[Monitor],
+        existing_assertion: SmartColumnMetricAssertion,
+    ) -> _SmartColumnMetricAssertionInput:
+        """Merge the input with the existing assertion and monitor entities.
+
+        Args:
+            dataset_urn: The urn of the dataset to be monitored.
+            column_name: The name of the column to be monitored.
+            metric_type: The type of the metric to be monitored.
+            operator: The operator to be used for the assertion.
+            value: The value to be used for the assertion.
+            value_type: The type of the value to be used for the assertion.
+            range: The range to be used for the assertion.
+            range_type: The type of the range to be used for the assertion.
+            urn: The urn of the assertion.
+            display_name: The display name of the assertion.
+            enabled: Whether the assertion is enabled.
+            detection_mechanism: The detection mechanism to be used for the assertion.
+            sensitivity: The sensitivity to be applied to the assertion.
+            exclusion_windows: The exclusion windows to be applied to the assertion.
+            training_data_lookback_days: The training data lookback days to be applied to the assertion.
+            incident_behavior: The incident behavior to be applied to the assertion.
+            tags: The tags to be applied to the assertion.
+            now_utc: The current UTC time from when the function is called.
+            assertion_input: The validated input to the function.
+            maybe_assertion_entity: The existing assertion entity from the DataHub instance.
+            maybe_monitor_entity: The existing monitor entity from the DataHub instance.
+            existing_assertion: The existing assertion from the DataHub instance.
+
+        Returns:
+            The merged assertion input.
+        """
+        merged_assertion_input = _SmartColumnMetricAssertionInput(
+            urn=urn,
+            entity_client=self.client.entities,
+            dataset_urn=dataset_urn,
+            column_name=_merge_field(
+                input_field_value=column_name,
+                input_field_name="column_name",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=SmartColumnMetricAssertion._get_column_name(
+                    maybe_assertion_entity
+                )
+                if maybe_assertion_entity
+                else None,
+            ),
+            metric_type=_merge_field(
+                input_field_value=metric_type,
+                input_field_name="metric_type",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=SmartColumnMetricAssertion._get_metric_type(
+                    maybe_assertion_entity
+                )
+                if maybe_assertion_entity
+                else None,
+            ),
+            operator=_merge_field(
+                input_field_value=operator,
+                input_field_name="operator",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=SmartColumnMetricAssertion._get_operator(
+                    maybe_assertion_entity
+                )
+                if maybe_assertion_entity
+                else None,
+            ),
+            value=_merge_field(
+                input_field_value=value,
+                input_field_name="value",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=SmartColumnMetricAssertion._get_value(
+                    maybe_assertion_entity
+                )
+                if maybe_assertion_entity
+                else None,
+            ),
+            value_type=_merge_field(
+                input_field_value=value_type,
+                input_field_name="value_type",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=SmartColumnMetricAssertion._get_value_type(
+                    maybe_assertion_entity
+                )
+                if maybe_assertion_entity
+                else None,
+            ),
+            range=_merge_field(
+                input_field_value=range,
+                input_field_name="range",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=SmartColumnMetricAssertion._get_range(
+                    maybe_assertion_entity
+                )
+                if maybe_assertion_entity
+                else None,
+            ),
+            range_type=_merge_field(
+                input_field_value=range_type,
+                input_field_name="range_type",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=SmartColumnMetricAssertion._get_range_type(
+                    maybe_assertion_entity
+                )
+                if maybe_assertion_entity
+                else None,
+            ),
+            display_name=_merge_field(
+                input_field_value=display_name,
+                input_field_name="display_name",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=maybe_assertion_entity.description
+                if maybe_assertion_entity
+                else None,
+            ),
+            enabled=_merge_field(
+                input_field_value=enabled,
+                input_field_name="enabled",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=existing_assertion.mode == AssertionMode.ACTIVE
+                if existing_assertion
+                else None,
+            ),
+            schedule=_merge_field(
+                input_field_value=schedule,
+                input_field_name="schedule",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=existing_assertion.schedule
+                if existing_assertion
+                else None,
+            ),
+            detection_mechanism=_merge_field(
+                input_field_value=detection_mechanism,
+                input_field_name="detection_mechanism",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=SmartColumnMetricAssertion._get_detection_mechanism(
+                    maybe_assertion_entity, maybe_monitor_entity, default=None
+                )
+                if maybe_assertion_entity and maybe_monitor_entity
+                else None,
+            ),
+            sensitivity=_merge_field(
+                input_field_value=sensitivity,
+                input_field_name="sensitivity",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=maybe_monitor_entity.sensitivity
+                if maybe_monitor_entity
+                else None,
+            ),
+            exclusion_windows=_merge_field(
+                input_field_value=exclusion_windows,
+                input_field_name="exclusion_windows",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=maybe_monitor_entity.exclusion_windows
+                if maybe_monitor_entity
+                else None,
+            ),
+            training_data_lookback_days=_merge_field(
+                input_field_value=training_data_lookback_days,
+                input_field_name="training_data_lookback_days",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=maybe_monitor_entity.training_data_lookback_days
+                if maybe_monitor_entity
+                else None,
+            ),
+            incident_behavior=_merge_field(
+                input_field_value=incident_behavior,
+                input_field_name="incident_behavior",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=SmartColumnMetricAssertion._get_incident_behavior(
+                    maybe_assertion_entity
+                )
+                if maybe_assertion_entity
+                else None,
+            ),
+            tags=_merge_field(
+                input_field_value=tags,
+                input_field_name="tags",
+                validated_assertion_input=assertion_input,
+                validated_existing_assertion=existing_assertion,
+                existing_entity_value=maybe_assertion_entity.tags
+                if maybe_assertion_entity
+                else None,
+            ),
+            created_by=existing_assertion.created_by
+            or DEFAULT_CREATED_BY,  # Override with the existing assertion's created_by or the default created_by if not set
+            created_at=existing_assertion.created_at
+            or now_utc,  # Override with the existing assertion's created_at or now if not set
+            updated_by=assertion_input.updated_by,  # Override with the input's updated_by
+            updated_at=assertion_input.updated_at,  # Override with the input's updated_at (now)
+        )
+
+        return merged_assertion_input
+
+    def sync_freshness_assertion(
+        self,
+        *,
+        dataset_urn: Union[str, DatasetUrn],
+        urn: Optional[Union[str, AssertionUrn]] = None,
+        display_name: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        detection_mechanism: DetectionMechanismInputTypes = None,
+        incident_behavior: Optional[
+            Union[AssertionIncidentBehavior, list[AssertionIncidentBehavior]]
+        ] = None,
+        tags: Optional[TagsInputType] = None,
+        updated_by: Optional[Union[str, CorpUserUrn]] = None,
+        freshness_schedule_check_type: Optional[
+            Union[str, models.FreshnessAssertionScheduleTypeClass]
+        ] = None,
+        schedule: Optional[Union[str, models.CronScheduleClass]] = None,
+        lookback_window: Optional[TimeWindowSizeInputTypes] = None,
+    ) -> FreshnessAssertion:
+        """Upsert and merge a freshness assertion.
+
+        Note: keyword arguments are required.
+
+        Upsert and merge is a combination of create and update. If the assertion does not exist,
+        it will be created. If it does exist, it will be updated. Existing assertion fields will
+        be updated if the input value is not None. If the input value is None, the existing value
+        will be preserved. If the input value can be un-set e.g. by passing an empty list or
+        empty string.
+
+        Schedule behavior:
+        - Create case: Uses default daily schedule (\"0 0 * * *\") or provided schedule
+        - Update case: Uses existing schedule or provided schedule.
+
+        Args:
+            dataset_urn: The urn of the dataset to be monitored.
+            urn: The urn of the assertion. If not provided, a urn will be generated and the assertion
+                will be _created_ in the DataHub instance.
+            display_name: The display name of the assertion. If not provided, a random display name
+                will be generated.
+            enabled: Whether the assertion is enabled. If not provided, the existing value
+                will be preserved.
+            detection_mechanism: The detection mechanism to be used for the assertion. Information
+                schema is recommended. Valid values are:
+                - "information_schema" or DetectionMechanism.INFORMATION_SCHEMA
+                - "audit_log" or DetectionMechanism.AUDIT_LOG
+                - {
+                    "type": "last_modified_column",
+                    "column_name": "last_modified",
+                    "additional_filter": "last_modified > '2021-01-01'",
+                } or DetectionMechanism.LAST_MODIFIED_COLUMN(column_name='last_modified',
+                additional_filter='last_modified > 2021-01-01')
+                - {
+                    "type": "high_watermark_column",
+                    "column_name": "id",
                     "additional_filter": "id > 1000",
                 } or DetectionMechanism.HIGH_WATERMARK_COLUMN(column_name='id',
                 additional_filter='id > 1000')
@@ -1592,6 +2606,167 @@ class AssertionsClient:
 
         return FreshnessAssertion._from_entities(assertion_entity, monitor_entity)
 
+    def sync_sql_assertion(
+        self,
+        *,
+        dataset_urn: Union[str, DatasetUrn],
+        urn: Optional[Union[str, AssertionUrn]] = None,
+        display_name: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        statement: str,
+        criteria: SqlAssertionCriteria,
+        incident_behavior: Optional[
+            Union[AssertionIncidentBehavior, list[AssertionIncidentBehavior]]
+        ] = None,
+        tags: Optional[TagsInputType] = None,
+        updated_by: Optional[Union[str, CorpUserUrn]] = None,
+        schedule: Optional[Union[str, models.CronScheduleClass]] = None,
+    ) -> SqlAssertion:
+        """Upsert and merge a sql assertion.
+
+        Note: keyword arguments are required.
+
+        Upsert and merge is a combination of create and update. If the assertion does not exist,
+        it will be created. If it does exist, it will be updated. Existing assertion fields will
+        be updated if the input value is not None. If the input value is None, the existing value
+        will be preserved. If the input value can be un-set e.g. by passing an empty list or
+        empty string.
+
+        Schedule behavior:
+        - Create case: Uses default daily schedule (\"0 0 * * *\") or provided schedule
+        - Update case: Uses existing schedule or provided schedule.
+
+        Args:
+            dataset_urn: The urn of the dataset to be monitored.
+            urn: The urn of the assertion. If not provided, a urn will be generated and the assertion
+                will be _created_ in the DataHub instance.
+            display_name: The display name of the assertion. If not provided, a random display name
+                will be generated.
+            enabled: Whether the assertion is enabled. If not provided, the existing value
+                will be preserved.
+            criteria: The criteria to be used for the assertion. This is of type SqlAssertionCriteria. It has the following fields:
+                - type: The type of sql assertion. Valid values are:
+                    - "METRIC" -> Looks at the current value of the metric.
+                    - "METRIC_CHANGE" -> Looks at the change in the metric between the current and previous run.
+                - change_type: The change type of the assertion, if the type is "METRIC_CHANGE". Valid values are:
+                    - "ABSOLUTE" -> Looks at the absolute change in the metric.
+                    - "PERCENTAGE" -> Looks at the percentage change in the metric.
+                - operator: The operator to be used for the assertion. Valid values are:
+                    - "GREATER_THAN" -> The metric value is greater than the threshold.
+                    - "LESS_THAN" -> The metric value is less than the threshold.
+                    - "GREATER_THAN_OR_EQUAL_TO" -> The metric value is greater than or equal to the threshold.
+                    - "LESS_THAN_OR_EQUAL_TO" -> The metric value is less than or equal to the threshold.
+                    - "EQUAL_TO" -> The metric value is equal to the threshold.
+                    - "NOT_EQUAL_TO" -> The metric value is not equal to the threshold.
+                    - "BETWEEN" -> The metric value is between the two thresholds.
+                - parameters: The parameters to be used for the assertion. This is of type SqlAssertionParameters. It has the following fields:
+                    - value: The value of the metric. This can be a single value or a tuple range.
+                        - If the operator is "BETWEEN", the value is a tuple of two values, with format min, max.
+                        - If the operator is not "BETWEEN", the value is a single value.
+            statement: The SQL statement to be used for the assertion.
+                - "SELECT COUNT(*) FROM table WHERE column > 100"
+            incident_behavior: The incident behavior to be applied to the assertion. Valid values are:
+                - "raise_on_fail" or AssertionIncidentBehavior.RAISE_ON_FAIL
+                - "resolve_on_pass" or AssertionIncidentBehavior.RESOLVE_ON_PASS
+            tags: The tags to be applied to the assertion. Valid values are:
+                - a list of strings (strings will be converted to TagUrn objects)
+                - a list of TagUrn objects
+                - a list of TagAssociationClass objects
+            updated_by: Optional urn of the user who updated the assertion. The format is
+                "urn:li:corpuser:<username>", which you can find on the Users & Groups page.
+                The default is the datahub system user.
+                TODO: Retrieve the SDK user as the default instead of the datahub system user.
+            schedule: Optional cron formatted schedule for the assertion. If not provided, a default
+                schedule will be used. The schedule determines when the assertion will be evaluated.
+                The format is a cron expression, e.g. "0 * * * *" for every hour using UTC timezone.
+                Alternatively, a models.CronScheduleClass object can be provided with string parameters
+                cron and timezone. Use `from datahub.metadata import schema_classes as models` to import the class.
+
+        Returns:
+            SqlAssertion: The created or updated assertion.
+        """
+        _print_experimental_warning()
+        now_utc = datetime.now(timezone.utc)
+
+        if updated_by is None:
+            logger.warning(
+                f"updated_by is not set, using {DEFAULT_CREATED_BY} as a placeholder"
+            )
+            updated_by = DEFAULT_CREATED_BY
+
+        # 1. If urn is not set, create a new assertion
+        if urn is None:
+            logger.info("URN is not set, creating a new assertion")
+            return self._create_sql_assertion(
+                dataset_urn=dataset_urn,
+                display_name=display_name,
+                enabled=enabled if enabled is not None else True,
+                criteria=criteria,
+                statement=statement,
+                incident_behavior=incident_behavior,
+                tags=tags,
+                created_by=updated_by,
+                schedule=schedule,
+            )
+
+        # 2. If urn is set, first validate the input:
+        assertion_input = _SqlAssertionInput(
+            urn=urn,
+            entity_client=self.client.entities,
+            dataset_urn=dataset_urn,
+            display_name=display_name,
+            criteria=criteria,
+            statement=statement,
+            incident_behavior=incident_behavior,
+            tags=tags,
+            created_by=updated_by,  # This will be overridden by the actual created_by
+            created_at=now_utc,  # This will be overridden by the actual created_at
+            updated_by=updated_by,
+            updated_at=now_utc,
+            schedule=schedule,
+        )
+
+        # 3. Merge the assertion input with the existing assertion and monitor entities or create a new assertion
+        # if the assertion does not exist:
+        merged_assertion_input_or_created_assertion = (
+            self._retrieve_and_merge_sql_assertion_and_monitor(
+                assertion_input=assertion_input,
+                dataset_urn=dataset_urn,
+                urn=urn,
+                display_name=display_name,
+                enabled=enabled,
+                criteria=criteria,
+                statement=statement,
+                incident_behavior=incident_behavior,
+                tags=tags,
+                updated_by=updated_by,
+                now_utc=now_utc,
+                schedule=schedule,
+            )
+        )
+
+        # Return early if we created a new assertion in the merge:
+        if isinstance(merged_assertion_input_or_created_assertion, _AssertionPublic):
+            # We know this is the correct type because we passed the assertion_class parameter
+            assert isinstance(merged_assertion_input_or_created_assertion, SqlAssertion)
+            return merged_assertion_input_or_created_assertion
+
+        # 4. Upsert the assertion and monitor entities:
+        assertion_entity, monitor_entity = (
+            merged_assertion_input_or_created_assertion.to_assertion_and_monitor_entities()
+        )
+        # If assertion upsert fails, we won't try to upsert the monitor
+        self.client.entities.upsert(assertion_entity)
+        # TODO: Wrap monitor upsert in a try-except and delete the assertion if monitor upsert fails (once delete is implemented https://linear.app/acryl-data/issue/OBS-1350/add-delete-method-to-entity-clientpy)
+        # try:
+        self.client.entities.upsert(monitor_entity)
+        # except Exception as e:
+        #     logger.error(f"Error upserting monitor: {e}")
+        #     self.client.entities.delete(assertion_entity)
+        #     raise e
+
+        return SqlAssertion._from_entities(assertion_entity, monitor_entity)
+
 
 def _merge_field(
     input_field_value: Any,