refactor

docs/docs/configuration/sql-templating.mdx

@@ -348,35 +348,38 @@ Here's a concrete example:
 
 **Time Filter for a Specific Column**
 
-The `{{ get_time_filter() }}` macro returns the time filter applied to a specific column. The macro takes the following
-parameters:
+The `{{ get_time_filter() }}` macro returns the time filter applied to a specific column. This is useful if you want
+to handle time filters inside the virtual dataset, as by default the time filter is placed on the outer query. This can
+have considerable performance implications, as many databases and query engines are able to optimize the query better
+if the temporal filter is placed on the inner query, as opposed to the outer query.
+
+The macro takes the following parameters:
 - `column`: Name of the temporal column. Leave undefined to reference the time range from a Dashboard Native Time Range
   filter (when present).
 - `target_type`: The target temporal type as recognized by the target  database (e.g. `TIMESTAMP`, `DATE` or
   `DATETIME`). If `column` is defined, the format will default to the type of the column. This is used to produce
-  the format of the `from_dttm` and `to_dttm` properties of the returned `TimeFilter` object. Note, that omitting
-  `column` and `target_type` will render format the temporal values as ISO format.
+  the format of the `from_expr` and `to_expr` properties of the returned `TimeFilter` object.
 
 The return type has the following properties:
-- `since`: the start of the time filter (if any)
-- `until`: the end of the time filter (if any)
+- `from_expr`: the start of the time filter (if any)
+- `to_expr`: the end of the time filter (if any)
 - `time_range`: The time range as defined on the
 
 Here's a concrete example using the `logs` table from the Superset metastore:
 
 ```
 {% set time_filter = get_time_filter("dttm", remove_filter=True) %}
-{% set since = time_filter.since %}
-{% set until = time_filter.until %}
+{% set from_expr = time_filter.from_expr %}
+{% set to_expr = time_filter.to_expr %}
 {% set time_range = time_filter.time_range %}
 
 SELECT
   *,
   {% if time_range %}'{{ time_range }}'{% else %}''{% endif %} as time_range
 FROM logs
-{% if since or until %}WHERE 1 = 1
-{% if since %}AND dttm >= {{ since }}{% endif %}
-{% if until %}AND dttm < {{ until }}{% endif %}
+{% if from_expr or to_expr %}WHERE 1 = 1
+{% if from_expr %}AND dttm >= {{ from_expr }}{% endif %}
+{% if to_expr %}AND dttm < {{ to_expr }}{% endif %}
 {% endif %}
 ```
 

superset/jinja_context.py

