AI as SQL virtual catalog

The gluesync.ai virtual catalog makes Gluesync AI, optional Spark agents, and caller-visible read-only MCP tools available through SQL. Connect through Query Forge, ask a natural-language question, and receive one row containing the plain-language answer, an optional SQL proposal, citations, and conversation context.

SQL surface

The shortest valid query is:

SELECT *
FROM gluesync.ai
WHERE question = 'retrieve customer data';

question is required and must use an equality predicate. A prepared parameter (?) is also accepted.

The statement returns one row.

Example result

The result appears as a regular JDBC result set. Long answers and SQL are shown in full by clients such as DBeaver and DataGrip when you open the cell value.

answer proposed_sql citations conversation_id question pipeline_id agent_id provider_id spark_agent

I found a CUSTOMERS table on the SQL Server source and PostgreSQL target. Since no scope was supplied, this proposal targets the source and has not been executed.

SELECT ID, NAME, SURNAME, ADDRESS, GENDER, PHONE, EMAIL FROM dbo.CUSTOMERS;

[]

b5acd3d2-7c9d-4100-8296-25b10132ebe0

retrieve customer data

NULL

NULL

NULL

NULL

The exact wording depends on the selected model or Spark agent and the schemas and tools visible to the caller. answer is the plain result. proposed_sql is a draft for review; Gluesync does not execute it.

This question names no pipeline, agent, schema, or table, so the row comes back with empty grounding and NULL IDs. See Name grounding from the question.

Scope the question to an agent

You do not need pipeline_id or agent_id in the WHERE clause. Prefer naming the pipeline, agent, schema, or table in the question so Core Hub can ground the answer:

SELECT answer, proposed_sql, citations, conversation_id
FROM gluesync.ai
WHERE question = 'retrieve the 100 most recently created customers from dbo.CUSTOMERS';

If two equally strong names collide, or you need to pin one database regardless of wording, you may optionally supply both pipeline_id and agent_id together. They are never required for a normal ask. Explicit IDs always win: when both are present in the WHERE clause, Hub uses that scope and does not read any names out of the question.

Name grounding from the question

When the query omits pipeline_id and agent_id, Core Hub tries to resolve the scope from whole names mentioned in the question — pipeline, agent, schema, and table names — against the catalogs the caller can already see.

SELECT answer, proposed_sql, pipeline_id, agent_id
FROM gluesync.ai
WHERE question = 'in the crm-sync pipeline, list the columns of the dbo.CUSTOMERS table';

  • Whole names, case-insensitive. A name takes part in resolution only when the whole catalog name appears in the question. Matching ignores case and treats punctuation as a word separator, so dbo.CUSTOMERS matches the dbo schema and the CUSTOMERS table. Fragments and abbreviations are not resolved.

  • Strongest unique match wins. Hub grounds the request on the single strongest candidate and returns the resolved pipeline_id and agent_id in the result row, so the answer shows which scope was used.

  • Weaker matches are ignored. A secondary name that matches less strongly than the leader does not make the request ambiguous.

  • Ties fail. When two or more candidates share the strongest score, the request fails with SQLSTATE 22023 and lists those candidates instead of Hub choosing one.

  • No match means empty grounding. When nothing in the question resolves, Hub answers with empty schema grounding and returns NULL for pipeline_id and agent_id.

Grounding never widens what the caller can read: only the pipelines, agents, schemas, and tables already visible to the caller’s token take part in resolution.

Match strength

Names are not all worth the same. Hub first compares agent and pipeline names, then breaks a remaining tie on schema and table names:

Name mentioned in the question Weight

Agent name

Strongest of the two agent-level signals; an agent name beats a pipeline name.

Pipeline name

Selects the pipeline’s agents, and loses to a question that also names an agent.

Table name

Strongest of the two catalog-level signals; a table name beats a schema name.

Schema name

Narrows to agents exposing that schema, and loses to a question that also names a table.

Grounding precedence

  1. Optional pipeline_id and agent_id supplied together in the WHERE clause — never required, but when present they win over names in the question.

  2. Strongest unique whole-name match resolved from the question.

  3. Empty grounding.

Select an LLM provider

Use provider_id to select a provider from Settings → LLM providers:

SELECT answer, proposed_sql, provider_id
FROM gluesync.ai
WHERE question = 'write a read-only query that finds duplicate customer emails'
  AND provider_id = 'provider-ollama-local';

If provider_id is omitted, Core Hub resolves a configured provider for the request. When spark_agent is set, that Spark agent’s assigned provider is used unless you override it with provider_id.

Call a Spark agent

spark_agent selects an AI Studio Spark agent by id or unique name. Query Forge uses that agent’s system prompt. Tools are the intersection of the agent’s allow-list and this path’s read-only catalog; write tools never run here.

