tai-sql 0.8.3__tar.gz → 0.8.4__tar.gz

{tai_sql-0.8.3 → tai_sql-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tai-sql
-Version: 0.8.3
+Version: 0.8.4
 Summary: SQL database management and code generation tool
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE

{tai_sql-0.8.3 → tai_sql-0.8.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tai-sql"
-version = "0.8.3"
+version = "0.8.4"
 description = "SQL database management and code generation tool"
 license = "LicenseRef-Proprietary"
 license-files = ["LICENSE"]

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/cli/commands/cmd_schema/schemas/auth.py

@@ -154,7 +154,8 @@ class AuthSchema(SchemaTemplate):
                 # se resolvía solo por nombre, así que un padre podía no existir o ser otro rol
                 # homónimo de otro realm. `restrict`: borrar un rol con subroles es un error,
                 # no una cascada que se los lleve (y `set null` vaciaría también `realm_name`).
-                parent: manytoone[Role] = relation(fields=["parent_role_name", "realm_name"], references=["name", "realm_name"], backref="subroles", onDelete="restrict")
+                # `tree=True`: la jerarquía de roles, con consultas en árbol (`find_many(tree_mode=...)`).
+                parent: manytoone[Role] = relation(fields=["parent_role_name", "realm_name"], references=["name", "realm_name"], backref="subroles", onDelete="restrict", tree=True)
 
                 subroles: onetomany[Role]
 

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/cli/commands/cmd_schema/schemas/chatbot.py

@@ -172,8 +172,9 @@ class ChatbotSchema(SchemaTemplate):
                 # La llamada que creó el sub-agente que hizo esta: del mismo mensaje, por la clave compuesta
                 # (message_id, padre) → (message_id, call_id). Por el id del modelo y no por el de la fila: las
                 # filas se crean anidadas en el mensaje, y el id de la del padre todavía no existe. Con padre
-                # vacío (las del agente principal) la clave no se comprueba. Borrar una se lleva sus hijas
-                llamada_padre: manytoone[ToolCall] = relation(fields=['message_id', 'padre'], references=['message_id', 'call_id'], backref='hijas', onDelete='cascade')
+                # vacío (las del agente principal) la clave no se comprueba. Borrar una se lleva sus hijas.
+                # `tree=True`: el árbol de llamadas de una respuesta, con consultas en árbol
+                llamada_padre: manytoone[ToolCall] = relation(fields=['message_id', 'padre'], references=['message_id', 'call_id'], backref='hijas', onDelete='cascade', tree=True)
                 hijas: onetomany[ToolCall]
 
 

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/drivers/base.py

@@ -1107,6 +1107,40 @@ class DatabaseDriver(ABC):
             f"WHERE {no_nulos} AND r.{self.quote_identifier(target_columns[0])} IS NULL"
         )
 
+    def orphans_fix_statements(
+        self, table_name: str, columns: Sequence[str],
+        target_table: str, target_columns: Sequence[str],
+        detach_columns: Sequence[str] = (), schema_name: str = None,
+    ) -> Dict[str, Optional[str]]:
+        """
+        Las sentencias que propone `push` cuando una FK nueva tiene filas huérfanas.
+
+        - `delete`: elimina las filas cuyas columnas de FK no encuentran pareja.
+        - `detach`: pone a NULL `detach_columns` en esas mismas filas, que es lo natural
+          en una FK de la tabla consigo misma —la fila pasa a ser una raíz—. `None` si no
+          se pide.
+
+        La pareja se busca por **todas** las columnas de la FK: con una compuesta, mirar
+        solo la primera borraba filas que no son huérfanas. Es SQL estándar (`NOT
+        EXISTS`); el motor que no acepte una subconsulta sobre la misma tabla que modifica
+        —MySQL— lo sobrescribe.
+        """
+        local = self.qualified_table(table_name, schema_name)
+        destino = self.qualified_table(target_table, schema_name)
+        union = ' AND '.join(
+            f"r.{self.quote_identifier(t)} = {local}.{self.quote_identifier(c)}"
+            for c, t in zip(columns, target_columns)
+        )
+        no_nulos = ' AND '.join(
+            f"{self.quote_identifier(c)} IS NOT NULL" for c in columns
+        )
+        condicion = f"{no_nulos} AND NOT EXISTS (SELECT 1 FROM {destino} r WHERE {union})"
+        detach = None
+        if detach_columns:
+            nulos = ', '.join(f"{self.quote_identifier(c)} = NULL" for c in detach_columns)
+            detach = f"UPDATE {local} SET {nulos} WHERE {condicion}"
+        return {'delete': f"DELETE FROM {local} WHERE {condicion}", 'detach': detach}
+
     # ── Tipos ────────────────────────────────────────────────────────────
 
     def is_sequence_default(self, value: str) -> bool:

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/drivers/mysql.py

@@ -508,6 +508,38 @@ class MySQLDriver(DatabaseDriver):
 
     # ── Escritura de datos ───────────────────────────────────────────────
 
+    def orphans_fix_statements(
+        self, table_name: str, columns: Sequence[str],
+        target_table: str, target_columns: Sequence[str],
+        detach_columns: Sequence[str] = (), schema_name: str = None,
+    ) -> Dict[str, Optional[str]]:
+        """
+        Con `LEFT JOIN` y no con `NOT EXISTS`.
+
+        MySQL no deja modificar una tabla con una subconsulta sobre ella misma (error
+        1093), que es justo el caso de una FK de la tabla consigo misma. El `UPDATE` y el
+        `DELETE` de varias tablas sí admiten unir la tabla consigo misma.
+        """
+        local = self.qualified_table(table_name, schema_name)
+        destino = self.qualified_table(target_table, schema_name)
+        union = ' AND '.join(
+            f"r.{self.quote_identifier(t)} = l.{self.quote_identifier(c)}"
+            for c, t in zip(columns, target_columns)
+        )
+        no_nulos = ' AND '.join(
+            f"l.{self.quote_identifier(c)} IS NOT NULL" for c in columns
+        )
+        huerfana = f"r.{self.quote_identifier(target_columns[0])} IS NULL"
+        joined = f"{local} l LEFT JOIN {destino} r ON {union}"
+        detach = None
+        if detach_columns:
+            nulos = ', '.join(f"l.{self.quote_identifier(c)} = NULL" for c in detach_columns)
+            detach = f"UPDATE {joined} SET {nulos} WHERE {no_nulos} AND {huerfana}"
+        return {
+            'delete': f"DELETE l FROM {joined} WHERE {no_nulos} AND {huerfana}",
+            'detach': detach,
+        }
+
     def upsert_statement(self, table, values, conflict_columns, update_columns,
                          returning=()):
         """

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/errors/collector.py

@@ -19,6 +19,11 @@ decir las cinco, y no obligar a arreglarlas de una en una, recompilando entre me
 
     collector.abort_if_errors()               # los presenta todos y sale
 
+Recoge también **avisos**: lo que conviene cambiar sin que impida seguir, como una forma
+del DSL que se va a retirar. Tienen la misma forma que un error —mensaje, solución,
+ubicación, código— y van aparte porque no cuentan para `has_errors()`: un schema con
+avisos se carga, se genera y se sincroniza igual.
+
 Vive aquí y no en `orm/analysis/`, que es donde nació, porque acumular no es un concepto
 del análisis: es la forma general de reportar varios problemas. La prueba es que
 `SafetyChecker` había reimplementado exactamente esto por su cuenta —una lista de
@@ -32,7 +37,7 @@ from __future__ import annotations
 
 from typing import Iterable, List, Optional
 
-from .render import render_diagnostics
+from .render import render_diagnostics, render_warning
 from .types import Diagnostic, ErrorCode
 
 
@@ -50,6 +55,7 @@ class ErrorCollector:
         self.context = context
         self.enable_colors = enable_colors
         self.errors: List[Diagnostic] = []
+        self.warnings: List[Diagnostic] = []
 
     # ── Registro ─────────────────────────────────────────────────────────
 
@@ -81,6 +87,26 @@ class ErrorCollector:
             )
         )
 
+    def add_warning(
+        self,
+        message: str,
+        solution: str,
+        location: Optional[str] = None,
+        code: Optional[ErrorCode] = None,
+    ) -> None:
+        """
+        Anota un aviso: algo que conviene cambiar, pero que no impide seguir.
+
+        Args:
+            message: Qué conviene saber.
+            solution: Qué cambiar. Obligatorio, igual que en un error.
+            location: Fichero, clase o campo donde ocurre.
+            code: Código para buscarlo en la documentación.
+        """
+        self.warnings.append(
+            Diagnostic(message=message, solution=solution, location=location, code=code)
+        )
+
     def extend(self, diagnostics: Iterable[Diagnostic]) -> None:
         """Anota varios problemas ya construidos."""
         self.errors.extend(diagnostics)
@@ -88,6 +114,7 @@ class ErrorCollector:
     def clear(self) -> None:
         """Olvida lo acumulado."""
         self.errors.clear()
+        self.warnings.clear()
 
     # ── Consulta ─────────────────────────────────────────────────────────
 
@@ -99,6 +126,14 @@ class ErrorCollector:
         """Copia de lo acumulado."""
         return self.errors.copy()
 
+    def has_warnings(self) -> bool:
+        """Si hay algún aviso acumulado."""
+        return bool(self.warnings)
+
+    def get_warnings(self) -> List[Diagnostic]:
+        """Copia de los avisos acumulados."""
+        return self.warnings.copy()
+
     # Nota: deliberadamente SIN __len__. Un colector se usa como objeto, no como
     # contenedor, y darle longitud lo vuelve falsy cuando está vacío — que es el estado
     # normal al empezar. El idioma `collector or ErrorCollector()` pasaba entonces a
@@ -112,6 +147,21 @@ class ErrorCollector:
             self.errors, context=self.context, colors=self.enable_colors
         )
 
+    def show_warnings(self) -> None:
+        """Presenta los avisos acumulados, uno detrás de otro."""
+        for warning in self.warnings:
+            where = ' · '.join(
+                p for p in (
+                    self.context, warning.location, warning.code and warning.code.value
+                ) if p
+            )
+            render_warning(
+                warning.message,
+                hint=warning.solution,
+                location=where or None,
+                colors=self.enable_colors,
+            )
+
     def abort_if_errors(self) -> None:
         """
         Si hay problemas, los presenta todos y termina con código 1.

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/errors/render.py

@@ -237,6 +237,11 @@ def render_warning(
         stream: Dónde escribir. Por defecto stderr.
         colors: `False` fuerza texto pelado.
     """
+    # Una solución de varias líneas —un trozo de código que pegar— sigue alineada bajo
+    # el 💡 en vez de volver al margen
+    if hint:
+        hint = hint.replace('\n', '\n      ')
+
     console = _console(stream) if colors else None
 
     if console is None:

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/errors/types.py

@@ -62,6 +62,9 @@ class ErrorCode(str, Enum):
     # Recursos generados
     GENERATION_FAILED = "E030"
 
+    # Avisos: lo que conviene cambiar, sin impedir seguir
+    DEPRECATED = "W001"
+
 
 @dataclass
 class Diagnostic:

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/diagram/README.md

@@ -37,8 +37,10 @@ lado aunque el schema las declarase:
   dibujaba como `STR`, porque el tipo canónico de la columna es el de sus valores.
 - Las **UNIQUE e índices de varias columnas**, que no caben en la fila de una columna. La
   UNIQUE compuesta es además la clave natural del feed.
-- Las **jerarquías** de `column(self_reference=…)`, que no producen `RelationModel`
-  —no hay dos entidades que relacionar— y por eso el árbol no se veía.
+- Las **jerarquías**. La de `relation(..., tree=True)` es una relación más, y su arista se
+  marca como jerarquía. La de `column(self_reference=…)` —deprecada— no produce
+  `RelationModel` —no hay dos entidades que relacionar— y por eso el árbol no se veía:
+  se añade como arista propia.
 - Las **dimensiones** de una columna vectorial, que es lo único que hay que saber de ella.
 
 Cada bloque se apaga con su `include_*`: `views`, `columns`, `relationships`, `triggers`,

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/diagram/builder.py

@@ -12,8 +12,9 @@ un render.
 Tres cosas que el diagrama enseña y que no salen de recorrer las columnas:
 
 - los **enumerados**, que no son entidades del schema pero tipan columnas;
-- las **jerarquías** de `column(self_reference=…)`, que no producen `RelationModel`
-  porque no hay dos entidades que relacionar;
+- las **jerarquías**: la relación con `tree=True` se dibuja como cualquier otra y se marca
+  como jerarquía, y la de `column(self_reference=…)` —deprecada—, que no produce
+  `RelationModel`, se añade como arista propia;
 - las **UNIQUE e índices de varias columnas**, que no caben en la fila de una columna.
 """
 from __future__ import annotations
@@ -95,14 +96,14 @@ class DiagramBuilder:
 
     def entity(self, entity) -> EREntity:
         """Construye una entidad de dibujo a partir de una del modelo lógico."""
-        hierarchy_column = (
-            entity.self_reference.column_name
-            if not entity.is_view and entity.has_self_reference
-            else None
+        hierarchy_columns = (
+            set(entity.hierarchy.pointer_columns)
+            if not entity.is_view and entity.has_hierarchy
+            else set()
         )
 
         columns = [
-            self.column(column, hierarchy_column)
+            self.column(column, hierarchy_columns)
             for column in entity.columns.values()
             if self.include_operative_fields or not column.is_operative
         ]
@@ -140,7 +141,7 @@ class DiagramBuilder:
             query=getattr(entity, 'query', None),
         )
 
-    def column(self, column, hierarchy_column: Optional[str]) -> ERColumn:
+    def column(self, column, hierarchy_columns=frozenset()) -> ERColumn:
         """Traduce una columna, resolviendo ya la etiqueta de su tipo."""
         return ERColumn(
             name=column.name,
@@ -154,7 +155,7 @@ class DiagramBuilder:
             calculated=column.is_calculated,
             description=column.description,
             is_vector=column.is_vector,
-            hierarchy=column.name == hierarchy_column,
+            hierarchy=column.name in hierarchy_columns,
             operative=column.is_operative,
         )
 
@@ -228,14 +229,17 @@ class DiagramBuilder:
         declarada y su inversa implícita), y quedarse con la implícita hace que la
         arista salga siempre del lado "uno".
 
-        Las jerarquías son aparte: `column(self_reference=…)` no produce `RelationModel`
-        —no hay dos entidades que relacionar—, así que sin esto el árbol no se veía en
-        el diagrama por ningún lado.
+        La jerarquía de `relation(..., tree=True)` es una relación más, marcada como
+        jerarquía. La de `column(self_reference=…)` es aparte: no produce `RelationModel`
+        —no hay dos entidades que relacionar—, así que sin esto el árbol no se veía en el
+        diagrama por ningún lado.
         """
         relationships: List[ERRelationship] = []
 
         for table in self.schema.tables.values():
 
+            tree = table.hierarchy.relation if table.has_hierarchy else None
+
             for relation in table.relations.values():
                 if not relation.implicit:
                     continue
@@ -252,10 +256,16 @@ class DiagramBuilder:
                         relationship_type=relation.direction,
                         local_name=relation.name,
                         target_name=relation.backref,
+                        # La inversa de la relación con `tree=True`, que es la que se dibuja
+                        hierarchy=(
+                            tree is not None
+                            and relation.backref == tree
+                            and relation.target == relation.local
+                        ),
                     )
                 )
 
-            if table.has_self_reference:
+            if table.has_hierarchy and table.hierarchy.relation is None:
                 if drawn is not None and table.tablename not in drawn:
                     continue
                 relationships.append(
@@ -263,8 +273,8 @@ class DiagramBuilder:
                         from_table=table.tablename,
                         to_table=table.tablename,
                         relationship_type=RelationshipType.ONE_TO_MANY.value,
-                        local_name=table.self_reference.column_name,
-                        target_name=table.self_reference.references,
+                        local_name=table.hierarchy.parent_columns[0],
+                        target_name=table.hierarchy.key_columns[0],
                         hierarchy=True,
                     )
                 )

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/diagram/generator.py

@@ -54,8 +54,9 @@ class ERDiagramGenerator(BaseGenerator):
       Graphviz ni conexión.
 
     Lo que dibuja, además de tablas, vistas y columnas: los enumerados con sus valores y
-    qué columna los usa, las UNIQUE e índices de varias columnas, las jerarquías de
-    `column(self_reference=…)` y las dimensiones de una columna vectorial.
+    qué columna los usa, las UNIQUE e índices de varias columnas, las jerarquías
+    (`relation(..., tree=True)` y la deprecada `column(self_reference=…)`) y las
+    dimensiones de una columna vectorial.
     """
 
     def __init__(

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/diagram/model.py

@@ -165,8 +165,9 @@ class ERRelationship:
     relationship_type: str
     local_name: str
     target_name: Optional[str]
-    #: `True` cuando la arista es una jerarquía declarada con `column(self_reference=…)`,
-    #: que no produce `RelationModel` y por tanto no llegaba al diagrama.
+    #: `True` cuando la arista es la jerarquía de la tabla: la relación con `tree=True`, o
+    #: la de `column(self_reference=…)`, que no produce `RelationModel` y sin esto no
+    #: llegaba al diagrama.
     hierarchy: bool = False
 
     @property

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/python_client/__init__.py

@@ -422,9 +422,9 @@ class PythonClientGenerator(BaseGenerator):
             for col in m.get('columns', [])
         )
 
-        # Pre-compute whether any model has self_reference (hierarchy)
+        # Pre-compute whether any model declares a hierarchy
         has_hierarchy = any(
-            m.get('has_self_reference', False)
+            m.get('has_hierarchy', False)
             for m in all_models_data
         )
 
@@ -494,7 +494,7 @@ class PythonClientGenerator(BaseGenerator):
         elif encoders_path.exists():
             encoders_path.unlink()
 
-        # _shared/utils/hierarchy.py — only when self_reference columns exist
+        # _shared/utils/hierarchy.py — only when some table declares a hierarchy
         hierarchy_path = utils_dir / 'hierarchy.py'
         if has_hierarchy:
             hierarchy_template = self.jinja_env.get_template('shared/utils/hierarchy.py.jinja2')

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/python_client/context.py

@@ -155,8 +155,15 @@ class TemplateContextBuilder:
                 for cc in table.calculated_columns.values()
             ],
             'has_calculated_columns': table.has_calculated_columns,
