Saltar a contenido

Escritura

dao = public_sync_api.usuario

Crear

usuario = dao.create(UsuarioCreate(nombre='Ana', email='ana@x.com'))   # → UsuarioRead
usuarios = dao.create_many([UsuarioCreate(...), UsuarioCreate(...)])   # → List[UsuarioRead]

create devuelve la fila creada, ya con su clave primaria asignada, y create_many las devuelve todas, en el mismo orden que la lista que recibió. Quien inserta necesita la fila que ha quedado —su clave autogenerada, sus defaults, lo que hayan escrito los triggers—, y contar las filas no se lo daba: hasta la 0.7.20 create_many solo devolvía cuántas.

Lo devuelto va sin las columnas vectoriales, como en find: se guardan, pero no se devuelven salvo que se pidan con include_vectors=True. Lo anidado sale siempre sin ellas.

Con relaciones anidadas

Los DTOs Create admiten el objeto relacionado, y tai-sql resuelve las claves foráneas:

public_sync_api.post.create(
    PostCreate(
        titulo='Hola',
        contenido='...',
        autor=UsuarioCreate(nombre='Ana', email='ana@x.com'),
    )
)

Actualizar

# Por clave primaria
n = dao.update(id=1, updated_values=UsuarioUpdateValues(email='nueva@x.com'))   # → int

# Masiva: filtros + valores
n = dao.update_many(UsuarioUpdate(
    filter=UsuarioFilter(activo=False),
    values=UsuarioUpdateValues(activo=True),
))

UsuarioUpdateValues solo lleva los campos que quieres escribir: lo que no declares no se toca.

Con relaciones anidadas

update también crea, actualiza y borra hijos de las relaciones one-to-many (en listas) y one-to-one implícitas (en singular), en la misma transacción:

dao.update(id=1, updated_values=UsuarioUpdateValues(
    posts=UsuarioPostsNestedUpdate(
        delete=[3],                                            # por clave primaria
        update=[PostUpdateNested(id=4, values=PostUpdateValues(titulo='Otro'))],
        create=[PostCreate(titulo='Nuevo', contenido='...')],  # la FK la pone el padre
    ),
))

Se aplican en este orden: delete → update → create, escribas el DTO como lo escribas. Es lo que permite quitar un hijo de clave natural y volver a ponerlo en la misma llamada —lo que hace un formulario que reenvía la lista entera—: cuando llega el alta, la fila vieja ya no está. Hasta la 0.7.21 se creaba primero y eso era un error de clave duplicada. Con este orden, un update de una fila que el mismo payload borra no la encuentra (un NestedRowNotFound, abajo), y uno de una fila que el mismo payload crea tampoco: sus valores van en el create.

Solo los hijos de ese registro

Un update o delete anidado solo alcanza a los hijos del registro que se actualiza: el DAO acota la búsqueda por la unión con el padre (post.autor_id = 1) y por las reglas rls que recibe update(), que bajan a los hijos y, desde ellos, a los nietos. Lo que no casa no se salta:

from database.database.public import NestedRowNotFound, NestedParentMismatch

try:
    dao.update(id=1, updated_values=UsuarioUpdateValues(
        posts=UsuarioPostsNestedUpdate(delete=[99]),    # el post 99 es de otro usuario
    ))
except NestedRowNotFound as error:
    error.field     # 'posts.delete.0': dónde estaba en el payload
    error.table     # 'post'
    error.key       # 99
  • NestedRowNotFound (un LookupError): la fila no existe, cuelga de otro registro o la regla de RLS no la alcanza. Los tres son el mismo error a propósito —distinguirlos delataría lo que la regla oculta—. En una API de tai-api, un 404.
  • NestedParentMismatch (un ValueError): un update anidado cambia la FK que une el hijo al padre, que lo sacaría de debajo del registro bajo el que se nombró. Reenviar el valor que ya tiene no es un cambio. Para mover una fila de padre, el DAO de su tabla. En tai-api, un 422.