SELECT answer, proposed_sql, spark_agent
FROM gluesync.ai
WHERE question = 'summarize replication lag'
  AND spark_agent = 'Ops helper';

  • answer is the Spark agent’s plain result.

  • proposed_sql is optional suggested SQL for review and is never executed.

  • spark_agent is the AI Studio agent. agent_id remains a database connector used for schema grounding.

Continue a conversation

Pass the conversation_id returned by the previous query to ask a follow-up:

SELECT answer, proposed_sql, conversation_id
FROM gluesync.ai
WHERE question = 'limit that query to active customers'
  AND conversation_id = 'b5acd3d2-7c9d-4100-8296-25b10132ebe0';

The returned row keeps the conversation identifier so the next query can continue the same exchange.

Use a prepared statement

Applications should bind user-provided questions instead of concatenating them into SQL:

try (PreparedStatement statement = connection.prepareStatement(
        "SELECT answer, proposed_sql, citations, conversation_id " +
        "FROM gluesync.ai WHERE question = ?")) {
    statement.setString(1, "retrieve customer data");
    try (ResultSet result = statement.executeQuery()) {
        if (result.next()) {
            String answer = result.getString("answer");
            String proposedSql = result.getString("proposed_sql");
        }
    }
}

Accepted WHERE predicates

Predicate Hub contract

question

Required equality predicate. A string literal or prepared parameter is accepted.

pipeline_id and agent_id

Optional advanced pin. Not required for normal asks. If used, they must be supplied together. They select the database context used for schema grounding and take precedence over any name mentioned in the question.

conversation_id

Optional. Continues an existing conversation.

provider_id

Optional. Selects a provider from the BYO LLM vault.

spark_agent

Optional. AI Studio Spark agent id or unique name. Write-capable tools are never offered on this path.

Only equality predicates on these columns are accepted. Predicates such as LIKE, ranges, and filters on output columns fail with SQLSTATE 22023.

Result columns

Column Hub contract

answer

Plain-language result for the supplied question. When spark_agent is set, this is the Spark agent’s reply.

proposed_sql

SQL proposed for review. Hub never auto-runs this statement.

citations

Citations as JSON text.

conversation_id

Conversation identifier for the returned row.

question

The question supplied in the WHERE clause.

pipeline_id

The requested pipeline ID, the pipeline ID resolved from a name in the question, or NULL when the request ran with empty grounding.

agent_id

The requested agent ID, the agent ID resolved from a name in the question, or NULL when the request ran with empty grounding.

provider_id

The requested provider ID, or NULL when provider selection was automatic.

spark_agent

The requested Spark agent id or name, or NULL when the generic AI SQL helper was used.

Authentication and RBAC

Requests use the caller’s Core Hub PAT (or equivalent Bearer / Forge token). The virtual catalog does not use an elevated service account.

MCP tool discovery and invocation keep the same RBAC as that caller. Only tools that Hub exposes as readOnly on this path are used.

BYO LLM vault prerequisite

The catalog requires a configured provider in the bring-your-own LLM vault. Provider setup belongs to AI models and LLM providers; it is not duplicated here.

MCP tools

Visible tools are the MCP tools allowed for the caller under that token’s RBAC, restricted to readOnly tools. Schema discovery and allow-list behavior follow that Hub path. This page does not add extra Control Plane allow-list fields.

Safety

  • proposed_sql is never auto-run.

  • This SQL path uses readOnly MCP tools only.

  • The catalog does not elevate the caller’s permissions.

Errors

Condition Hub contract

Empty BYO LLM vault

The query fails. A Super admin (SUPER_ADMIN) must configure a provider. SQLSTATE 55000.

Residual WHERE predicates

Predicates Hub does not accept on gluesync.ai fail with SQLSTATE 22023.

Not found

Hub maps not-found to SQLSTATE 42S02. An explicit pipeline_id / agent_id pair that the caller’s token cannot see is reported this way. An unknown spark_agent is also 42S02.

Only one of pipeline_id / agent_id

The pair must be supplied together. Supplying one alone fails with SQLSTATE 22023.

Ambiguous name grounding

Two or more equally strong name matches in the question fail with SQLSTATE 22023. Optionally pin the scope with both pipeline_id and agent_id, or rephrase the question so one name wins.

No name resolved

Not an error. Omitting pipeline_id / agent_id with nothing resolvable in the question runs with empty grounding.

RBAC denial

The caller’s PAT/RBAC applies. Hub does not grant extra rights on this path.

Related

  • Query Forge explains how to connect a JDBC client and query the virtual catalog.

  • AI models and LLM providers explains how to configure the BYO LLM vault, including local Ollama models.

  • AI Studio is the in-product agent workspace. Spark agents defined there can be invoked from Query Forge with spark_agent.

  • Query Studio AI helper is a separate in-product chat and autocomplete surface.