# Sesiones de Spark

Una sesión de <Term id="spark">Spark</Term> le da toda la API de DataFrames de PySpark sobre sus tablas de <Term id="nexus">Nexus</Term>, mediante Spark Connect. Úsela cuando una sentencia SQL no basta: explorar en un notebook, encadenar transformaciones o preparar un DataFrame para `ingest_frame`.

Para una sola consulta, [`nexus.sql()`](/docs/es/developers/sql) es más simple y más barato. Para scripts sin supervisión, use un [trabajo](/docs/es/developers/jobs).

<Callout type="warn" title="Una sesión cobra desde que se abre">
Una sesión sigue en marcha, y usando <Term id="credits">créditos</Term>, hasta que se cierra o llega al tiempo máximo de su plan. `spark.stop()` solo cierra su lado de la conexión; cierre la sesión misma, como se muestra abajo.
</Callout>

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

- **Usted es administrador del <Term id="workspace">espacio de trabajo</Term>.** Una sesión lee el almacenamiento directamente, más allá del acceso a carpetas, así que cualquier otra persona recibe `RefusedError`.
- **Instale el extra de Spark.** Fija la versión de PySpark que usa Nexus; otras versiones fallan de formas confusas.

```bash
pip install "klarety[spark]"
```

- **El espacio de trabajo tiene créditos** para la sesión.

## Elija un rol [#elija-un-rol]

Una sesión se abre con un rol:

| Rol | Qué puede hacer la sesión |
| --- | --- |
| `read` (por defecto) | Leer tablas. |
| `write` | Leer tablas y cambiar sus filas. |
| `ddl` | Todo lo de `write`, más crear y cambiar tablas. |

Pida lo mínimo que necesite. Pedir un rol que su clave no tiene falla con `AuthError` (`401`).

## Abra, use y cierre una sesión [#abra-use-y-cierre-una-sesión]

Cerrar una sesión requiere su ID. `nexus.spark()` devuelve un `SparkSession` listo pero no el ID, así que esa sesión corre hasta el límite de su plan. Para cerrarla al terminar (el caso habitual), ábrala mediante la API, que devuelve el ID:

```python title="spark_session.py"
import os

import httpx
from pyspark.sql import SparkSession

API = "https://api.klarety.ai"

token = httpx.post(
    f"{API}/v1/token", json={"api_key": os.environ["KLARETY_API_KEY"]}, timeout=30
).raise_for_status().json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

opened = httpx.post(
    f"{API}/v1/spark/session", json={"role": "read"}, headers=headers, timeout=360
).raise_for_status().json()

spark = SparkSession.builder.remote(opened["connect_url"]).getOrCreate()
try:
    orders = spark.table("orders")
    orders.groupBy("customer").count().orderBy("count", ascending=False).show(10)
finally:
    spark.stop()
    httpx.delete(
        f"{API}/v1/spark/session/{opened['session_id']}", headers=headers, timeout=30
    ).raise_for_status()
    print("Session closed")
```

El bloque `finally` cierra la sesión aunque su código falle. Abrirla puede tardar unos minutos, de ahí el tiempo de espera largo. La respuesta también trae `expires_at`, cuando la conexión deja de aceptarse.

### El atajo del SDK [#el-atajo-del-sdk]

Para una mirada rápida en la que la sesión puede correr hasta el límite de su plan, el SDK la abre en una línea:

```python
from klarety import KlaretyError, Nexus

with Nexus.connect() as nexus:
    try:
        spark = nexus.spark(role="read")
    except KlaretyError as refused:
        raise SystemExit(str(refused))
    spark.table("orders").show(5)
```

`nexus.spark()` se niega antes de abrir nada si falta PySpark ("install klarety[spark] to open a Spark session") o si su versión es distinta de la de Nexus, nombrando ambas versiones; reinstale con `pip install "klarety[spark]"`.

## Vea qué hace Spark [#vea-qué-hace-spark]

```python
with Nexus.connect() as nexus:
    print(nexus.spark_status())  # off, starting, ready or busy
    print(nexus.spark_usage())   # your machine's CPUs and memory, and their use over the last hour
```

## Cargue un DataFrame en una tabla [#cargue-un-dataframe-en-una-tabla]

`nexus.ingest_frame()` escribe un DataFrame en una tabla de Nexus con la misma limpieza que una carga de archivo:

```python
run = nexus.ingest_frame(summary_frame, table="customer_summary", key=["customer"])
print(run.run_id, run.state)
```

Con `key`, las filas existentes se actualizan en vez de agregarse dos veces. Siga la carga con `nexus.ingest_status(run.run_id)`, como en [Cargar datos](/docs/es/developers/ingest).

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

| Problema | Causa | Solución |
| --- | --- | --- |
| `RefusedError` al abrir | Usted no es administrador del espacio de trabajo. | Pida a un administrador que la abra. |
| `AuthError` al abrir | La clave no tiene el rol que pidió. | Pida `read`, o use una clave con más acceso. |
| `InsufficientCreditsError` | El espacio de trabajo no puede pagar una sesión. | Agregue créditos. |
| `install klarety[spark] to open a Spark session` | PySpark no está instalado. | `pip install "klarety[spark]"`. |
| Un mensaje que nombra dos versiones de PySpark | Su versión de PySpark difiere de la de Nexus. | Reinstale con `pip install "klarety[spark]"`. |
| `429` al abrir | Todas las sesiones que permite su plan están en uso. | Cierre una sesión que ya no necesite, o intente más tarde. |
| Los créditos siguen bajando después de terminar | La sesión no se cerró. | Ciérrela con su `session_id`. |

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

- [Ejecutar SQL](/docs/es/developers/sql) para consultas sueltas.
- [Trabajos y trabajos por lotes](/docs/es/developers/jobs) para correr un script en segundo plano.
- [Límites y límites de solicitudes](/docs/es/developers/limits) para leer los límites de sesión de su plan.