<a id="vs-reference"></a>

# Reference for Vector Search

This page is a technical reference for working with Vector Search in ScyllaDB.
It includes a list of supported instance types, the CQL syntax needed to define
and query vector data, and the API endpoints for managing Vector Search clusters.

<a id="vector-search-clusters-instances"></a>

## Supported Instance Types

The following instance types are supported for Vector Search clusters.

<a id="vs-instance-types-aws"></a>

### On AWS

| Instance Type   |   ID |   vCPUs |   RAM (GiB) | Use Case                       |
|-----------------|------|---------|-------------|--------------------------------|
| t4g.medium      |  176 |       2 |           4 | Development and testing        |
| r7g.medium      |  177 |       1 |           8 | Small workloads                |
| r7g.large       |  204 |       2 |          16 | Light production workloads     |
| r7g.xlarge      |  205 |       4 |          32 | Medium workloads               |
| r7g.2xlarge     |  206 |       8 |          64 | General-purpose production     |
| r7g.4xlarge     |  207 |      16 |         128 | Large indexes                  |
| r7g.8xlarge     |  208 |      32 |         256 | Very large indexes             |
| r7g.12xlarge    |  209 |      48 |         384 | High-dimensional / high-volume |
| r7g.16xlarge    |  210 |      64 |         512 | Maximum Graviton capacity      |
| r7i.24xlarge    |  211 |      96 |         768 | Extreme workloads (Intel)      |
| r7i.48xlarge    |  212 |     192 |       1,536 | Maximum capacity (Intel)       |

<a id="vs-instance-types-gcp"></a>

### On GCP

| Instance Type   | ID                                      |   vCPUs |   RAM (GiB) | Use Case                       |
|-----------------|-----------------------------------------|---------|-------------|--------------------------------|
| e2-medium       | 179                                     |       2 |           4 | Development and testing        |
| n4-highmem-2    | 180                                     |       2 |          16 | Small workloads                |
| n4-highmem-4    | 213                                     |       4 |          32 | Light production workloads     |
| n4-highmem-8    | 214                                     |       8 |          64 | General-purpose production     |
| n4-highmem-16   | 215                                     |      16 |         128 | Large indexes                  |
| n4-highmem-32   | 216                                     |      32 |         256 | Very large indexes             |
| n4-highmem-48   | 217                                     |      48 |         384 | High-dimensional / high-volume |
| n4-highmem-64   | 218                                     |      64 |         512 | High-dimensional / high-volume |
| n4-highmem-80   | 219                                     |      80 |         640 | Maximum N4 capacity            |
| m4-megamem-28   | 220 (limited availability - contact us) |      28 |         448 | Memory-optimized workloads     |
| m4-ultramem-56  | 221 (limited availability - contact us) |      56 |         896 | Ultra-memory workloads         |
| m4-ultramem-112 | 222 (limited availability - contact us) |     112 |       1,792 | Extreme workloads              |
| m4-ultramem-224 | 223 (limited availability - contact us) |     224 |       3,584 | Maximum capacity               |

<a id="vs-cql-reference"></a>

## CQL Reference

<a id="vs-cql-create-table"></a>

### Create Vector Table

Syntax:

```cql
CREATE TABLE IF NOT EXISTS keyspace.table (
  column1 type,
  column2 type,
  vector_column_name vector<float, n>,
  PRIMARY KEY (column1, column2)
);
```

Example:

```cql
CREATE TABLE IF NOT EXISTS myapp.comments (
  record_id timeuuid,
  id uuid,
  commenter text,
  comment text,
  comment_vector vector<float, 5>,
  created_at timestamp,
  PRIMARY KEY (id, created_at)
);
```

<a id="vs-cql-create-index"></a>

### Create Vector Index

Syntax:

```cql
CREATE CUSTOM INDEX [ IF NOT EXISTS ] index_name
ON table_name (vector_column_name)
USING 'vector_index'
[ WITH OPTIONS = { options } ];
```

Available options:

| Option                     | Default   | Description                                                                       |
|----------------------------|-----------|-----------------------------------------------------------------------------------|
| `similarity_function`      | `COSINE`  | Distance metric: `COSINE`, `DOT_PRODUCT`, or `EUCLIDEAN`.                         |
| `maximum_node_connections` | `16`      | Max connections per HNSW graph node (commonly known as `m`).                      |
| `construction_beam_width`  | `128`     | Dynamic candidate list size during index build (commonly known as `efConstruct`). |
| `search_beam_width`        | `128`     | Dynamic candidate list size during queries (commonly known as `efSearch`).        |
| `quantization`             | `f32`     | Vector precision: `f32`, `f16`, `bf16`, `i8`, or `b1`.                            |
| `oversampling`             | `1.0`     | Candidate multiplier for quantized search (1.0-100.0).                            |
| `rescoring`                | `false`   | Re-rank results using full-precision vectors from disk.                           |

Example:

