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, andTO_VARCHAR(expression).ANY,SOMEandALLsubquery 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)orTABLESAMPLE 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.