docs: clarify Jinja from_dttm/to_dttm availability in SQL Lab

[rusackas]

User description

SUMMARY

This PR addresses a long-standing source of confusion documented in #21793: users attempting to use {{ from_dttm }} and {{ to_dttm }} Jinja variables directly in SQL Lab queries receive "undefined parameter" errors.

Root cause: These variables are only populated when a chart or dashboard provides a time range filter context. They are NOT available in standalone SQL Lab queries.

Changes

1. Updated variable descriptions to explicitly note context requirements
2. Added "Understanding Context Availability" section explaining:
   • When these variables are populated (Explore/Chart views, dashboard filters)
   • Why they fail in standalone SQL Lab queries
3. Documented three workarounds for testing in SQL Lab:
   • Using Jinja default filter (recommended)
   • Using SQL Lab Parameters
   • Using {% set %} for testing
4. Added tip about filter values overriding defaults when used in charts

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

N/A - documentation only

TESTING INSTRUCTIONS

1. Review the updated docs at docs/docs/configuration/sql-templating.mdx
2. Verify the explanations are clear and accurate
3. Optionally test the workarounds in a local Superset instance

ADDITIONAL INFORMATION

• Fixes [Jinja] {{from_dttm}} and {{to_dttm}} variables not working as expected #21793 (3+ year old issue)
• This was identified through code analysis of superset/jinja_context.py and superset/models/helpers.py
• The from_dttm/to_dttm variables are deprecated in favor of get_time_filter() starting in v5.0

🤖 Generated with Claude Code

---

CodeAnt-AI Description

Docs: clarify availability of Jinja time variables and how to test in SQL Lab

What Changed

• Documentation now states that from_dttm and to_dttm are only provided when a chart or dashboard supplies a time filter and are not available in standalone SQL Lab queries (avoids "undefined parameter" errors)
• Added a new "Understanding Context Availability" section explaining when these Jinja variables are populated (Explore/Chart views, dashboard filters)
• Added three concrete ways to test time-filtered queries in SQL Lab: Jinja default filter (recommended), SQL Lab Parameters, and {% set %} examples; includes a note that chart filter values override test defaults

Impact

✅ Clearer undefined-parameter errors when using Jinja in SQL Lab
✅ Easier testing of time-filtered queries in SQL Lab
✅ Fewer support questions about Jinja time variables

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[codeant-ai-for-open-source]

CodeAnt AI is reviewing your PR.

[codeant-ai-for-open-source]

Nitpicks 🔍

🔒 No security issues identified

⚡ Recommended areas for review Type mismatch / casting The Option 1 example uses string literals in the WHERE clause (e.g. '{{ from_dttm | default("2024-01-01", true) }}'), which may be rendered as SQL strings and cause type or formatting errors on some databases. Consider demonstrating or recommending a conversion/cast (e.g., using the to_datetime filter or a DB-specific cast) so the example works reliably across engines. default behavior clarity The Option 1 example uses | default("2024-01-01", true). The second boolean parameter controls whether falsy values are treated as missing — this is easy to misinterpret. Verify the docs clearly align with Jinja semantics and consider clarifying why true is passed and what cases it covers. Hard-coded, potentially stale examples The examples use fixed 2024 dates in both the SQL and JSON parameter examples. These will become outdated and could confuse readers. Use placeholders (e.g. "YYYY-MM-DD"), relative dates, or explain that these are illustrative values. Example Staleness The SQL examples use hard-coded calendar years ("2024-01-01" / "2024-12-31"). These will become outdated and can confuse readers testing queries in later years. Consider using placeholders, relative examples, or ISO timestamps with times to avoid format mismatches with real datasets.

[codeant-ai-for-open-source]

CodeAnt AI finished reviewing your PR.

[Copilot]

Pull request overview

This PR clarifies when Jinja time variables (from_dttm and to_dttm) are available in Superset, addressing a long-standing source of user confusion documented in issue #21793.

• Updated variable descriptions to explicitly note they require time range filter context
• Added "Understanding Context Availability" section explaining when these variables are populated and why they fail in standalone SQL Lab queries
• Documented three practical workarounds for testing time-filtered queries in SQL Lab

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
docs/versioned_docs/version-6.0.0/configuration/sql-templating.mdx	Added context availability notes and testing workarounds for Jinja time variables
docs/docs/configuration/sql-templating.mdx	Same documentation updates for the current version