DataFrames

Requiere pandas en el proyecto. tai-sql no lo instala: el cliente generado lo importa solo cuando usas estos dos métodos.

Exportar

df = dao.as_dataframe(limit=1000, activo=True)

Acepta los mismos filtros que find_many —salvo los in_<campo>— y devuelve un DataFrame con los dtypes optimizados según los tipos de las columnas, no todo como object.

df = dao.as_dataframe(
    limit=500, offset=0,
    min_creado_en=datetime(2026, 1, 1),
    activo=True,
)

No acepta order_by

A diferencia de find_many. Si necesitas un orden concreto, ordénalo en el DataFrame (df.sort_values(...)) o usa find_many y constrúyelo tú.

Importar

n = dao.from_dataframe(
    df,
    mode='upsert',                 # 'create' | 'upsert'
    match_fields=['email'],
    validate_types=False,
    ignore_extra_columns=False,
    fill_missing_nullable=True,
)

Parámetro	Qué hace
mode	'create' inserta siempre; 'upsert' inserta o actualiza según match_fields
match_fields	Columnas que deciden si la fila ya existe. Por defecto, la clave natural
validate_types	Valida los tipos del DataFrame antes de insertar
ignore_extra_columns	Ignora columnas del DataFrame que no existen en la tabla
fill_missing_nullable	Rellena con None las columnas opcionales que falten

Antes de insertar, valida el DataFrame contra el esquema de la tabla: si falta una columna obligatoria o sobra una que no existe, lanza ValueError con lo que está mal, en vez de dejar una carga a medias.

Cada tabla tiene además su validador suelto, por si quieres comprobar sin insertar:

from database.public import UsuarioDataFrameValidator

UsuarioDataFrameValidator().validate_dataframe_schema(
    df, ignore_extra_columns=False, fill_missing_nullable=True
)

Cargas grandes

from_dataframe con mode='upsert' acaba en el camino de upsert_many, que usa la sentencia nativa del motor si la tabla no tiene triggers. Con triggers, el trabajo pasa a ser fila a fila: cuenta con ello antes de cargar un millón de filas.