feat: Show JSON editor when query contains unsupported visual builder features

[samjewell]

Summary

When a query contains features that the visual query builder cannot handle, show the full query as an editable JSON editor instead of the point-and-click interface. This eliminates hidden configuration and allows users to edit advanced features directly.

Problem

The visual query builder supports a subset of Cube.js capabilities:

Feature	JSON Support	Visual Builder
Simple filters (operators equals, notEquals)	Yes	Yes
Simple filters (other operators)	No, but planned	Yes
OR/AND filter groups	No, but planned	No
Time dimensions	Yes	No
Date range with $__from/$__to	Yes	No
Dashboard variables in dimensions/measures/filter-members	No	No
Dashboard variables in filter-values	Yes	Yes

Currently, queries with advanced features have hidden configuration that users cannot see or edit in the UI. This leads to confusion and silent behavior.

Solution

Implement a detectUnsupportedFeatures(query) function and switch to a JSON editor when unsupported features are detected:

function QueryEditor({ query, ... }) {
  const unsupportedFeatures = detectUnsupportedFeatures(query);
  
  if (unsupportedFeatures.length > 0) {
    return <JsonQueryEditor query={query} reasons={unsupportedFeatures} />;
  }
  
  return <VisualQueryEditor query={query} />;
}

The JSON editor should show:

• An info banner explaining why JSON mode is active (list the detected features)
• The full query as editable Read-only JSON
• A "Try Visual Editor" button (with warning if features would be lost)

Implementation

• Create detectUnsupportedFeatures(query): string[] function
• Create basic JsonQueryEditor JsonQueryViewer component
• Update QueryEditor to check for unsupported features first

detectUnsupportedFeatures

Simple boolean checks that return human-readable descriptions:

• Check for time dimensions

Future PRs that add further functionality, will also add features to this detect… function:

• Check for filter operators other than equals/notEquals (eg. <)
• Check for OR/AND filter groups

JsonQuery Editor Viewer

• Display info banner with reasons for JSON mode
• JSON text editor viewer (textarea or basic Monaco)
• Parse JSON on change, pass to onChange handler
• "Try Visual Editor" toggle with confirmation if lossy

Benefits

1. No hidden config - Users see exactly what is configured
2. Editable - Users can modify advanced features directly
3. LLM-friendly - JSON format matches Cube docs, so LLMs can generate valid queries, and put them directly into Dashboard/Panel JSON
4. Future-proof - As visual builder adds features, queries graduate to visual mode

Trade-offs

• Users with advanced queries lose visual builder (but gain visibility)
• JSON editing is harder for non-technical users
• Invalid JSON produces errors only when query runs

Future Enhancements

These are optional improvements for a separate PR if users need the JSON viewer to be editable, and perhaps need better validation:

Editable:

• JSON text editor (textarea or basic Monaco)
• Parse JSON on change, pass to onChange handler
• "Try Visual Editor" toggle with confirmation if lossy

Better validation:

• Add Zod schema validation for real-time error feedback
• Monaco JSON Schema integration for autocomplete
• Inline error markers showing which field is invalid

For now, relying on Cube API error messages should be sufficient.

Context

Identified during OR/AND filter implementation. Rather than building piecemeal solutions for each unsupported feature, a consistent JSON fallback provides better architecture and user experience.

[samjewell]

@cursor

I'm not sure about:

A "Try Visual Editor" button (with warning if features would be lost)

It seems of dubious value.

My concern is with silent and hidden behaviour. Maybe the simplest fix is-

• implement everything on this ticket, but make the json read only, not editable, and
• don't allow the "try visual editor" button.

Instead suggest they continue editing via the dashboard JSON initially, and suggest they use an LLM.

WDYT? That's probably the smallest scope ticket we can do, right?
We can always extend later, with maybe

• making the json text an editable input, and
• possibly adding a button on the visual query builder "edit query-json as free text to allow for advanced functionality"

What do you think?

[samjewell]

I think I want to take a slightly different approach, and build in a slightly different order.

I want to:

• Remove dashboard-variable interpolation from Dimensions and Measures, and keep the surface area of this plugin small - only build features when we realise we truly need them, and remove features otherwise: YAGNI. Done in PR chore: remove unused dashboard variable interpolation (YAGNI) #73

• Remove dashboard-variable from other places too, until we need it - eg from Filters and Ordering and Limits. We probably only need to support $__from and $__to, and only support those in the timeDimension part of the query. Also done in chore: remove unused dashboard variable interpolation (YAGNI) #73 (only removed from Filter Member. Wasn't present in Ordering or Limit, and works well in Filter Value, and was already used there)

• Then add this feature - the read-only JSON viewer - as a way to ensure no hidden behaviours, and to be up-front with users about what is happening and why. BUT

  • Don't include any support for Filter OR and AND operators yet. That doesn't exist yet, so should go into a future PR

• Then, finally, start extending the app functionality, to make migration of existing SQL panels to Cube easier. For each of these features listed we will:

  • Add support to the Panel JSON, so LLMs can migrate there successfully
  • Add it to the feature-detection list (detecting features not supported by the visual editor), so we avoid silent/hidden behaviour
  • But don't add it to the visual editor. These are advanced features, and can be migrated to the visual editor later

  The features we need support for in the Panel JSON for LLMs to migrate panels over are:

  • Filter greater than > operator. Indeed all filter operators. This will also require updating the filter validation code, which currently removes filters that are equals|notEquals but where their list of values is empty
  • The AND/OR operator for filters.
    • AND/OR particularly important where conditions are somewhat independent, such as "in EMEA OR qualified lead", as this result can't be calculated easily with math. It can be done I guess with A = "EMEA", B = "qualified lead, not EMEA", then result is $A + $B, but this is more likely both to attract bugs and to trip up the LLM.

At that point we should be able to migrate panels quickly and easily, and won't:

• See differences vs the original panels (thx to the > operator and other filter operators existing)
• Need extra SSEs such as the Math or SQL SSE. At least we'll be able to use OR to replace math with $A + $B

We'll probably still need:

• math for dividing to calculate fractions/percentages: $A / $B)
• Grafana Transforms, to rename fields

Open questions:

• Filters on measures? Not sure if we'll find we need these. We'll cross that bridge when we come to it.

[samjewell]

Implementation Note: Allowlist vs Blocklist for detectUnsupportedFeatures

When we implement this, we'll need to decide between two approaches:

Blocklist (detect unsupported patterns)

if (hasTimeDimensions) issues.push('Time dimensions');
if (hasFilterGroups) issues.push('OR/AND filter groups');
if (hasDollarInDimensions) issues.push('Template variables in dimensions');
// Everything else → visual mode

Pros: Simpler to implement - just check for specific patterns we know are unsupported.

Cons: Permissive by default. Typos, invalid dimension names, and other malformed input will still go to visual mode, where:

• The visual builder may hide unknown values (showing empty dropdowns)
• The query runs and Cube returns an error
• Users see both a broken UI and an API error

Allowlist (detect supported structure)

const isSupported = 
  hasOnlySimpleDimensions(query) &&
  hasOnlySimpleMeasures(query) &&
  hasOnlyFlatFilters(query) &&
  hasOnlySupportedOperators(query) &&
  hasNoTimeDimensions(query);

if (!isSupported) → JSON mode

Pros: Defensive by default. Anything we haven't explicitly blessed gets JSON mode, which shows the actual configuration.

Cons: Requires defining the complete "shape" of a supported query. More code to maintain as visual builder capabilities grow.

---

We haven't decided which approach to take yet. Worth discussing when we pick this up.