> For the complete documentation index, see [llms.txt](https://docs.seemoredata.io/external-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.seemoredata.io/external-docs/fundamentals/our-features/auto-clustering-agent.md).

# Auto-Clustering Agent

## Overview

Auto-Clustering Agent helps you **choose and maintain the right clustering keys** for your tables—so you can **improve performance for queries running on top of those tables** (better pruning, less scanning) while also **reducing overall cost**.

A big part of the cost optimization is identifying tables where **Snowflake Automatic Clustering (auto-clustering)** is enabled but **not providing enough value**, and recommending to **disable auto-clustering** (and in some cases also **drop clustering keys**) to avoid unnecessary spend.

{% hint style="info" %}
**Required role:** [Viewer](/external-docs/fundamentals/settings/user-roles.md) or higher.

This feature is read-only inside Seemore — any authenticated user can view recommendations. Applying the recommended changes is done in Snowflake.
{% endhint %}

## What problem it solves

Choosing clustering keys is one of the highest-leverage optimizations in Snowflake—but it’s also easy to get wrong.

Common issues:

* clustering keys are defined, but **don’t match real query filters**, so queries still scan too much
* **Snowflake auto-clustering is enabled** on tables that **don’t benefit**, which increases cost
* clustering keys are a poor fit due to **cardinality**, so pruning value is limited
* the “right” key changes as workloads change, and manual tuning doesn’t keep up

Auto-Clustering Agent helps you continuously **select better clustering keys** (to improve performance), and also highlights where **auto-clustering should be disabled** to reduce cost.

## Prerequisites

To start using Auto-Clustering Agent, please follow the [Create Snowflake User and Privileges](/external-docs/fundamentals/getting-set-up/setting-integrations/snowflake/create-snowflake-user-and-privileges.md) page to provide Seemore the following permissions

* **Agent enablement permissions** (ability to start/run the agent in your environment)
* **Permission to execute a customer-created function** we use to fetch **clustering health metadata** (column/table clustering status) — **not table data**

## Clustering concepts (quick refresher)

Snowflake stores data in **micro-partitions** and maintains **micro-partition metadata** that enables pruning (skipping irrelevant partitions during scans).

To cluster a table, you **define the clustering key** (using `CLUSTER BY`). The key can include multiple columns/expressions, and **the order you specify matters**.

**Snowflake Automatic Clustering (auto-clustering)** is the service that **reclusters a table over time** to maintain clustering **based on the key you defined**—and this service is what can **incur additional cost**.

{% hint style="info" %}
Clustering is generally most cost-effective for tables that are **queried frequently** and **don’t change frequently**—start with a small set of tables and measure impact before expanding.
{% endhint %}

## What the Auto-Clustering Agent does

### List the tables currently using auto-clustering

The agent lists the tables where **Snowflake auto-clustering is enabled**, and provides an analysis for the **top 10 tables by default**.

For the rest of the tables, you can generate analysis **ad hoc** by clicking **Generate analysis**.

For each table, the agent provides:

* a **Health Score**
* a recommendation to **Optimize**, **Keep**, or **Disable auto-clustering** (and in some cases **Drop clustering keys**)
* an explanation for the decision (impact on **query performance** + **auto-clustering cost**)
* an **estimated cost impact** for applying the change (focused on the savings from disabling Snowflake auto-clustering)

<figure><img src="/files/krBrsIsrOzll0HaSwrXS" alt=""><figcaption></figcaption></figure>

### Generating a report

If you want to handle the **top recommendations first** (instead of going one-by-one), use the report.

We provide a report for:

* **Top 10 tables with auto-clustering enabled**\
  Recommendations focused mainly on **disabling Snowflake auto-clustering** where it doesn’t pay off, and on **optimizing/keeping** clustering keys where they do improve performance.
* **Top 10 tables without auto-clustering enabled**\
  Recommendations to **cluster the tables** (including suggested clustering keys). You choose the approach:
  * **Manual clustering** (define clustering keys and manage it yourself)
  * **Enable Snowflake auto-clustering** (define clustering keys and then clustering is maintained automatically)

This helps you prioritize the biggest wins: **better keys for performance**, and **disable auto-clustering where it’s wasting money**.

<figure><img src="/files/aMLkAWUPwQ7cLGY3awml" alt=""><figcaption></figcaption></figure>

### Recommendation types

* **For tables enabled with Auto-Clustering**
  * **Optimize**\
    Improve performance by adjusting clustering keys (or key order) to match real query filters—so pruning is better across queries.
  * **Keep**\
    Auto-clustering is providing value and is likely cost-effective for this table.
  * **Disable auto-clustering** (and sometimes **drop keys**)\
    Recommended when the ongoing Snowflake auto-clustering cost outweighs the benefit. In some cases, the agent also recommends **dropping the clustering keys** if they provide little/no value.
* For tables that are not clustered
  * **Add to Auto-Clustering** - including suggested clustering keys and full analysis of the reason
  * **Don't Add -** the table is not a good fit for Auto-Clustering

## How to act on recommendations

For every recommendation, we provide the **exact SQL commands** you need — just **copy-paste** them into your Snowflake worksheet and run.

### If the agent recommends **disabling auto-clustering** (and sometimes dropping keys)

Typical reasons:

* auto-clustering cost outweighs performance benefit (table is not queried enough, or pruning gains are low)
* clustering keys don’t match real query filters, so queries still scan too much
* **column cardinality isn’t a good fit for clustering** (too high or too low), so clustering provides little to no pruning value
* clustering keys themselves provide little/no value, so the agent may also recommend **dropping the keys**

Recommended actions:

* disable Snowflake auto-clustering for the table
* optionally drop clustering keys (if recommended)

### If the agent recommends **adding/optimizing clustering keys**

Typical reasons:

* the table is frequently queried and better pruning can improve performance
* filters/usage patterns suggest strong pruning benefits

Recommended actions:

* define or optimize clustering keys by using the agent recommendations
* optionally enable Snowflake auto-clustering if you want Snowflake to maintain clustering automatically (with associated cost)

## FAQ

* **Will Auto-Clustering Agent change anything automatically?**\
  By default, the agent provides **analysis + suggested clustering keys** and generates copy-paste SQL. Applying changes depends on your workflow and permissions.
* **What’s the main cost saving?**\
  Reducing unnecessary spend from **Snowflake auto-clustering** by recommending where to **disable auto-clustering** when it doesn’t provide enough value.
* **Why do you sometimes recommend dropping clustering keys too?**\
  If the keys provide little/no pruning value (for example due to poor fit or cardinality), dropping them can simplify maintenance—especially when auto-clustering is being disabled anyway.