Las dos heredan de NestedWriteError, llevan reason ('not_found' / 'parent_mismatch') y la marca tai_nested_write, y su field es la ruta entera desde el registro raíz (libros.update.0.values.resenas.delete.1 a dos niveles). La transacción se deshace entera: ni el padre ni los otros hijos quedan escritos. Hasta la 0.7.21 el hijo se buscaba solo por su clave —delete=[99] borraba el post de otro usuario—, rls no bajaba a los anidados, y un hijo que no se encontraba se ignoraba.

Un hijo anidado no trae su padre

Un hijo que se crea anidado cuelga del registro bajo el que se escribe, así que no puede traer la relación con su padre: PostCreate(autor=UsuarioCreate(...)) dentro de posts.create —o de UsuarioCreate(posts=[...])— no se construye (ValidationError con el sitio y la solución; un 422 en tai-api), y el DAO lo comprueba otra vez por si el DTO se modificó después. Con ella se creaba otro usuario y el post acababa colgando de él, o, al crear, ese usuario se perdía sin error. La columna FK (autor_id) sí puede llegar: la pone siempre el padre, con el valor que traiga.

Un update solo con anidados, sin ninguna columna del padre, también los aplica: busca el padre con la misma regla de RLS que recibe y devuelve 1 si existe; si no lo alcanza, 0 y no toca ningún hijo. Hasta la 0.7.21, en una tabla sin campos operativos devolvía 0 sin escribir nada, y una API de tai-api lo convertía en un 404 sobre una fila que existe.

update_many no admite escrituras anidadas

Un anidado nombra hijos de un registro; un masivo no tiene uno, sino un filtro. UsuarioUpdate no se construye con ellos (ValidationError sobre values; en tai-api, un 422 en el PATCH masivo) y update_many lo vuelve a comprobar antes de escribir, por si el DTO se modificó después de validarse. Hasta la 0.7.21 su UPDATE ... SET los descartaba sin error, y por el camino fila a fila se aplicaban una vez por cada fila que casara. Para tocar hijos, update() por registro o el DAO de la tabla hija.

update_many va fila a fila cuando hace falta

Si la tabla tiene triggers de update, o los valores tocan una columna cifrada o hasheada, update_many busca las filas que casan con el filtro y llama a update() con cada una, en la misma transacción: los triggers se ejecutan por fila y los setters cifran o hashean. Si no, es una sola sentencia UPDATE ... WHERE, que no tiene nada de eso que saltarse. Por los dos caminos devuelve cuántas filas cambió.

Upsert

usuario = dao.upsert(
    UsuarioCreate(nombre='Ana', email='ana@x.com'),
    match_fields=['email'],
)

n = dao.upsert_many(registros, match_fields=['email'], batch_size=1000)

match_fields son las columnas con las que se decide si la fila ya existe. Por defecto, la clave natural de la tabla. Cada registro las trae con valor, y en upsert_many ninguna clave puede repetirse: las dos cosas son un ValueError antes de escribir nada.

Sin triggers Con triggers
upsert SELECT + create() o update() igual, y los hooks se ejecutan
upsert_many sentencia nativa del motor (INSERT ... ON CONFLICT, INSERT ... ON DUPLICATE KEY), por lotes separa altas y modificaciones, y delega en create_many() y update()

Qué se escribe

Un upsert escribe lo que se ha dicho al construir cada DTO, registro a registro:

El campo… Si la fila es nueva Si la fila ya existía
se pasa con valor ese valor ese valor
se pasa como None NULL NULL
no se pasa el default de la columna no se toca

Una columna server_now pasada como None cuenta como no pasada: es NOT NULL, así que la pone la base de datos (NOW()), como en create(). Y una columna de match_fields con default en el DTO que no se pasa cuenta con ese default: es la fila que se insertaría.

