Emit COMMENT and DEFAULT for function arguments and descriptions in CREATE FUNCTION

Abierto
  • ¿Algo no está bien?
#1,764 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 6 días

@alvinism ya está trabajando en esto.

Desde el 5/11/2026.

  • #1765 de @alvinism — abierto

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
python, sql
Área
backend, databases

Línea de trabajo

The issue specifies changes to the scalar function argument and creation macros, persist_docs, unit tests, a SQL warehouse functional test, and the CHANGELOG. First inspect the existing Databricks function macros and the PostgreSQL and Snowflake argument rendering patterns named in the issue. Done means SQL and Python scalar functions handle defaults, comments, escaping, and persist_docs as proposed, with the tests and changelog entry; an open linked pull request already covers this work.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

enhancement
Describe the feature

dbt-core already parses description on a function and its arguments, and default_value on its arguments. dbt-databricks doesn't render any of them, so the function is created without comments or defaults:

functions:
  - name: double_it
    description: Doubles a value
    arguments:
      - name: x
        data_type: double
        description: Input value
      - name: factor
        data_type: int
        default_value: 2
    returns:
      data_type: double

renders today as

CREATE OR REPLACE FUNCTION `cat`.`sch`.`double_it` (x double, factor int)
RETURNS double
LANGUAGE SQL
RETURN ...

Unity Catalog can only set a function's comment inside CREATE FUNCTION. There's no COMMENT ON FUNCTION, and ALTER FUNCTION can't change it. So today there's no way to get yml descriptions into Unity Catalog. Those comments are what Genie, AI agents and Catalog Explorer show to describe a function.

There is also a related failure. With persist_docs: {relation: true}, the default function_execute_build_sql calls persist_docs. databricks__persist_docs then runs COMMENT ON FUNCTION ... IS '...', which Databricks rejects, so the model fails.

Proposal (scalar functions, SQL and Python):

  1. Override databricks__formatted_scalar_function_args_sql to render name type [DEFAULT <default_value>] [COMMENT '<description>'], the order in the CREATE FUNCTION syntax. DEFAULT is rendered like dbt-postgres and dbt-snowflake already do (default_value is inserted as a raw SQL expression). The docs say "DEFAULT is supported for LANGUAGE SQL only", so Python UDFs skip DEFAULT and warn, the way an unsupported volatility is handled. dbt-core already rejects a non-defaulted argument after a defaulted one, which matches the Databricks ordering rule.

  2. Add COMMENT '<description>' to the function's CREATE FUNCTION statement, using the existing get_create_sql_comment for escaping.

  3. Gate the comments behind persist_docs, the same way databricks__comment_clause does for tables:

    • persist_docs.relation controls the function comment;
    • persist_docs.columns controls the argument comments.

    Projects that don't opt in get exactly the same SQL as today.

  4. Make persist_docs skip the post-create COMMENT ON for function relations, because the comment is now part of CREATE FUNCTION. This fixes the failure above.

Table functions (RETURNS TABLE (...)) are out of scope until dbt-core models return columns (dbt-labs/dbt#12492).

Describe alternatives you've considered
  • Write the clauses inside data_type, for example data_type: "int DEFAULT 2 COMMENT 'Row limit'", plus COMMENT after the type in returns.data_type. It works because data_type is pasted into the SQL as-is, and that's what we run in production today. But the descriptions stay out of dbt docs, and it relies on unvalidated passthrough.
  • Override the macros in each project. It works, but every project has to maintain a copy of adapter internals, and it breaks silently if the macros are renamed.
  • Always emit the comment, ungated. This is simpler, but it changes the generated SQL for every existing project with function descriptions. Gating on persist_docs matches how tables, views, MVs and STs already behave.
  • Setting the comment after creation: not possible, as explained above.
Additional context
  • Versions: dbt-databricks 1.13.0, dbt-core 1.12.x.
  • dbt-postgres and dbt-snowflake already render default_value in their formatted_scalar_function_args_sql overrides, so per-adapter rendering is the established pattern.
  • Newer dbt-tests-adapter releases ship SqlUDFDefaultArgSupport / PythonUDFDefaultArgSupport (used by the Postgres, Snowflake, BigQuery and Redshift adapters), but the version dbt-databricks pins doesn't include them yet. The PR adds Databricks functional tests that check the same behaviour against information_schema: the SQL default applies, and the Python default is ignored.
Who will this benefit?

Teams that use dbt functions as a governed definition layer in Unity Catalog. We manage about 50 shared business-logic UDFs (time-zone conversion, cohort assignment, funnel metrics, and so on) with dbt. Analysts, Genie spaces and AI agents find and choose them through their UC comments. We currently keep the comments inside data_type, and this change would let us move them into normal description fields.

Are you interested in contributing this feature?

Yes, I'd like to implement it: the macros plus unit tests for argument and function comments, defaults, escaping, persist_docs gating and the persist_docs skip, a functional test against a SQL warehouse, and a CHANGELOG entry. Happy to adjust the design, especially the persist_docs gating, before opening the PR.

Lenguaje dominante
Python
Estrellas
391
Forks
231
Merge medio
9 d 7 h
PR fusionados (30 d)
29

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de databricks/dbt-databricks

Todos los issues de databricks/dbt-databricks

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.