SQL Editor¶

The SQL editor is AI Studio’s interactive query workbench for structured data in a workspace. It lets you browse accessible databases and tables, write and run SQL, view results and charts, and preserve valuable queries as reusable workbooks.

It is suitable for exploration, validation, and analysis. When a piece of SQL becomes stable processing logic that must run repeatedly, place it in a SQL node in a workflow.

What the Editor Helps You Do¶

Task	How the SQL editor helps
Understand data	View databases, tables, views, and field information in the database tree
Validate quickly	Write SQL against the current table and immediately inspect returned rows, duration, and errors
Analyze results	Switch results between table and chart views to quickly examine trends, comparisons, and distributions
Preserve query assets	Save workbooks by topic and maintain draft and finalized versions
Reproduce issues	Use SQL text, execution status, and query history to diagnose anomalies
Connect externally	View and copy the workspace database connection string when you have the required permission

The SQL editor shows only database objects accessible to the current user in the current workspace. If a table is not visible, first confirm that you are in the correct workspace, then check object permissions and the selected database rather than assuming the table was deleted.

Understanding the Interface¶

The page generally consists of three coordinated areas: the database/workbook tree on the left, the SQL editing area in the center, and the results and charts area at the bottom. You can expand, collapse, or resize these areas as needed.

Area	Purpose	Common actions
Database	Browse and search databases, tables, views, and fields	Select a database, expand objects, search, refresh, and view fields
Workbook	Manage savable query collections	Create, rename, search, switch, and delete workbooks
SQL editing area	Write, select, and run SQL	Edit the current statement, select a fragment, run it, and view draft status
Results area	View each statement’s status, table results, and charts	Switch result tabs, terminate execution, download, minimize, or maximize

A recommended habit is to confirm objects and fields in the database tree first, write the smallest verifiable SQL in the editing area, and then save the validated query to a workbook.

Browsing Databases and Fields¶

The database tree is organized by objects currently accessible in the workspace. It helps you confirm actual database and table names, object hierarchy, and field structure before writing SQL, avoiding table or field names recalled incorrectly from memory.

Basic Operations¶

Select the database you want to use on the “Database” tab on the left.
Expand the database or object to locate the target table, view, or other queryable object.
Use “Search databases or tables” to filter the object tree quickly.
Click a table to view field names, data types, and other column information provided by the interface.
After a data structure is created, deleted, or modified, refresh the object tree.

The table schema is the source of truth when writing SQL. For result tables produced by workflows or loading tasks, confirm field names, types, and sample content before using aggregation, joins, or write-back statements.

Writing and Running SQL¶

Enter SQL in the central editing area. The editor supports line numbers, syntax highlighting, and multi-statement text. When executing, it identifies the statement range from the current cursor position or selected content.

Recommended Validation Rhythm¶

Start with a limited SELECT to check fields, filter conditions, and result counts.
Then add joins, aggregations, window functions, or transformation logic.
Before writes or schema changes, confirm the target database and table, affected scope, and current user’s permissions.
After execution, inspect each statement’s results, status, and duration. If an error occurs, read the complete error message first.

When placing multiple statements in one workbook, separate them clearly with semicolons. The results area creates a separate result tab for each statement in the current execution so you can inspect them individually.

Exercise Caution with Write Operations¶

Statements such as CREATE, ALTER, DROP, INSERT, UPDATE, and DELETE affect real workspace assets. Before running them, confirm the target object, permissions, and downstream impact, especially for shared tables, workflow output tables, and tables on which knowledge bases depend.

If write SQL will run periodically or in batches, do not rely on manual clicks indefinitely. First validate its logic and idempotency in a workbook, then design it as a workflow SQL node with an explicit target table, write mode, and execution record.

Selecting the Right Compute Resource¶

Queries in the SQL editor use query compute resources. The resource determines whether a query can run, the data scale it can handle, and the workspace’s runtime cost.

Situation	Recommendation
Ad hoc table lookup or limited validation	Use the workspace’s available default query resource
Large-scale aggregation, complex joins, or long-running analysis	Confirm resource status and specifications, and use a suitable dedicated query resource if necessary
A query remains queued, fails, or is unusually slow	Check the SQL and data scale first, then check resource status, capacity, and concurrent load

Parsing, embedding, and other non-SQL data processing use task compute resources and should not be substituted with SQL query resources. See Compute resources for selection principles for both resource types.

Viewing Results, Status, and Errors¶

After execution, the results area at the bottom displays query results, execution status, returned row count, duration, and other information. Multiple statements produce multiple result tabs; long-running statements can be terminated when the interface allows it.

Information	Question it helps answer
Running/succeeded/failed/terminated	What state is the current statement in, and should you wait, fix, or rerun it?
Returned and displayed row counts	Does the result size meet expectations, and is the interface displaying only part of it?
Duration	Does the query have an obvious performance problem?
Error message	Does the problem come from SQL syntax, a missing object, permissions, resources, or data?
Query details	What context should be retained to reproduce, compare, or further diagnose the query?

