# Running queries from Builder

## Requirements

To run this example you'll need:

* An active CARTO organization
* The latest version of the [Analytics Toolbox](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-snowflake/getting-access) installed in your Snowflake database

## Guide

Once you have gained access to the Analytics Toolbox through the Snowflake Data Marketplace (see [*Getting Access*](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-snowflake/getting-access) for details), you can create custom SQL layers in Builder that make use of any of the available spatial functions.

To get started, let’s run a simple example query to cluster a set of points using the [`ST_CLUSTERKMEANS`](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-snowflake/sql-reference/clustering#st_clusterkmeans) function from the *clustering* module.

1. Click on the *Add source from* button in Builder, that can be found at the bottom left of the screen.

   <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-4f86693625d82a3f0edc47610fc75d18dc5caf57%2Flayer_choose_sf_connection.png?alt=media&#x26;token=75de1bb3-47d9-40fe-bda9-d1139048888d" alt=""><figcaption></figcaption></figure>
2. Select the second tab *Custom Query (SQL)* and pick the Snowflake connection that you will use to run the query. Please make sure this connection has access to the Analytics Toolbox database.

   <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-ac5f04254a294b65f1e89dc8132319b47911b827%2Fbuilder_custom_query_option_sf.png?alt=media&#x26;token=e7218154-dbe9-428e-9b5a-5a882c6c4612" alt=""><figcaption></figcaption></figure>
3. Click on *Add source*. A SQL console will be displayed.

   <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-354735bead703391b7b77a39a0749d5553e1ac28%2Fbuilder_custom_query_console_sf.png?alt=media&#x26;token=1cf0f61f-ad8d-49a1-a1c2-8ca4209a0081" alt=""><figcaption></figcaption></figure>
4. Copy and paste the following query:

   ```sql
   WITH data AS(
     SELECT geog
     FROM MYDB.MYSCHEMA.starbucks_locations_usa
     WHERE geog IS NOT null
     ORDER BY id
   ),
   clustered_points AS
   (
       SELECT CARTO.CARTO.ST_CLUSTERKMEANS(ARRAY_AGG(ST_ASGEOJSON(geog)::STRING), 8) AS cluster_arr
       FROM data
   )
   SELECT GET(VALUE, 'cluster') AS cluster, TO_GEOGRAPHY(GET(VALUE, 'geom')) AS geom
   FROM clustered_points, lateral FLATTEN(input => cluster_arr)
   ```
5. Run the query. This query computes eight clusters from the points of the `starbucks_locations_usa` table, provided as sample data within the Analytics Toolbox. As a result, each point is assigned a `cluster` ID.
6. Style the layer by the `cluster` attribute.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-bb3de27b23a80ec48272a0b6b586d7fe254e1384%2Fbuilder_custom_query_clustering-sf_new.png?alt=media&#x26;token=5e740354-4a1c-4b33-8c2e-48cf8a17edf6" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
For more examples, visit the [Examples](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-snowflake/step-by-step-tutorials) section or try executing any of the queries included in every function definition in the [SQL Reference](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-snowflake/sql-reference).
{% endhint %}


---

# 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/data-and-analysis/analytics-toolbox-for-snowflake/guides/running-queries-from-builder.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.