-            'has_self_reference': table.has_self_reference,
-            'self_reference': self._self_reference(table),
+            'has_hierarchy': table.has_hierarchy,
+            'hierarchy': self._hierarchy(table),
+            # Las dos de antes, con su forma: el contexto es contrato con tai-api, que lee
+            # `has_self_reference` para tipar `tree_level`, `ancestors` y `descendants`.
+            # Valen para cualquier jerarquía, también la de `tree=True`; `self_reference`
+            # solo tiene forma para una clave de una columna. Se retiran con
+            # `column(self_reference=...)`.
+            'has_self_reference': table.has_hierarchy,
+            'self_reference': self._legacy_self_reference(table),
         }
 
     def view(self, view: ViewModel) -> Dict[str, Any]:
@@ -493,14 +500,41 @@ class TemplateContextBuilder:
             for event in TRIGGER_EVENTS
         }
 
-    def _self_reference(self, table: TableModel) -> Optional[Dict[str, Any]]:
-        """Metadatos de la jerarquía declarada, o None si la tabla no declara ninguna."""
-        if table.self_reference is None:
+    def _hierarchy(self, table: TableModel) -> Optional[Dict[str, Any]]:
+        """
+        La jerarquía de la tabla, o None si no declara ninguna.
+
+        `root_type` es el tipo de `tree_root` en el `find_many` generado: el valor de la
+        clave si es de una columna, y una tupla en el orden de `key_columns` o un dict por
+        nombre si es compuesta.
+        """
+        hierarchy = table.hierarchy
+        if hierarchy is None:
+            return None
+        if hierarchy.is_composite:
+            root_type = (
+                f"Union[tuple[{', '.join(hierarchy.key_python_types)}], Dict[str, Any]]"
+            )
+        else:
+            root_type = hierarchy.key_python_types[0]
+        return {
+            'key_columns': list(hierarchy.key_columns),
+            'parent_columns': list(hierarchy.parent_columns),
+            'is_composite': hierarchy.is_composite,
+            'root_type': root_type,
+            'relation': hierarchy.relation,
+        }
+
+    @staticmethod
+    def _legacy_self_reference(table: TableModel) -> Optional[Dict[str, Any]]:
+        """La clave `self_reference` de antes, para una jerarquía de una columna."""
+        hierarchy = table.hierarchy
+        if hierarchy is None or hierarchy.is_composite:
             return None
         return {
-            'column_name': table.self_reference.column_name,
-            'references': table.self_reference.references,
-            'pk_python_type': table.self_reference.pk_python_type,
+            'column_name': hierarchy.parent_columns[0],
+            'references': hierarchy.key_columns[0],
+            'pk_python_type': hierarchy.key_python_types[0],
         }
 
     def _constraints(self, column: ColumnModel) -> Dict[str, Any]:

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/python_client/templates/domain/dao.py.jinja2

