create_smart_visual

Create a CDV chart visual that reliably renders data without SQL errors.

This tool only exposes visual types and column configurations that are confirmed to work through the CDV API. Unsupported patterns are rejected with a clear error and guidance on what to use instead.

SUPPORTED visual_type values:

• "trellis-bars" Best for one measure vs. one dimension (horizontal bars).

• "trellis-groupedbars" One SUM measure grouped by a color dimension.

• "pie" One SUM measure broken down by one dimension.

NOT SUPPORTED via this tool (use CDV's interactive builder instead):

• trellis-lines, trellis-areas (time-series; timestamp dimensions fail via API)

• scatter, histogram, boxplot (require CDV builder shelf configuration)

• table, crosstab (use query_dataapi for tabular results)

• All other chart types

Each entry in columns must have:

• column_name (str, required): exact column name in the dataset.

• aggregate_function (str, optional): sum | avg | min | max Columns WITH this field are measures; columns WITHOUT are dimensions. IMPORTANT: "count" is not supported — use "sum" on a numeric column instead.

• shelf (str, optional): explicit shelf override. Use "color_shelf" to add a grouping/color dimension to bar or pie charts.

COLUMN COMPATIBILITY RULES (enforced, CDV-side constraints):

• At least one measure (column with aggregate_function) is required.

• Column names that start with avg_, sum_, min_, max_, count_ CANNOT be used as aggregate targets (CDV's tokenizer confuses them with functions). Example: avg(avg_lead_time_days) fails. Use a different column.

• Date/timestamp columns (names with "date", "time", "year", etc.) should NOT be used as dimensions — CDV fails to generate valid SQL for them. Use CDV's builder for time-series charts.

FILTERS ARE NOT SUPPORTED: CDV's filter SQL generation always produces bracket notation in the WHERE clause that Impala cannot parse. After creating the visual, open it in CDV's interactive builder to add filters manually.

EXAMPLES:

Total spend by supplier (bar chart): columns=[ {"column_name": "supplier_name"}, {"column_name": "total_price", "aggregate_function": "sum"}, ]

Supplier spend grouped by priority (grouped bar): visual_type="trellis-groupedbars", columns=[ {"column_name": "supplier_name"}, {"column_name": "priority_code", "shelf": "color_shelf"}, {"column_name": "total_price", "aggregate_function": "sum"}, ]

Spend breakdown by item (pie chart): visual_type="pie", columns=[ {"column_name": "item_description"}, {"column_name": "total_price", "aggregate_function": "sum"}, ]

VISIBILITY: Chart visuals do NOT appear in the CDV workspace until you call create_dashboard() with their IDs. Always follow up with create_dashboard().

Returns the created visual's metadata including its id, visual_id, and url.