# Cargar datos

La carga convierte un archivo en filas de una tabla de <Term id="nexus">Nexus</Term>. Nexus lee el archivo, deduce columnas y tipos, limpia los valores y escribe una tabla <Term id="iceberg">Apache Iceberg</Term>. Puede ver primero el resultado, elegir cómo se agregan las filas y seguir la carga.

## Antes de empezar [#antes-de-empezar]

- El **Acceso** de su clave permite escribir en el <Term id="schema">esquema</Term> de destino.
- El espacio de trabajo tiene <Term id="credits">créditos</Term> y espacio para guardar los datos.
- El archivo es de un tipo que Nexus lee, como CSV, TSV, Parquet, JSON, JSON Lines, Excel, GeoJSON, GeoPackage o shapefile.

## Cargue un archivo en una tabla [#cargue-un-archivo-en-una-tabla]

<Steps>
<Step>
### Véalo antes [#véalo-antes]

`ingest_preview()` lee una muestra e informa lo que encontró, sin escribir nada:

```python
from klarety import Nexus

with Nexus.connect() as nexus:
    preview = nexus.ingest_preview("sales_2026.csv", into="sales")
    print(preview["source_format"], preview["rows_sampled"])
    for column in preview["columns"]:
        print(column)
```

Revise los nombres y tipos de columna. Si uno está mal, corrija el archivo primero.
</Step>
<Step>
### Inicie la carga [#inicie-la-carga]

```python
run = nexus.ingest("sales_2026.csv", into="sales", key=["order_id"])
print(run.run_id, run.state)
```

Una ruta local se sube por partes, así que los archivos más grandes que la memoria no son problema. `ingest()` devuelve un `IngestRun` en cuanto se acepta la carga.
</Step>
<Step>
### Sígala hasta el final [#sígala-hasta-el-final]

```python
while run.state in ("accepted", "running"):
    time.sleep(5)
    run = nexus.ingest_status(run.run_id)
print("Finished:", run.state)
```

Una carga termina como `succeeded`, `failed` o `cancelled`.
</Step>
<Step>
### Revise las filas [#revise-las-filas]

```python
print(nexus.sql("SELECT COUNT(*) AS n FROM sales").rows)
```

El script de abajo reúne los cuatro pasos.
</Step>
</Steps>

### El script completo [#el-script-completo]

```python title="load_sales.py"
import sys
import time

from klarety import InsufficientCreditsError, Nexus, RefusedError, ServiceError

PATH, TABLE = "sales_2026.csv", "sales"

with Nexus.connect() as nexus:
    try:
        run = nexus.ingest(PATH, into=TABLE, key=["order_id"])
        while run.state in ("accepted", "running"):
            time.sleep(5)
            run = nexus.ingest_status(run.run_id)
    except FileNotFoundError:
        sys.exit(f"{PATH} is neither a file nor a uri")
    except InsufficientCreditsError:
        sys.exit("The workspace is out of credits")
    except RefusedError as refused:
        sys.exit(f"Load refused: {refused}")
    except ServiceError as failed:
        sys.exit(f"Load failed on our side, try again: {failed}")

    if run.state != "succeeded":
        sys.exit(f"Load ended as {run.state}")
    print(nexus.sql(f"SELECT COUNT(*) AS n FROM {TABLE}").rows[0]["n"], "rows")
```

## Elija cómo se agregan las filas [#elija-cómo-se-agregan-las-filas]

`mode` decide qué pasa cuando la tabla ya tiene filas:

| Modo | Qué hace |
| --- | --- |
| `auto` (por defecto) | Una primera carga crea la tabla. Después, con `key` actualiza las filas cuya clave existe y agrega el resto; sin clave agrega solo las filas que aún no están. |
| `append` | Agrega todas las filas, aunque la misma fila ya esté. |
| `upsert` | Actualiza las filas cuya `key` existe y agrega el resto. Indique una `key`. |
| `replace` | Reemplaza todas las filas de la tabla por las del archivo. |

`key` nombra las columnas que identifican una fila, como `["order_id"]`. Otros parámetros:

- `into`: la tabla en la que se carga.
- `schema`: el esquema de la tabla, `default` salvo que nombre otro.
- `force`: vuelve a cargar un archivo ya cargado en esta tabla. Sin él, un archivo se carga una sola vez por tabla, así que repetir su script no hace daño.

## Cargue desde otros lugares [#cargue-desde-otros-lugares]

```python
# A file already in a folder in Object Storage: every file directly in it
run = nexus.folders.at("exports/daily").load(into="daily_exports", mode="append")

# Chosen files by their IDs
run = nexus.files.load(["file-id-1", "file-id-2"], into="daily_exports")

# A file in an Amazon S3 bucket you connected
result = nexus.connections.read(connection_id, "exports/2026-11.parquet", into="exports")
```

Para cargar cada archivo nuevo al llegar a una carpeta, use `folder.watch(into="table")`. Vea [Archivos y carpetas](/docs/es/developers/files) y [Conexiones](/docs/es/developers/connections).

## Cargue un DataFrame de Spark [#cargue-un-dataframe-de-spark]

Si preparó datos en una [sesión de Spark](/docs/es/developers/spark), cargue el DataFrame directamente:

```python
run = nexus.ingest_frame(frame, table="customer_summary", key=["customer"])
```

## Qué puede salir mal [#qué-puede-salir-mal]

| Problema | Causa | Solución |
| --- | --- | --- |
| `FileNotFoundError` | La ruta no es un archivo ni una uri. | Revise la ruta. |
| `RefusedError` | No tiene acceso de escritura, o el archivo supera lo que su plan permite por carga. El mensaje dice cuál. | Use una clave con acceso, o conecte el bucket donde está el archivo y léalo desde allí. |
| La carga termina en `failed` | El archivo no se pudo leer. | Véalo antes, corríjalo y cárguelo de nuevo. |
| No se cargó nada nuevo | El mismo archivo ya se cargó en esta tabla. | Pase `force=True` si quiere cargarlo de nuevo. |

## Próximos pasos [#próximos-pasos]

- [Tablas y esquemas](/docs/es/developers/tables) para definir reglas y describir columnas.
- [Archivos y carpetas](/docs/es/developers/files) para guardar archivos y vigilar carpetas.
- [CLI](/docs/es/developers/cli) para cargar un archivo desde su terminal con `klarety ingest`.