# Vector Search Deployments
Before you work with Vector Search, you need to ensure that the Vector Search
feature is enabled for your cluster. Enabling the feature involves adding
Vector Search nodes to the cluster, with the possibility of deploying multiple
nodes in each Availability Zone (AZ).
You can enable Vector Search on new and existing clusters, including
[free trial](https://cloud.docs.scylladb.com/stable/cloud-services/free-trial.md) clusters.
## Vector Search on Free Trial Clusters
You can enable Vector Search on a free trial cluster to explore similarity
search without any cost. Free trial clusters support only the smallest
available Vector Search instance size:
* **AWS** — `t4g.medium` (2 vCPUs, 4 GiB RAM)
* **GCP** — `e2-medium` (2 vCPUs, 4 GiB RAM)
To get started:
1. [Sign up](https://auth.cloud.scylladb.com/oauth/account/sign-up) for a
ScyllaDB Cloud account if you don’t have one.
2. Create a free trial cluster and enable the **Vector Search** option
(see [Creating a New Cluster with Vector Search Enabled](#vs-create-cluster)).
3. Connect to your cluster and follow the
[Quick Start Guide](https://cloud.docs.scylladb.com/stable/vector-search/vector-search-quick-start.md).
The free trial is limited to one cluster per account. For larger instance
types and production workloads, upgrade to a paid plan.
## Vector Search Availability
* **ScyllaDB Version**
Vector Search is available on clusters running ScyllaDB 2025.4.3 or later.
* **Cluster Types**
Vector Search can be enabled on *Standard* and *X Cloud* clusters.
See [Cluster Types](https://cloud.docs.scylladb.com/stable/cloud-setup/cluster-types/index.md).
* **BYOA**
You can create a Vector Search cluster under the ScyllaDB account
or your own account on [AWS](https://cloud.docs.scylladb.com/stable/cloud-setup/byoa-aws.md) or [GCP](https://cloud.docs.scylladb.com/stable/cloud-setup/byoa-gcp.md).
* **Instance Types**
See [Supported Instance Types](https://cloud.docs.scylladb.com/stable/vector-search/reference-vector-search.md#vector-search-clusters-instances)
for a complete list of supported instance types.
### Feature Compatibility Matrix
The following table shows which ScyllaDB version is required for each
Vector Search feature:
| ScyllaDB Version | Features |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 2026.2.0 | Cassandra SAI vector index and LangChain compatibility, migrating
indexes to use different set of options, vector similarity search
for Alternator using lists of numbers, row expiration on
vector-indexed tables via per-row TTL. |
| 2026.1.0 | Filtering, quantization, getting similarity values, real-time
ingestion. |
| 2025.4.3 | Internal authorization providing the maximal privacy of data. |
| 2025.4.0 | Basic vector search: vector data type, HNSW indexing, ANN queries,
per-partition and global indexes. |
## Node Placement and Availability Zones
ScyllaDB Cloud deploys Vector Search nodes alongside your ScyllaDB storage
nodes and, by default, spreads them across the cluster’s Availability Zones
(AZs) to provide redundancy. You control how many Vector Search nodes are
deployed through the `nodeCount` parameter (in the API) or the node-count
selector (in the UI). The number of Vector Search nodes does **not** have to
match the number of storage nodes.
How you place Vector Search nodes relative to your storage nodes affects three
things: the amount of cross-zone network traffic, query latency, and the
failure domain that vector search can tolerate. The two topologies below
describe the most common choices for a cluster with a replication factor of 3
(RF=3) deployed across three AZs.
### Recommended Topology: One Node per Availability Zone
For a production cluster with RF=3 spread across three AZs, the recommended
topology is to deploy one Vector Search node in each AZ (three Vector Search
nodes in total). In this configuration:
* Every ScyllaDB storage node has a Vector Search node in the **same**
Availability Zone. ANN query traffic between a storage node and its vector
index stays **within the zone**, which keeps latency low and avoids
cross-AZ data transfer charges.
* High availability is **zonal**: each AZ holds a full, independently usable
copy of the vector index. The cluster can lose an entire Availability Zone
and still serve vector queries from the surviving zones.
This topology delivers the lowest and most uniform query latency and is the
best choice for latency-sensitive or high-throughput workloads.
### Cost-Optimized Topology: Fewer Vector Search Nodes than Storage Nodes
To reduce the cost of the Vector Search tier, ScyllaDB Cloud also supports
deploying **fewer Vector Search nodes than ScyllaDB storage nodes**. A common
example is a three-node ScyllaDB cluster (RF=3, one storage node per AZ across
three AZs) served by **two Vector Search nodes** instead of three.
Two Vector Search nodes still keep the vector index redundant — if one node
fails, the other continues to serve ANN queries — while removing the cost of
the third node. Because only two of the three AZs host a Vector Search node,
this topology has the following trade-offs:
1. **Cross-zone traffic.** The storage node in the AZ that has no local
Vector Search node must route its ANN queries to Vector Search nodes in
the other AZs and receive the results back across the AZ boundary. These
redirected queries are load-balanced across the Vector Search nodes in the
remaining zones, so no single zone absorbs all of the cross-zone traffic.
This generates cross-zone (inter-AZ) network traffic, which is billed as
cloud data transfer. This traffic scales with your query rate, so a low-QPS
workload produces only a small volume and the additional cost is usually
negligible. The higher your sustained QPS, the more cross-zone data
transfer you should expect to pay for.
2. **Slightly higher latency for one zone.** Queries that are coordinated by
the storage node in the AZ **without** a co-located Vector Search node
incur one extra network hop across Availability Zones. This adds a small
amount of latency (typically on the order of one to a few milliseconds,
depending on the cloud provider and region) to those queries only. Queries
served within a zone that has a local Vector Search node are not affected.
3. **Regional instead of zonal high availability.** With a Vector Search node
in only two of the three AZs, vector search is no longer self-sufficient in
every zone. The deployment still tolerates the failure of a single Vector
Search node (or its AZ), because the remaining node keeps serving queries —
so high availability is provided at the **regional** level. However, it is
no longer **zonal**: the AZ without a local node depends on cross-zone
access for vector search and would lose vector search capability if it
became isolated from the zones that host the Vector Search nodes.
#### NOTE
This trade-off applies only to the Vector Search tier. Your ScyllaDB
storage nodes remain RF=3 across all three AZs, so the durability and
availability of your primary data are unchanged, and standard CQL reads
and writes continue to be served locally in every zone. See
[Configure Availability Zones](https://cloud.docs.scylladb.com/stable/cloud-setup/availability-zones.md) for
how AZ placement affects the storage layer.
Choose the cost-optimized topology when you want to lower Vector Search
infrastructure costs and your workload has a low-to-moderate query rate and
can tolerate slightly higher latency for one zone. Choose the recommended
one-node-per-AZ topology when you need uniform low latency and zonal high
availability.
## Creating a New Cluster with Vector Search Enabled
You can create a new cluster with Vector Search enabled either through
the ScyllaDB Cloud web UI or programmatically using the ScyllaDB Cloud API.
Create via the UI
1. Go to [cloud.scylladb.com](https://cloud.scylladb.com) and log in to your
account, or sign up to create a new user account.
2. Click **New Cluster** to create a cluster.
3. Configure the required options:
> * Cluster name
> * Cloud provider: **AWS** or **GCP**
> * Cluster type: **Standard** or **X Cloud**
4. Enable the **Vector Search** option.
ScyllaDB Cloud will display available instance types with their pricing
and the billing summary.
5. Choose the instance type.
6. Click **Next**.
7. Review the *Billing Options* page for your cluster. The page displays
the number of Vector Search nodes and the associated costs.
Vector Search UI supports only [on-demand billing](https://cloud.docs.scylladb.com/stable/cloud-services/billing.md).
If you want to use your existing contract, please contact ScyllaDB Support.
8. Click **Next** to configure cluster properties.
9. Click **Launch Cluster**. It will take a few minutes for your cluster to launch.
10. When your cluster is deployed, go to the **Connect** tab. It displays
instructions on how to connect to your cluster.
11. Choose **Cqlsh** from the left menu and follow the instructions.
Create with the API
To use the ScyllaDB Cloud API, you need to generate a personal API
token for authenticating requests to the API endpoints. See
[Create a Personal Token for Authentication](https://cloud.docs.scylladb.com/stable/api-docs/create-api-token.md)
for details.
1. Get your account ID (`ACCOUNT_ID`):
```bash
curl -X GET "https://api.cloud.scylladb.com/account/default" \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
Response looks like:
```json
{
"error": "",
"data": {
"accountId": 12345,
"name": "my-account",
"userId": "12345"
}
}
```
Here 12345 is your `ACCOUNT_ID`.
2. Create a new cluster that includes the **\`\`vectorSearch\`\`** field in
the API request body.
Make sure to replace `ACCOUNT_ID` and `YOUR_API_TOKEN` with actual
values in the example below.
```bash
curl -X POST "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/cluster" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"clusterName": "my-vector-cluster",
"cloudProviderId": 1,
"regionId": 1,
"numberOfNodes": 3,
"instanceId": 62,
"replicationFactor": 3,
"vectorSearch": {
"nodeCount": 1,
"defaultInstanceTypeId": 176
}
}'
```
This will deploy dedicated vector search nodes in the cluster.
3. Connect to the cluster with cqlsh.
> 1. Go to [https://cloud.scylladb.com/](https://cloud.scylladb.com/), choose your cluster and go to
> the **Connect** tab.
> 2. Choose **Cqlsh** from the left menu and follow the instructions.
Your cluster is ready to work with Vector Search!
## Enabling Vector Search on an Existing Cluster
#### NOTE
Vector Search is supported **on clusters running ScyllaDB 2025.4.3 or later**.
Before enabling Vector Search for an existing cluster, please verify that
your cluster has been upgraded to version 2025.4.3.
To enable Vector Search on an existing cluster, you must deploy new Vector
Search nodes. You can do it either through the ScyllaDB Cloud web UI or using
the ScyllaDB Cloud API.
Enable via the UI
1. Select the cluster where you want to enable Vector Search to open
the cluster details page.
2. Check the **ScyllaDB Version**. Vector Search is supported in
ScyllaDB 2025.4.3 and later.
3. Choose **Enable Vector Search** from the three-dot menu in
the datacenter overview section.
ScyllaDB Cloud will display available instance types with pricing.
4. Choose the Vector Search instance types you want to add to your
cluster and click **Add Vector Search Instances**.
Enable with the API
To use the ScyllaDB Cloud API, you need to generate a personal API
token for authenticating requests to the API endpoints. See
[Create a Personal Token for Authentication](https://cloud.docs.scylladb.com/stable/api-docs/create-api-token.md)
for details.
Before you deploy new Vector Search nodes, you need to retrieve your
account ID, cluster ID, and datacenter (DC) ID.
In the examples below, make sure to replace `YOUR_API_TOKEN` with your
actual access token value.
1. Get your account ID (`ACCOUNT_ID`):
```bash
curl -X GET "https://api.cloud.scylladb.com/account/default" \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
Response looks like:
```json
{
"error": "",
"data": {
"accountId": 12345,
"name": "my-account",
"userId": "12345"
}
}
```
Here 12345 is your `ACCOUNT_ID`.
2. List your clusters to get your cluster ID:
```bash
curl -X GET "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/clusters" \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
Response looks like:
```json
{
"data": {
"clusters": [
{
"id": 6789,
"name": "my-vector-cluster",
"status": "ACTIVE"
}
]
}
}
```
Here 6789 is your `clusterId`.
3. List the datacenters (DCs) for your cluster to get the DC ID.
```bash
curl -X GET "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/cluster/{CLUSTER_ID}/dcs" \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
Response looks like:
```json
{
"data": {
"dataCenters": [
{
"id": 222,
"name": "us-east-1a",
"status": "ACTIVE"
}
]
}
}
```
Here 222 is the `dcId` you need for vector store operations.
4. Deploy Vector Search nodes.
```bash
curl -X POST "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/cluster/{CLUSTER_ID}/dc/{DC_ID}/vector-search" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"nodeCount": 1,
"defaultInstanceTypeId": 176
}'
```
5. Connect to the cluster with cqlsh.
> 1. Go to [https://cloud.scylladb.com/](https://cloud.scylladb.com/), choose your cluster and go to
> the **Connect** tab.
> 2. Choose **Cqlsh** from the left menu and follow the instructions.
## Resizing a Vector Search Cluster
You can resize your Vector Search deployment by changing the number of nodes
or switching to a different instance type. Resizing is available through the
ScyllaDB Cloud web UI or the ScyllaDB Cloud API.
Resize via the UI
1. Select the cluster where you want to resize Vector Search to open
the cluster details page.
2. Choose **Resize Vector Search** from the three-dot menu in
the datacenter overview section.
3. Choose the new instance type and/or adjust the number of Vector
Search nodes.
4. Confirm the resize operation. The operation is asynchronous — you
can monitor its progress in the cluster’s activity log.
Resize with the API
Send a `PATCH` request to the Vector Search endpoint for the target
datacenter. The request body accepts two parameters:
* `nodeCount` (integer, 1–27) — the desired number of vector search
nodes.
* `defaultInstanceTypeId` (integer) — the instance type ID. Use the
`target=VECTOR_SEARCH` query parameter on the
[deployment endpoint](https://cloud.docs.scylladb.com/stable/vector-search/reference-vector-search.md#vs-api-get-vs-instances) to list
available instance types.
```bash
curl -X PATCH "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/cluster/{CLUSTER_ID}/dc/{DC_ID}/vector-search" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"nodeCount": 3,
"defaultInstanceTypeId": 177
}'
```
A successful response returns `HTTP 202 (Accepted)` with a
`ClusterRequest` object. You can
[track the operation status](https://cloud.docs.scylladb.com/stable/vector-search/reference-vector-search.md#vs-api-track-request) using the
returned request ID.
## Disabling Vector Search
You can disable Vector Search through the ScyllaDB Cloud UI or using
the ScyllaDB Cloud API.
Disable via the UI
Choose **Remove Vector Search** from the three-dot menu in the datacenter
overview section to disable Vector Search on your cluster.
Disabling Vector Search removes all the Vector Search nodes from your
cluster.
Disable with the API
Remove Vector Search nodes one by one from the cluster.
To remove all Vector Search nodes from a specific datacenter, send
a `DELETE` request to the Vector Search endpoint. This operation is
asynchronous and returns a `ClusterRequest` object that you can monitor
for progress.
```bash
curl -X DELETE "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/cluster/{CLUSTER_ID}/dc/{DC_ID}/vector-search" \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
The request schedules the removal of all Vector Search nodes from the
specified datacenter. A successful response returns `HTTP 202 (Accepted)`
along with a `ClusterRequest` object that describes the operation.
## Monitoring Vector Search Clusters
You can monitor Vector Search clusters and nodes through the dedicated **Vector
Search** dashboard provided in the ScyllaDB Monitoring Stack. The dashboard is
available from the **Monitoring** tab in your cluster’s view.
See [Monitoring Clusters](https://cloud.docs.scylladb.com/stable/operate/monitor-cluster.md) for details about
the ScyllaDB Monitoring Stack.
### Dashboard Overview
The Vector Search dashboard provides an at-a-glance overview of vector search
health and performance. It includes the following panels:
* **Status** — Whether the vector search service is online (green) or
offline (red).
* **# Indexes** — The total number of vector indexes currently loaded across
the cluster’s vector search nodes.
* **Disk Usage** — Storage consumed by vector search data on the node’s disk,
shown as a pie chart (used vs. free) and as an absolute value.
* **Memory Usage** — Memory consumed by the vector search process, including
in-memory HNSW indexes. Monitor this to determine when to scale up or
enable quantization.
* **CPU Usage** — CPU utilization of the vector search nodes. High CPU usage
may indicate heavy query traffic or bulk index builds.
The dashboard supports filtering by **datacenter (DC)**, **node**, and
**index** using the variable selectors at the top of the page.
### Vector Search Metrics
Vector search nodes export application-level Prometheus metrics alongside
standard infrastructure metrics. You can use these metrics to monitor query
performance, index growth, and write throughput.
**Application metrics**
The following metrics are exported by the vector search service:
| Metric | Type | Labels | Description |
|---------------------------|-----------|---------------------------------------|------------------------------------------------------------------------------------------------------------------|
| `request_latency_seconds` | Histogram | `keyspace`, `index_name` | Latency of ANN search requests within the vector search node. Uses
fine-grained buckets from 0.1 ms to 10 s. |
| `index_size` | Gauge | `keyspace`, `index_name` | Current number of vectors in each index. Updated when the metrics
endpoint is scraped. |
| `index_modified` | Counter | `keyspace`, `index_name`, `operation` | Number of index modification operations. The `operation` label is
one of `insert`, `update`, or `remove`. |
**Infrastructure metrics**
Each vector search node also runs standard Prometheus exporters:
* **Node Exporter** — hardware and OS-level metrics (CPU, memory, disk,
network).
* **Process Exporter** — per-process metrics (CPU, memory, I/O for the
vector search process).
### Example PromQL Queries
Use the following PromQL queries to monitor key aspects of your vector search
deployment:
**Search latency (p99):**
```promql
histogram_quantile(0.99,
sum(rate(request_latency_seconds_bucket[5m])) by (le)
)
```
To get per-index latency, add label selectors:
```promql
histogram_quantile(0.99,
rate(request_latency_seconds_bucket{keyspace="my_ks", index_name="my_idx"}[5m])
)
```
**Search request rate (queries per second):**
```promql
sum(rate(request_latency_seconds_count[5m]))
```
**Vector insert throughput per index:**
```promql
rate(index_modified_total{operation="insert"}[5m])
```
**Total write throughput (inserts + updates + removes):**
```promql
sum(rate(index_modified_total[5m])) by (keyspace, index_name)
```
**Current number of vectors per index:**
```promql
index_size
```
### What to Watch For
* **Rising p99 search latency** — May indicate memory pressure, growing
index size, or resource contention during bulk writes. Consider
[quantization](https://cloud.docs.scylladb.com/stable/vector-search/vector-search-quantization.md) to reduce
index memory, or scale to a larger instance type.
* **Sustained high insert/update rate** — During bulk ingestion or initial
index build, a high `index_modified` rate is expected. If the rate
remains elevated after ingestion completes, investigate whether your
application is performing unnecessary re-inserts.
* **Index size plateaus or drops unexpectedly** — A sudden drop in
`index_size` may indicate bulk deletes or an index rebuild. Verify that
the drop is intentional.
* **High memory utilization** — HNSW indexes are held in memory. As
indexes grow, memory usage rises. If utilization stays above 80 %,
consider enabling
[quantization](https://cloud.docs.scylladb.com/stable/vector-search/vector-search-quantization.md) to
shrink the in-memory footprint, or resize to an instance type with
more RAM.
* **Elevated CPU utilization** — Spikes during bulk index builds or heavy
query traffic are normal. Sustained high CPU outside of ingestion
windows may mean the instance is undersized for the query load.
Scale up the instance type or add more vector search nodes.
* **Disk usage approaching capacity** — While the HNSW index lives in
memory, vector search nodes also store data on disk. Monitor disk usage
to avoid running out of space.
* **Status offline** — If the Status panel shows offline, check that the
vector search nodes are running and that network connectivity between
storage nodes and vector search nodes is intact.
## What’s Next
* [Working with Vector Search](https://cloud.docs.scylladb.com/stable/vector-search/work-with-vector-search.md) —
learn the CQL syntax for vector tables, indexes, and ANN queries.
* [Quick Start Guide](https://cloud.docs.scylladb.com/stable/vector-search/vector-search-quick-start.md) —
end-to-end walkthrough of your first similarity search.
* [Reference](https://cloud.docs.scylladb.com/stable/vector-search/reference-vector-search.md) —
supported instance types, CQL reference, and API endpoints.