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:
- Una raíz que la regla no alcanza da
[], la des entree_rooto salga de los filtros: para ese usuario no existe, igual que en unfind. - 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])sobrecapitulo): 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.