# CREATE / DROP VECTOR INDEX — native similarity search

Create the native index that powers [`VECTOR_DISTANCE`](https://dynostudio.dev/docs/dynostudio-partiql-reads/#vector-similarity-search), or remove that read path without deleting a base-table item. Both statements lower to `UpdateTable.VectorIndexUpdates`, and both use live `DescribeTable` metadata to fail closed before the wire.

## Syntax

```sql
CREATE VECTOR INDEX "index" ON "table" (vector_attribute)
  DIMENSIONS 1..4096
  DISTANCE COSINE | EUCLIDEAN | DOT_PRODUCT
  [PARTITION BY (hash_attribute)]
  [FILTER BY (inline_filter_attribute, …)]
  PROJECT ALL | KEYS | (attribute, …);

DROP VECTOR INDEX "index" ON "table";
```

- **Vector** — exactly one top-level vector attribute and `1`–`4096` dimensions.
- **Distance** — `COSINE`, `EUCLIDEAN`, or `DOT_PRODUCT`.
- **`PARTITION BY`** — optional, at most one attribute. It becomes the `HASH` SearchSchema field that every search must pin with equality.
- **`FILTER BY`** — optional, up to 18 attributes. They become `INLINE_FILTER` fields accepted as optional equality filters.
- **`PROJECT`** — `ALL`, `KEYS`, or `1`–`20` included attributes. Include fields a search returns; the vector and SearchSchema fields are intrinsic and must not be repeated in the include list.
- **Names** — table and index names are `3`–`255` characters and may contain letters, numbers, underscore, hyphen, and period.

The vector attribute cannot also be a SearchSchema attribute; an attribute cannot appear in both `PARTITION BY` and `FILTER BY`; duplicate attributes are refused. The editor completes this grammar clause by clause and uses the connected descriptor for table, index, attribute, dimensions, metric, projection, and readiness suggestions.

## Live requirements and lifecycle

- **Professional** — creating and dropping vector indexes are Professional capabilities.
- **Fresh metadata** — create and drop require a complete, current `DescribeTable`; a missing or stale descriptor never becomes an optimistic write.
- **On-demand table** — create requires `ON_DEMAND` billing. A provisioned table refuses with the exact fix.
- **Table limits** — the index name must be new, the table may have at most five vector indexes, and indexes sharing one vector attribute must use the same `DIMENSIONS` value.
- **Double-run confirmation** — the first Run validates and arms the operation; the second unchanged Run dispatches it.
- **Asynchronous receipt** — create is tracked through descriptor appearance and backfill to ready (`ACTIVE` with `Backfilling` cleared). Drop is tracked until the descriptor disappears. Accepted DDL invalidates the metadata cache immediately.

## Use cases

### Search within one category

Product embeddings are 1,536-dimensional. Every search belongs to one category, may filter by brand or status, and returns only product identity and display fields.

```sql
CREATE VECTOR INDEX "ProductEmbeddingIndex" ON "Products" (Embedding)
  DIMENSIONS 1536
  DISTANCE COSINE
  PARTITION BY (Category)
  FILTER BY (Brand, Status)
  PROJECT (ProductId, Title, Price)
```

_Executes as:_ UpdateTable · VectorIndexUpdates.Create ProductEmbeddingIndex · 1536d COSINE · Category HASH · Brand/Status INLINE_FILTER

- Searches stay refused until the descriptor is `ACTIVE` and no longer backfilling. The Background Tasks panel tracks that transition.

_Quote this example:_ https://dynostudio.dev/docs/dynostudio-vector-index/#category-partitioned-products

### A global top-k index

The catalog is small enough that every query searches the full vector index and needs no SearchSchema filters.

```sql
CREATE VECTOR INDEX "CatalogSimilarity" ON "Products" (Embedding)
  DIMENSIONS 768
  DISTANCE DOT_PRODUCT
  PROJECT ALL
```

_Executes as:_ UpdateTable · VectorIndexUpdates.Create CatalogSimilarity · 768d DOT_PRODUCT · no SearchSchema · Projection ALL

- A later query uses nearest-first `DESC` for `DOT_PRODUCT`; omitting the direction selects the descriptor's nearest-first order.

_Quote this example:_ https://dynostudio.dev/docs/dynostudio-vector-index/#unpartitioned-catalog

### Remove the similarity read path

Callers have moved to a replacement index. Remove the old vector index and its storage while retaining every product item.

```sql
DROP VECTOR INDEX "ProductEmbeddingIndexV1" ON "Products";
```

_Executes as:_ UpdateTable · VectorIndexUpdates.Delete ProductEmbeddingIndexV1

- Searches against the index fail as deletion begins. The base table and its items are unchanged.

_Quote this example:_ https://dynostudio.dev/docs/dynostudio-vector-index/#drop-vector-index

> **Projection is a query contract:** A vector search can return only fields projected by the index (plus one explicitly aliased service score). If callers later need unprojected base-table fields, use a separate join-back composition rather than pretending `SearchVectors` fetched them.

Related: [Vector similarity search](https://dynostudio.dev/docs/dynostudio-partiql-reads/#vector-similarity-search) · [SELECT](https://dynostudio.dev/docs/dynostudio-select/#vector-top-k) · [Tables, indexes, backups & replicas](https://dynostudio.dev/docs/dynostudio-partiql-ddl/) · [keyword reference](https://dynostudio.dev/docs/dynostudio-partiql-keywords/).

---
_Source: https://dynostudio.dev/docs/dynostudio-vector-index/ · DynoStudio Docs_