# Hágale una pregunta a sus datos

<TLDR>
Abra el **Editor SQL**, haga clic en el nombre de una tabla para insertarlo, escriba un `SELECT` y pulse **Ejecutar** (Cmd o Ctrl Enter). Desde código, `nx.sql("...")` devuelve las mismas filas. Los resultados grandes se paginan, y el editor muestra cuánto lee una consulta antes de ejecutarla.
</TLDR>

## Qué va a construir [#qué-va-a-construir]

Tres consultas <Term id="sql">SQL</Term> sobre una <Term id="table">tabla</Term> real: un vistazo a las filas, un conteo y un resumen agrupado que responde una pregunta de negocio. Además, cómo leer resultados grandes y qué hacer cuando se rechaza una consulta.

Los ejemplos usan una tabla `orders` con las columnas `order_id`, `customer`, `amount` y `created_at`. Use los nombres de su propia tabla.

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

- Una tabla en <Term id="nexus">Nexus</Term>. Si no tiene, siga primero [Convierta una hoja de cálculo en tabla](/docs/es/guides/spreadsheet-to-table).
- Acceso para leer esa tabla. Los propietarios y administradores leen todo; los miembros necesitan **Leer sus datos** en [Acceso a datos](/docs/es/data/data-access).
- Para desarrolladores: el <Term id="sdk">SDK</Term> instalado y una <Term id="api-key">clave de API</Term>. Vea el [Inicio rápido](/docs/es/get-started/quickstart).

<Callout type="info" title="Consejo">
Agregue un `LIMIT` mientras explora para mantener los resultados rápidos y dentro del tamaño de su plan.
</Callout>

## Pasos [#pasos]

<ForEveryone>
<Steps>
<Step>
### Abra el Editor SQL [#abra-el-editor-sql]
Vaya a <AppLink to="data.sql" />. El panel lateral muestra sus <Term id="schema">esquemas</Term> y tablas, con un buscador. Haga clic en un nombre para insertarlo, o parta de una consulta lista para ver filas o contarlas.

<Screenshot src="/docs/_media/sql-editor.png" alt="El panel lateral del Editor SQL con esquemas, tablas, buscador y consultas listas" />
</Step>
<Step>
### Mire las filas [#mire-las-filas]
```sql
SELECT * FROM orders LIMIT 100
```
Seleccione **Ejecutar** o pulse Cmd Enter (Ctrl Enter en Windows). Las filas aparecen debajo, con el número de filas.
</Step>
<Step>
### Cuéntelas [#cuéntelas]
```sql
SELECT COUNT(*) AS orders FROM orders
```
</Step>
<Step>
### Responda una pregunta [#responda-una-pregunta]
¿Qué clientes gastaron más el mes pasado?

```sql
SELECT customer, SUM(amount) AS total
FROM orders
WHERE created_at >= DATE '2026-10-01' AND created_at < DATE '2026-11-01'
GROUP BY customer
ORDER BY total DESC
LIMIT 10
```
</Step>
<Step>
### Vea el costo antes de ejecutar [#vea-el-costo-antes-de-ejecutar]
El editor muestra cuántos datos lee la consulta y avisa antes de ejecutar una que su plan no permite. Acótela con un `WHERE` sobre una fecha o una clave.
</Step>
</Steps>
</ForEveryone>

<ForDevelopers>
<Steps>
<Step>
### Conéctese [#conéctese]
```python
from klarety import Nexus

nx = Nexus.connect()  # reads KLARETY_API_KEY
```
</Step>
<Step>
### Ejecute una consulta [#ejecute-una-consulta]
```python
result = nx.sql("SELECT * FROM orders LIMIT 100")
print(len(result), "rows, read", result.bytes_scanned, "bytes")
for row in result.rows[:5]:
    print(row)
```
</Step>
<Step>
### Pase valores de forma segura [#pase-valores-de-forma-segura]
Use marcadores `:name` y `params`. Cada valor se inserta como texto literal, nunca como SQL, así que conviértalo donde se espera un número o una fecha:

```python
top = nx.sql(
    """
    SELECT customer, SUM(amount) AS total
    FROM orders
    WHERE created_at >= CAST(:start AS DATE) AND created_at < CAST(:end AS DATE)
    GROUP BY customer
    ORDER BY total DESC
    LIMIT 10
    """,
    params={"start": "2026-10-01", "end": "2026-11-01"},
)
print(top.rows)
```
</Step>
<Step>
### Estime antes de ejecutar [#estime-antes-de-ejecutar]
`estimate` le dice qué leería una sentencia y si su plan lo permite, sin ejecutarla.

```python
print(nx.estimate("SELECT * FROM orders"))
```
</Step>
<Step>
### Lea un resultado grande [#lea-un-resultado-grande]
`max_rows` va de 1 a 10,000, y como mucho llega a la vez una página de filas de su plan. Cuando hay más filas, `truncated` es verdadero y `result_rows` lee todas:

```python
result = nx.sql("SELECT * FROM orders", max_rows=10000)
if result.truncated:
    for row in nx.result_rows(result):
        ...
```
</Step>
</Steps>
</ForDevelopers>

<Screenshot src="/docs/_media/sql-editor.png" alt="El Editor SQL con una consulta y sus resultados" />

## Compruebe que funcionó [#compruebe-que-funcionó]

- El conteo coincide con el número de filas que espera en la tabla.
- La consulta agrupada devuelve como mucho diez filas, el total mayor primero.
- Desde código, `result.rows` es una lista de diccionarios con el nombre de cada columna.

## Si algo sale mal [#si-algo-sale-mal]

<Accordions>
<Accordion title="No se encuentra la tabla">
Revise su nombre exacto y su esquema en el panel lateral. Desde código, liste las tablas con `nx.tables.list()`, o ejecute `klarety tables`.
</Accordion>
<Accordion title="El resultado dice que solo se guarda la primera parte">
El resultado completo superó el tamaño de su plan. Acote la consulta o agregue un `LIMIT`. Sus límites están en <AppLink to="settings.usage" />, o en `nx.limits()` desde código.
</Accordion>
<Accordion title="Se rechaza la consulta">
Puede que no tenga **Leer sus datos** en esa tabla, o que la consulta lea más de lo que permite su plan. Desde código esto lanza `RefusedError` o `OverBudgetError`. Vea [Errores](/docs/es/developers/errors).
</Accordion>
<Accordion title="Los números grandes llegan como texto">
Desde código, un número entero mayor que 2^53 llega como texto para que ningún lector JSON lo redondee. Conviértalo con `int()`.
</Accordion>
</Accordions>

## Siguientes pasos [#siguientes-pasos]

- [Editor SQL](/docs/es/data/sql-editor): todo lo que hace el editor.
- [SQL desde código](/docs/es/developers/sql): parámetros, paginación y errores a fondo.
- [Envíe un informe diario](/docs/es/guides/daily-report): que un agente ejecute una consulta así cada mañana.