The number of rows shown in the results area may be limited by the current query and page display policy. To retain complete business results, use the download capability actually provided by the page, or write validated results to a governed Catalog object.

Using Charts to Understand Results Quickly¶

The results area provides chart views for quickly assessing trends, category comparisons, proportions, and correlations without leaving the editor. They support exploration and communication, but do not replace formal metric governance or business reporting.

Chart	Better suited for observing
Bar chart	Numerical comparisons across categories or groups
Line chart	Time series and continuous trends
Pie chart	Proportions within a whole
Scatter plot	Distribution or correlation between two numeric fields
Area chart	Cumulative trends or changes across multiple series

After switching to charts, select a chart type and configure result columns for the X and Y axes. The Y axis should generally use numeric fields, with an aggregation method set as needed. For multiple series, add multiple columns for comparison.

Chart quality depends on the granularity of the SQL results. If details and aggregate rows are mixed, dates are unsorted, or numeric columns are treated as text, the chart will be misleading. Return to the SQL and correct the data shape first.

Downloading Query Results¶

Query results can be downloaded when the results area provides a download option. Availability depends on the current query status, returned results, and permissions; the page displays a corresponding notice when results cannot currently be downloaded.

Downloaded files must be used only in ways that comply with workspace data governance requirements. Before exporting, check whether they contain sensitive fields, personal information, or restricted business data, and avoid bypassing object permissions and sharing processes.

To continuously send large amounts of data to external systems, use Data export or a designed workflow rather than repeatedly downloading query results manually.

Workbooks: Making SQL a Reusable Asset¶

A workbook is a named, savable collection of SQL queries. It helps teams organize queries by project, topic, or data product instead of scattering valuable SQL across browser tabs and personal clipboards.

Routine Workbook Operations¶

Operation	Purpose
Create	Create a separate SQL space for a new analysis topic
Rename	Use a business-oriented name to describe the object or question the workbook serves
Search	Quickly locate existing query assets when many workbooks exist
Switch	Open another workbook and load its latest editable content
Delete	Remove an unneeded workbook; the system retains at least one workbook

The editor saves workbook drafts. To continue changing a finalized version, create a new draft version instead of rewriting historical content directly. This preserves how the query evolved and lets you revisit previously validated versions.

Organizing a Good Workbook¶

Keep each workbook focused on one business topic, such as “contract extraction quality checks” or “daily sales summary.”
Use SQL comments to explain data sources, key assumptions, and output definitions.
Separate exploratory SQL from formal validation SQL to avoid accidentally running write operations.
Identify SQL that must run repeatedly over time and migrate it to a workflow after validation.
Retain finalized versions of critical queries so historical conclusions remain reproducible after changes.

Security Boundaries for Connection Strings¶

The toolbar can open the SQL connection-string window for connecting to the current workspace database from an authorized terminal or client. Before copying, confirm that the destination environment is secure and that the connection string will not be pasted into chat records, tickets, screenshots, or public documents.

A connection string provides database connection information; it does not replace AI Studio workspace permissions, Catalog governance, or workflow execution records. SQL executed from external clients must follow the same data-access and change-management rules.

SQL Troubleshooting Order¶

Problem	First action	Then go to
Object or field does not exist	Return to the database tree and verify the database, table, and field names, as well as the currently selected database	Catalog
Permission denied	Confirm the workspace, object permissions, and current role	User permissions
Statement fails	Read the complete error in the results area and reduce it to the smallest reproducible SQL	Continue validating in the SQL editor
Query is slow	Check filters, joins, scan scope, and result size	SQL History
SQL in a workflow fails	Open job details and inspect node parameters and runtime inputs	Run and Debug
DDL/DML impact exceeds expectations	Stop subsequent operations and confirm the object and downstream dependencies	Catalog · Operation Logs

Division of Responsibilities with Workflows¶

SQL editor	Workflow SQL node
Suitable for interactive exploration, rapid validation, visualization, and preserving queries in workbooks	Suitable for placing stable SQL in an executable, schedulable, and observable processing chain
The runner directly selects statements and views immediate results	At runtime, it is driven by the saved DSL, parameters, resources, and trigger policy
Focuses on understanding data and validating logic	Focuses on productionization, rerunnability, and coordination with other nodes

The recommended path is to confirm the data and logic in the SQL editor first, then migrate established processing steps into a workflow. After execution, cross-check problems through jobs and SQL history.

Next Steps¶

To turn stable queries into a data production chain, read Workflow and Workflow nodes.
To diagnose query performance, results, or execution plans, read SQL History.
To understand how SQL, workflows, and Catalog combine into typical solutions, read Processing patterns.