@@ -72,7 +72,7 @@ from {{ import_prefix }}_shared import (
     AggField,
     GroupByField
 )
-{% if model.has_self_reference %}
+{% if model.has_hierarchy %}
 from {{ import_prefix }}_shared import (
     HierarchyResolver,
     HierarchyConfig,

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/python_client/templates/domain/dtos.py.jinja2

@@ -138,7 +138,7 @@ class {{ model.name }}Read(PrettyModel):
     {% endif %}
     {% endfor %}
 
-{% if model.has_self_reference %}
+{% if model.has_hierarchy %}
     tree_level: Optional[int] = Field(default=None, description="Nivel en el árbol jerárquico (0 = nodo raíz de la consulta)")
     descendants: Optional[List[{{ model.name }}Read]] = Field(default=None, description="Subárbol de descendientes (poblado en tree_mode='descendants' o 'full_tree')")
     ancestors: Optional[List[{{ model.name }}Read]] = Field(default=None, description="Cadena de ancestros (poblado en tree_mode='ancestors' o 'full_tree')")

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/python_client/templates/macros/hierarchy.jinja2

@@ -1,8 +1,10 @@
 {# ─────────────────────────────────────────────────────────────────────────────
    Hierarchy macros — generates CTE-based recursive queries for self-referencing tables.
-   
-   Activated when a model has `has_self_reference == True` (i.e., a column with
-   self_reference='pk_column' is defined).
+
+   Activated when a model has `has_hierarchy == True`: a self relation declared with
+   `relation(..., tree=True)`, or the deprecated `column(self_reference='pk_column')`.
+   Both arrive with the same shape: `key_columns` (the node key) and `parent_columns`
+   (what points to the parent), one or several of each.
    
    Delegates to HierarchyResolver (in _shared/utils/hierarchy.py) for all CTE
    construction and tree assembly logic.
@@ -11,9 +13,9 @@
 
 {# ── Parameters for find_many signature ─────────────────────────────────── #}
 {% macro generate_hierarchy_parameters(model) %}
-{% if model.has_self_reference %}
+{% if model.has_hierarchy %}
 tree_mode: Literal["flat", "descendants", "ancestors", "full_tree"] = "flat",
-tree_root: Optional[{{ model.self_reference.pk_python_type }}] = None,
+tree_root: Optional[{{ model.hierarchy.root_type }}] = None,
 tree_depth: Optional[int] = None,
 {% endif %}
 {% endmacro %}
@@ -21,34 +23,50 @@ tree_depth: Optional[int] = None,
 
 {# ── Docstring args for hierarchy parameters ────────────────────────────── #}
 {% macro generate_hierarchy_args(model) %}
-{% if model.has_self_reference %}
+{% if model.has_hierarchy %}
 - tree_mode: Modo de consulta jerárquica. 'flat' (por defecto) desactiva la recursión.
-      'descendants' obtiene todos los subequipos del nodo raíz.
-      'ancestors' obtiene todos los equipos superiores hasta la raíz.
+      'descendants' obtiene todos los descendientes del nodo raíz.
+      'ancestors' obtiene todos sus ancestros, hasta la raíz del árbol.
       'full_tree' obtiene tanto descendientes como ancestros.
-- tree_root: PK del nodo raíz para la consulta jerárquica. Si es None y tree_mode != 'flat',
-      se usan los registros encontrados por los filtros como nodos raíz.
-- tree_depth: Profundidad máxima de recursión. None = sin límite.
+{% if model.hierarchy.is_composite %}
+- tree_root: Clave del nodo raíz para la consulta jerárquica: una tupla
+      ({{ model.hierarchy.key_columns | join(', ') }}) o un dict con esas claves. Si es None y
+      tree_mode != 'flat', se usan los registros encontrados por los filtros como nodos raíz.
+{% else %}
+- tree_root: Clave ({{ model.hierarchy.key_columns[0] }}) del nodo raíz para la consulta
+      jerárquica. Si es None y tree_mode != 'flat', se usan los registros encontrados por
+      los filtros como nodos raíz.
+{% endif %}
+- tree_depth: Profundidad máxima de recursión. None = hasta 100 niveles:
+      al alcanzarlo se corta y queda un aviso en el log.
 {% endif %}
 {% endmacro %}
 
 
-{# ── Root ID resolution block (before filters are logged) ──────────────── #}
+{# ── Root ID resolution block: after the filters AND the rls, so a root is a row the user sees ── #}
 {% macro generate_hierarchy_query(model) %}
-{% if model.has_self_reference %}
-{% set sr = model.self_reference %}
+{% if model.has_hierarchy %}
+{% set hr = model.hierarchy %}
         # ── Hierarchy: resolver nodos raíz ────────────────────────────────────
         _hierarchy_mode = TreeMode(tree_mode)
+        _hierarchy_config = HierarchyConfig(
+            {{ model.name }},
+            key_columns=({% for c in hr.key_columns %}'{{ c }}', {% endfor %}),
+            parent_columns=({% for c in hr.parent_columns %}'{{ c }}', {% endfor %}),
+        )
         _hierarchy_root_ids = None
 
         if _hierarchy_mode != TreeMode.FLAT:
             if tree_root is not None:
-                _hierarchy_root_ids = [tree_root]
+                _hierarchy_root_ids = [_hierarchy_config.root_key(tree_root)]
             else:
-                # Ejecutar query filtrada para obtener PKs raíz
+                # Las raíces son las filas de la consulta ya filtrada y acotada por rls
                 {{ def_keyword }} _get_root_ids(_sess):
                     _root_result = {{ await_keyword -}} _sess.execute(query)
-                    return [row.{{ sr.references }} for row in _root_result.scalars().all()]
+                    return [
+                        _hierarchy_config.key(instance)
+                        for instance in _root_result.scalars().all()
+                    ]
 
                 if session is not None:
                     _hierarchy_root_ids = {{ await_keyword -}} _get_root_ids(session)
@@ -64,8 +82,7 @@ tree_depth: Optional[int] = None,
 
 {# ── Execute block using HierarchyResolver ──────────────────────────────── #}
 {% macro generate_hierarchy_execute(model, max_depth) %}
-{% if model.has_self_reference %}
-{% set sr = model.self_reference %}
+{% if model.has_hierarchy %}
 {% set vector_cols_with_encoder = [] -%}
 {% for vcol in model.columns | selectattr('type', 'equalto', 'vector') | list -%}
   {% if vcol.get('has_encoder') -%}
@@ -74,7 +91,7 @@ tree_depth: Optional[int] = None,
 {% endfor -%}
         # ── Hierarchy resolver instance ───────────────────────────────────────
         _hierarchy_resolver = HierarchyResolver(
-            config=HierarchyConfig({{ model.name }}, '{{ sr.references }}', '{{ sr.column_name }}'),
+            config=_hierarchy_config,
             dto_factory=lambda instance, includes, max_depth: {{ model.name }}Read.from_instance(
                 instance,
                 {% if not model.is_view %}
@@ -82,6 +99,7 @@ tree_depth: Optional[int] = None,
                 max_depth=max_depth
                 {% endif %}
             ),
+            rls=rls,
         )
 
         {{ def_keyword }} execute_query(session: {{ session_type }}) -> List[{{ model.name }}Read]:

{tai_sql-0.8.3 → tai_sql-0.8.4}/tai_sql/generators/python_client/templates/macros/read.jinja2

@@ -207,8 +207,6 @@
 
 {{ vector_macros.generate_vector_query(model) }}
 
-{{ hierarchy_macros.generate_hierarchy_query(model) }}
-
         # Log de parámetros aplicados
         if filters:
             _log_tx(session, f"[{{ schema_name }}]     filters={filters}")
@@ -216,6 +214,8 @@
         # Aplicar regla RLS (si existe)
         if rls is not None:
             query = RLSQueryApplicator.apply_rls(query, {{ model.name }}, rls)
+
+{{ hierarchy_macros.generate_hierarchy_query(model) }}
         
         # Aplicar opciones de carga optimizada
         if includes:
@@ -269,7 +269,7 @@
 {% endif %}
 
         # Ejecutar query
-{% if model.has_self_reference %}
+{% if model.has_hierarchy %}
 {% if vector_cols_with_encoder %}
 {# El modo `flat` de la jerarquía es la consulta vectorial de siempre: se emite con otro
    nombre y el bloque jerárquico la llama, en vez de repetirla a medias. #}