> For the complete documentation index, see [llms.txt](https://docs.e6data.com/query-engine/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.e6data.com/query-engine/guides/clusters/create-and-manage-clusters.md).

# Create and manage clusters

Create a cluster, configure its settings, connect to it, and manage its version and lifecycle.

A **cluster** is the compute layer of e6data. It receives SQL queries, plans execution, and distributes work across executor nodes. You size it for your workload; e6data handles auto-scaling, suspend/resume, and zero-downtime upgrades.

A cluster connects to one or more catalogs, and every query is routed to the cluster named in your connection string. The **cluster name** is 3–30 characters - letters (upper or lower case), digits, and hyphens - and is the routing key in every connection. It must start with a letter and end with a letter or digit, is case-sensitive, and cannot be changed after creation. See [resource naming conventions](/query-engine/reference/platform-reference/resource-naming-conventions.md) for the full rules.

{% hint style="info" %}
Running e6data in your own VPC? This page covers the Console UI. For the kubectl/CRD/GitOps workflow, see [CloudPrem cluster operations](/query-engine/guides/clusters/cloudprem-cluster-operations.md).
{% endhint %}

## Create a cluster

1. Open the Console and go to **Clusters**.
2. Click **Create Cluster**.
3. Fill in the fields:

| Field         | Required | Default    | Description                                                                                                                                                                     |
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name          | Yes      | -          | 3–30 chars; letters (upper or lower case), digits, and hyphens; must start with a letter and end with a letter or digit. Case-sensitive. Cannot be changed later.               |
| Size          | Yes      | XS         | XS (1), S (2), M (4), L (8), XL (16), XXL (32), or **Custom** (1–100 executors). See [Cluster sizing and scaling](/query-engine/guides/clusters/cluster-sizing-and-scaling.md). |
| Version       | Yes      | Latest     | An available e6data release (the Cluster Runtime).                                                                                                                              |
| Query timeout | No       | 900 s      | Maximum query execution time, 1–3600 s.                                                                                                                                         |
| Auto-suspend  | No       | On, 30 min | Suspend after this many idle minutes. See [Suspend and resume](/query-engine/guides/clusters/suspend-and-resume.md).                                                            |
| Auto-resume   | No       | On         | Resume automatically when a query arrives.                                                                                                                                      |

4. Click **Create**. The cluster moves through **Creating → Running** and is ready for queries.

You choose a release version when creating or updating a cluster; the e6data team manages the release lifecycle (publishing, testing, deprecation), so you always pick from a curated, validated set.

## Configure a cluster

After creation, tune these from **Cluster → Settings**:

| Setting            | Range                          | Default   | Description                                          |
| ------------------ | ------------------------------ | --------- | ---------------------------------------------------- |
| Query timeout      | 1–3600 s                       | 900 s     | Maximum query execution time.                        |
| Result cache       | on / off                       | off       | Cache query results to speed up repeated queries.    |
| Cache TTL          | 60–86400 s                     | 300 s     | How long cached results stay valid.                  |
| SQL transpiler     | on / off                       | off       | Translate SQL from another dialect before execution. |
| Transpiler dialect | snowflake / trino / databricks | snowflake | Source SQL dialect when the transpiler is on.        |

Execution mode (standard vs. native) and result caching as performance levers are covered in [Cluster sizing and scaling](/query-engine/guides/clusters/cluster-sizing-and-scaling.md).

## Connect to a cluster

Each cluster exposes connection details from **Cluster → Connection**. The same cluster supports several protocols simultaneously - pick whichever fits your client:

| Protocol                 | Use for                                                |
| ------------------------ | ------------------------------------------------------ |
| JDBC / ODBC (gRPC)       | BI tools, Java applications, drivers                   |
| REST API (HTTP)          | Programmatic access, integrations, lightweight clients |
| PostgreSQL wire protocol | BI tools that speak Postgres (DBeaver, psql, Looker)   |
| Python connector         | Python applications and notebooks                      |

For any method you need the endpoint hostname, port (typically 443 for gRPC/HTTP, 5432 for PostgreSQL), authentication (a [personal access token](/query-engine/guides/security/access-tokens/pat-and-service-account-keys.md), recommended), the catalog name, and the cluster name. Endpoints are tied to the **workspace**, not the cluster, so suspending or recreating a cluster keeps the endpoint stable. See [Connecting to the engine](/query-engine/developers/connecting-to-the-engine.md) for tool-specific guides and [Endpoints and cluster ingress](broken://pages/Wh4d9jql2OPH1ux7JE4O) for allowlisting.

## Manage and upgrade

Edit a cluster's settings or version from **Cluster → Settings**. Changing the version triggers a **zero-downtime upgrade**: the new version is brought up alongside the current one, traffic switches over once it's healthy, and the old version drains in-flight queries before shutting down - queries are never interrupted. See [Zero-downtime upgrades](/query-engine/guides/clusters/zero-downtime-upgrades.md).

### Cluster states

| State                  | Meaning                                                            |
| ---------------------- | ------------------------------------------------------------------ |
| Creating               | Initial provisioning                                               |
| Running                | Active and serving queries                                         |
| Updating               | Configuration or version change rolling out (queries continue)     |
| Suspending / Suspended | Draining / zero replicas, no cost                                  |
| Resuming               | Coming back from suspension (\~30–90 s)                            |
| Failed                 | Irrecoverable error - check the error and retry or contact support |
| Degraded               | Partially functional; may self-heal                                |

The full state machine and error codes are in [Lifecycle states and error codes](/query-engine/guides/clusters/lifecycle-states-and-error-codes.md).

## See also

* [Cluster sizing and scaling](/query-engine/guides/clusters/cluster-sizing-and-scaling.md)
* [Suspend and resume](/query-engine/guides/clusters/suspend-and-resume.md)
* [Lifecycle states and error codes](/query-engine/guides/clusters/lifecycle-states-and-error-codes.md)
* [Troubleshooting clusters](/query-engine/guides/clusters/troubleshooting-clusters.md)
* [CloudPrem cluster operations](/query-engine/guides/clusters/cloudprem-cluster-operations.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.e6data.com/query-engine/guides/clusters/create-and-manage-clusters.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.