Escritura¶
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(unLookupError): 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(unValueError): unupdateanidado 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¶
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:
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.