Relational DB

The Relational DB Tool lets Dataworkz Agents connect directly to relational databases and execute SQL queries. Use it for advanced cases where queries involve joins, sub-queries, or SQL constructs that go beyond what the Dataset Tool supports.

💡 Note: For simple filtered data access, the Dataset Tool is the recommended option. Use the Relational DB Tool only when you need direct SQL control or complex query logic.

---

When to Use

Use the Relational DB Tool when an Agent needs to:

• Connect directly to relational databases such as MySQL, PostgreSQL, Oracle, or Microsoft SQL Server

• Execute complex SQL queries including joins, sub-queries, aggregations, and advanced SQL constructs

• Have precise control over query definition beyond what the Dataset Tool's filter interface provides

• Work with custom schema structures or multi-table operations

---

Prerequisites

Before creating a Relational DB Tool, ensure the following:

• A database connection has been configured in Dataworkz Configuration under the appropriate storage type

• The target database is accessible from the Dataworkz environment

• You have the schema name, table names, and column names needed to write the query

---

Creating a Relational DB Tool

Go to AI Agents → Create Tool and select Relational DB from the Tool type selector.

The creation flow has four sections:

---

About Tool

Field	Required	Description
Tool name	Yes	A meaningful name that conveys what the Tool queries — for example, getProductsByCategory or fetchOpenInvoices
Description	Yes	A clear explanation of what the Tool retrieves, which database it connects to, and when the Agent should invoke it
Notes	No	Internal notes for documentation purposes — not used by the Agent during reasoning

💡 Note: A specific and well-defined description improves AI responses in the Agent. Include what the query returns, the database it targets, and any conditions or constraints the Agent should be aware of.

---

Configuration

The Configuration section defines the database connection and the SQL query the Tool will execute.

Field	Required	Description
Storage	Yes	Select the database connection configured in Data Studio. This determines which database system the Tool connects to
Database	Yes	Select the specific database to query from within the selected storage connection
Query	Yes	Define how the SQL query is constructed — either as a fixed parameterised query or dynamically from the conversation

Query modes:

Mode	Description	When to Use
Custom Parameterised Query	Write a prepared SQL statement with named parameter placeholders using the ${parameterName} syntax. Parameters are fixed at configuration time and populated by the Agent at runtime	When the query structure is known and consistent — recommended for most use cases
Dynamic Query from Conversation	The entire SQL query is generated dynamically from the Agent conversation and provided as a parameter	When the query structure varies based on user input and cannot be defined in advance

Custom Parameterised Query example:

SELECT * FROM schema_name.table WHERE name LIKE ${searchCriteria}

Reference parameters in the query using the format ${parameterName} — for example, ${productId} or ${searchCriteria}. Each placeholder automatically becomes an input parameter in the Input Parameters section.

⚠️ Warning: Use Custom Parameterised Query wherever possible. Dynamic Query from Conversation gives the Agent full control over the SQL structure, which can introduce unpredictable or unsafe queries if not carefully managed.

---

Input Parameters

Input parameters are detected automatically from the ${parameterName} placeholders defined in your SQL query. Each placeholder becomes a named parameter the Agent populates at runtime based on the user's request.

For each detected parameter, configure:

Field	Description
Name	Automatically populated from the placeholder in the query
Type	The data type — such as String, Integer, Boolean, or Date
Description	A clear explanation of what the parameter represents, including required formats, valid values, or examples

💡 Note: If no parameters appear, add ${parameterName} placeholders to your SQL query. Each placeholder becomes an input parameter the Agent populates at runtime.

💡 Note: Write clear, detailed descriptions for each parameter. Include required formats — for example, date formats such as YYYY-MM-DD — and any enumerated values or constraints. The Agent uses these descriptions to determine what value to supply for each parameter.

---

Output

The Output section defines the structure of the data returned by the SQL query.

Field	Description
Output type name	The type of output returned — typically Object for a single row result or List for multiple rows
Description	A plain language description of what the query returns — for example, "the matching product records" or "the list of open invoices"
Object structure	A JSON definition describing the fields and structure of the returned data

Example output structure:

{
  "name": "object",
  "description": "the result"
}

Mark output as artifact — Enable this toggle when the query result should be treated as a file or document rather than structured data.

💡 Note: If you are unsure of the exact output structure, run the Tool using the Test panel first and apply the returned structure automatically. This ensures the output definition accurately reflects the columns and data types returned by the query.

---

Testing the Tool

Use the Test panel on the right side of the page to validate the Relational DB Tool before adding it to an Agent Scenario:

1. Enter sample values for each input parameter

2. Click Test → to execute the SQL query against the connected database

3. Review the returned results to confirm the query is correct and the output structure matches what you have defined

4. Adjust the query or output definition as needed and retest

💡 Note: Always test the Relational DB Tool with representative parameter values before connecting it to an Agent. Confirm that the query returns the correct rows and columns and that the output structure is accurately defined.

⚠️ Warning: Be careful when testing Tools that execute write operations or queries against production databases. Test against a non-production environment where possible.

---

Saving the Tool

Once all sections are complete and the Tool has been tested, click Save & Close to save and return to the My Tools list, or Save to save without closing.

💡 Note: Once saved, the Relational DB Tool is immediately available to be referenced in any Agent Scenario within your Dataworkz environment.

💡 Note: If the same database is used across multiple Tools, consider naming Tools clearly to reflect the specific table or operation they target — for example, getCustomerById, listOpenOrders, or fetchProductInventory — so the Agent can identify and select the correct Tool accurately during reasoning.