> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Документация по типу данных QBit в ClickHouse, который поддерживает тонко настраиваемое квантование для приближенного векторного поиска

# Тип данных QBit

Тип данных `QBit` реорганизует хранение векторов, чтобы ускорить приближенный поиск. Вместо того чтобы хранить элементы каждого вектора вместе, он группирует одинаковые позиции битов во всех векторах.
При этом векторы хранятся с полной точностью, а во время поиска вы можете выбирать уровень квантования: считывать меньше битов, чтобы сократить I/O и ускорить вычисления, или больше битов для более высокой точности. Это дает выигрыш в скорости за счет уменьшения объема передаваемых данных и вычислений благодаря квантованию, при этом все исходные данные при необходимости остаются доступными.

Чтобы объявить столбец типа `QBit`, используйте следующий синтаксис:

```sql theme={null}
column_name QBit(element_type, dimension)
```

* `element_type` – тип каждого элемента вектора. Допустимые типы: `BFloat16`, `Float32` и `Float64`
* `dimension` – размерность, то есть число элементов в каждом векторе

<div id="creating-qbit">
  ## Создание QBit
</div>

Использование типа `QBit` при определении столбца таблицы:

```sql theme={null}
CREATE TABLE test (id UInt32, vec QBit(Float32, 8)) ENGINE = Memory;
INSERT INTO test VALUES (1, [1, 2, 3, 4, 5, 6, 7, 8]), (2, [9, 10, 11, 12, 13, 14, 15, 16]);
SELECT vec FROM test ORDER BY id;
```

```text theme={null}
┌─vec──────────────────────┐
│ [1,2,3,4,5,6,7,8]        │
│ [9,10,11,12,13,14,15,16] │
└──────────────────────────┘
```

<div id="converting-arrays-to-qbit">
  ## Преобразование массивов в QBit
</div>

Массивы преобразуются в `QBit`, если длина массива соответствует размерности `QBit`. Тип элементов массива не обязательно должен совпадать с типом элементов `QBit`. Любой числовой тип элементов автоматически преобразуется в нужный тип. Это позволяет напрямую перенести существующий столбец эмбеддингов в столбец `QBit`:

```sql theme={null}
CREATE TABLE embeddings (id UInt32, embedding Array(Float32)) ENGINE = Memory;
INSERT INTO embeddings VALUES (1, [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]), (2, [0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2, 0.1]);

CREATE TABLE vectors (id UInt32, vec QBit(Float32, 8)) ENGINE = Memory;
INSERT INTO vectors SELECT id, embedding FROM embeddings;

SELECT * FROM vectors ORDER BY id;
```

```text theme={null}
┌─id─┬─vec───────────────────────────────┐
│  1 │ [0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8] │
│  2 │ [0.8,0.7,0.6,0.5,0.4,0.3,0.2,0.1] │
└────┴───────────────────────────────────┘
```

Явное преобразование также работает с `CAST`, например `CAST(embedding AS QBit(Float32, 8))`.

<div id="qbit-subcolumns">
  ## Подстолбцы QBit
</div>

`QBit` реализует шаблон доступа к подстолбцам, который позволяет обращаться к отдельным битовым плоскостям сохранённых векторов. Доступ к каждой битовой позиции можно получить с помощью синтаксиса `.N`, где `N` — это позиция бита:

```sql theme={null}
CREATE TABLE test (id UInt32, vec QBit(Float32, 8)) ENGINE = Memory;
INSERT INTO test VALUES (1, [0, 0, 0, 0, 0, 0, 0, 0]);
INSERT INTO test VALUES (1, [-0, -0, -0, -0, -0, -0, -0, -0]);
SELECT bin(vec.1) FROM test;
```

```text theme={null}
┌─bin(tupleElement(vec, 1))─┐
│ 00000000                  │
│ 11111111                  │
└───────────────────────────┘
```

Количество доступных подстолбцов зависит от типа элементов:

* `BFloat16`: 16 подстолбцов (1-16)
* `Float32`: 32 подстолбца (1-32)
* `Float64`: 64 подстолбца (1-64)

<div id="vector-search-functions">
  ## Функции векторного поиска
</div>

Это функции расстояния для поиска по векторному сходству, использующие тип данных `QBit`:

* [`L2DistanceTransposed`](/ru/reference/functions/regular-functions/distance-functions#L2DistanceTransposed)
* [`cosineDistanceTransposed`](/ru/reference/functions/regular-functions/distance-functions#cosineDistanceTransposed)