• RUNNING
  • SUCCESS
  • FAILURE
  • HUMAN

How to run heavy spatial SQL jobs with your AI

Connect CARTO to your AI client to offload massive spatial ETL tasks to your cloud data warehouse. Your agent handles the heavy lifting while you move on to other work.

Ask AI about this page

Short answer

Can my AI run long spatial SQL queries?

Yes. Your AI sends the SQL command to your warehouse and then checks back periodically to see if the job finished. You get the results once the asynchronous process completes. Here is how the handoff works.

Job outcomes

Where your data processing lands.

The AI manages the lifecycle of the spatial job from submission to completion.

RUNNING

Job is in progress

The AI submits the spatial transformation to your warehouse. You can keep chatting while the cloud engine processes the geometry.

SUCCESS

Data is ready

The AI confirms the job finished successfully. You can then ask your agent to analyze the new spatial layers or export the results.

FAILURE

Error reported

If the SQL fails, the AI catches the error message. You can then ask your agent to debug the syntax or check the spatial logic.

HUMAN

Manual review needed

If a job hangs or requires complex logic changes, the AI flags it. You decide whether to retry the job or change the SQL parameters.

The workflow

What your AI does when a spatial job arrives.

Instead of timing out, your AI uses asynchronous patterns to manage heavy workloads.

  1. Submit the job

    Your agent sends the complex spatial SQL command to your warehouse to start the transformation.

    create_async_sql_job

  2. Monitor progress

    The AI checks the status of the running job so you don't have to manually refresh a dashboard.

    poll_async_job_status

  3. Verify completion

    The AI keeps polling until the job reaches a terminal state, like success or failure.

    poll_async_job_status

  4. Report results

    Once the job is done, the AI notifies you of the outcome or the specific error encountered.

    poll_async_job_status

Try it

Copy these to start.

Use these prompts to trigger your first spatial job.

Starting points

Replace the bracketed text with your specific table names or spatial functions.

CARTO Connector

You're all set. Choose your MCP client and follow the setup instructions.

Connector linkhttps://edge.vinkius.com/vk_preview_6NUh4SJzIYKcgYcjPGz3lmRBTXiut011mCAsyHQM/mcp

Claude Desktop

Follow the steps below to connect in seconds.

  1. 1In Claude Desktop, open Settings → Connectors.
  2. 2Click “Add custom connector” and paste the connector link above as the remote MCP server URL.
  3. 3Click Add and start a new chat — CARTO capabilities are ready to use.
Configuration · claude_desktop_config.jsonCopy
{
  "mcpServers": {
    "carto-mcp": {
      "url": "https://edge.vinkius.com/vk_preview_6NUh4SJzIYKcgYcjPGz3lmRBTXiut011mCAsyHQM/mcp"
    }
  }
}
Copy into chat04

  • Run an async SQL job in CARTO to buffer the 'city_boundaries' table by 500 meters.

  • Check the status of my last spatial transformation job in CARTO.

  • Create a new spatial layer by joining 'points_of_interest' with 'census_tracts' using an async job.

  • Tell me why my last spatial SQL job failed in CARTO.

  • Claude
  • ChatGPT
  • Cursor
  • VS Code
  • Windsurf
  • Claude Code
  • JetBrains
  • Cline

Start here

Connect CARTO once, then ask.

One connection gives your AI access to your spatial warehouse. Your credentials stay encrypted and secure.

Connect CARTO to your AI

FAQ

How the spatial jobs behave

  • 01

    Does the AI wait for the job to finish before responding?

    The AI uses asynchronous polling. It will track the job status in the background so you aren't stuck waiting for a single response.

  • 02

    Can the AI fix my SQL errors automatically?

    No. The AI can read the error message and suggest a fix, but you must review and approve any changes to the SQL code.

  • 03

    Can the AI delete my existing spatial tables?

    No. The tools provided only allow for creating and polling jobs. The AI cannot perform destructive operations like dropping tables.

  • 04

    How does the AI know when a job is done?

    The AI uses the polling tool to check the job status repeatedly until it sees a success or failure signal.

  • 05

    Can I run multiple jobs at once?

    Yes. You can ask your agent to trigger multiple asynchronous jobs, and it will track each one individually.

  • More questions about CARTO? The Connector page answers them. See everything the CARTO Connector can do

Connect CARTO to Claude, Cursor, ChatGPT & more