Beyond SQL Dialects: A Governed Business Query Language for AI Agents

An AI agent becomes much more useful when it can answer questions that an application team did not anticipate when the system was built.

Consider this request:

Find customers who placed more than three orders in the last 30 days, have a refund rate above 20%, and still have an unresolved support ticket.

A conventional application may not have an endpoint for that exact question. A model with unrestricted SQL access could try to construct it, but it would also need to know the physical schema, joins, enum encodings, tenant filters, authorization rules, soft-delete conventions, and database dialect. That is a large and dangerous contract to place in a prompt.

TeaQL offers a different boundary:

Give the model composable business semantics, not database authority.

TeaQL sits above SQL dialects as a governed business query language. The model can combine approved domain concepts into a query that has never been exposed as a dedicated endpoint, while the application retains control of identity, permissions, limits, audit, and execution.

The Gap Between Fixed APIs and Raw SQL

Most agent-to-data integrations begin at one of two extremes.

At one extreme, the application exposes a fixed set of narrow API operations:

getCustomerById
listOpenOrders
findOverdueInvoices

These operations are easy to govern, but their composition space is limited. Every new question may require another endpoint, deployment, and integration.

At the other extreme, the application gives the model a generic SQL tool:

executeSql(sql: string)

This is flexible, but the abstraction boundary is wrong. SQL exposes storage mechanics rather than business capabilities. A syntactically valid query can still violate tenant isolation, reveal sensitive fields, scan an unreasonable amount of data, or encode the wrong business meaning.

TeaQL occupies the space between them:

Boundary	Composition	Governance	Coupling
Fixed application APIs	Low to medium	Strong	Coupled to predefined use cases
Raw SQL	High	Difficult	Coupled to schema and database dialect
TeaQL business queries	High within declared capabilities	Enforced by the runtime	Coupled to stable domain semantics

The objective is not unrestricted flexibility. It is governed query composition.

SQL Describes Storage; TeaQL Describes the Business

SQL is excellent at describing how to retrieve and transform rows. It speaks in tables, columns, joins, predicates, grouping, ordering, and database-specific functions.

An agent working on behalf of a user needs a different vocabulary:

• Customer, Order, Refund, and Support Ticket;
• active, overdue, unresolved, and eligible;
• relationships between business objects;
• fields that may be filtered, projected, aggregated, or sorted;
• the current user's tenant and permitted data scope;
• the purpose of the query and the limits of the operation.

TeaQL maps that business vocabulary to generated, typed query APIs. Database providers remain responsible for translating the resulting request into the appropriate SQL and parameter representation.

Natural-language request
  -> model-selected business query
  -> TeaQL domain semantics and runtime policy
  -> PostgreSQL, MySQL, Oracle, SQL Server, SQLite, or another provider

The database still executes SQL. The important change is that SQL is no longer the contract between the model and the application.

New Queries Without New Database Authority

Dynamic query composition matters because users rarely ask only the questions that developers predicted.

A TeaQL query can combine declared capabilities such as:

• filters over typed business properties;
• relationship traversal and nested selection;
• projection of an approved field set;
• sorting, pagination, grouping, and aggregation;
• reusable domain predicates;
• runtime policies applied through the current context.

These pieces can express a new question without creating a new repository method for every combination.

The model should not emit TeaQL source code directly. Instead, it should call a tool with a constrained, machine-readable query specification. The server validates that specification and maps it to generated TeaQL APIs.

{
  "entity": "Order",
  "filters": [
    { "field": "status", "operator": "is", "value": "PAID" },
    { "field": "createdAt", "operator": "after", "value": "2026-08-01T00:00:00Z" }
  ],
  "select": ["id", "customerName", "createdAt"],
  "orderBy": [{ "field": "createdAt", "direction": "desc" }],
  "limit": 20
}

This is not a second textual query language for the model to improvise. It is a validated capability document. Only registered entities, fields, operators, relations, and limits are accepted.

The Model Does Not Receive Trusted Context

The model proposes what it wants to query. The server decides under whose authority the query runs.

TeaQL execution uses a trusted context selected by the application. It can carry identity, tenant, authorization policy, data services, audit facilities, and other runtime resources. That context is captured server-side and is never accepted as model input.

