query interface updates to add Dimension(...).grain(...) support

.changes/unreleased/Features-20230929-123932.yaml

@@ -0,0 +1,6 @@
+kind: Features
+body: 'Backport: Add support for Dimension(...).grain(...) syntax in where parameter'
+time: 2023-09-29T12:39:32.834352-05:00
+custom:
+  Author: DevonFulcher
+  Issue: None

dbt_semantic_interfaces/call_parameter_sets.py

@@ -13,15 +13,15 @@
 
 @dataclass(frozen=True)
 class DimensionCallParameterSet:
-    """When 'dimension(...)' is used in the Jinja template of the where filter, the parameters to that call."""
+    """When 'Dimension(...)' is used in the Jinja template of the where filter, the parameters to that call."""
 
     entity_path: Tuple[EntityReference, ...]
     dimension_reference: DimensionReference
 
 
 @dataclass(frozen=True)
 class TimeDimensionCallParameterSet:
-    """When 'time_dimension(...)' is used in the Jinja template of the where filter, the parameters to that call."""
+    """When 'TimeDimension(...)' is used in the Jinja template of the where filter, the parameters to that call."""
 
     entity_path: Tuple[EntityReference, ...]
     time_dimension_reference: TimeDimensionReference
@@ -30,7 +30,7 @@ class TimeDimensionCallParameterSet:
 
 @dataclass(frozen=True)
 class EntityCallParameterSet:
-    """When 'entity(...)' is used in the Jinja template of the where filter, the parameters to that call."""
+    """When 'Entity(...)' is used in the Jinja template of the where filter, the parameters to that call."""
 
     entity_path: Tuple[EntityReference, ...]
     entity_reference: EntityReference

dbt_semantic_interfaces/errors.py

@@ -22,3 +22,10 @@ class ModelTransformError(Exception):
     """Exception to represent errors related to model transformations."""
 
     pass
+
+
+class InvalidQuerySyntax(Exception):
+    """Raised when query syntax is invalid."""
+
+    def __init__(self, msg: str) -> None:  # noqa: D
+        super().__init__(msg)

dbt_semantic_interfaces/parsing/where_filter/parameter_set_factory.py

