# 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. Default behavior is `POST` (no caching, 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>

# Cached read (GET, 1-year cache, 1-minute timeout)
carto sql query <connection> "SELECT * FROM dataset.table" --cache

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

**Options:**

| Option          | Description                                              |
| --------------- | -------------------------------------------------------- |
| `--cache`       | Use `GET` with caching (1-year cache, 1-minute timeout). |
| `--file <path>` | Read SQL from a file.                                    |

**Default behavior:** `POST`, no caching, no URL length limit, 1-minute timeout.

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

Run a DDL/DML job. Polls until complete; no timeout. Used when no result set is returned.

```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
```

**Use cases:**

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

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


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.