Database

Tired of writing SQL or asking the data team every time you need to analyze internal data? DbSphere auto-converts natural language to SQL to query databases. Ask “show me this month’s sales” and the AI generates SQL, executes it, and responds with the results in natural language and a table, visualizing them as a chart on request.

Example

“Compare sales by department this quarter”

Method	Process	Time
Write SQL yourself	Write SQL → execute → interpret	10–30 min
Ask the data team	Request → wait → receive	Hours to days
DbSphere	Natural-language question → instant answer + chart	10 sec

Database list — View connected DBs in Workspace > Database

NL-to-SQL Pipeline

Stage	Description
Schema analysis	The AI analyzes connected table structure and column descriptions
SQL generation	Converts the natural-language question to SQL in the right DB dialect
Safety check	Read-only by default — runs SELECT and blocks INSERT, UPDATE, DELETE, and DDL. Turning on Allow data modifications for a database permits writes, but every call goes through user approval (Data Modification Control)
Run query	Executes validated SQL on the database
NL response	Converts query results to natural-language text or chart

Supported Databases

10 databases are supported by default.

Database	Type	Strengths
PostgreSQL	RDBMS	Advanced features, JSON support, open-source
MySQL	RDBMS	Most widely used RDBMS
Microsoft SQL Server (MSSQL)	RDBMS	Enterprise environments
Oracle	RDBMS	Large enterprise
SQLite	RDBMS	Lightweight embedded database
Snowflake	Cloud DW	Cloud data warehouse
BigQuery	Cloud DW	Google Cloud data warehouse, service account key auth
Databricks	Lakehouse	Databricks SQL Warehouse, Delta Lake integrated
Azure Synapse	Cloud DW	Azure unified analytics platform
Microsoft Fabric	Lakehouse / DW	Power BI integrated analytics environment

All 10 are enabled by default. Admins can narrow or expand the visible list with the DBSPHERE_TYPES environment variable.

Connect a Database

Enter basic information

In Workspace > Database, click + New Database to open the create form. Enter a name and description, then set the permission.

Database creation form — Enter name, description, and permissions

Field	Description	Example
Name	Connection display name	”Sales Analytics DB”
Description	Database purpose	”Sales team revenue data”
Permission	Public / Private. If private, pick targets in the Groups card below	Private + “Sales”

Enter connection info

In DB Information, click Configure to enter the credentials needed to connect to the database. The required fields depend on the database type.Common fields:

Field	Description
Host	DB server address
Port	Connection port
Database	DB name to connect to
Username	DB account
Password	DB password
Max query time	Query timeout in seconds. Leave blank to use the server default

Per-DB additional fields

Beyond the common fields (host, port, database, username, password, max query time), each DB type adds the fields below.

DB Type	Additional Fields	Notes
MySQL	—	Common fields only
MSSQL	Schema	Schema name (default: `dbo`)
PostgreSQL	Schema	Schema name (default: `public`)
Snowflake	Account, Warehouse, Role, Schema	No host/port needed
Oracle	Schema, Service Name, SID	Use Service Name or SID instead of Database
SQLite	Database file	No host/port/auth — only the file path
Databricks	Server hostname, HTTP path, Access token, Catalog, Schema	Delta Lake / SQL Warehouse
Synapse	Schema	Schema name (default: `dbo`)
Fabric	Schema	Schema name (default: `dbo`)
BigQuery	Project ID, Dataset, Service Account JSON	No host/port/username/password needed

Test connection

Click “Test Connection” to verify access.

Pick tables

After successful connection, select tables the AI will reference.

Table selection — Select only tables the AI should access — exclude tables with sensitive data

Always exclude tables containing sensitive info (PII, passwords, etc.). Selected tables are accessible by the AI.

Set tool description (optional)

Write a tool description that tells the agent when and how to use this database.AI auto-generation: Click the auto-generate button next to the tool description field — the AI drafts it based on connected table structure and column info.

Example tool description

This database holds the sales team's order, customer, and inventory info.
Use for revenue analysis, customer lookup, inventory checks, and similar.
JOIN the orders table with the customers table
to get per-customer purchase history.

The more accurate the tool description, the more accurately the agent picks the right database among many.