@@ -0,0 +1,95 @@
+from typing import Sequence
+
+from dbt_semantic_interfaces.call_parameter_sets import (
+    DimensionCallParameterSet,
+    EntityCallParameterSet,
+    ParseWhereFilterException,
+    TimeDimensionCallParameterSet,
+)
+from dbt_semantic_interfaces.naming.dundered import DunderedNameFormatter
+from dbt_semantic_interfaces.naming.keywords import (
+    METRIC_TIME_ELEMENT_NAME,
+    is_metric_time_name,
+)
+from dbt_semantic_interfaces.references import (
+    DimensionReference,
+    EntityReference,
+    TimeDimensionReference,
+)
+from dbt_semantic_interfaces.type_enums import TimeGranularity
+
+
+class ParameterSetFactory:
+    """Creates parameter sets for use in the Jinja sandbox."""
+
+    @staticmethod
+    def _exception_message_for_incorrect_format(element_name: str) -> str:
+        return (
+            f"Name is in an incorrect format: '{element_name}'. It should be of the form: "
+            f"<primary entity name>__<dimension_name>"
+        )
+
+    @staticmethod
+    def create_time_dimension(
+        time_dimension_name: str, time_granularity_name: str, entity_path: Sequence[str] = ()
+    ) -> TimeDimensionCallParameterSet:
+        """Gets called by Jinja when rendering {{ TimeDimension(...) }}."""
+        group_by_item_name = DunderedNameFormatter.parse_name(time_dimension_name)
+
+        # metric_time is the only time dimension that does not have an associated primary entity, so the
+        # GroupByItemName would not have any entity links.
+        if is_metric_time_name(group_by_item_name.element_name):
+            if len(group_by_item_name.entity_links) != 0 or group_by_item_name.time_granularity is not None:
+                raise ParseWhereFilterException(
+                    f"Name is in an incorrect format: {time_dimension_name} "
+                    f"When referencing {METRIC_TIME_ELEMENT_NAME},"
+                    "the name should not have any dunders (double underscores, or __)."
+                )
+        else:
+            if len(group_by_item_name.entity_links) != 1 or group_by_item_name.time_granularity is not None:
+                raise ParseWhereFilterException(
+                    ParameterSetFactory._exception_message_for_incorrect_format(time_dimension_name)
+                )
+
+        return TimeDimensionCallParameterSet(
+            time_dimension_reference=TimeDimensionReference(element_name=group_by_item_name.element_name),
+            entity_path=(
+                tuple(EntityReference(element_name=arg) for arg in entity_path) + group_by_item_name.entity_links
+            ),
+            time_granularity=TimeGranularity(time_granularity_name),
+        )
+
+    @staticmethod
+    def create_dimension(dimension_name: str, entity_path: Sequence[str] = ()) -> DimensionCallParameterSet:
+        """Gets called by Jinja when rendering {{ Dimension(...) }}."""
+        group_by_item_name = DunderedNameFormatter.parse_name(dimension_name)
+        if is_metric_time_name(group_by_item_name.element_name):
+            raise ParseWhereFilterException(
+                f"{METRIC_TIME_ELEMENT_NAME} is a time dimension, so it should be referenced using "
+                f"TimeDimension(...) or Dimension(...).grain(...)"
+            )
+
+        if len(group_by_item_name.entity_links) != 1:
+            raise ParseWhereFilterException(ParameterSetFactory._exception_message_for_incorrect_format(dimension_name))
+
+        return DimensionCallParameterSet(
+            dimension_reference=DimensionReference(element_name=group_by_item_name.element_name),
+            entity_path=(
+                tuple(EntityReference(element_name=arg) for arg in entity_path) + group_by_item_name.entity_links
+            ),
+        )
+
+    @staticmethod
+    def create_entity(entity_name: str, entity_path: Sequence[str] = ()) -> EntityCallParameterSet:
+        """Gets called by Jinja when rendering {{ Entity(...) }}."""
+        group_by_item_name = DunderedNameFormatter.parse_name(entity_name)
+        if len(group_by_item_name.entity_links) > 0 or group_by_item_name.time_granularity is not None:
+            ParameterSetFactory._exception_message_for_incorrect_format(
+                f"Name is in an incorrect format: {entity_name} "
+                f"When referencing entities, the name should not have any dunders (double underscores, or __)."
+            )
+
+        return EntityCallParameterSet(
+            entity_path=tuple(EntityReference(element_name=arg) for arg in entity_path),
+            entity_reference=EntityReference(element_name=entity_name),
+        )

dbt_semantic_interfaces/parsing/where_filter/where_filter_dimension.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import List, Optional, Sequence
+
+from typing_extensions import override
+
+from dbt_semantic_interfaces.errors import InvalidQuerySyntax
+from dbt_semantic_interfaces.protocols.protocol_hint import ProtocolHint
+from dbt_semantic_interfaces.protocols.query_interface import (
+    QueryInterfaceDimension,
+    QueryInterfaceDimensionFactory,
+)
+
+
+class WhereFilterDimension(ProtocolHint[QueryInterfaceDimension]):
+    """A dimension that is passed in through the where filter parameter."""
+
+    @override
+    def _implements_protocol(self) -> QueryInterfaceDimension:
+        return self
+
+    def __init__(  # noqa
+        self,
+        name: str,
+        entity_path: Sequence[str],
+    ) -> None:
+        self.name = name
+        self.entity_path = entity_path
+        self.time_granularity_name: Optional[str] = None
+
+    def grain(self, time_granularity: str) -> QueryInterfaceDimension:
+        """The time granularity."""
+        self.time_granularity_name = time_granularity
+        return self
+
+    def descending(self, _is_descending: bool) -> QueryInterfaceDimension:
+        """Set the sort order for order-by."""
+        raise InvalidQuerySyntax("descending is invalid in the where parameter and filter spec")
+
+    def date_part(self, _date_part: str) -> QueryInterfaceDimension:
+        """Date part to extract from the dimension."""
+        raise InvalidQuerySyntax("date_part isn't currently supported in the where parameter and filter spec")
+
+
+class WhereFilterDimensionFactory(ProtocolHint[QueryInterfaceDimensionFactory]):
+    """Creates a WhereFilterDimension.
+
+    Each call to `create` adds a WhereFilterDimension to `created`.
+    """
+
+    @override
+    def _implements_protocol(self) -> QueryInterfaceDimensionFactory:
+        return self
+
+    def __init__(self) -> None:  # noqa
+        self.created: List[WhereFilterDimension] = []
+
+    def create(self, dimension_name: str, entity_path: Sequence[str] = ()) -> WhereFilterDimension:
+        """Gets called by Jinja when rendering {{ Dimension(...) }}."""
+        dimension = WhereFilterDimension(dimension_name, entity_path)
+        self.created.append(dimension)
+        return dimension

