kaxil commented on code in PR #76799:
URL: https://github.com/apache/airflow/pull/76799#discussion_r4580818703


##########
providers/common/ai/docs/toolsets/sql.rst:
##########
@@ -337,9 +344,114 @@ Parameters
   Must be a valid Python identifier. Set it when one agent has another toolset 
with the
   same tool names, since duplicate tool names are rejected. A function passed 
to
   ``.approval_required()`` sees these prefixed names; see ``allow_writes`` 
above.
+- ``include_table_comments``: When ``True``, ``list_tables`` returns
+  ``{"name": ..., "comment": ...}`` objects instead of bare names; ``comment`` 
is
+  present only for tables that have one. Default ``False``. ``get_schema`` 
returns
+  comments regardless. See :ref:`sql-toolset-comments`.
+- ``search_backend``: Registers the ``search_tables`` tool. Default ``None``, 
no search
+  tool. See :ref:`sql-toolset-table-search`.
+- ``max_listed_tables``: With a ``search_backend``, the number of tables above 
which
+  ``list_tables`` stops listing and points at ``search_tables``. Default 
``100``. No
+  effect without a ``search_backend``.
 - ``max_retries``: How many times the model may correct a failed call to these
   tools. Default ``None``, the agent's ``retries``. See 
:ref:`toolset-retry-budget`.
 
+.. _sql-toolset-comments:
+
+Table and column comments
+-------------------------
+
+A column named ``amt_adj_2`` tells an agent little; the comment the database 
holds for
+it often does. ``get_schema`` returns ``table_comment`` and a ``comment`` on 
each column
+where the database reports one:
+
+.. code-block:: json
+
+    {"columns": [{"name": "amt_adj_2", "type": "NUMERIC", "comment": "Net of 
refunds"}],
+     "column_count": 1, "table_comment": "Customer orders"}
+
+Comments are read through ``DbApiHook.get_table_comment`` and
+``DbApiHook.get_table_columns_with_comments``, which ``common.sql`` provides 
from the
+release that added them. With an older ``common.sql``, or on a dialect that 
cannot report

Review Comment:
   Could this name the version? common.ai still allows 
`apache-airflow-providers-common-sql>=2.2.0`, so plenty of readers will land on 
the fallback and need the number to know what to upgrade to.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to