BlazeSQL

Save a BlazeSQL-compatible graph from an executed SQL result and add it as a dashboard tile. Use only when the user asks to add/save the graph to a dashboard or clearly names a dashboard target. Do not use dashboard tools as ordinary data discovery; for normal data questions, use schema discovery and execute_sql first. Prefer query_request_id from execute_sql so the saved dashboard graph matches the result shape you already inspected. If the user names a dashboard but not its ID, use list_dashboards/search_dashboards only to identify that specific dashboard. dynamicChartCode is optional and stored on the saved BlazeSQL query for custom chart rendering in the app. Use helpers.theme for theme-aware neutral colors: backgroundColor, secondarySurfaceColor, textColor, secondaryTextColor, borderColor, gridColor, and accentColor. Use helpers.theme.secondarySurfaceColor for tooltip or raised-surface backgrounds. These values automatically follow the host app's light, dark, or custom theme. Use helpers.theme.borderRadius, which is 4, as the default corner radius for containers and chart marks. For Plotly bar charts, use marker.cornerradius: helpers.theme.borderRadius; helpers.renderPlotly also applies this default when it is omitted. The widget already shows graphConfig.name above the chart. Do not repeat that name in Plotly layout.title; reserve the chart title area for a genuinely different note. When a horizontal legend sits below a chart that has an x-axis title, place the legend at y: -0.32 or lower and leave at least 100px of bottom margin so the labels do not overlap. For click drill-downs that reveal a list of records or items, keep the widget's outer size stable: replace the chart with a separate detail page inside the same container, include a clear Back control that restores the chart, and do not append the list below or beside the chart. In Codex, visualization iframes are content-sized rather than given a stable height to fill. For non-map Plotly charts, always return helpers.renderPlotly({ data, layout, config }); do not call Plotly.newPlot directly or set height, min-height, or aspect-ratio on the container or chart root. Let the helper establish and report the chart height while the width stays responsive. helpers.renderPlotly clears the visualization container and returns a Promise that resolves to the rendered chart element. Attach Plotly click handlers in .then((chartElement) => { ... }); for a same-size drill-down, measure that rendered chart only when opening the detail page, scroll inside the detail page, and call Plotly.Plots.resize(chartElement) when restoring the chart.

add_graph_to_dashboard

Internal: Returns live progress updates for the currently running BlazeSQL query. Intended for the BlazeSQL UI only.

blazesql_query_progress

Check the status of a long-running BlazeSQL query or SQL execution. Use when blazesql_query or execute_sql returns a job_id indicating the work is still running.

check_query_status

Deprecated compatibility-only tool. Do not use this tool for new requests. Use list_schemas, list_tables, and describe_tables to understand the database, then use execute_sql. This tool remains registered only so conversations using the previously published BlazeSQL ChatGPT tool contract can complete successfully.

blazesql_query

Return full metadata (columns, data types, descriptions, knowledge notes) for specific tables in the selected BlazeSQL database. Provide each table as an exact reference, preferably schema.table (e.g. public.orders). A bare table name works only when it is unique across schemas. Use this before writing SQL against specific tables.

describe_tables

Execute one read-only SQL statement against the selected BlazeSQL database, or execute an existing saved/dashboard query by query_id. Provide exactly one of query or query_id. Format raw SQL for readability with appropriate line breaks and consistent indentation. For ordinary data questions, write SQL in query after schema discovery. Use query_id only when the user specifically asks to run an existing saved query/dashboard tile or has selected one. To learn the schema, use the schema discovery tools (list_schemas, list_tables, describe_tables) — do NOT use execute_sql for schema discovery (e.g. information_schema, SHOW TABLES/COLUMNS, pg_catalog), unless the user explicitly asks for it or you are debugging a specific schema/metadata discrepancy. Use describe_tables first when you need table or column names. When passing raw SQL in query, include the user's original request and a step-by-step rationale for observability. When passing query_id, original_user_request and rationale are optional. If the user asks for a graph or chart, run execute_sql first, inspect the returned rows and requestId, then call graph_sql_result with that query_request_id.

execute_sql

Create a dynamic graph from an already completed SQL result. Use this after execute_sql, once you have inspected the returned rows and requestId. Provide exactly one of query_request_id or query_id. Prefer query_request_id from execute_sql so the graph is based on the exact result the user just saw. query_id can execute and graph an existing saved BlazeSQL query. Use graphType, xAxisVariable, yAxisVariable, groupByVariable, and stacked when they map to BlazeSQL graph settings. Make the visualization interactive by default with hover/focus tooltips on chart marks. For graphType map, use the built-in helpers.createWorldBubbleMap helper for tile-backed country, city, or local bubble maps. In dynamicChartCode, data.rows is an array of objects keyed by column name; use row.date or row.metric_name, not row[0]. Use helpers.theme for theme-aware neutral colors: backgroundColor, secondarySurfaceColor, textColor, secondaryTextColor, borderColor, gridColor, and accentColor. Use helpers.theme.secondarySurfaceColor for tooltip or raised-surface backgrounds. These values automatically follow the host app's light, dark, or custom theme. Use helpers.theme.borderRadius, which is 4, as the default corner radius for containers and chart marks. For Plotly bar charts, use marker.cornerradius: helpers.theme.borderRadius; helpers.renderPlotly also applies this default when it is omitted. The widget already shows graphConfig.name above the chart. Do not repeat that name in Plotly layout.title; reserve the chart title area for a genuinely different note. When a horizontal legend sits below a chart that has an x-axis title, place the legend at y: -0.32 or lower and leave at least 100px of bottom margin so the labels do not overlap. For click drill-downs that reveal a list of records or items, keep the widget's outer size stable: replace the chart with a separate detail page inside the same container, include a clear Back control that restores the chart, and do not append the list below or beside the chart. In Codex, visualization iframes are content-sized rather than given a stable height to fill. For non-map Plotly charts, always return helpers.renderPlotly({ data, layout, config }); do not call Plotly.newPlot directly or set height, min-height, or aspect-ratio on the container or chart root. Let the helper establish and report the chart height while the width stays responsive. helpers.renderPlotly clears the visualization container and returns a Promise that resolves to the rendered chart element. Attach Plotly click handlers in .then((chartElement) => { ... }); for a same-size drill-down, measure that rendered chart only when opening the detail page, scroll inside the detail page, and call Plotly.Plots.resize(chartElement) when restoring the chart.

graph_sql_result

List dashboards the user can access through creator, direct, team, or access-group sharing. Not for ordinary data questions; use schema tools and execute_sql unless the user asks for dashboards/reports. Returns dashboard IDs, names, descriptions, BlazeSQL URLs, access info, tile counts, selected-database query tile counts, timestamps, and refresh settings.

list_dashboards

List the schemas in the selected BlazeSQL database, with schema descriptions and table counts. If the database has a single visible schema, its tables are listed too. If the full schema is small enough, the complete table/column metadata (including knowledge notes) is included automatically. Start here to discover the database, then narrow with list_tables for a schema, then describe_tables for specific tables before writing SQL.

list_schemas

List the tables in the selected BlazeSQL database, with table descriptions and column counts. Requires one or more schema names from list_schemas. If the returned table set is small enough, the complete table/column metadata (including knowledge notes) is included automatically. Use describe_tables to get full metadata for specific tables before writing SQL.

list_tables