---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ydb.tech/docs/en/yql/reference/syntax/create_table/vector_index.md?version=main
  - https://ydb.tech/docs/ru/yql/reference/syntax/create_table/vector_index.md?version=main
sourcePath: en/core/yql/reference/syntax/create_table/vector_index.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/en/llms.txt

# Vector index

[Vector index](https://ydb.tech/docs/en/dev/vector-indexes.md?version=main) in [row-oriented](https://ydb.tech/docs/en/concepts/datamodel/table.md?version=main#row-oriented-tables) tables is created using the same syntax as [secondary indexes](https://ydb.tech/docs/en/yql/reference/syntax/create_table/secondary_index.md?version=main), by specifying `vector_kmeans_tree` as the index type. Subset of syntax available for vector indexes:

```yql
CREATE TABLE `<table_name>` (
    ...
    INDEX `<index_name>`
        GLOBAL
        [SYNC]
        USING vector_kmeans_tree
        ON ( <index_columns> )
        [COVER ( <cover_columns> )]
        [WITH ( <parameter_name> = <parameter_value>[, ...])]
    [,   ...]
)
```

Where:

* `<index_name>` - unique index name for data access
* `SYNC` - indicates synchronous data writing to the index. This is the only currently available option, and it is used by default.
* `<index_columns>` - comma-separated list of table columns used for index searches (the last column is used as embedding, others as filtering columns)
* `<cover_columns>` - list of additional table columns stored in the index to enable retrieval without accessing the main table
* `<parameter_name>` and `<parameter_value>` - list of key-value parameters:

<!-- source: en/yql/reference/syntax/_includes/vector_index_parameters.md -->
  * common parameters for all vector indexes:
    * `vector_dimension` - embedding vector dimensionality (should be between 1 and 16384)
    * `vector_type` - vector value type (`float`, `uint8`, or `int8`)
    * `distance` - [distance function](https://ydb.tech/docs/en/yql/reference/udf/list/knn.md?version=main#functions-distance) (`cosine`, `manhattan`, or `euclidean`), mutually exclusive with `similarity`
    * `similarity` - [similarity function](https://ydb.tech/docs/en/yql/reference/udf/list/knn.md?version=main#functions-distance) (`inner_product` or `cosine`), mutually exclusive with `distance`
  * specific parameters for `vector_kmeans_tree` ([read more about the index type](https://ydb.tech/docs/en/dev/vector-indexes.md?version=main#kmeans-tree-type)):
    * `clusters` - number of centroids for k-means algorithm (should be between 2 and 2048)
    * `levels` - number of levels in the tree (should be between 1 and 16)
    * `overlap_clusters` - the number of nearest clusters to add each vector to (default 1)
    * `adaptive_clusters` - for [filtered indexes](https://ydb.tech/docs/en/dev/vector-indexes.md?version=main#filtered), automatically choose the number of clusters per filtering-column value based on how many vectors that value has (`true` or `false`, default `false`). See [Adaptive clusters](https://ydb.tech/docs/en/dev/vector-indexes-kmeans-tree-type.md?version=main#adaptive-clusters).
    * the total number of nodes in the tree, calculated as `clusters` raised to the power of `levels`, should be no more than 1073741824
    * the product of `vector_dimension` and `clusters` should be no more than 4194304
<!-- endsource: en/yql/reference/syntax/_includes/vector_index_parameters.md -->

{% note warning %}

It is recommended to create a vector index after loading data into the table, as an index created on an empty table will have only one cluster and will not speed up the search at all. For more details, see [Updating Vector Indexes](https://ydb.tech/docs/en/dev/vector-indexes.md?version=main#update).

{% endnote %}

<!-- source: en/_includes/not_allow_for_olap_note.md -->
{% note warning %}

<!-- source: en/_includes/not_allow_for_olap_text.md -->
Supported only for [row-oriented](https://ydb.tech/docs/en/concepts/datamodel/table.md?version=main#row-oriented-tables) tables. Support for [column-oriented](https://ydb.tech/docs/en/concepts/datamodel/table.md?version=main#column-oriented-tables) tables is currently under development.
<!-- endsource: en/_includes/not_allow_for_olap_text.md -->

{% endnote %}
<!-- endsource: en/_includes/not_allow_for_olap_note.md -->

## Example

```yql
CREATE TABLE user_articles (
    article_id Uint64,
    user String,
    title String,
    text String,
    embedding String,
    INDEX emb_cosine_idx GLOBAL SYNC USING vector_kmeans_tree
    ON (user, embedding) COVER (title, text)
    WITH (
        distance="cosine",
        vector_type="float",
        vector_dimension=512,
        clusters=128,
        levels=2,
        overlap_clusters=3
    ),
    PRIMARY KEY (article_id)
)
```