Set access permissions

Click the lock button at the top to set who can use the database.

Option	Description
Public	Available to all users
Private	Available only to you
Group	Available only to members of the specified groups

Activity History

Click Activity History at the top of the database detail screen to see changes made to this database in chronological order. Each row shows the action · who did it · the target · the exact timestamp, with the total count at the bottom of the dialog. Use it to trace when the connection details or table selection changed.

How the AI Generates SQL

When you connect a DB to an agent, user questions go through this process to become SQL.

Successful queries auto-accumulate in memory. The more you use it, the more accurate SQL the AI generates for similar questions.

Memory System

DbSphere uses 4 types of memory to improve SQL generation accuracy. The more memory, the more accurate the AI’s queries.

Memory	Badge	Content	Creation
DDL Schema	DDL Schema	Table structure + column descriptions	Auto on schema extraction
SQL Few-shot	SQL Few-shot	Question-SQL pairs (past successful queries)	Auto-accumulated on query success
Documentation	Documentation	Business terms, rules, context	Manual entry
SQL Example	SQL Example	Reference SQL examples (use case, tags)	Manual entry or auto on extraction

Memory list — Manage 4 memory types in the Memory tab

Improve Accuracy with DDL Schema Descriptions

Adding business descriptions to the tables and columns in DDL Schema memory greatly improves the AI’s SQL generation accuracy. After schema extraction, go to Memory tab → click DDL Schema → Edit and enter descriptions for each table and column.

DDL schema description input — Enter table and column descriptions under Memory tab → DDL Schema → Edit

You can also configure the LLM to auto-generate table/column descriptions and sample Q&A during schema extraction. Reviewing and correcting the auto-generated results improves accuracy further.

Example schema description

Table: orders
Description: Order history table
Columns:
- order_id: Unique order number
- customer_id: Customer ID (references customers table)
- order_date: Order timestamp
- total_amount: Total order amount (KRW)
- status: Order status (pending/confirmed/shipped/delivered)

SQL Few-shot is Key

SQL Few-shot is a few-shot learning memory where successful queries are auto-saved.

Use Count	SQL Few-shot	AI Behavior
First	0	Guess SQL from schema only
5	5	Generate referencing similar past queries
50+	50+	Generate accurate SQL using validated patterns

Documentation Use

Tell the AI about business rules it doesn’t know via Documentation.

Type	Example
Term	”MRR is the abbreviation for Monthly Recurring Revenue, stored in the monthly_revenue column”
Rule	”When aggregating revenue, orders with status=‘cancelled’ must be excluded”
Context	”Customer tiers are 4 levels: S/A/B/C, with S being the highest”

When the AI repeatedly generates wrong SQL with a recurring pattern, add the rule to Documentation. The AI references it from the next question onward.

Data Visualization

SQL results are provided as a table by default. When you ask (e.g., “show me a chart”), they’re visualized with a chart suited to the data, and you can switch directly via the chart-type toggle at the top of the results.

Chart Type	Suitable Data
Bar	Comparison by category
Line	Time-series trend
Pie	Ratio / composition
Scatter	Correlation
Heatmap	Cross analysis
Histogram	Distribution
Grouped bar	Multi-dimensional comparison
Table	Detailed data

When you request a chart, the chart type that fits the data structure is recommended and auto-selected, and you can switch to another type via the top toggle.

Querying Databases

Connect to an Agent

In the agent edit screen, click “Select Database” in the “Database” section
Pick the database to connect
Click Apply

Use in Chat

When you chat with an agent that has databases connected, the AI analyzes the question and auto-generates and runs SQL.

User: What's the revenue growth rate this quarter vs. last?

AI: Quarterly revenue analysis:

| Quarter | Revenue | QoQ |
|---------|---------|-----|
| Q4 2024 | ₩1.25B | - |
| Q1 2025 | ₩1.42B | +13.6% |

This quarter's revenue grew 13.6% QoQ.
Key drivers: new customer acquisition (+23%), repeat-buyer rate up (+8%)

Example Questions

Revenue Analysis
Customer Analysis
Inventory
HR

- What's this month's revenue?
- Show daily revenue trend last week
- List the top 10 customers by revenue
- What's the share of revenue by product category?

