# do (Data Observatory)

Browse, search, and subscribe to datasets from the CARTO Data Observatory catalog (10,000+ spatial datasets from 50+ providers).

```bash
# Discover available filters (countries, categories, providers, licenses, etc.)
carto do filters                              # All filter values with dataset counts
carto do filters --json | jq '.categories'    # Just categories (programmatic)

# Browse and search
carto do list --category demographics         # Browse datasets by category
carto do list --country usa --limit 10        # Browse by country
carto do list --provider experian             # Browse by provider
carto do list --license public                # Filter by license type
carto do search "demographics united states"  # Full-text search
carto do search "flood risk" --license public # Search with filters

# AI-powered semantic variable search (requires embeddings)
carto do search-variables "purchasing power" --country deu
carto do search-variables "population density" --limit 10

# Dataset details
carto do details <dataset-id>                 # Full dataset metadata
carto do sample <dataset-id>                  # Data sample + data dictionary

# Subscriptions (public datasets only — premium requires contacting sales)
carto do subscriptions                        # List your subscriptions
carto do subscribe <dataset-id>               # Subscribe using catalog slug
carto do subscribe wp_population_29d72d59     # Resolves slug → creates BQ view
carto do subscribe <id> --filter "WHERE country_iso = 'US'"  # Partial subscription
carto do subscribe <id> --columns "geoid, population, geom"  # Specific columns only
carto do subscribe <id> --connection my-sf --destination db.tbl  # Subscribe + transfer
carto do unsubscribe <dataset-id>             # Remove a subscription
carto do unsubscribe <dataset-id> --yes       # Skip confirmation
```

## `carto do list` / `carto do search`

| Option               | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `--category <name>`  | Filter by category (e.g. `Demographics`, `Environmental`). |
| `--provider <name>`  | Filter by provider (e.g. `Experian`, `TomTom`).            |
| `--country <name>`   | Filter by country.                                         |
| `--license <type>`   | Filter: `premium` or `public`.                             |
| `--limit <n>`        | Results per page (default: 20).                            |
| `--page <n>`         | Page number (default: 1).                                  |
| `--order-by <field>` | Order: `popular`, `recent`, `alphabetical` (list only).    |

## `carto do subscribe`

| Option                  | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| `--filter <where>`      | SQL `WHERE` clause to filter data (e.g. `"WHERE country_iso = 'US'"`). |
| `--columns <cols>`      | Comma-separated columns to include (default: all).                     |
| `--connection <name>`   | Transfer data to this connection after subscribing.                    |
| `--destination <table>` | Destination table (required with `--connection`).                      |


---

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