Saltar a contenido

Consultas jerárquicas

Cuando una tabla declara su jerarquía —una relación consigo misma con tree=True—, su find_many gana tres parámetros:

equipos = public_sync_api.equipo.find_many(
    tree_mode='descendants',    # 'flat' (default) | 'descendants' | 'ancestors' | 'full_tree'
    tree_root=17,               # clave del nodo raíz
    tree_depth=3,               # profundidad máxima; None = hasta 100 niveles
)

Los cuatro modos

tree_mode Qué devuelve
'flat' Lo de siempre: una lista plana. Es el valor por defecto
'descendants' El nodo raíz y todo lo que cuelga de él
'ancestors' La cadena desde el nodo hasta la raíz
'full_tree' Los dos anteriores a la vez: el nodo con todo lo que cuelga de él y su cadena hasta la raíz. No trae sus hermanos ni las otras ramas

Elegir la raíz

# Explícita
public_sync_api.equipo.find_many(tree_mode='descendants', tree_root=17)

# Implícita: las filas que pasen los filtros son las raíces
public_sync_api.equipo.find_many(tree_mode='descendants', centro_id=3)

Sin tree_root, tai-sql ejecuta primero la consulta filtrada para saber de qué nodos partir, y luego recorre desde ellos. Si el filtro no devuelve nada, la lista sale vacía sin recorrer nada.

Con clave compuesta

tree_root es la clave entera del nodo: una tupla en el orden de references, o un dict por nombre.

public_sync_api.capitulo.find_many(tree_mode='descendants', tree_root=(libro.id, '1'))
public_sync_api.capitulo.find_many(
    tree_mode='descendants', tree_root={'libro_id': libro.id, 'numero': '1'},
)

El árbol de un libro no recoge los capítulos de otro aunque se numeren igual: el recorrido une por todas las columnas de la clave. Una clave incompleta es un ValueError que dice qué columnas faltan.

Con RLS

Las reglas rls acotan cada nodo del recorrido, no solo la consulta de partida:

mios = public_sync_api.equipo.find_many(tree_mode='descendants', tree_root=17, rls=reglas)
  • Una raíz que la regla no alcanza da [], la des en tree_root o salga de los filtros: para ese usuario no existe, igual que en un find.
  • Un nodo fuera de la regla ni sale ni se atraviesa. Lo que cuelga de él no se alcanza aunque la regla lo deje ver: no se llega a lo propio pasando por lo ajeno. En 'ancestors', la cadena acaba en el último nodo que la regla alcanza.
  • La regla puede seguir relaciones, como en cualquier consulta (RLS(Libro, 'id', [3]) sobre capitulo): se aplica en las dos partes del recorrido.

Hasta tai-sql 0.8.3, tree_mode se saltaba rls: el tree_root no se comprobaba, las raíces sacadas de los filtros se calculaban antes de aplicar la regla y el recorrido no la recibía. Con las reglas de un usuario se leía el árbol de otro. Con tree_mode='flat' (el de por defecto) nunca pasó.

Profundidad

tree_depth limita los niveles que se recorren. Sin él, el recorrido baja hasta 100 niveles: es holgado para cualquier jerarquía real y garantiza que la consulta termina aunque haya un ciclo —una fila que acaba colgando de sí misma—, que la clave ajena no impide. Si el árbol sigue más abajo, se corta en el 100 y queda un aviso en el log; para un árbol más hondo, pásale tree_depth=.

Qué devuelve

La misma lista de DTOs <Modelo>Read que find_many, con las relaciones que hayas pedido en includes. Cada uno trae tree_level (0 en el nodo de partida) y sus descendants o ancestors anidados. La estructura de árbol se reconstruye siguiendo la relación de la jerarquía.

Combínalo con includes

public_sync_api.equipo.find_many(
    tree_mode='full_tree',
    tree_root=17,
    includes=['componentes'],
)