- How many new sign-ups this month?
- Show me the VIP customer list
- Which customers haven't purchased in the last 3 months?
- Distribution of customers by region

- List products with inventory below 10
- What products are arriving this week?
- Top 5 products with low inventory turnover

- Show headcount by department
- How many joined/left this month?
- What's the average tenure?

Reviewing SQL Execution Results

A “SQL Query” button appears below the AI response. Click to see the actual SQL run and detailed results.

Feature	Description
View SQL	Show the executed SQL with formatting (uppercase keywords, indentation)
Copy SQL	Copy SQL to clipboard — useful when re-running in a separate query tool
Result table	View query results as a table

Result data is shown up to 100 rows. When the total exceeds 100, a “Showing 100 of N rows” notice appears. If you need the complete data, download it via Export to CSV at the top-right of the chat result table.

DB Dialect Differences

Each DB has slightly different SQL syntax. Cloosphere dynamically injects per-DB dialect rules into the system prompt when converting natural language to SQL, guiding the AI to produce correct SQL. Still, expressing intent clearly produces more accurate SQL.

Key Differences

Item	PostgreSQL	MySQL	Oracle	MSSQL/Synapse/Fabric	SQLite	Snowflake	BigQuery	Databricks
Identifier quoting	`"name"`	`name`	`"NAME"`	`[name]`	`"name"`	`"NAME"`	`name`	`name`
LIMIT expression	`LIMIT n`	`LIMIT n`	`FETCH FIRST n ROWS ONLY`	`TOP n`	`LIMIT n`	`LIMIT n`	`LIMIT n`	`LIMIT n`
Date literal	`'2026-04-26'`	`'2026-04-26'`	`TO_DATE('2026-04-26', 'YYYY-MM-DD')`	`'2026-04-26'`	`'2026-04-26'`	`'2026-04-26'`	`DATE '2026-04-26'`	`'2026-04-26'`
Date format function	`TO_CHAR()`	`DATE_FORMAT()`	`TO_CHAR()`	`FORMAT()`	`strftime()`	`TO_CHAR()`	`FORMAT_DATE()`	`date_format()`
Date arithmetic	`+ INTERVAL '1 day'`	`DATE_ADD(d, INTERVAL 1 DAY)`	`+ 1` (direct)	`DATEADD(day, 1, d)`	`date(d, '+1 day')`	`DATEADD(day, 1, d)`	`DATE_ADD(d, INTERVAL 1 DAY)`	`date_add(d, 1)`
String concat	`\|\|`	`CONCAT()`	`\|\|`	`+`	`\|\|`	`\|\|`	`CONCAT()`	`\|\|`
Empty string = NULL	✗	✗	✓ ⚠️	✗	✗	✗	✗	✗
Case-sensitive identifiers	When quoted ✓	Default ✗	Uppercase by default	Default ✗	When quoted ✓	When quoted ✓	Default ✗	When quoted ✓

System Auto-Correction vs. User Responsibility

Handled automatically:

Dashboard period filter ($st/$ed placeholders): auto-converted to per-DB date literals
Identifier quoting during Knowledge Graph value extraction: auto-selects per-DB quotes
Per-DB dialect rules dynamically injected into the AI’s system prompt (LIMIT, date, identifiers, etc.)

User/AI responsibility:

When you write Korean/special-char column names directly in natural-language queries — the AI may miss quotes and fail
Oracle empty-string comparisons (see Oracle quirks below)
Complex window functions and CTEs vary by DB — verify AI output

Oracle DB Quirks

Oracle has some behaviors that differ from ANSI SQL — worth knowing.

Empty strings are treated as NULL ⚠️

Oracle treats '' (empty string) the same as NULL. So conditions like the following always return 0 rows:

-- ❌ All wrong patterns (Oracle)
WHERE col <> ''
WHERE col = ''
WHERE TRIM(col) <> ''

Correct usage:

-- ✅ Use NULL checks instead
WHERE col IS NOT NULL
WHERE TRIM(col) IS NOT NULL

Cloosphere’s system prompt includes this rule, and the AI auto-avoids it. Still, when natural-language queries use ambiguous phrasing like “non-empty items” and 0 rows are returned, suspect this pattern.

