Saltar a contenido

Lectura

dao = public_sync_api.usuario

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.

dao.find_many(in_id=[3, 7, 12])     # WHERE id IN (3, 7, 12)
dao.count(in_id=ids)

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:

dao.find_many(nombre='An%')     # todos los que empiezan por "An"

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.

dao.find_many(in_id=[])       # [] → WHERE false
dao.find_many(in_id=None)     # todas: sin filtro

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

dao.count(activo=True)          # int
dao.exists(email='ana@x.com')   # bool

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.