@@ -90,8 +90,8 @@ class TimeFilter:
     Container for temporal filter.
     """
 
-    since: str | None
-    until: str | None
+    from_expr: str | None
+    to_expr: str | None
     time_range: str | None
 
 
@@ -394,15 +394,15 @@ def get_time_filter(
         Usage example::
 
             {% set time_filter = get_time_filter("dttm", remove_filter=True) %}
-            {% set since = time_filter.since %}
-            {% set until = time_filter.until %}
+            {% set from_expr = time_filter.from_expr %}
+            {% set to_expr = time_filter.to_expr %}
             {% set time_range = time_filter.time_range %}
             select *,
             {% if time_range %}'{{ time_range }}'{% else %}''{% endif %} as time_range
             from logs
-            {% if since or until %}where 1 = 1
-            {% if since %}and dttm >= {{ since }}{% endif %}
-            {% if until %}and dttm < {{ until }}{% endif %}
+            {% if from_expr or to_expr %}where 1 = 1
+            {% if from_expr %}and dttm >= {{ from_expr }}{% endif %}
+            {% if to_expr %}and dttm < {{ to_expr }}{% endif %}
             {% endif %}
 
         This will render the time filter inside the virtual dataset subquery with the
@@ -413,7 +413,7 @@ def get_time_filter(
         :param target_type: The target temporal type as recognized by the target
             database (e.g. `TIMESTAMP`, `DATE` or `DATETIME`). If `column` is defined,
             the format will default to the type of the column. This is used to produce
-            the format of the `since` and `until` properties of the returned
+            the format of the `from_expr` and `to_expr` properties of the returned
             `TimeFilter` object. Note, that omitting `column` and `target_type` will
             render format the temporal values as ISO format.
         :param remove_filter: When set to true, mark the filter as processed,
@@ -450,7 +450,7 @@ def get_time_filter(
                     target_type = self.table.columns_types.get(column)
 
         time_range = time_range or NO_TIME_RANGE
-        since, until = get_since_until_from_time_range(time_range)
+        from_expr, to_expr = get_since_until_from_time_range(time_range)
 
         def _format_dttm(dttm: datetime | None) -> str | None:
             if target_type is None and dttm:
@@ -462,8 +462,8 @@ def _format_dttm(dttm: datetime | None) -> str | None:
             )
 
         return TimeFilter(
-            since=_format_dttm(since),
-            until=_format_dttm(until),
+            from_expr=_format_dttm(from_expr),
+            to_expr=_format_dttm(to_expr),
             time_range=time_range,
         )
 

tests/unit_tests/jinja_context_test.py

@@ -849,8 +849,8 @@ def test_metric_macro_no_dataset_id_with_context_chart_no_datasource_id(
             "postgresql://",
             [{}],
             TimeFilter(
-                since=None,
-                until=None,
+                from_expr=None,
+                to_expr=None,
                 time_range="No filter",
             ),
             [],
@@ -862,8 +862,8 @@ def test_metric_macro_no_dataset_id_with_context_chart_no_datasource_id(
             "postgresql://",
             [{"time_range": "Last week"}],
             TimeFilter(
-                since="TO_TIMESTAMP('2024-08-26 00:00:00.000000', 'YYYY-MM-DD HH24:MI:SS.US')",
-                until="TO_TIMESTAMP('2024-09-02 00:00:00.000000', 'YYYY-MM-DD HH24:MI:SS.US')",
+                from_expr="TO_TIMESTAMP('2024-08-26 00:00:00.000000', 'YYYY-MM-DD HH24:MI:SS.US')",
+                to_expr="TO_TIMESTAMP('2024-09-02 00:00:00.000000', 'YYYY-MM-DD HH24:MI:SS.US')",
                 time_range="Last week",
             ),
             [],
@@ -885,8 +885,8 @@ def test_metric_macro_no_dataset_id_with_context_chart_no_datasource_id(
                 }
             ],
             TimeFilter(
-                since="TO_TIMESTAMP('2024-08-26 00:00:00.000000', 'YYYY-MM-DD HH24:MI:SS.US')",
-                until="TO_TIMESTAMP('2024-09-02 00:00:00.000000', 'YYYY-MM-DD HH24:MI:SS.US')",
+                from_expr="TO_TIMESTAMP('2024-08-26 00:00:00.000000', 'YYYY-MM-DD HH24:MI:SS.US')",
+                to_expr="TO_TIMESTAMP('2024-09-02 00:00:00.000000', 'YYYY-MM-DD HH24:MI:SS.US')",
                 time_range="Last week",
             ),
             [],
@@ -908,8 +908,8 @@ def test_metric_macro_no_dataset_id_with_context_chart_no_datasource_id(
                 }
             ],
             TimeFilter(
-                since="TO_DATE('2024-08-26', 'YYYY-MM-DD')",
-                until="TO_DATE('2024-09-02', 'YYYY-MM-DD')",
+                from_expr="TO_DATE('2024-08-26', 'YYYY-MM-DD')",
+                to_expr="TO_DATE('2024-09-02', 'YYYY-MM-DD')",
                 time_range="Last week",
             ),
             ["dt"],
@@ -931,8 +931,8 @@ def test_metric_macro_no_dataset_id_with_context_chart_no_datasource_id(
                 }
             ],
             TimeFilter(
-                since="DATE '2024-08-02'",
-                until="DATE '2024-09-02'",
+                from_expr="DATE '2024-08-02'",
+                to_expr="DATE '2024-09-02'",
                 time_range="Last month",
             ),
             ["dttm"],
@@ -966,7 +966,7 @@ def test_get_time_filter(
     )
 
     with (
-        freeze_time("2024-09-03"),
+        freeze_time("2024-09-03T00:00:00Z"),
         app.test_request_context(
             json={"queries": queries},
         ),