Ejecutar SQL

nexus.sql() ejecuta una sentencia de Spark SQL en Nexus y espera la respuesta. En la app, las mismas consultas se ejecutan en DatosEditor SQL. Para scripts largos o procesamiento pesado, vea Sesiones de Spark y Trabajos.

Antes de empezarCopiar el enlace

• El SDK está instalado y usted puede conectarse (Inicio rápido del SDK).
• El Acceso de su clave permite lo que hace la sentencia. Una clave de solo lectura solo puede leer.
• El espacio de trabajo tiene créditos.

Ejecute una consultaCopiar el enlace

from klarety import Nexus, RefusedError, ServiceError

with Nexus.connect() as nexus:
    try:
        result = nexus.sql(
            "SELECT customer, SUM(amount) AS total "
            "FROM orders GROUP BY customer ORDER BY total DESC",
            max_rows=10,
        )
    except RefusedError as refused:
        raise SystemExit(f"Query refused: {refused}")
    except ServiceError as failed:
        raise SystemExit(f"Nexus could not answer, try again: {failed}")

    for row in result.rows:
        print(row["customer"], row["total"])
    print(f"Read {result.bytes_scanned} bytes")

Las tablas sin nombre de esquema se leen de default. Nombre otro esquema como esquema.tabla.

Qué se devuelveCopiar el enlace

sql() devuelve un ResultSet:

Dos tipos de valor requieren cuidado:

• Un número entero mayor que 2⁵³ llega como texto, para que ningún lector JSON lo redondee. Conviértalo con int().
• Un valor timestamptz llega en UTC sin desplazamiento escrito. Agregue Z antes de que lo lea un analizador estricto.

Pase valores con parámetrosCopiar el enlace

Nunca una la entrada del usuario al SQL. Use params: cada :nombre se llena como literal de texto, nunca se lee como SQL.

result = nexus.sql(
    "SELECT * FROM orders WHERE customer = :customer AND amount > CAST(:minimum AS DOUBLE)",
    params={"customer": "Acme", "minimum": "100"},
)

Cada valor es texto; use CAST para números y fechas en el SQL, como arriba. Un nombre de parámetro empieza con una letra o guion bajo y tiene hasta 64 letras, dígitos o guiones bajos; una sentencia acepta hasta 256 parámetros.

Controle cuántas filas se devuelvenCopiar el enlace

max_rows limita las filas devueltas: de 1 a 10.000, 1.000 por defecto, nunca más que la página de filas de su plan. Si hay más, truncated es True.

Lea un resultado grandeCopiar el enlace

Cuando un resultado no cabe en una respuesta, Nexus guarda el resto un día y define result_id. nexus.result_rows(result) lee todas las filas página por página, sin cargarlo todo en memoria:

result = nexus.sql("SELECT * FROM events WHERE day = '2026-11-01'")

if result.truncated:
    count = 0
    for row in nexus.result_rows(result):
        count += 1
    print(f"{count} rows in total")

Si result_id es None, result_rows() devuelve las filas que tiene, así que siempre es seguro llamarlo.

Estime antes de ejecutarCopiar el enlace

nexus.estimate() indica cuánto leería una sentencia, sin ejecutarla ni cobrarla:

estimate = nexus.estimate("SELECT * FROM events")
print(estimate["bytes_scanned"], estimate["allowed_bytes"], estimate["within_budget"])

Si within_budget es False, sería rechazada con OverBudgetError. Agregue un WHERE sobre una columna por la que esté organizada la tabla, seleccione menos columnas o agregue primero.

Inicie Nexus con anticipaciónCopiar el enlace

Tras un periodo sin actividad, la primera sentencia puede esperar mientras Nexus arranca. Antes de una ráfaga conocida (por ejemplo, al iniciar su app), llame a nexus.warm(); responde de inmediato y arranca Nexus en segundo plano. nexus.spark_status() le dice si está apagado, arrancando, listo u ocupado.

Reintentos y tiempos de esperaCopiar el enlace

No necesita escribir ciclos de reintento alrededor de sql():

• Cada sentencia lleva un ID elegido por el SDK. Si la conexión se cae, el SDK la reenvía con el mismo ID, y Nexus la ejecuta una sola vez.
• Cuando todos los espacios que permite su plan están ocupados, o Nexus está arrancando, el SDK espera y reintenta hasta por cinco minutos.
• Una sentencia que no terminó en ese tiempo lanza AnswerNotReadyError. Ejecútela de nuevo: nada se ejecutó dos veces.

Qué puede salir malCopiar el enlace

Próximos pasosCopiar el enlace

• Tablas y esquemas para crear y cambiar las tablas que consulta.
• Trabajos y trabajos por lotes para cambiar filas con SQL.
• Errores para la lista completa de excepciones.