> ## 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.

# Spark SQL

> Submit Spark SQL queries that write results to Iceberg tables.

## `submitSparkSql(options)`

Submit a Spark SQL query that writes its result to an Iceberg output table. Returns run info immediately; use `getRun()` or `submitSparkSqlAndWait()` to poll status.

```ts theme={null}
const submitted = await client.submitSparkSql({
  namespace: "my-namespace",
  name: "nightly-agg",
  query: "SELECT day, count(*) AS n FROM oleander.default.events GROUP BY day",
  outputTable: "default.daily_counts",
});

console.log(submitted.run_id, submitted.state); // "..." SUBMITTED
```

### Parameters

<ParamField body="options.namespace" type="string" required>
  Job namespace.
</ParamField>

<ParamField body="options.name" type="string" required>
  Job name.
</ParamField>

<ParamField body="options.query" type="string" required>
  The Spark SQL query to execute.
</ParamField>

<ParamField body="options.outputTable" type="string" required>
  The Iceberg table the query result is written to.
</ParamField>

<ParamField body="options.writeMode" type="string" default="OVERWRITE">
  `OVERWRITE` or `APPEND`. Case-insensitive on input.
</ParamField>

<ParamField body="options.driverMachineType" type="SparkMachineType" default="spark.1.b">
  Driver machine type.
</ParamField>

<ParamField body="options.executorMachineType" type="SparkMachineType" default="spark.1.b">
  Executor machine type.
</ParamField>

<ParamField body="options.executorNumbers" type="number" default="2">
  Number of executors, from 1 to 20.
</ParamField>

### Return type: `SparkSqlSubmitResponse`

| Field          | Type            | Description                                                        |
| -------------- | --------------- | ------------------------------------------------------------------ |
| `run_id`       | `string`        | The ID of the submitted run                                        |
| `state`        | `string`        | Initial run state (for example, `SUBMITTED`)                       |
| `namespace`    | `string`        | Job namespace                                                      |
| `job_name`     | `string`        | Job name                                                           |
| `pipeline_id`  | nullable string | Pipeline ID if one exists                                          |
| `submitted_at` | `string`        | ISO timestamp of submission                                        |
| `compute`      | `object`        | `driver_machine_type`, `executor_machine_type`, `executor_numbers` |
| `output_table` | `string`        | The output table                                                   |
| `write_mode`   | `string`        | The write mode used                                                |

***

## `submitSparkSqlAndWait(options)`

Submit a Spark SQL query and poll until the run reaches a terminal state (`COMPLETE`, `FAIL`, or `ABORT`). Throws an error if the timeout is exceeded.

```ts theme={null}
const { runId, state, run } = await client.submitSparkSqlAndWait({
  namespace: "my-namespace",
  name: "nightly-agg",
  query: "SELECT day, count(*) AS n FROM oleander.default.events GROUP BY day",
  outputTable: "default.daily_counts",
  writeMode: "APPEND",
});

if (state !== "COMPLETE") {
  throw new Error(`Run ${runId} ended with state: ${state}`);
}
```

Accepts all `submitSparkSql` options plus:

<ParamField body="options.pollIntervalMs" type="number" default="10000">
  Milliseconds between status polls.
</ParamField>

<ParamField body="options.timeoutMs" type="number" default="600000">
  Maximum time to wait in milliseconds before throwing a timeout error.
</ParamField>

### Return shape

| Field   | Type          | Description                                     |
| ------- | ------------- | ----------------------------------------------- |
| `runId` | `string`      | The ID of the submitted run                     |
| `state` | `string`      | Terminal state (`COMPLETE`, `FAIL`, or `ABORT`) |
| `run`   | `RunResponse` | Full run details                                |