Saltar a contenido

Columnas calculadas y jerarquías

Columnas calculadas

Una columna calculada es una columna física cuyo valor se deriva de otras columnas de la misma fila. No es una propiedad de Python: existe en la base de datos, se puede filtrar y se puede ordenar por ella.

Hay dos formas de declararla, equivalentes, y se pueden mezclar en la misma tabla:

El tipo de retorno col[...] ya la declara.

class Usuario(Table):
    __tablename__ = 'usuario'

    nombre: col[str]
    apellido: col[str]

    def nombre_completo(self) -> col[str]:
        return f'{self.nombre} {self.apellido}'

Obligatorio en v1, donde el retorno es un tipo desnudo.

class Tarea(Table):
    __tablename__ = 'tarea'

    inicio: Optional[datetime]
    fin: Optional[datetime]

    @calculated_column
    def duracion_horas(self) -> Optional[float]:
        if self.fin is None or self.inicio is None:
            return None
        return (self.fin - self.inicio).total_seconds() / 3600

Sin col[...] ni decorador, un método es solo un método

Un -> str desnudo y sin @calculated_column no declara una columna, y no avisa. Es justo lo que impide que feed() o cualquier helper de la tabla acaben convertidos en columnas.

Reglas

  • Una calculada que pida parámetros además de self es un error de análisis: el valor sale de la propia fila y no hay de dónde sacarlos.
  • El orden de las calculadas sigue al fichero, y afecta al orden de columnas en el DDL y en los DTOs.
  • Una columna que el feed() no rellena vale None dentro de la calculada, igual que es NULL en la base de datos.

Qué hace el generador con ellas

Transpila el cuerpo del método a dos cosas:

  1. El cuerpo Python que recalcula la columna cada vez que el cliente escribe la fila.
  2. Cuando la expresión es traducible —una expresión pura, sin pasos intermedios—, una expresión SQLAlchemy equivalente, con la que se puede filtrar y ordenar directamente en la consulta.

Si la expresión no es traducible, la columna sigue funcionando: solo pierde la segunda mitad.

tai-sql pull no las puede reconstruir

Una calculada es una columna física, y en la base de datos no queda rastro de cómo se calcula. Al adoptar una base de datos existente, aparecerá como una columna normal.

Jerarquías: tree=True

Una tabla cuyas filas cuelgan de otras de la misma tabla —equipos y subequipos, carpetas, capítulos y secciones— declara su jerarquía con una relación de la tabla consigo misma y tree=True:

class Equipo(Table):
    __tablename__ = 'equipo'

    id: col[int] = column(primary_key=True, autoincrement=True)
    nombre: col[str]
    equipo_superior: col[int | None]

    superior: manytoone[Equipo] = relation(
        fields=['equipo_superior'], references=['id'],
        backref='subequipos', onDelete='restrict', tree=True,
    )
    subequipos: onetomany[Equipo]

Es una relación como cualquier otra —clave ajena, onDelete, superior y subequipos navegables, includes y escrituras anidadas— y tree=True le añade las consultas jerárquicas: ancestros, descendientes y árbol completo. El diagrama ER la dibuja como jerarquía.

En v1 es lo mismo con el tipo desnudo: superior: Equipo = relation(...) y subequipos: List[Equipo].

Con clave compuesta

La clave del padre puede tener varias columnas. Es lo normal cuando un número solo es único dentro de algo: un capítulo dentro de su libro, una llamada dentro de su mensaje.

class Capitulo(Table):
    __tablename__ = 'capitulo'
    __constraints__ = unique_constraint('libro_id', 'numero')

    id: col[bigint] = column(primary_key=True, autoincrement=True)
    libro_id: col[bigint]
    numero: col[str]                # 1, 1.2, 1.2.3… solo único en su libro
    padre: col[str | None]          # vacío en los capítulos de primer nivel

    capitulo_padre: manytoone[Capitulo] = relation(
        fields=['libro_id', 'padre'], references=['libro_id', 'numero'],
        backref='secciones', onDelete='cascade', tree=True,
    )
    secciones: onetomany[Capitulo]

La clave ajena impide que una sección cuelgue del capítulo de otro libro aunque se numere igual, y las consultas en árbol unen por las dos columnas. Una fila con alguna columna del padre vacía es una raíz: aquí, padre.

Reglas

  • Solo en un manytoone de la tabla consigo misma: hacia otra tabla no hay árbol que recorrer, y en un onetoone cada padre tendría un solo hijo.
  • Una por tabla. Una tabla puede tener más relaciones consigo misma —un «sustituido por»—, pero solo la que lleva tree=True es el árbol.
  • Lo que referencia (references) es la clave primaria o una clave única: lo exige la clave ajena.

self_reference, la forma antigua

column(self_reference='id') declaraba lo mismo sin clave ajena y con una sola columna: un padre podía no existir, borrarlo dejaba a los hijos apuntando a nada, y una jerarquía que solo es única dentro de algo (un rol dentro de su realm) mezclaba ramas. Está deprecada: sigue funcionando, el análisis avisa (W001) con el código exacto que la sustituye, y se retirará en la próxima versión.

⚠️  'Equipo.equipo_superior' declara la jerarquía con self_reference, que no crea clave
    ajena y se retirará en la próxima versión
   💡 Quita self_reference='id' de la columna 'equipo_superior' y declara la jerarquía
      como una relación de 'Equipo' consigo misma:

          padre: manytoone[Equipo] = relation(
              fields=['equipo_superior'], references=['id'],
              backref='hijos', onDelete='restrict', tree=True)
          hijos: onetomany[Equipo]

El primer push después del cambio crea la clave ajena. Si hay filas cuyo padre no existe —que self_reference permitía—, el push lo bloquea y propone soltar ese padre (la fila queda como raíz) o eliminarlas.