# Ask your data a question

<TLDR>
Open the **SQL editor**, click a table name to insert it, write a `SELECT` and press **Run** (Cmd or Ctrl Enter). From code, `nx.sql("...")` returns the same rows. Large results are paged, and the editor shows what a query reads before it runs.
</TLDR>

## What you will build [#what-you-will-build]

Three <Term id="sql">SQL</Term> queries on a real <Term id="table">table</Term>: a look at the rows, a count, and a grouped summary that answers a business question. Plus how to read large results and what to do when a query is refused.

The examples use an `orders` table with `order_id`, `customer`, `amount` and `created_at` columns. Use your own table and column names.

## Before you start [#before-you-start]

- A table in <Term id="nexus">Nexus</Term>. If you have none, follow [Turn a spreadsheet into a table](/docs/guides/spreadsheet-to-table) first.
- Access to read that table. Owners and admins can read everything; members need **Read its data** given in [Data access](/docs/data/data-access).
- For developers: the <Term id="sdk">SDK</Term> installed and an <Term id="api-key">API key</Term>. See the [Quickstart](/docs/get-started/quickstart).

<Callout type="info" title="Tip">
Add a `LIMIT` while you explore to keep results fast and inside your plan's size.
</Callout>

## Steps [#steps]

<ForEveryone>
<Steps>
<Step>
### Open the SQL editor [#open-the-sql-editor]
Go to <AppLink to="data.sql" />. The side panel lists your <Term id="schema">schemas</Term> and tables; **Find a table** searches. Click a name to insert it, or start from **Preview rows** or **Count rows**.

<Screenshot src="/docs/_media/sql-editor.png" alt="The SQL editor side panel with schemas, tables, Find a table, Preview rows and Count rows" />
</Step>
<Step>
### Look at the rows [#look-at-the-rows]
```sql
SELECT * FROM orders LIMIT 100
```
Select **Run** or press Cmd Enter (Ctrl Enter on Windows). The rows appear below with the row count.
</Step>
<Step>
### Count them [#count-them]
```sql
SELECT COUNT(*) AS orders FROM orders
```
</Step>
<Step>
### Answer a question [#answer-a-question]
Which customers spent the most last month?

```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>
### Read the cost before you run [#read-the-cost-before-you-run]
Above the results, the editor shows how much data the query reads, and warns before running one your plan does not allow. Narrow it with a `WHERE` clause on a date or key.
</Step>
</Steps>
</ForEveryone>

<ForDevelopers>
<Steps>
<Step>
### Connect [#connect]
```python
from klarety import Nexus

nx = Nexus.connect()  # reads KLARETY_API_KEY
```
</Step>
<Step>
### Run a query [#run-a-query]
```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>
### Pass values safely [#pass-values-safely]
Use `:name` placeholders and `params`. Each value is filled in as a string literal, never as SQL, so cast it where a number or date is meant:

```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>
### Estimate before running [#estimate-before-running]
`estimate` tells you what a statement would read and whether your plan allows it, without running it.

```python
print(nx.estimate("SELECT * FROM orders"))
```
</Step>
<Step>
### Read a large result [#read-a-large-result]
`max_rows` is 1 to 10,000, and at most your plan's page of rows comes back at once. When more rows exist, `truncated` is true and `result_rows` reads every row:

```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="The SQL editor with a query and its results" />

## Check that it worked [#check-that-it-worked]

- The count matches the number of rows you expect in the table.
- The grouped query returns at most ten rows, largest total first.
- From code, `result.rows` is a list of dictionaries keyed by column name.

## If something goes wrong [#if-something-goes-wrong]

<Accordions>
<Accordion title="The table is not found">
Check its exact name and schema in the side panel. From code, list tables with `nx.tables.list()`, or run `klarety tables`.
</Accordion>
<Accordion title="The result says only the first part is kept">
The whole result passed your plan's size. Narrow the query or add a `LIMIT`. Your limits are in <AppLink to="settings.usage" />, or `nx.limits()` from code.
</Accordion>
<Accordion title="The query is refused">
You may not have **Read its data** on that table, or the query reads more than your plan allows. From code this raises `RefusedError` or `OverBudgetError`. See [Errors](/docs/developers/errors).
</Accordion>
<Accordion title="Large numbers come back as text">
From code, a whole number past 2^53 comes back as text so no JSON reader rounds it. Convert it with `int()`.
</Accordion>
</Accordions>

## Next steps [#next-steps]

- [SQL editor](/docs/data/sql-editor): everything the editor does.
- [SQL from code](/docs/developers/sql): parameters, paging and errors in depth.
- [Send a daily report](/docs/guides/daily-report): have an agent run a query like this every morning.