> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/cli/command-reference/sql.md).

# sql

Run SQL on your data warehouse using existing connections. Two modes: `query` returns result rows; `job` runs DDL/DML and polls to completion without returning a result set.

## `carto sql query <connection> [sql]`

Run a SQL query and return results. Queries are sent as a `POST` (no URL-length limit, 1-minute timeout).

```bash
# Query argument
carto sql query <connection> "SELECT * FROM dataset.table LIMIT 10"

# Read SQL from a file
carto sql query <connection> --file query.sql

# Pipe via stdin
echo "SELECT COUNT(*) FROM dataset.table" | carto sql query <connection>

# Bind parameters
carto sql query <connection> "SELECT * FROM t WHERE id = @id" --param id=a-001

# Run a saved named source by name
carto sql query <connection> my_named_source --param id=a-001

# JSON output
carto sql query <connection> "SELECT * FROM dataset.table" --json
```

**Options:**

| Option                 | Description                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `--file <path>`        | Read SQL from a file.                                                                                               |
| `--param <key=value>`  | Bind a query parameter. Repeatable. Values are JSON-parsed (number, boolean, array), otherwise treated as a string. |
| `--params-json <json>` | Bind query parameters from a JSON object or array, for full type control. Not combinable with `--param`.            |

## `carto sql job <connection> [sql]`

Run a DDL/DML job. Used when no result set is returned. The CLI polls every second and waits up to 10 minutes for the job to finish. For longer jobs, pass `--no-wait` and check progress with `carto sql job status`.

```bash
# CREATE TABLE
carto sql job <connection> "CREATE TABLE dataset.newtable AS SELECT * FROM dataset.oldtable"

# INSERT
carto sql job <connection> "INSERT INTO dataset.table VALUES (1, 'test')"

# Read from a file
carto sql job <connection> --file create_table.sql

# Submit and return the job ID right away
carto sql job <connection> --file create_table.sql --no-wait
```

**Options:**

| Option                 | Description                                                                       |
| ---------------------- | --------------------------------------------------------------------------------- |
| `--file <path>`        | Read SQL from a file.                                                             |
| `--no-wait`            | Submit the job and return its ID immediately instead of waiting for it to finish. |
| `--param <key=value>`  | Bind a query parameter. Repeatable. Same behavior as in `sql query`.              |
| `--params-json <json>` | Bind query parameters from a JSON object or array. Not combinable with `--param`. |

**Use cases:**

* `CREATE TABLE` operations.
* `INSERT`, `UPDATE`, `DELETE` statements.
* Long-running data transformations.
* Operations that don't return result sets.

## `carto sql job status <connection> <job-id>`

Check the status of a job submitted with `--no-wait`.

```bash
carto sql job status <connection> <job-id>
carto sql job status <connection> <job-id> --json
```

## `carto sql job cancel <connection> <job-id>`

Cancel a running job.

```bash
carto sql job cancel <connection> <job-id>
```

## Input methods (both `query` and `job`)

1. Command argument: `carto sql query myconn "SELECT * FROM table"`.
2. File: `carto sql query myconn --file query.sql`.
3. Stdin: `echo "SELECT * FROM table" | carto sql query myconn`.
4. Named source: pass the name of a saved [named source](https://docs.carto.com/carto-for-agents/cli/command-reference/named-sources.md) instead of SQL, for example `carto sql query myconn my_named_source`. CARTO runs the saved query, and `--param` / `--params-json` bind its parameters.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.carto.com/carto-for-agents/cli/command-reference/sql.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
