# SQL queries

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FYoaDzzKMJkPKV8OQhYyB%2Fdatabase.png?alt=media&#x26;token=c2737f53-61b0-414b-9b22-14d4b6ed9247" alt=""><figcaption></figcaption></figure>

Felt’s SQL query feature lets you write and execute SQL queries directly against your database, enabling you to easily visualize results from custom filters, joins and spatial analysis powered upstream. It gives you full control over how your data is displayed, ensuring your maps are tailored to meet your specific requirements. Whether you're refining data or creating complex visualizations from generated SQL results, Felt makes it easy to seamlessly integrate your custom queries with your mapping workflow.

{% hint style="success" %}
This feature is only available to customers on the [Enterprise plan](https://felt.com/pricing). To upgrade, [contact sales](https://felt.com/sales).
{% endhint %}

### Set up

Connecting a cloud data source is required to access this feature, and SQL can only be run on the tables and views connected in your cloud source. The supported cloud sources supporting SQL queries today are:

* PostGIS
* Snowflake
* BigQuery
* Microsoft SQL Server
* Databricks
* Redshift

To set up a source connection, [see detailed instructions on cloud sources](https://help.felt.com/upload-anything/cloud-sources).&#x20;

### Using Felt AI SQL

Felt AI SQL is a conversational interface that transforms natural language questions into optimized SQL queries across multiple cloud database platforms. It allows anyone on your team to perform complex spatial analysis without writing code or waiting for technical assistance.

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2F5UzWIK7iPMrG6a0KZPEO%2FUI.png?alt=media&#x26;token=639ebb44-510b-455b-aa9d-ebd6388dd480" alt="" width="563"><figcaption></figcaption></figure>

Any editor in Felt can use AI to:

1. Perform complex spatial analysis without waiting for technical assistance

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FKUAkpUfx2HcZN7OE2r5G%2FSQL_query.gif?alt=media&#x26;token=2f4b7f64-e002-4891-b59c-76fe34a02124" alt="" width="563"><figcaption></figcaption></figure>

2. Update or edit SQL queries run in Felt&#x20;

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FSVoN1eTpLOIJu1oE82Xh%2Fupdate_query.gif?alt=media&#x26;token=efe4ae07-bb76-4f7a-81e2-9c411802b8a9" alt="" width="563"><figcaption></figcaption></figure>

3. Explore data schema and table attributes in the source

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FbCpuQkYOyKfg93Uiw1wd%2Fexplore_attributes.gif?alt=media&#x26;token=df2d4fca-09c0-4562-bd57-0fb94f7aa678" alt="" width="563"><figcaption></figcaption></figure>

#### Generating SQL layers

1. Click on the **Library** (toolbar) and select your data source under the `Sources` heading.
2. Select `+ New SQL query` (or select a table and click `...` > `Write SQL query`).
3. The **SQL query** window will open

   <figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2F5mslC6XMP2x20NXok8Ns%2Fai-sql.webp?alt=media&#x26;token=91b848b1-7b7e-45c1-b691-46cef9059b99" alt=""><figcaption></figcaption></figure>

   1. **the left side** includes all the tables and views available in your source as well as recent queries the team has run
   2. **the right side** includes the SQL query editor (top) and the AI prompt area (bottom) where you can provide prompts to Felt AI. Use the `Schema` and `Metadata` tabs (bottom) to learn more about the structure of tables in the database.&#x20;
4. Once Felt AI generates SQL, a preview will run automatically. Use the `Results` tab (bottom right) to review results from the SQL query in table format.&#x20;
5. Click **`Create Layer`** to add your data to the map.

   1. The dropdown option allows you to set the **Live** sync Frequency or turn **Live** syncs off

   <figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FTblAgl2gpnnAHistTNYC%2Fimage.png?alt=media&#x26;token=aa00ca2b-660c-47a9-b249-897222bda599" alt="" width="232"><figcaption></figcaption></figure>
6. A new layer will be added to your map and you can start styling your results.

### Editing SQL layers

You can review and edit existing layers with updated SQL either with or without AI assistance. You can edit or write queries directly within the query editor (top right).

To edit or update an existing layer built with SQL:

1. Select the Layer in Edit mode
2. Navigate to the `Data` tab in the layer menu
3. Click on `SQL query` next to `Dataset`

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FRJc2vwTEN3Jx3YShsoi0%2Fimage.png?alt=media&#x26;token=21ea9776-7343-4314-9914-e1b547a84232" alt="" width="219"><figcaption></figcaption></figure>

4. Either edit the SQL directly or use Felt AI assistant to make modifications to the query
5. Click `Save` to update the existing layer with the new query

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2Fd8WytoXoAV6ZGSAGFM04%2FScreen%20Recording%202025-09-12%20at%2010.32.20%E2%80%AFAM.gif?alt=media&#x26;token=d1e1489f-05cc-4129-a001-b20ab90e7d0d" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Once edits are saved and while a layer is processing the updated query it cannot be modified or changed until it has finished the updates.
{% endhint %}

### Copy recent queries

The 20 most recent SQL queries that created layers on maps will appear at the top when opening a source via the Library. This will show you a history of all the queries run on maps in the account.

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FRoD3klIafk4InnLNy9N8%2Fimage.png?alt=media&#x26;token=a063ba56-672c-411e-ba74-1898353e1270" alt="" width="563"><figcaption></figcaption></figure>

To re-use and fork queries other teammates have run, click on any of the entries listed under `Queries` and start editing.&#x20;

### Debugging

1. Run previews by clicking on the `Preview` button (top right) to verify the SQL query is valid
2. Errors will appear in the `Results` tab (bottom right) with more details
3. You can fix errors with Felt's AI assistant by clicking `Fix errors with AI` option

<figure><img src="https://217108486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmRfGitkyjOEMvVsEyGWN%2Fuploads%2FUscfEaDQtENqXjrShOA4%2FScreen%20Recording%202025-09-12%20at%2010.29.45%E2%80%AFAM.gif?alt=media&#x26;token=69d8b655-b77a-4d63-afd1-50a7c428fdc0" alt=""><figcaption></figcaption></figure>

### Supported Spatial Operations

Different SQL platforms offer varying levels of support for spatial operations, with some providing extensive libraries of geospatial functions and others offering more basic capabilities. While some focus on advanced geographic and geometric queries, others prioritize scalability and integration with broader data processing workflows. The specific capabilities and limitations depend on the platform, so refer to the relevant documentation linked below for more details.

* [Databricks](https://docs.databricks.com/en/sql/language-manual/sql-ref-h3-geospatial-functions.html)
* [BigQuery](https://cloud.google.com/bigquery/docs/reference/standard-sql/geography_functions)
* [MS SQL Server](https://learn.microsoft.com/en-us/sql/relational-databases/spatial/spatial-data-sql-server?view=sql-server-ver16)
* [Redshift](https://docs.aws.amazon.com/redshift/latest/dg/geospatial-functions.html)
* [Snowflake](https://docs.snowflake.com/en/sql-reference/functions-geospatial)
* Postgres ([PostGIS](https://postgis.net/docs/reference.html))

{% hint style="info" %}
&#x20;The SQL query feature supports only `SELECT` statements, ensuring read-only access to your database.
{% endhint %}

## Example Operations

{% hint style="success" %}
Not sure which operation to use? Ask [Felt AI](#using-felt-ai-sql) to run the operation for you.
{% endhint %}

<table><thead><tr><th>Spatial Operation</th><th width="252">Definition</th><th>Code Example</th></tr></thead><tbody><tr><td>ST_Intersects</td><td>Tests whether two geometries share any space in common. Returns true if geometries intersect, false otherwise. Used for identifying overlapping areas.</td><td><code>SELECT a.*, b.* FROM service_areas a JOIN market_zones b ON ST_Intersects(a.geometry, b.geometry);</code></td></tr><tr><td>ST_Within</td><td>Tests whether one geometry is completely inside another. Returns true if the first geometry is completely within the second geometry.</td><td><code>SELECT a.name, b.name FROM points a JOIN polygons b ON ST_Within(a.geometry, b.geometry);</code></td></tr><tr><td>ST_Buffer</td><td>Creates a new geometry that represents all points within a given distance from the input geometry. Useful for creating service areas or zones of influence.</td><td><code>SELECT location_id, ST_Buffer(geometry, 5000) as service_area FROM distribution_centers;</code></td></tr><tr><td>ST_Centroid</td><td>Computes the geometric center (centroid) of a geometry. Returns a point that represents the average position of all points in the geometry.</td><td><code>SELECT region_name, ST_Centroid(geometry) as center_point FROM service_regions;</code></td></tr><tr><td>ST_Distance</td><td>Calculates the shortest distance between two geometries. Returns the minimum distance between any two points in the two geometries.</td><td><code>SELECT a.id, b.id, ST_Distance(a.geometry, b.geometry) as distance FROM points a CROSS JOIN points b WHERE a.id != b.id;</code></td></tr><tr><td>ST_Area</td><td>Calculates the area of a polygon geometry. Returns the area in the units of the spatial reference system.</td><td><code>SELECT territory_id, ST_Area(geometry::geography) as area_sqm FROM market_territories;</code></td></tr><tr><td>ST_Length</td><td>Calculates the length of a linear geometry (linestring). Returns the length in the units of the spatial reference system.</td><td><code>SELECT route_id, ST_Length(geometry::geography) as length_meters FROM delivery_routes;</code></td></tr><tr><td>ST_Union</td><td>Combines multiple geometries into a single geometry. Dissolves overlapping boundaries and creates a single continuous geometry.</td><td><code>SELECT region_id, ST_Union(geometry) as combined_geometry FROM parcels GROUP BY region_id;</code></td></tr><tr><td>ST_Intersection</td><td>Returns the geometry representing the shared portions of two geometries. Creates a new geometry containing only the overlapping areas.</td><td><code>SELECT ST_Intersection(a.geometry, b.geometry) as overlap FROM zone_a a CROSS JOIN zone_b b;</code></td></tr><tr><td>ST_Transform</td><td>Transforms a geometry from one coordinate system to another. Used to convert between different spatial reference systems (SRS).</td><td><code>SELECT id, ST_Transform(geometry, 4326) as wgs84_geom FROM locations;</code></td></tr><tr><td>ST_Envelope</td><td>Computes the minimum bounding rectangle that contains a geometry. Returns a rectangular polygon that completely encloses the input geometry.</td><td><code>SELECT region_id, ST_Envelope(ST_Collect(geometry)) as bbox FROM market_regions GROUP BY region_id;</code></td></tr><tr><td>ST_ConvexHull</td><td>Computes the smallest convex polygon that contains all points in a geometry. Creates a shape that represents the outer boundary of a set of points.</td><td><code>SELECT cluster_id, ST_ConvexHull(ST_Collect(geometry)) as boundary FROM points GROUP BY cluster_id;</code></td></tr><tr><td>ST_Contains</td><td>Tests whether one geometry completely contains another. Returns true if the second geometry is completely contained within the first geometry.</td><td><code>SELECT points.* FROM customer_points points JOIN service_areas areas ON ST_Contains(areas.geometry, points.geometry);</code></td></tr></tbody></table>
