# named-sources

Manage **Named Sources** — server-side aliases for SQL queries. Instead of exposing raw SQL in client applications, create a Named Source with a name and reference it by name wherever the CARTO APIs accept a `sqlQuery` parameter.

{% hint style="info" %}
The Named Sources API requires **OAuth Access Tokens** (from `carto auth login`), not API Access Tokens.
{% endhint %}

```bash
carto named-sources list                              # List named sources
carto named-sources get <name>                        # Get named source details
carto named-sources create --name <n> --source <sql>  # Create named source
carto named-sources update <name> --source <sql>      # Update named source
carto named-sources delete <name>                     # Delete named source
```

## `carto named-sources list`

| Option             | Description                   |
| ------------------ | ----------------------------- |
| `--page-size <n>`  | Items per page (default: 10). |
| `--page <n>`       | Page number (default: 1).     |
| `--search <query>` | Search named sources by text. |

## `carto named-sources create`

| Option           | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| `--name <name>`  | Source name (3–50 chars, lowercase letters/numbers, dashes/underscores allowed). |
| `--source <sql>` | SQL query for the named source.                                                  |

## Examples

```bash
# List all named sources
carto named-sources list

# Search named sources
carto named-sources list --search "my_source"

# Create a named source
carto named-sources create --name my_source --source "SELECT * FROM project.dataset.table"

# Get details
carto named-sources get my_source

# Update the SQL query
carto named-sources update my_source --source "SELECT id, geom FROM project.dataset.table"

# Delete (with confirmation)
carto named-sources delete my_source

# Delete (skip confirmation for CI/CD)
carto named-sources delete my_source --yes
```


---

# 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/named-sources.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.