create_hana_sql_agent

hana_ai.agents.hana_sql_agent.create_hana_sql_agent(llm: any, connection_context: ConnectionContext, tools: BaseTool = None, agent_type: None | Literal['openai-tools', 'tool-calling'] = None, callback_manager: BaseCallbackManager | None = None, prefix: str | None = None, suffix: str | None = None, format_instructions: str | None = None, input_variables: List[str] | None = None, top_k: int = 10, max_iterations: int | None = 15, max_execution_time: float | None = None, early_stopping_method: str = 'force', verbose: bool = False, agent_executor_kwargs: Dict[str, Any] | None = None, extra_tools: Sequence[BaseTool] = (), *, prompt: BasePromptTemplate | None = None, schema: str | None = None, include_tables: Sequence[str] | None = None, **kwargs: Any)

Create a HANA SQL agent.

SQL queries are limited to one read-only SELECT within the configured object scope, including nested queries, CTEs and joins. Use a dedicated HANA account with only the necessary SELECT privileges; parser checks do not replace database authorization. These checks do not constrain separately supplied custom tools or HANAMLToolkit model-training/storage tools.

Parameters:
llm: any

The language model to use.

tools: List[BaseTool], optional

Additional tools to include in the SQL toolkit.

agent_type: Union[AgentType, Literal["openai-tools", "tool-calling"]], optional

The type of agent to create.

callback_manager: BaseCallbackManager, optional

The callback manager to use.

prefix: str, optional

The prefix to use.

suffix: str, optional

The suffix to use.

format_instructions: str, optional

The format instructions to use.

input_variables: List[str], optional

The input variables to use.

top_k: int

The top k to use.

max_iterations: int, optional

The max iterations to use.

max_execution_time: float, optional

The max execution time to use.

early_stopping_method: str

The early stopping method to use.

verbose: bool

The verbose to use.

agent_executor_kwargs: Dict[str, Any], optional

The agent executor kwargs to use.

extra_tools: Sequence[BaseTool]

The extra tools to use.

connection_context: ConnectionContext

The connection context to use.

prompt: BasePromptTemplate, optional

The prompt to use.

schema: str, optional

The only schema the agent may query. Queries must qualify table names with it.

include_tables: Sequence[str], optional

Explicit table allowlist. At least one of schema or include_tables is required.

kwargs: Any

The kwargs to use.

Examples

Assume cc is a read-only connection to a SAP HANA instance and llm is configured:

>>> from hana_ai.agents.hana_sql_agent import create_hana_sql_agent
>>> agent_executor = create_hana_sql_agent(llm=llm, connection_context=cc, include_tables=["IRIS_DATA_FULL_TBL"], verbose=True)
>>> agent_executor.invoke("show me the min and max value of sepalwidthcm in the table iris_data_full_tbl?")

Supported SELECT syntax

The SQL agent checks every table reference against the configured schema and/or include_tables. It supports explicit joins, parenthesized table expressions, subqueries, scoped CTEs, built-in scalar/aggregate functions, and the following HANA constructs:

  • CAST(expression AS type) with built-in HANA types, including numeric precision and string length parameters, and TO_VARCHAR(expression).

  • ANY, SOME and ALL subquery comparisons.

  • WITH HINT (NO_INLINE, CS_JOIN) and hint names with flat literal/name arguments, at the end of the outer SELECT statement (including the final SELECT of a CTE or UNION query).

  • table PARTITION (1, 2) AS alias.

  • table AS alias TABLESAMPLE SYSTEM (50) or TABLESAMPLE BERNOULLI (50).

  • CROSS JOIN LATERAL (SELECT ...) AS alias, including correlated subqueries and CTEs inside the lateral query.

CAST operands and all nested queries retain the same object checks as the outer query. Type/partition/sample parameters accept numeric literals; they cannot hide function calls or SQL expressions. Hint arguments cannot contain nested SQL. Hints inside subqueries/CTE bodies, repeated hint clauses, and any SQL following a hint are rejected before execution. Put joins, filters, ordering and set operations before the final hint; one trailing statement terminator remains supported.

Use explicit JOIN syntax. Comma joins, arbitrary scalar/table UDFs, sequence access and three-part table names remain unsupported and are rejected before query execution. A read-only HANA account with restricted object permissions remains necessary; these checks do not replace database authorization.

Semicolons in other hana-ml tools

The SQL agent executes through SQLAlchemy and preserves semicolons inside string literals. Tools that construct SQL for ConnectionContext.sql() or execute_sql() reject semicolons in values and identifiers because hana-ml splits the raw text before the database parses SQL quotes. This includes vector query text/model versions, forecasting group values and split/future-table identifiers. The rejection is intentional; SQL quoting alone cannot make these inputs safe at those execution APIs. The read-only SELECT tools accept one trailing statement terminator and remove it before calling hana-ml.