Date literals must use TO_DATE()

Unlike other DBs, Oracle doesn’t auto-cast strings to dates.

-- ❌ Fails on Oracle
WHERE created_at >= '2026-04-01'

-- ✅ Oracle recommended
WHERE created_at >= TO_DATE('2026-04-01', 'YYYY-MM-DD')

BI dashboard period filters ($st/$ed) auto-substitute as TO_DATE(...) when using Oracle. But you must specify it yourself when writing SQL directly in the SQL result screen.

Date arithmetic uses direct ± instead of INTERVAL

-- ❌ Oracle doesn't support INTERVAL '1 day'
WHERE created_at >= SYSDATE - INTERVAL '1 day'

-- ✅ Oracle recommended
WHERE created_at >= SYSDATE - 1

Use TRUNC(col, 'DD') instead of DATE_TRUNC(), and TO_CHAR(col, 'D') instead of EXTRACT(DOW FROM col) for day-of-week.

Quoting Korean/special-char column names

In Oracle, using a Korean column alias (AS 공장코드) directly causes ORA-00936: missing expression.

-- ❌ Fails on Oracle
SELECT plant_code AS 공장코드 FROM plants

-- ✅ Oracle recommended
SELECT plant_code AS "공장코드" FROM plants

The system prompt includes this rule and the AI auto-applies quotes — but in environments with many Korean columns, verify the result and fix manually if needed.

Use FETCH FIRST instead of LIMIT

-- ❌ Oracle 12c minimum, or wrong usage
SELECT * FROM users LIMIT 10

-- ✅ Oracle 12c+
SELECT * FROM users FETCH FIRST 10 ROWS ONLY

-- ✅ Oracle 11g compatible (subquery)
SELECT * FROM (SELECT * FROM users) WHERE ROWNUM <= 10

Security

Data Modification Control

DbSphere is read-only by default. This is not a fixed property, though — it is a per-database setting you can turn on and off. The Allow data modifications switch at the top of the DB configuration modal decides this. As the on-screen caption puts it:

Off: agent can only run SELECT (read-only). On: agent can also run INSERT/UPDATE/DELETE/DDL, but each call requires user approval.

	Off (default)	On
SELECT · aggregates · JOIN · subqueries	Runs immediately	Runs immediately
INSERT · UPDATE · DELETE	Blocked	Runs after user approval
DDL (CREATE, DROP, ALTER, TRUNCATE, GRANT)	Blocked	Runs after user approval
Unclassifiable or multi-statement SQL	Blocked	Treated as a write → needs approval

With data modifications allowed, the agent can genuinely change your data. If you are reviewing security or approving access on the assumption that DbSphere is read-only, confirm that this switch is off for the database in question.Admins cannot bypass this switch. An admin bypasses access control (ACL), but this safety switch still applies to them.

Write Approval Flow

When modifications are allowed and the agent produces a write statement, it does not run right away — an approval card appears in the chat.

Card element	Content
Pending confirmation badge	Marks the statement as awaiting execution
Expiry countdown	The request disappears once this elapses
SQL text	The full statement the agent generated
Affected-rows preview	The data about to change, where it can be previewed
Commit / Rollback	Nothing is applied until you commit; rollback cancels it

Even when you need modifications enabled, keep the least-privilege guidance under Database Account Setup. Account grants and this switch are two independent layers of defense.

Credential Protection

DB passwords are stored encrypted
Connection info is only viewable by users with access permission

Best Practices

Database Account Setup

Create a dedicated account: Make a read-only account just for AI use
Grant least privilege: Grant SELECT permission only on needed tables
Set query limits: Configure timeout and result row limits

Table Selection

Pick only what’s needed: Connecting all tables can confuse the AI
Exclude sensitive data: Always exclude tables with PII or passwords
Pick related tables together: Pick tables that need to JOIN together

Schema Description Writing

Korean descriptions encouraged: Describe tables and columns using business terminology
Add business context: Document possible values and meanings of “status” columns
State relationships explicitly: Describe foreign-key relationships and JOIN conditions

Troubleshooting

Connection test fails

