> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Lake Query

> Execute SQL queries against the oleander lake.

## `query(sql, options?)`

Execute a SQL query against the oleander lake using DuckDB. Returns structured results with columns, types, and rows. If the API rejects the query, the SDK throws instead of returning a failed result.

```ts theme={null}
const result = await client.query(
  "SELECT * FROM oleander.default.flowers LIMIT 10",
);

const columns = result.results?.columns;   // ["sepal_length", "sepal_width", ...]
const rows = result.results?.rows;         // [[5.1, 3.5, ...], ...]
const count = result.row_count;            // 10
const elapsed = result.execution_time;     // "42ms"
```

### Parameters

<ParamField body="sql" type="string" required>
  The SQL query to execute. Supports DuckDB SQL syntax.
</ParamField>

<ParamField body="options.save" type="boolean" default="false">
  When `true`, persists query results as a table. The table name is returned in `saved_table_name`.
</ParamField>

### Saving results

Use `save: true` to persist query results as a table for later use.

```ts theme={null}
const result = await client.query(
  "SELECT * FROM oleander.default.flowers LIMIT 10",
  { save: true },
);

if (result.saved_table_name) {
  const followUp = await client.query(
    `SELECT avg(sepal_length) FROM ${result.saved_table_name}`,
  );
}
```

### Iterating over results

```ts theme={null}
const result = await client.query(
  "SELECT species, sepal_length FROM oleander.default.flowers LIMIT 10",
);

const { columns, rows } = result.results!;
const speciesIdx = columns.indexOf("species");
const sepalLengthIdx = columns.indexOf("sepal_length");

for (const row of rows) {
  const species = row[speciesIdx] as string;
  const sepalLength = row[sepalLengthIdx] as number;
  // process each record ...
}
```

### Return type: `LakeQueryResult`

| Field              | Type      | Description                                              |
| ------------------ | --------- | -------------------------------------------------------- |
| `success`          | `boolean` | Whether the query executed successfully                  |
| `results`          | `object`  | Query results with `columns`, `column_types`, and `rows` |
| `row_count`        | `number`  | Number of rows returned                                  |
| `execution_time`   | `string`  | Query execution time (for example, `"42ms"`)             |
| `saved_table_name` | `string`  | Table name if `save: true` was used                      |
| `query`            | `string`  | The original SQL query                                   |