# Ana ya existe con teléfono. Esto le quita el teléfono y no toca nada más
dao.upsert_many([UsuarioCreate(email='ana@x.com', nombre='Ana', telefono=None)])

# Y esto no toca su teléfono
dao.upsert_many([UsuarioCreate(email='ana@x.com', nombre='Ana')])

Lo que no se escribe nunca en una fila que ya existía: las columnas de match_fields, la clave generada, created_at/created_by y las columnas hasheadas. Una contraseña se escribe al crear la fila y, después, solo si se pide con update_columns: relanzar una carga con la contraseña inicial no puede devolver a su valor de fábrica la que alguien ya cambió. Las calculadas se recalculan con la fila completa.

Con operative_fields, la auditoría es la de create() y update(): created_* con el usuario de username_context() al insertar, updated_* al actualizar. Si de lo dicho no hay nada que actualizar, la fila queda como estaba, updated_at incluido.

Hasta la 0.8.7, un None no se escribía

El DTO se pasaba a diccionario quitando los None, y upsert_many decidía las columnas con el primer registro: una columna nula en el primero no se actualizaba en ninguno, y poner una a NULL no era posible. Si tu código pasaba None contando con que no pisara, ahora pisa. Para conservar lo de antes, no pases la clave: UsuarioCreate(**{k: v for k, v in fila.items() if v is not None}). Ver Actualizar a 0.8.8.

update_columns: qué se actualiza en las filas que ya existían

# Las filas nuevas se crean completas; en las existentes, solo cambia el precio
dao.upsert_many(articulos, update_columns=['precio'])

# Crear lo que falte sin tocar lo que ya existe
dao.upsert_many(categorias_base, update_columns=[])

# Reescribir también la contraseña
dao.upsert_many(usuarios, update_columns=['password', 'email'])

Es un parámetro por nombre de upsert, upsert_many y from_dataframe(mode='upsert'), y también de t.upsert/t.upsert_many dentro de un trigger. De la lista, se actualizan las que trae cada registro. Una columna que no existe, que está en match_fields, que es la clave generada, una calculada o una de auditoría es un ValueError antes de escribir.

upsert_many no admite escrituras anidadas (ValueError): escribe solo filas de su tabla. upsert sí las admite cuando crea la fila (va por create()), y las rechaza si ya existía.

Una columna vectorial que el DAO calcula de otra (source) se actualiza con su origen, aunque update_columns no la nombre.

Borrar

n = dao.delete(id=1)            # → int
n = dao.delete_many(activo=False)

delete_many acepta los mismos filtros que find_many.

delete_many() sin filtros vacía la tabla

No hay una confirmación que te salve. Si el borrado es ancho, compruébalo primero con count().

Una lista vacía no cuenta como «sin filtro»: delete_many(in_id=[]) no borra nada y devuelve 0, y lo mismo un update_many cuyo Filter lleva in_<campo>=[]. Ninguno de los dos dispara triggers: por el camino fila a fila no encuentran filas, y por el directo la sentencia lleva WHERE false. Hasta 0.7.21 era al revés —una lista vacía se ignoraba y delete_many(in_id=[]) vaciaba la tabla—, así que si la lista se calculaba y salía vacía, el borrado era total y silencioso.

Auditoría

Si el schema declara operative_fields=True, todas las escrituras rellenan created_at, updated_at, created_by y updated_by por su cuenta. El usuario sale del contexto:

from database.public import set_username
set_username('ana')

Ver auditoría.

Triggers

Lo que declares como trigger se ejecuta dentro de estas operaciones, en la misma transacción, salvo en los caminos masivos que dice la tabla de arriba.

Todo en una transacción

with sync_session_manager.get_session() as session:
    usuario = dao.create(UsuarioCreate(nombre='Ana'), session=session)
    public_sync_api.post.create(
        PostCreate(titulo='Primero', contenido='...', autor_id=usuario.id),
        session=session,
    )

Ver sesiones y transacciones.