Skip to main content

​
Overview

MagOneAI gives agents two distinct SQL capabilities:
  • Query uploaded files. When a user uploads a tabular file — a CSV or Excel/XLSX spreadsheet — as an input to a workflow or agent, MagOneAI gives the agent a SQL query tool scoped to that file’s data. The agent answers analytical questions by writing and running real SQL, instead of reasoning over thousands of rows of raw text. This is automatic and needs no configuration.
  • Query a live database. The built-in database integration connects agents to a real PostgreSQL, MySQL, or MongoDB database, read-only. You configure the connection once, and a workspace can hold more than one connection.
Most of this page covers the uploaded-file query tool. See Connecting to a live database for the database integration.
The uploaded-file query tool works on CSV and Excel inputs and needs no setup. To query a live PostgreSQL, MySQL, or MongoDB database, enable the built-in database integration. It is read-only. For any other engine, or to allow writes, build a custom MCP tool that wraps your database access.

​
How it works

1

A tabular file is provided as input

A CSV or XLSX file reaches the agent as a workflow input (for example at the Start node) or directly as an agent input. See Triggers and execution for how files enter a workflow.
2

The file is converted to a queryable table

Behind the scenes, MagOneAI reads the file and converts it to an efficient columnar format. The column names and types are detected automatically.
3

The agent gets a dedicated query tool

For each tabular input, the agent receives its own SQL query tool, named after the input field. The tool’s description automatically includes the table’s columns and schema, so the agent knows exactly what it can query.
4

The agent writes and runs SQL

During its reasoning loop, the agent writes a SELECT query, runs it against the file, and reads the results back — just like any other tool call.

​
The query engine

Queries run on DuckDB, an in-process analytical SQL engine. Two things matter for how you design prompts and workflows:
  • It is read-only. Only SELECT and WITH (CTE) queries are allowed. INSERT, UPDATE, DELETE, and any DDL (CREATE, DROP, ALTER, …) are rejected. The agent can read and analyze the uploaded data, but it can never modify it.
  • It speaks standard SQL. Aggregations, filters, GROUP BY, ORDER BY, window functions, and CTEs all work, so the agent can express genuinely analytical questions.
Example query an agent might run:
Because the column list is in the tool description, the agent constructs queries against the real schema rather than guessing column names.

​
Querying multiple files

If several tabular files are supplied together as an array of inputs — up to 10 files — each becomes its own table, and the agent can JOIN across them in a single query. Example: joining two uploaded files:
This lets an agent reconcile, enrich, or cross-reference datasets — for example matching an uploaded contacts list against an uploaded transactions export — without any pre-processing step.

​
What this is good for

Database tools shine whenever the answer lives in a spreadsheet and would be tedious or unreliable to reason over as plain text:
  • Aggregate questions — “What’s the total revenue by region?” or “What’s the average order value per month?”
  • Data quality checks — “Which rows are missing an email address?” or “How many duplicate IDs are there?”
  • Filtering and ranking — “List the top 10 accounts by spend” or “Show every order over AED 50,000.”
  • Cross-file analysis — join an uploaded list against another uploaded export to find matches, gaps, or totals.
By delegating the counting and filtering to SQL, the agent spends its reasoning on interpreting results rather than arithmetic over raw rows.

​
Connecting to a live database

Separately from the uploaded-file tool, the built-in database integration lets agents query a live database. It supports PostgreSQL, MySQL, and MongoDB, and it is read-only by design: SELECT-style reads run, while destructive statements (INSERT, UPDATE, DELETE, and DDL) are blocked automatically.
1

Add a connection string credential

In Settings → Credentials, add a db_connection_string credential in the form postgresql://user:pass@host:5432/db (or mysql://… or mongodb://…). Like all secrets, it is stored in HashiCorp Vault.
2

Configure one or more connections

A workspace isn’t limited to a single database. You can configure multiple connections — for example a reporting replica and an analytics warehouse — each with its own name, and point an agent at the one it should use.
3

Agents query it read-only

Enabled agents get the database tool and can run read queries against the connection. Any attempt to modify data is rejected before it reaches the database.
The built-in database integration is read-only across all three engines. There is no supported way to make it write. If a workflow must write to a database, wrap that access in a custom MCP tool with its own guardrails.

​
Using it in a workflow

The uploaded-file query tool is part of file handling and agent tooling — there’s no separate connection to configure.
1

Accept a tabular file input

Define a file input on your workflow trigger or agent. Provide a CSV or XLSX file at run time. See Triggers and execution.
2

Run an Agent node

When the Agent node executes, the per-file query tool is attached automatically. No tool needs to be enabled by hand.
3

Prompt the agent to answer from the data

In the agent’s instructions, tell it to answer questions by querying the file. The agent will choose when to call the query tool during its tool-calling loop.
Example agent instruction:

​
Troubleshooting

Symptoms: The agent answers from guesswork or says it can’t see the data.Solutions:
  • Confirm the file was actually provided as an input to the workflow or agent.
  • Confirm the file is CSV or Excel/XLSX — other file types don’t get a query tool.
  • Make the instruction explicit: tell the agent to use the query tool to answer.
Symptoms: A query fails because it tried to modify data.Solutions:
  • The engine is read-only by design. Rewrite the request as a SELECT or WITH query.
  • There is no way to write back to the file — database tools are for analysis only.
Symptoms: Queries fail with unknown-column errors.Solutions:
  • Column names come from the file’s header row — make sure the spreadsheet has clear headers.
  • Avoid duplicate or blank header cells, which make columns ambiguous.
Symptoms: The agent can only see one table.Solutions:
  • Provide the files together as an array input (up to 10 files), so each becomes its own table.
  • Make sure the files share a column the agent can join on.

​
Next steps

Triggers and execution

Learn how files enter a workflow as inputs

Agents overview

Understand how agents call tools during reasoning

Tools overview

See all the tools your agents can use

Custom MCP tools

Wrap a live database with a custom tool