El cliente generado¶
Es un paquete Python autónomo que produce PythonClientGenerator. No importa tai_sql: sus
únicas dependencias en runtime son sqlalchemy, pydantic, tai_alphi y —si el schema las
pide— cryptography, pgvector, los encoders sobre langchain y pandas.
Eso es deliberado: tai-sql es una herramienta de desarrollo, y el cliente se despliega donde tai-sql no está instalado.
Nunca se edita
Todo el directorio es desechable: se borra y se regenera. Si el cliente no hace lo que necesitas, el cambio va en el schema.
Estructura¶
<schema>/
├── __init__.py fachada: <schema>_sync_api, <schema>_async_api, DTOs, modelos
├── _base.py declarative base, cifrado si aplica
├── _session.py gestión de sesiones y pool
├── _shared/ utilidades comunes: agregaciones, RLS, contexto de usuario
└── <tabla>/
├── model.py modelo SQLAlchemy
├── dtos.py DTOs Pydantic
├── dao_sync.py operaciones síncronas
└── dao_async.py operaciones asíncronas
La fachada¶
from database.public import (
public_sync_api, # namespace de todos los DAOs síncronos
public_async_api, # el equivalente asíncrono
sync_session_manager, # el gestor de sesiones
Usuario, UsuarioRead, UsuarioCreate, UsuarioFilter,
UsuarioUpdate, UsuarioUpdateValues,
set_username, username_context,
AggRequest, AggField, GroupByField, DatetimeTrunc, AggOrderBy,
RLS,
)
Cada tabla, vista y enumerado es una propiedad de la fachada, con su nombre físico:
public_sync_api.usuario # → UsuarioSyncDAO (tabla: CRUD completo)
public_sync_api.post # → PostSyncDAO
public_sync_api.resumen_autor # → ResumenAutorSyncDAO (vista: solo lectura)
public_sync_api.estado # → EnumModel (enumerado: sus valores)
Los DAOs son stateless —todos sus métodos son classmethod—, así que la fachada es solo un
espacio de nombres. Se pueden usar directamente si prefieres importar la clase:
Lo que hay en cada DAO¶
| Grupo | Métodos |
|---|---|
| Lectura | find, find_many, count, exists |
| Escritura | create, create_many, update, update_many, upsert, upsert_many, delete, delete_many |
| Agregación | sum, mean, max, min, agg |
| DataFrames | as_dataframe, from_dataframe |
| Vectorial | find_similar_by_<columna>, una por cada vector_column() |
Solo lectura: find_many, count, exists, as_dataframe y las agregaciones. Ni find
—necesitaría clave primaria— ni nada que escriba.
El parámetro session¶
Todos los métodos aceptan un session= opcional. Sin él, cada llamada abre su propia
transacción y la cierra; pasándoles la misma sesión, varias operaciones van en una sola. Ver
sesiones y transacciones.
Sincrono y asíncrono¶
Con mode='both' (el valor por defecto) se generan las dos variantes, con la misma API: