SQL expressions in VISUALISE mappings silently consumed as SQL instead of reporting parse error

[cpsievert]

Summary

When a ggsql query contains a SQL expression (like CAST(...)) inside a VISUALISE mapping, the parser does not report an error. Instead, it silently treats the entire query — including the VISUALISE clause — as plain SQL. The validate() result reports valid() = True, errors() = [], but has_visual() = False and visual() = ''.

This makes it very difficult for callers to diagnose what went wrong: the query appears valid but has no visual component, even though the user clearly intended to create a visualization.

Reproducible example

import ggsql

query = """SELECT sex, survived, COUNT(*) AS n FROM titanic GROUP BY sex, survived
VISUALISE sex AS x, n AS y, CAST(survived AS VARCHAR) AS fill
DRAW bar"""

result = ggsql.validate(query)
print("valid:", result.valid())        # True
print("errors:", result.errors())      # []
print("warnings:", result.warnings())  # []
print("has_visual:", result.has_visual())  # False
print("visual:", repr(result.visual()))    # ''
print("sql:", repr(result.sql()))          # entire query including VISUALISE

Expected behavior

ggsql.validate() should report an error or warning when it encounters a non-column-name expression (like CAST(...), function calls, or other SQL expressions) in a VISUALISE or MAPPING position. Something like:

Error: unexpected expression in VISUALISE mapping at 'CAST(survived AS VARCHAR)'.
VISUALISE mappings accept column names only. Move data transformations to the SELECT clause.

At minimum, if valid() returns True but the raw query text contains the VISUALISE keyword and has_visual() returns False, a warning should be surfaced via warnings().

Context

This came up when integrating ggsql with an LLM-powered tool. The LLM frequently generates queries like this — putting CAST() inside VISUALISE instead of in the SELECT clause. The silent failure makes it hard to provide useful error feedback to guide the LLM toward a corrected query.

The correct version of the query above would be:

SELECT sex, CAST(survived AS VARCHAR) AS survived, COUNT(*) AS n FROM titanic GROUP BY sex, survived
VISUALISE sex AS x, n AS y, survived AS fill
DRAW bar

[cpsievert]

I had Claude dig into the grammar and Rust source to understand why this happens and propose a couple fix options:

Why the silent failure occurs

The tree-sitter grammar defines VISUALISE mapping sources as strictly column references (single identifiers) or literal values — no SQL expressions are allowed:

// grammar.js
mapping_value: $ => choice(
  $.column_reference,  // single identifier
  $.literal_value      // string, number, boolean, null
),

When the parser encounters CAST(survived AS VARCHAR) AS fill in a VISUALISE position, it can't parse it as a mapping_value. Instead, the preceding select_body rule (which greedily matches SQL tokens via prec.left(repeat1(...))) consumes the entire CAST(survived AS VARCHAR) AS fill expression as part of the SQL column list. The VISUALISE keyword that follows is what terminates select_body, so the parser sees:

• SQL portion: everything up to and including CAST(survived AS VARCHAR) AS fill
• VISUALISE portion: the mappings after VISUALISE that don't contain the CAST

In the reported example, this means the VISUALISE clause loses the fill mapping entirely, and depending on how the remaining tokens parse, the visual portion may end up empty — which is exactly what we see (has_visual() = False, visual() = '').

Option A: Support SQL expressions in VISUALISE mappings

This is hard due to AS ambiguity. In CAST(survived AS VARCHAR) AS fill, there are two AS tokens — one is part of the SQL cast syntax, the other is the ggsql aesthetic mapping delimiter. The parser can't distinguish them without either:

• Changing the mapping delimiter to something other than AS (e.g., -> or =>)
• Special-casing every SQL expression type that uses AS internally

Both are significant grammar changes with broad consequences.

Option B: Better validation (recommended)

A post-parse heuristic in validate.rs would catch this cleanly. After parsing, if the source text contains the VISUALISE/VISUALIZE keyword but has_visual() returns false (or the visual portion is empty), emit an error or warning. For example:

// In validate.rs, after building the AST
if !source_tree.has_visual() {
    let upper = source.to_uppercase();
    if upper.contains("VISUALISE") || upper.contains("VISUALIZE") {
        return Err(GgsqlError::ValidationError(
            "VISUALISE clause was not recognized. \
             Mappings accept column names only — not SQL expressions like CAST(). \
             Move data transformations to the SELECT clause, \
             then reference the resulting column by name in VISUALISE.".into()
        ));
    }
}

This could be refined further by inspecting the SQL portion's text for SQL-expression-like tokens (CAST, function calls with parentheses) near the boundary to give an even more specific diagnostic.

This approach is low-risk, requires no grammar changes, and directly addresses the confusing silent failure.