Manage SQL workbooks and data dashboards

Save SQL, maintain draft and finalized versions, and create, run, update, refresh, and delete data dashboards and charts. This page does not execute arbitrary SQL; to execute SQL and inspect its results, see Execute SQL and manage SQL metadata.

Prerequisites

Prepare credentials that can access the target workspace and existing object IDs required for saved SQL, chart, or dashboard operations. For service endpoints, authentication, and general request formats, see Prepare to call an API.

Before modifying, finalizing, deleting, running, or updating, obtain target IDs from saved-SQL records, versions, or data-dashboard lists and details.

Call sequence

  1. Query saved SQL and versions to determine whether to create a saved record, create a draft, or modify an existing version.

  2. Finalize a version when you need to preserve it, then confirm the target version through its content.

  3. After creating a data dashboard, create or update charts. To generate chart SQL from a natural-language question, generate an SQL draft first. Preview chart SQL before running or refreshing a chart when needed.

  4. Query or download chart results to confirm output. Delete charts, dashboards, or saved SQL only when they are no longer needed.

API operations

Save SQL and manage versions

What you need to do

API operation

Use it when

View saved SQL

List SQL workbooks

Find a saved-SQL record or obtain a target ID.

Create a saved-SQL record

Create a SQL workbook

Add a saved-SQL record.

Rename a saved-SQL record

Update a SQL workbook

Adjust a saved-record name.

Delete a saved-SQL record

Delete a SQL workbook

You confirmed that the record is no longer needed.

View saved-SQL versions

List SQL workbook versions

Find an existing version or obtain a version ID.

View saved-SQL version content

Get SQL workbook content

Inspect a specified version’s content.

Create a SQL draft version

Create a SQL workbook draft

Add a draft version.

Modify a SQL draft version

Update a SQL workbook draft

Adjust draft content.

Finalize a SQL version

Finalize a SQL workbook version

Finalize a target version.

Manage data dashboards and charts

What you need to do

API operation

Use it when

Query data dashboards

List data dashboards

Find a dashboard or obtain a target ID.

Create a data dashboard

Create a data dashboard

Add a data dashboard.

Query dashboard details

Get data dashboard details

Inspect current information for one dashboard.

Update a data dashboard

Update a data dashboard

Adjust an existing dashboard.

Delete a data dashboard

Delete a data dashboard

You confirmed that the dashboard is no longer needed.

Create a chart

Create a dashboard chart

You identified the target dashboard and need to add a chart.

Update a chart

Update a dashboard chart

Adjust an existing chart.

Delete a chart

Delete a dashboard chart

You confirmed that the chart is no longer needed.

Generate chart SQL draft

Generate dashboard chart SQL draft

Generate and validate a read-only SQL draft from a natural-language question.

Preview chart SQL

Preview dashboard chart SQL

Inspect chart SQL before running it.

Run a chart

Run a dashboard chart

Run one chart.

Refresh all charts

Refresh all dashboard charts

Refresh every chart in a dashboard.

Query chart results

Get a dashboard chart result

Inspect chart output.

Download chart results

Download a dashboard chart result

Obtain chart results.

Confirm the result

After creating, modifying, or finalizing SQL, query the saved record, version list, and version content to confirm the target version. After creating, updating, running, or refreshing a dashboard, use Get data dashboard details to confirm dashboard information and Get a dashboard chart result to inspect chart output.

Limitations and notes

  • Saved-SQL records, draft versions, finalized versions, data dashboards, and charts are different objects. Confirm the IDs you hold before calling an API.

  • Running or refreshing a chart does not mean its result is readable. Use the chart-result query to confirm.

  • Before deleting a saved record, dashboard, or chart, confirm its impact scope.

Next steps

Last updated on