```cql
CREATE CUSTOM INDEX comment_ann_index
ON myapp.comments(comment_vector)
USING 'vector_index'
WITH OPTIONS = {
  'similarity_function': 'COSINE',
  'maximum_node_connections': '16',
  'quantization': 'i8',
  'oversampling': '5.0',
  'rescoring': 'true'
};
```

See
[Global Secondary Indexes - Vector Index](https://docs.scylladb.com/manual/branch-2026.1/cql/secondary-indexes.html#vector-index-scylladb-cloud)
in the ScyllaDB documentation for details.

<a id="vs-cql-drop-index"></a>

### Drop Vector Index

Syntax:

```cql
DROP INDEX [ IF EXISTS ] index_name;
```

Example:

```cql
DROP INDEX IF EXISTS comment_ann_index;
```

<a id="vs-cql-ann-query"></a>

### Run Similarity Search

Syntax:

```cql
SELECT column1, column2, ...
FROM keyspace.table
[ WHERE condition ]
ORDER BY vector_column_name ANN OF [v1, v2, ..., vn]
LIMIT k
[ ALLOW FILTERING ];
```

Example:

```cql
SELECT id, commenter, comment
FROM myapp.comments
ORDER BY comment_vector ANN OF [0.12, 0.34, 0.56, 0.78, 0.91]
LIMIT 3;
```

See
[Data Manipulation - SELECT - Vector Queries](https://docs.scylladb.com/manual/branch-2026.1/cql/dml/select.html#vector-queries-scylladb-cloud)
in the ScyllaDB documentation for details.

To combine similarity search with metadata constraints using global or local
indexes, see [Filtering Vector Search Results](https://cloud.docs.scylladb.com/stable/vector-search/vector-search-filtering.md).

<a id="vs-cql-similarity-functions"></a>

### Retrieve Similarity Scores

Use one of the built-in similarity functions to return a similarity score for
each row. The function must match the `similarity_function` configured on
your vector index.

Available functions:

* `similarity_cosine(<vector>, <vector>)`
* `similarity_dot_product(<vector>, <vector>)`
* `similarity_euclidean(<vector>, <vector>)`

Each argument can be either a vector column name or a vector literal. Both
arguments must have the same dimension.

#### NOTE
There is no generic `similarity()` function. You must call the specific
function matching your index’s distance metric.

Syntax:

```cql
SELECT column1, similarity_cosine(vector_column, [v1, ..., vn])
FROM keyspace.table
ORDER BY vector_column ANN OF [v1, ..., vn]
LIMIT k;
```

Example:

```cql
SELECT commenter, comment,
       similarity_cosine(comment_vector, [0.12, 0.34, 0.56, 0.78, 0.91])
       AS similarity
FROM myapp.comments
ORDER BY comment_vector ANN OF [0.12, 0.34, 0.56, 0.78, 0.91]
LIMIT 3;
```

Each function returns a `float` in the range [0, 1]. Values closer to 1
indicate greater similarity. The `similarity_euclidean` and
`similarity_dot_product` functions do not perform vector normalization
prior to computing similarity.

#### NOTE
`similarity_dot_product` assumes that all input vectors are L2-normalized.
Supplying non-normalized vectors will produce values that are not meaningful
for similarity comparison. If your vectors are not normalized, use
`similarity_cosine` instead.

See
[Vector Similarity Functions](https://docs.scylladb.com/manual/stable/cql/functions.html#vector-similarity-functions)
in the ScyllaDB documentation for details.

<a id="vs-alternator-api-reference"></a>

## Alternator API Reference

These operations use the DynamoDB-compatible Alternator API through the
[alternator-client](https://github.com/scylladb/alternator-client-python)
Python driver. They apply to the 2026.2.x series, where embeddings are stored
as lists of numbers. For a full walkthrough and a comparison with CQL, see
[Vector Search with Alternator](https://cloud.docs.scylladb.com/stable/vector-search/vector-search-alternator.md).

The examples assume an open `AlternatorResource` named `resource` and its
`client` (`client = resource.meta.client`).

<a id="vs-alternator-api-create-table"></a>

### Create a Table

```python
resource.create_table(
    TableName="comments",
    KeySchema=[{"AttributeName": "id", "KeyType": "HASH"}],
    AttributeDefinitions=[{"AttributeName": "id", "AttributeType": "S"}],
    BillingMode="PAY_PER_REQUEST",
)
```

<a id="vs-alternator-api-insert"></a>

### Insert an Item with a Vector

The vector is a list of numbers. In the DynamoDB resource interface, numbers
are represented as `Decimal`:

```python
from decimal import Decimal

table = resource.Table("comments")
table.put_item(
    Item={
        "id": "1",
        "comment": "I like vector search in ScyllaDB.",
        "comment_vector": [Decimal(str(x)) for x in (0.12, 0.34, 0.56, 0.78, 0.91)],
    }
)
```

<a id="vs-alternator-api-create-index"></a>

### Create a Vector Index

```python
client.update_table(
    TableName="comments",
    VectorIndexUpdates=[
        {
            "Create": {
                "IndexName": "comment_ann_index",
                "VectorAttribute": {
                    "AttributeName": "comment_vector",
                    "Dimensions": 5,
                },
            }
        }
    ],
)
```

The index builds asynchronously. Poll `describe_table` until the index status
is `ACTIVE`:

```python
import time

while True:
    indexes = client.describe_table(TableName="comments")["Table"].get(
        "VectorIndexes", []
    )
    if indexes and indexes[0]["IndexStatus"] == "ACTIVE":
        break
    time.sleep(1)
```

<a id="vs-alternator-api-query"></a>

### Run a Similarity Search

Pass the query vector in `VectorSearch` and use `Limit` for the number of
nearest neighbors (`k`). The index projects only the key, so read the full
item for each match:

```python
from decimal import Decimal

query_vector = [Decimal(str(x)) for x in (0.12, 0.34, 0.56, 0.78, 0.91)]
response = table.query(
    IndexName="comment_ann_index",
    VectorSearch={"QueryVector": query_vector},
    Limit=3,
)
for match in response["Items"]:
    item = table.get_item(Key={"id": match["id"]})["Item"]
    print(item["comment"])
```

<a id="vs-api-reference"></a>

## API Reference

All ScyllaDB Cloud API requests require a personal API token for
authentication. See
[Create a Personal Token](https://cloud.docs.scylladb.com/stable/api-docs/create-api-token.md) for details.

<a id="vs-api-create-cluster"></a>

### Create a Vector Search Cluster

Create a new cluster with Vector Search enabled:

```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
    }
  }'
```

<a id="vs-api-deploy-nodes"></a>

### Deploy Vector Search Nodes

Deploy Vector Search nodes in the specified datacenter (DC):

```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
  }'
```

<a id="vs-api-delete-nodes"></a>

### Delete Vector Search Nodes

Delete Vector Search nodes from the specified datacenter (DC):

```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"
```

<a id="vs-api-resize-nodes"></a>

### Resize Vector Search Nodes

Resize the Vector Search deployment in the specified datacenter (DC) by
changing the node count or instance type:

```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
  }'
```

Parameters:

* `nodeCount` (integer, 1–27, required) — number of vector search nodes,
  distributed evenly across cluster racks.
* `defaultInstanceTypeId` (integer, required) — ID of the instance type.
  See [Supported Instance Types](#vector-search-clusters-instances) or
  use the [deployment endpoint](#vs-api-get-vs-instances) with
  `target=VECTOR_SEARCH` to list available types.

<a id="vs-api-get-nodes"></a>

### Get Vector Search Nodes

Get information about Vector Search nodes in the specified datacenter (DC):

```bash
curl -X GET "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/cluster/{CLUSTER_ID}/dc/{DC_ID}/vector-search" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Example response:

```json
{
  "data": {
    "availabilityZones": [
      {
        "azid": "use1-az4",
        "nodes": [
          {
            "id": 337,
            "instanceTypeId": 176,
            "status": "ACTIVE"
          }
        ]
      },
      {
        "azid": "use1-az5",
        "nodes": [
          {
            "id": 338,
            "instanceTypeId": 176,
            "status": "ACTIVE"
          }
        ]
      },
      {
        "azid": "use1-az2",
        "nodes": [
          {
            "id": 339,
            "instanceTypeId": 176,
            "status": "ACTIVE"
          }
        ]
      }
    ]
  }
}
```

<a id="vs-api-get-account"></a>

### Get Your Account ID

```bash
curl -X GET "https://api.cloud.scylladb.com/account/default" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Response:

```json
{
  "error": "",
  "data": {
    "accountId": 12345,
    "name": "my-account",
    "userId": "12345"
  }
}
```

<a id="vs-api-get-cluster"></a>

### Get Your Cluster ID

```bash
curl -X GET "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/clusters" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

<a id="vs-api-get-dc"></a>

### Get Your DC ID

```bash
curl -X GET "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/cluster/{CLUSTER_ID}/dcs" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

<a id="vs-api-get-vs-instances"></a>

### Get Available Vector Search Instance Types

List available Vector Search instance types for a specific cloud provider
and region by passing `target=VECTOR_SEARCH`:

```bash
curl -X GET "https://api.cloud.scylladb.com/deployment/cloud-provider/{CLOUD_PROVIDER_ID}/region/{REGION_ID}?target=VECTOR_SEARCH" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

The response contains a list of instance types with their IDs. Use the
instance type ID as the `defaultInstanceTypeId` parameter when deploying
or resizing Vector Search nodes.

<a id="vs-api-track-request"></a>

### Track Operation Status

All asynchronous Vector Search operations (deploy, resize, delete) return a
`ClusterRequest` object with a request ID. You can poll for the operation
status:

```bash
curl -X GET "https://api.cloud.scylladb.com/account/{ACCOUNT_ID}/cluster/request/{REQUEST_ID}" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

The `status` field in the response is one of: `QUEUED`, `IN_PROGRESS`,
`COMPLETED`, or `FAILED`.