dbt_semantic_interfaces/parsing/where_filter/where_filter_entity.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import List, Sequence
+
+from typing_extensions import override
+
+from dbt_semantic_interfaces.call_parameter_sets import EntityCallParameterSet
+from dbt_semantic_interfaces.parsing.where_filter.parameter_set_factory import (
+    ParameterSetFactory,
+)
+from dbt_semantic_interfaces.protocols.protocol_hint import ProtocolHint
+from dbt_semantic_interfaces.protocols.query_interface import (
+    QueryInterfaceEntity,
+    QueryInterfaceEntityFactory,
+)
+
+
+class EntityStub(ProtocolHint[QueryInterfaceEntity]):
+    """An Entity implementation that just satisfies the protocol.
+
+    QueryInterfaceEntity currently has no methods and the parameter set is created in the factory.
+    So, there is nothing to do here.
+    """
+
+    @override
+    def _implements_protocol(self) -> QueryInterfaceEntity:
+        return self
+
+
+class WhereFilterEntityFactory(ProtocolHint[QueryInterfaceEntityFactory]):
+    """Executes in the Jinja sandbox to produce parameter sets and append them to a list."""
+
+    @override
+    def _implements_protocol(self) -> QueryInterfaceEntityFactory:
+        return self
+
+    def __init__(self) -> None:  # noqa
+        self.entity_call_parameter_sets: List[EntityCallParameterSet] = []
+
+    def create(self, entity_name: str, entity_path: Sequence[str] = ()) -> EntityStub:
+        """Gets called by Jinja when rendering {{ Entity(...) }}."""
+        self.entity_call_parameter_sets.append(ParameterSetFactory.create_entity(entity_name, entity_path))
+        return EntityStub()

dbt_semantic_interfaces/parsing/where_filter/where_filter_time_dimension.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import List, Optional, Sequence
+
+from typing_extensions import override
+
+from dbt_semantic_interfaces.call_parameter_sets import TimeDimensionCallParameterSet
+from dbt_semantic_interfaces.errors import InvalidQuerySyntax
+from dbt_semantic_interfaces.parsing.where_filter.parameter_set_factory import (
+    ParameterSetFactory,
+)
+from dbt_semantic_interfaces.protocols.protocol_hint import ProtocolHint
+from dbt_semantic_interfaces.protocols.query_interface import (
+    QueryInterfaceTimeDimension,
+    QueryInterfaceTimeDimensionFactory,
+)
+
+
+class TimeDimensionStub(ProtocolHint[QueryInterfaceTimeDimension]):
+    """A TimeDimension implementation that just satisfies the protocol.
+
+    QueryInterfaceTimeDimension currently has no methods and the parameter set is created in the factory.
+    So, there is nothing to do here.
+    """
+
+    @override
+    def _implements_protocol(self) -> QueryInterfaceTimeDimension:
+        return self
+
+
+class WhereFilterTimeDimensionFactory(ProtocolHint[QueryInterfaceTimeDimensionFactory]):
+    """Executes in the Jinja sandbox to produce parameter sets and append them to a list."""
+
+    @override
+    def _implements_protocol(self) -> QueryInterfaceTimeDimensionFactory:
+        return self
+
+    def __init__(self) -> None:  # noqa
+        self.time_dimension_call_parameter_sets: List[TimeDimensionCallParameterSet] = []
+
+    def create(
+        self,
+        time_dimension_name: str,
+        time_granularity_name: str,
+        entity_path: Sequence[str] = (),
+        descending: Optional[bool] = None,
+        date_part_name: Optional[str] = None,
+    ) -> TimeDimensionStub:
+        """Gets called by Jinja when rendering {{ TimeDimension(...) }}."""
+        if descending is not None:
+            raise InvalidQuerySyntax("descending is invalid in the where parameter and filter spec")
+        if date_part_name is not None:
+            raise InvalidQuerySyntax("date_part isn't currently supported in the where parameter and filter spec")
+        self.time_dimension_call_parameter_sets.append(
+            ParameterSetFactory.create_time_dimension(time_dimension_name, time_granularity_name, entity_path)
+        )
+        return TimeDimensionStub()