Lectura¶
find — por clave primaria¶
usuario = dao.find(id=1) # UsuarioRead | None
usuario = dao.find(id=1, includes=['posts'])
usuario = dao.find(id=1, includes=['posts', 'posts.comentarios'])
| Parámetro | Para qué |
|---|---|
| la clave primaria | Se llama como la columna (id=, codigo=…) |
includes |
Relaciones a cargar |
rls |
Regla de filtrado por fila |
session |
Participar en una transacción existente |
find_by — por una clave única¶
Las tablas con claves únicas además de la primaria —una columna unique=True, una
unique_constraint(...) o un índice único— tienen un find_by, que busca por una de ellas y devuelve
un registro o None, como find. Es uno por tabla, para todas sus claves:
autor = dao.find_by(nombre='cervantes') # autor.nombre es unique=True
libro = dao.find_by(autor_id=3, titulo='El Quijote') # unique_constraint('autor_id', 'titulo')
libro = dao.find_by(autor_id=3, titulo='El Quijote', includes=['autor'])
Cada llamada busca por una clave, con todas sus columnas y solo ellas. Con dos claves, como
ficha_tecnica con (isbn) y (libro_id), se busca por una o por la otra:
ficha = dao.find_by(isbn='978-84-376-0494-7')
ficha = dao.find_by(libro_id=3)
ficha = dao.find_by(isbn='978-84-376-0494-7', libro_id=3) # ValueError
Las dos a la vez no: con OR podrían ser dos registros, y con AND la segunda solo comprobaría lo que ya
encuentra la primera. Media clave tampoco, ni un valor None: varios NULL no chocan con un UNIQUE,
así que no sería un registro. El ValueError dice qué claves valen, y la docstring de cada find_by
las lista. Acepta includes, rls y session, como find, e include_vectors si la tabla tiene
columnas vectoriales: sin él, el vector ni se carga ni se devuelve.
Solo cuentan las claves que no encuentra ya otra: la que contiene la primaria, o contiene otra clave
única, no está en find_by; y una tabla sin más unicidad que la primaria no lo tiene. Tampoco la de
una columna cifrada o hasheada: lo guardado lleva IV o salt, y la igualdad no lo encontraría.
tai-api lo expone como GET /{tabla}/find-by, con las claves de la tabla en su descripción del OpenAPI.
find_many — con filtros¶
usuarios = dao.find_many(
limit=10, offset=20,
order_by=['creado_en', 'nombre'], order='DESC',
nombre='Ana', # igualdad
in_email=['a@x.com', 'b@x.com'], # IN (OR lógico)
min_creado_en=datetime(2026, 1, 1), # >= (incluido)
max_creado_en=datetime(2026, 12, 31),
includes=['posts'],
)
Qué filtros existen para cada columna¶
Los genera el tipo de la columna, no una convención genérica:
| Tipo | Filtros generados |
|---|---|
int, bigint, smallint, date |
<campo>, in_<campo>, min_<campo>, max_<campo> |
str, text |
<campo>, in_<campo> |
float, numeric, datetime, timestamptz, time |
min_<campo>, max_<campo> |
bool |
<campo> |
dict, largebinary |
ninguno |
Las claves primarias y foráneas siempre reciben <campo> e in_<campo>, sea cual sea su
tipo.
La clave primaria autoincremental es la excepción: solo tiene in_<pk>, ni igualdad ni
rango. Para un registro está find(id), y un rango sobre un contador que pone el motor no dice
nada del dato; pero pedir varios por su id —los que devolvió otra consulta, un nivel de un grafo—
sí es una pregunta, y sin el filtro costaba una consulta por id.
Las columnas cifradas y hasheadas no tienen ningún filtro: la sal o el vector de inicialización hacen que dos filas con el mismo valor guarden textos distintos.
Búsqueda por patrón
En las columnas de texto, el filtro de igualdad acepta patrones con % y se resuelve como
ILIKE:
Los min_/max_ son inclusivos (>= y <=), y los filtros se combinan con AND. Para un
OR sobre valores de la misma columna, in_<campo>.
Una lista vacía es «ninguna fila»
in_<campo>=[] no casa con nada: find_many(in_id=[]) devuelve [], count() da 0,
exists() da False y una agregación, la de un conjunto vacío. Es lo que se espera de
una lista calculada —los ids que devolvió otra consulta— que sale vacía. «Sin filtro» es
None, o no pasarlo.
Cambio de comportamiento. Hasta 0.7.21 una lista vacía se ignoraba, como si
el filtro no estuviera, y find_many(in_id=[]) devolvía todas las filas. Quien pasaba []
para decir «todos» tiene que pasar None.
Relaciones: includes¶
dao.find_many(includes=['autor']) # una relación
dao.find_many(includes=['autor', 'autor.empresa']) # anidada, con notación de punto
dao.find_many(includes=['autor', 'comentarios']) # varias
Sin includes, las relaciones no vienen cargadas. Con él, se cargan de forma optimizada —una
consulta, no N+1— hasta el max_depth que declare el generador (5 por defecto).
Orden y paginación¶
dao.find_many(order_by=['creado_en'], order='DESC')
dao.find_many(limit=10) # los 10 primeros
dao.find_many(limit=10, offset=20) # la tercera página de 10
order se aplica a todas las columnas de order_by, y solo tiene efecto si hay order_by.
count y exists¶
Aceptan los mismos filtros que find_many. exists cuenta por dentro y compara con cero, así
que cuesta lo mismo que count: elígelo por legibilidad, no por rendimiento.
Lo que devuelve¶
Un DTO Pydantic <Modelo>Read, no el modelo de SQLAlchemy. Es un objeto normal, sin sesión
detrás: se puede serializar, devolver por una API o guardar, y no lanza DetachedInstanceError.
usuario = dao.find(id=1, includes=['posts'])
usuario.nombre # str
usuario.posts # List[PostRead], ya cargada
usuario.model_dump() # dict
usuario.model_dump_json() # str
Las columnas cifradas vienen descifradas, y
las vectoriales no vienen salvo que las pidas con include_vectors=True.