docs: add query introspection guide [SPK-392]#586
Draft
charliedowler wants to merge 9 commits intomainfrom
Draft
docs: add query introspection guide [SPK-392]#586charliedowler wants to merge 9 commits intomainfrom
charliedowler wants to merge 9 commits intomainfrom
Conversation
Adds a developer guide covering the new ld.query.fields and
ld.query.filters Liquid checks. Covers what to check, where it works,
the {% raw %} requirement for dbt YAML, and three worked examples:
- smart_revenue: a metric that defaults to a built-in filter but
respects the user's filter when applied
- active_users: composes ld.parameters with ld.query.filters in the
same Liquid block
- a custom dimension built in the UI from the explore, no PR needed
Wires the page into the Developer guides nav after using-parameters,
and adds a related-link from the parameters page.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Contributor
🤖 Documentation Bot✅ All checks passed! No issues found. |
Table calculations run as SQL in a wrapping SELECT, not client-side, and Liquid blocks inside them are evaluated by the same render pipeline as dimensions and metrics. The previous note said neither — claiming they ran client-side and didn't support introspection. Rewrote it as a practical "don't reach for this here" caveat instead of an incorrect technical claim. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
🤖 Documentation Bot✅ All checks passed! No issues found. |
- drop the rich-text "does not work in" section: rich-text/markdown
tiles aren't a SQL pipeline at all, so calling out a "different
engine (${value.formatted})" was misleading
- clarify joined-table dotted-id: it's the value under `join:`, not
the `label` — avoids "Order Customer.first_name" guesses
Contributor
🤖 Documentation Bot✅ All checks passed! No issues found. |
Replace the opinionated "rarely useful, stick to dimensions and metrics" guidance with a factual description of what each check returns inside a table calculation. Calls out the asymmetry between fields (largely tautological) and filters (genuinely informative, since filter context isn't in the result columns).
Contributor
🤖 Documentation Bot✅ All checks passed! No issues found. |
The other "where it works" bullets are one-liners; the table-calc bullet was a paragraph. Trim it so the list reads consistently.
Contributor
🤖 Documentation Bot✅ All checks passed! No issues found. |
Move the explanation into a Note callout so the list stays one-line per item, but readers still see the asymmetry between ld.query.fields (largely tautological) and ld.query.filters (useful because filter context isn't in the result columns).
Contributor
🤖 Documentation Bot✅ All checks passed! No issues found. |
The factual parts of the original wording hold up — `ld.query.fields` is largely redundant inside a table calculation, and "stick to dimensions and metrics" is the right default steer for analysts.
Contributor
🤖 Documentation Bot✅ All checks passed! No issues found. |
The Liquid + introspection feature was scoped to dimensions and metrics in the original design. Liquid happening to evaluate inside table calculations is an incidental side-effect of where the renderer runs in the query pipeline, not a deliberate feature surface. Don't advertise it as supported.
Contributor
🤖 Documentation Bot✅ All checks passed! No issues found. |
- Drop "anywhere sql: is evaluated" intro that overstated scope - Note that join `alias:` overrides the model name in dotted ids - Replace URL-derived field-id tip with a sidebar-hover instruction - Flag that date dimensions expand into per-interval ids — `event_date` won't match a filter on `event_date_day` - Add the Create Custom Dimension dialog screenshot to the UI example Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
🤖 Documentation Bot✅ All checks passed! No issues found. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a developer guide covering the new
ld.query.fieldsandld.query.filtersLiquid checks (the "query introspection" feature shipped in PR #21032).The guide covers:
Changes
Test plan
Notes for reviewers
🤖 Generated with Claude Code