Query Forge

Overview

Query Forge turns Gluesync Core Hub into a single, federated SQL endpoint. Where Query Studio lets you query one agent from inside the Gluesync portal, Query Forge lets an external JDBC client — DBeaver, DataGrip, Tableau, a BI dashboard, a script — run one query that spans several of the Core Hub’s SQL-capable agents at once, joining tables that live behind different agents.

It works on the same unit of access as Query Studio: each SQL-capable agent (a pipeline + agent) becomes a schema you can query. Each remote table scan is pushed down to that agent’s existing Query Studio execute endpoint, so no customer data path changes — the query engine only sees the rows you are already permitted to read.

Query Forge federates the agents of a Core Hub; it does not introduce a new data channel. Reads reuse the same permissioned Query Studio path.

How it works

JDBC client (jdbc:gluesync:// driver)
  -> Query Forge endpoint
  -> Core Hub (per-user auth, SQL-capable agent discovery)
  -> Query Studio execute, per pipeline + agent
  -> your databases

  • Each SQL-capable agent you can access becomes a schema in the JDBC connection.

  • Each table behind that agent becomes a table under its schema.

  • A cross-agent JOIN is planned centrally; the individual table reads (with filters and column projections) are pushed down to each agent.

Connecting

Driver

Query Forge ships a branded JDBC driver. Add the gluesync-unified-jdbc driver JAR to your SQL client’s driver classpath, then use the connection URL:

jdbc:gluesync://<host>:<port>

Internally the driver speaks Apache Avatica; you only ever deal with the jdbc:gluesync: URL.

Authentication

You always authenticate as yourself against Core Hub: every query runs with your identity and permissions, and you only see the SQL-capable agents your account may query. There is no shared service token.

There are two ways to authenticate, depending on how your account was created.

A. With a token (required for SSO / OIDC users)

If you sign in through SSO / OIDC, you do not have a local password to give a JDBC client. Instead, supply an existing Core Hub token:

  • set a token connection property to your token, or

  • set the username to __token__ and paste the token into the password field (useful for SQL clients that only expose user and password inputs).

The token can be either a session token (obtained when you log in) or a long-lived Personal API Token (gsp_…) — Core Hub accepts either. Personal API Tokens are the recommended choice for a JDBC client you configure once.

B. With username and password (local accounts)

If your Core Hub account uses a local username and password, connect with:

  • user: your Core Hub username

  • password: your Core Hub password

Gluesync exchanges these for a token behind the scenes.

When you reach Core Hub through Gluesync Connect, the same endpoint and the same authentication apply — Connect simply proxies to the Core Hub API. There is no separate configuration for local vs. Connect access.

Example: DBeaver

  1. Register a new driver pointing at the gluesync-unified-jdbc JAR; the driver class is handled automatically by the jdbc:gluesync: URL.

  2. Create a connection with URL jdbc:gluesync://corehub.example.com:8765.

  3. Authenticate:

    • Local account: put your username in Username and your password in Password.

    • SSO / OIDC account: put __token__ in Username and your token in Password (or add a token driver property).

  4. Connect. The schema browser shows one schema per SQL-capable agent you can access.

Writing federated SQL

Reference each agent by its schema name, then a table:

SELECT c.name, COUNT(o.id) AS order_count, SUM(o.total) AS revenue
FROM crm.customers c
JOIN sales.orders o ON o.customer_id = c.id
GROUP BY c.name
ORDER BY c.name;

Schema naming:

  • A pipeline with a single SQL-capable agent is exposed under the pipeline name (for example, sales.orders).

  • A pipeline with multiple SQL-capable agents disambiguates by agent (for example, sales__pg.orders).

Identifiers are case-insensitive, matching the friendliest behavior for BI tools.

Ask AI from Query Forge

Query Forge exposes the reserved gluesync.ai virtual table alongside your database catalogs. It turns a natural-language question into one regular JDBC result row containing:

  • answer — the model’s (or Spark agent’s) plain-language result;

  • proposed_sql — an optional read-only SQL proposal, never executed automatically;

  • schema citations;

  • a conversation ID for follow-up questions;

  • the question, plus the pipeline, database-agent, provider, and optional Spark-agent IDs the request actually used.

Before using it, a Super admin must configure at least one provider under Settings → LLM providers. OpenAI, Anthropic, Azure OpenAI, and local Ollama models are supported. See AI models and LLM providers.

Ask a question without IDs

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

Example result:

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. 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

This example omits pipeline_id and agent_id and names nothing Core Hub can resolve, so it runs with empty grounding and reports NULL IDs.

You do not need pipeline_id or agent_id for a grounded answer. When the question names a pipeline, agent, schema, or table the caller can see, Core Hub grounds the answer on the strongest unique match and returns the resolved IDs in the row:

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';

Two equally strong matches are ambiguous and fail with SQLSTATE 22023. Only then is it useful to pin the scope with both IDs together — they are optional and never required for a normal ask. See name grounding from the question.

Choose a provider

Use provider_id to select a configured cloud or Ollama provider:

SELECT answer, proposed_sql
FROM gluesync.ai
WHERE question = 'find duplicate customer email addresses'
  AND provider_id = 'provider-ollama-local';

Call a Spark agent

spark_agent selects an AI Studio Spark agent by id or unique name. Query Forge applies that agent’s system prompt and only the overlap of its tool allow-list with this path’s read-only MCP / Query Studio tools. Write, DDL, DML, and administrative tools stay blocked even if the Spark agent allows them in chat.

Do not confuse spark_agent with agent_id. agent_id is a database agent used for schema grounding. spark_agent is the AI Studio agent that answers the question.

The Spark agent’s plain result is the answer column. proposed_sql remains an optional SQL draft for review and is never executed:

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

Ask a follow-up

Continue the exchange by passing the returned conversation_id:

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';

proposed_sql is returned for review and is never executed automatically. The AI path only exposes caller-visible read-only MCP tools and never elevates the JDBC user’s permissions.

For the complete column contract, accepted predicates, prepared-statement example, SQLSTATE errors, and safety behavior, see AI as SQL virtual catalog.

What is pushed down

To keep large tables from being dragged across the network, Query Forge pushes work to each agent where it can:

  • Column projection — only the columns your query needs are requested from the remote agent.

  • Filters — comparisons (=, <>, <, <=, >, >=), IS NULL / IS NOT NULL, LIKE, and AND / OR / NOT combinations are translated into the SQL run at the agent.

  • Anything that cannot be pushed down safely (for example, complex IN lists or column-to-column comparisons) is evaluated centrally after the needed rows are fetched.

Column types come from each agent’s schema metadata, so numeric aggregations (SUM, AVG, …) and typed comparisons behave as expected.

Security notes

  • Per-user scope: you only see the SQL-capable agents your account may query; a rejected token or bad credentials fail the connection immediately.

  • Read-only: queries run against agents through Query Studio’s read-only path.

  • Transport: place the endpoint behind TLS (a reverse proxy, or the platform’s own TLS termination) so credentials and result sets are encrypted in transit.

Limitations

  • Date and time values are currently exposed as text; ISO-formatted values compare and sort correctly, but native DATE / TIMESTAMP typing is a future enhancement.

  • Federation performance depends on how selectively filters push down; a query with no usable filter against a very large remote table will fetch that table before joining.

  • gluesync.ai accepts equality predicates only on question, conversation_id, pipeline_id, agent_id, provider_id, and spark_agent. Only question is required. pipeline_id and agent_id are optional; if you use them, supply both together.

See also