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

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

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