Cause	Solution
Network issue	Check firewall rules, VPN connection
Auth failure	Re-verify account, password, permissions
Port blocked	Verify the DB port is open
SSL config	Check SSL certificate requirements

The AI generates wrong SQL

Cause	Solution
Insufficient schema description	Add detailed descriptions for tables and columns
Business rules not reflected	Add rules to Documentation memory
Related tables missing	Pick tables that need JOIN together
Ambiguous question	Include specific conditions (date range, filters) in the question
No past reference queries	Add correct query examples to SQL Example memory

Slow responses

Cause	Solution
Large data volume	Add conditions like date range to the question
Complex query	Simplify the question or break into multiple
DB performance	Optimize indexes, check DB resources

FAQ

Can the data be modified?

Not by default — DbSphere is read-only out of the box. Anything that isn’t a SELECT is blocked.That said, each database has an Allow data modifications switch in its configuration modal. Turn it on and the agent can also run INSERT, UPDATE, DELETE, and DDL. Even then nothing lands immediately: every call raises an approval card that you have to commit before it applies.If you need a guarantee that a database stays read-only, confirm the switch is off for it — admins cannot bypass it either. See Data Modification Control for details.

Can I see the executed SQL?

Yes — the AI response shows the generated SQL. You can also see the executed SQL and results in detail under Tracing.

Can I JOIN multiple tables?

Yes — pick all related tables and describe inter-table relationships in the schema description. The AI will generate appropriate JOIN queries.

Can one agent connect multiple databases?

Yes — when multiple databases are connected to an agent, the AI auto-picks the right one based on the question. Writing detailed tool descriptions for each DB improves selection accuracy.

What's different when picking a model during schema extraction?

With a model, the LLM auto-generates business descriptions for tables/columns and sample Q&A pairs. Without a model, only DDL structure is stored. Picking a model is recommended.

Agents

Connect a DB to an agent to enable natural-language queries

Glossary

Tell the AI about DB business terminology to improve accuracy

Tracing

Track the SQL generation and execution process step by step

Workspace

AI Agents

Knowledge & Data

Safety

Customization

Example

NL-to-SQL Pipeline

Supported Databases

Connect a Database

Activity History

How the AI Generates SQL

Memory System

Improve Accuracy with DDL Schema Descriptions

SQL Few-shot is Key

Documentation Use

Data Visualization

Querying Databases

Connect to an Agent

Use in Chat

Example Questions

Reviewing SQL Execution Results

DB Dialect Differences

Key Differences

System Auto-Correction vs. User Responsibility

Oracle DB Quirks

Security

Data Modification Control

Write Approval Flow

Credential Protection

Best Practices

Database Account Setup

Table Selection

Schema Description Writing

Troubleshooting

FAQ

Agents

Glossary

Tracing

​Example

​NL-to-SQL Pipeline

​Supported Databases

​Connect a Database

​Activity History

​How the AI Generates SQL

​Memory System

​Improve Accuracy with DDL Schema Descriptions

​SQL Few-shot is Key

​Documentation Use

​Data Visualization

​Querying Databases

​Connect to an Agent

​Use in Chat

​Example Questions

​Reviewing SQL Execution Results

​DB Dialect Differences

​Key Differences

​System Auto-Correction vs. User Responsibility

​Oracle DB Quirks

​Security

​Data Modification Control

​Write Approval Flow

​Credential Protection

​Best Practices

​Database Account Setup

​Table Selection

​Schema Description Writing

​Troubleshooting

​FAQ

​Related Pages

Agents

Glossary

Tracing

Example

NL-to-SQL Pipeline

Supported Databases

Connect a Database

Activity History

How the AI Generates SQL

Memory System

Improve Accuracy with DDL Schema Descriptions

SQL Few-shot is Key

Documentation Use

Data Visualization

Querying Databases

Connect to an Agent

Use in Chat

Example Questions

Reviewing SQL Execution Results

DB Dialect Differences

Key Differences

System Auto-Correction vs. User Responsibility

Oracle DB Quirks

Security

Data Modification Control

Write Approval Flow

Credential Protection

Best Practices

Database Account Setup

Table Selection

Schema Description Writing

Troubleshooting

FAQ

Related Pages