Model-generated query specification
  -> schema and capability validation
  -> server-owned context
  -> authorization and tenant policy
  -> TeaQL request execution
  -> bounded, projected result

This separation prevents the model from choosing another tenant, replacing a data service, or granting itself a permission through tool arguments.

Governance Is More Than Preventing Bad SQL

Removing raw SQL is useful, but it is not the complete security model. A governed business query also needs explicit decisions about:

• which entities and relationships an agent may use;
• which fields may be filtered or returned;
• which operators and aggregates are available;
• maximum page size, traversal depth, and execution cost;
• sensitive-field masking and result projection;
• authorization and tenant isolation;
• query purpose, audit metadata, and telemetry;
• safe error messages returned to the model.

The model's prompt is guidance. These controls belong in deterministic server code and runtime policy.

The useful distinction is:

SQL permissions answer what a database connection can execute. TeaQL capabilities answer what this user, through this agent, may do in this business context.

Dynamic Reads, Explicit Business Actions

The freedom to compose reads should not imply arbitrary writes.

Queries are naturally exploratory. Within declared limits, it is reasonable for an agent to combine filters and projections to answer a new question. Mutations have different risks: they may trigger workflows, violate state transitions, affect money, or require human confirmation.

TeaQL therefore benefits from an asymmetric boundary:

Read request
  -> constrained dynamic query
  -> validation and policy
  -> bounded result

Write request
  -> explicit business action
  -> input validation
  -> user approval when required
  -> authorization and domain validation
  -> audited save

An agent may dynamically discover orders that qualify for review. Creating a refund, approving it, or closing an order should still happen through explicit actions such as createRefundRequest, approveRefund, or closeOrder.

This preserves useful query flexibility without turning the agent into a general-purpose database administrator.

One Business Language Across Runtimes and Databases

Database portability is often described as hiding placeholder syntax or pagination differences. For agents, the larger benefit is semantic stability.

The same business concept should retain its meaning when an application moves between database providers or when a TeaQL service is implemented in a different supported language. The model-facing tool should not need to learn whether a timestamp comparison becomes a PostgreSQL expression, an Oracle expression, or a SQLite expression.

That creates a layered contract:

Layer	Stable responsibility
Model	Select a tool and supply schema-valid business arguments
TeaQL AI SDK	Convert allowed capabilities into model-facing tools
TeaQL runtime	Apply context, domain semantics, policy, audit, and execution rules
Database provider	Produce correct parameterized operations for its database

Models and database providers can change independently while the business language remains recognizable.

A Practical Agent Interaction

Suppose a user asks:

Show me secondary schools created this year whose contact phone is missing.

The interaction can follow this path:

1. The model selects an approved school-search tool.
2. It supplies typed filters for school type, creation date, and an explicitly null contact phone.
3. The server validates the query against the published capability schema.
4. The application attaches its trusted TeaQL context.
5. Runtime policy applies authorization, tenant filters, projection, and result limits.
6. The database provider executes parameterized SQL in its own dialect.
7. The tool returns a bounded business result, not unrestricted database rows.
8. The model explains the result to the user.

If the user then asks the agent to update a phone number, the agent switches to an explicit write capability with validation, approval, and audit.

The Role of @teaql/ai-sdk

The TeaQL AI SDK is designed to connect TeaQL business capabilities to model tool calling. It complements an agent SDK; it does not provide a model or replace the agent loop.

The agent SDK handles model providers, conversations, streaming, and tool-call orchestration. TeaQL provides the business-data boundary underneath:

Model and agent loop
  -> TeaQL AI SDK tools
  -> TeaQL runtime context and policy
  -> business data

For a concrete example of explicit capabilities, approval, server-owned context, safe failures, and audited writes, read Build a Safe SQL Agent Without Giving the Model SQL Access.

Beyond the Dialect Boundary

TeaQL does not need to replace SQL to move the application boundary above it. SQL remains an effective execution language for relational databases. TeaQL provides the stable business language that applications and AI agents can use without depending directly on physical schema or dialect.

The resulting proposition is simple:

Ask questions your application has never implemented, without giving AI unrestricted SQL access.

Or, in architectural terms:

TeaQL is a governed business query language above SQL dialects: composable like a query, governed like an application API, and designed for AI agents.