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 Make your first AI Studio API call.

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

Task

Use it when

View saved SQL

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

Create a saved-SQL record

Add a saved-SQL record.

Rename a saved-SQL record

Adjust a saved-record name.

Delete a saved-SQL record

You confirmed that the record is no longer needed.

View saved-SQL versions

Find an existing version or obtain a version ID.

View saved-SQL version content

Inspect a specified version’s content.

Create a SQL draft version

Add a draft version.

Modify a SQL draft version

Adjust draft content.

Finalize a SQL version

Finalize a target version.

Manage data dashboards and charts

Task

Use it when

Query data dashboards

Find a dashboard or obtain a target ID.

Create a data dashboard

Add a data dashboard.

Query dashboard details

Inspect current information for one dashboard.

Update a data dashboard

Adjust an existing dashboard.

Delete a data dashboard

You confirmed that the dashboard is no longer needed.

Create a chart

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

Update a chart

Adjust an existing chart.

Delete a chart

You confirmed that the chart is no longer needed.

Generate chart SQL draft

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

Preview chart SQL

Inspect chart SQL before running it.

Run a chart

Run one chart.

Refresh all charts

Refresh every chart in a dashboard.

Query chart results

Inspect chart output.

Download chart results

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