Saltar a contenido

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, para validar
update_columns En 'upsert', las únicas columnas que se actualizan en las filas que ya existían (ver Upsert)

En 'upsert', cada columna del DataFrame se escribe en todas sus filas: un NaN o un None es un NULL. Una columna que no está en el DataFrame no se toca en las filas que ya existían, aunque fill_missing_nullable la haya añadido para validar. Para no pisar una columna, que no esté en el DataFrame. Hasta la 0.8.7 un NaN no se escribía nunca.

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.