[#14319] Add docs for Roaring UDF (#14484)

Co-authored-by: Ivan Blinkov <ivan@ydb.tech>

6 files changed, 196 insertions, 0 deletions

diff --git a/ydb/docs/en/core/yql/reference/udf/list/index.md b/ydb/docs/en/core/yql/reference/udf/list/index.md
index f6d5a0912b..c265afebd3 100644
--- a/ydb/docs/en/core/yql/reference/udf/list/index.md
+++ b/ydb/docs/en/core/yql/reference/udf/list/index.md
@@ -14,6 +14,7 @@ Many application functions that on the one hand are too specific to become part
 * [Pcre](pcre.md)
 * [Pire](pire.md)
 * [Re2](re2.md)
+* [Roaring](roaring.md)
 * [String](string.md)
 * [Unicode](unicode.md)
 * [Url](url.md)
diff --git a/ydb/docs/en/core/yql/reference/udf/list/roaring.md b/ydb/docs/en/core/yql/reference/udf/list/roaring.md
new file mode 100644
index 0000000000..cee7927c84
--- /dev/null
+++ b/ydb/docs/en/core/yql/reference/udf/list/roaring.md
@@ -0,0 +1,96 @@
+# Roaring
+
+## Introduction
+
+Bitsets, also called bitmaps, are commonly used as fast data structures. Unfortunately, they can use too much memory. To compensate, we often use compressed bitmaps.
+
+Roaring bitmaps are compressed bitmaps which tend to outperform conventional compressed bitmaps such as WAH, EWAH or Concise. In some instances, roaring bitmaps can be hundreds of times faster and they often offer significantly better compression. They can even be faster than uncompressed bitmaps.
+
+## Implementation
+
+You can work with Roaring bitmaps in {{ ydb-short-name }} using a set of user-defined functions (UDFs) in the `Roaring` module. These functions provide the ability to work with 32-bit Roaring bitmaps. To do this, the data must be serialized in the format for 32-bit bitmaps described in the [specification](https://github.com/RoaringBitmap/RoaringFormatSpec?tab=readme-ov-file#standard-32-bit-roaring-bitmap). This can be done using a function available in the Roaring bitmap library itself.
+
+Such libraries exist for many programming languages, such as [Go](https://github.com/RoaringBitmap/roaring). If the serialization happened on the client side, the application can then save the serialized bitmap in a column with the `String` type.
+
+To work with Roaring bitmaps in a query, data from the `String` type must be deserialized into the [Resource<roaring_bitmap>](../../types/special.md) type. To save the data, you need to perform the reverse operation. After that, the application can read the updated bitmap from {{ ydb-short-name }} and deserialize it.
+
+## Available methods
+
+```yql
+Roaring::Deserialize(String{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::FromUint32List(List<Uint32>{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::Serialize(Resource<roaring_bitmap>{Flags:AutoMap})->String
+Roaring::Uint32List(Resource<roaring_bitmap>{Flags:AutoMap})->List<Uint32>
+
+Roaring::Cardinality(Resource<roaring_bitmap>{Flags:AutoMap})->Uint32
+
+Roaring::Or(Resource<roaring_bitmap>{Flags:AutoMap}, Resource<roaring_bitmap>{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::OrWithBinary(Resource<roaring_bitmap>{Flags:AutoMap}, String{Flags:AutoMap})->Resource<roaring_bitmap>
+
+Roaring::And(Resource<roaring_bitmap>{Flags:AutoMap}, Resource<roaring_bitmap>{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::AndWithBinary(Resource<roaring_bitmap>{Flags:AutoMap}, String{Flags:AutoMap})->Resource<roaring_bitmap>
+
+Roaring::AndNot(Resource<roaring_bitmap>{Flags:AutoMap}, Resource<roaring_bitmap>{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::AndNotWithBinary(Resource<roaring_bitmap>{Flags:AutoMap}, String{Flags:AutoMap})->Resource<roaring_bitmap>
+
+Roaring::RunOptimize(Resource<roaring_bitmap>{Flags:AutoMap})->Resource<roaring_bitmap>
+```
+
+## Serialization and deserialization
+
+Two functions, `Deserialize` and `FromUint32List`, are available for creating `Resource<roaring_bitmap>`. The second function allows creating a Roaring bitmap from a list of unsigned integers, i.e., without the need to use the Roaring bitmap library code to create a binary representation.
+
+{{ ydb-short-name }} does not store data with the `Resource` type, so the created bitmap must be converted to a binary representation using the `Serialize` method.
+
+To use the resulting bitmap, for example, in a `WHERE` condition, the `Uint32List` method is provided. This method returns a list of unsigned integers from the `Resource<roaring_bitmap>`.
+
+## Bitwise operations
+
+Currently, three modifying binary operations with bitmaps are supported:
+
+- `Or`
+- `And`
+- `AndNot`
+
+The operations are modifying, meaning that they modify the `Resource<roaring_bitmap>` passed as the first argument. Each of these operations has a version with the `WithBinary` suffix, which allows working with the binary representation without having to deserialize it into the `Resource<roaring_bitmap>` type. The implementation of these methods still has to deserialize the data to perform the operation, but it does not create an intermediate `Resource`, thereby saving resources.
+
+## Other operations
+
+The `Cardinality` function is provided to obtain the number of bits set to 1 in the `Resource<roaring_bitmap>`.
+
+After the bitmap has been constructed or modified, it can be optimized using the `RunOptimize` method. The internal format of a Roaring bitmap can use containers with better representations for different bit sequences.
+
+## Examples
+
+```yql
+$b = Roaring::FromUint32List(AsList(42));
+$b = Roaring::Or($b, Roaring::FromUint32List(AsList(56)));
+
+
+SELECT Roaring::Uint32List($b) AS `Or`; -- [42, 56]
+```
+
+
+```yql
+$b1 = Roaring::FromUint32List(AsList(10, 567, 42));
+$b2 = Roaring::FromUint32List(AsList(42));
+
+$b2ser = Roaring::Serialize($b2); -- save this to String column
+
+SELECT Roaring::Cardinality(Roaring::AndWithBinary($b1, $b2ser)) AS Cardinality; -- 1
+
+SELECT Roaring::Uint32List(Roaring::And($b1, $b2)) AS `And`; -- [42]
+SELECT Roaring::Uint32List(Roaring::AndWithBinary($b1, $b2ser)) AS AndWithBinary; -- [42]
+```
+
+```yql
+$b1 = Roaring::FromUint32List(AsList(10, 567, 42));
+$b2 = Roaring::FromUint32List(AsList(42));
+
+$b2ser = Roaring::Serialize($b2); -- save this to String column
+
+SELECT Roaring::Cardinality(Roaring::AndNotWithBinary($b1, $b2ser)) AS Cardinality; -- 2
+
+SELECT Roaring::Uint32List(Roaring::AndNot($b1, $b2)) AS AndNot; -- [10,567]
+SELECT Roaring::Uint32List(Roaring::AndNotWithBinary($b1, $b2ser)) AS AndNotWithBinary; -- [10,567]
+```
diff --git a/ydb/docs/en/core/yql/reference/udf/list/toc_base.yaml b/ydb/docs/en/core/yql/reference/udf/list/toc_base.yaml
index d1fddde502..ff13d458c4 100644
--- a/ydb/docs/en/core/yql/reference/udf/list/toc_base.yaml
+++ b/ydb/docs/en/core/yql/reference/udf/list/toc_base.yaml
@@ -11,6 +11,7 @@ items:
 - { name: Pcre,                   href: pcre.md }
 - { name: Pire,                   href: pire.md }
 - { name: Re2,                    href: re2.md }
+- { name: Roaring,                href: roaring.md }
 - { name: String,                 href: string.md }
 - { name: Unicode,                href: unicode.md }
 - { name: Url,                    href: url.md }
diff --git a/ydb/docs/ru/core/yql/reference/udf/list/index.md b/ydb/docs/ru/core/yql/reference/udf/list/index.md
index 9cc26c2056..cd32cc30dd 100644
--- a/ydb/docs/ru/core/yql/reference/udf/list/index.md
+++ b/ydb/docs/ru/core/yql/reference/udf/list/index.md
@@ -14,6 +14,7 @@
 * [Pcre](pcre.md)
 * [Pire](pire.md)
 * [Re2](re2.md)
+* [Roaring](roaring.md)
 * [String](string.md)
 * [Unicode](unicode.md)
 * [Url](url.md)
diff --git a/ydb/docs/ru/core/yql/reference/udf/list/roaring.md b/ydb/docs/ru/core/yql/reference/udf/list/roaring.md
new file mode 100644
index 0000000000..6204d36ec4
--- /dev/null
+++ b/ydb/docs/ru/core/yql/reference/udf/list/roaring.md
@@ -0,0 +1,96 @@
+# Roaring
+
+## Введение
+
+Битовые множества, также называемые битовыми картами (bitmaps), обычно используются в качестве быстрых структур данных. К сожалению, они могут потреблять слишком много памяти. Чтобы уменьшить занимаемый объём, применяется сжатие.
+
+Roaring bitmaps — это сжатые битовые карты, которые, как правило, превосходят обычные алгоритмы сжатия битовых карт, такие как WAH, EWAH или Concise. В некоторых случаях Roaring bitmaps могут быть в сотни раз быстрее, а также часто обеспечивают значительно лучшее сжатие. Они могут быть даже быстрее, чем несжатые битовые карты.
+
+## Реализация
+
+Работать с Roaring bitmap в {{ ydb-short-name }} можно с помощью набора пользовательских функций UDF в модуле `Roaring`. Они предоставляют возможность работать с 32-битными Roaring bitmap. Для этого данные должны быть сериализованы в формате 32-битных битовых масок, описанном в [спецификации](https://github.com/RoaringBitmap/RoaringFormatSpec?tab=readme-ov-file#standard-32-bit-roaring-bitmap). Это можно сделать с помощью функции, доступной в библиотеке Roaring bitmap. Такие библиотеки есть для многих языков, например, для [Go](https://github.com/RoaringBitmap/roaring).
+
+Сериализованную битовую маску приложение может сохранить в колонке с типом `String`.
+
+Для работы с Roaring bitmap данные из строкового типа необходимо десериализовать в тип [Resource<roaring_bitmap>](../../types/special.md). Для сохранения нужно выполнить обратную операцию. После этого приложение сможет прочитать обновлённую битовую маску из {{ ydb-short-name }} и десериализовать её уже на своей стороне.
+
+## Доступные методы
+
+```yql
+Roaring::Deserialize(String{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::FromUint32List(List<Uint32>{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::Serialize(Resource<roaring_bitmap>{Flags:AutoMap})->String
+Roaring::Uint32List(Resource<roaring_bitmap>{Flags:AutoMap})->List<Uint32>
+
+Roaring::Cardinality(Resource<roaring_bitmap>{Flags:AutoMap})->Uint32
+
+Roaring::Or(Resource<roaring_bitmap>{Flags:AutoMap}, Resource<roaring_bitmap>{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::OrWithBinary(Resource<roaring_bitmap>{Flags:AutoMap}, String{Flags:AutoMap})->Resource<roaring_bitmap>
+
+Roaring::And(Resource<roaring_bitmap>{Flags:AutoMap}, Resource<roaring_bitmap>{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::AndWithBinary(Resource<roaring_bitmap>{Flags:AutoMap}, String{Flags:AutoMap})->Resource<roaring_bitmap>
+
+Roaring::AndNot(Resource<roaring_bitmap>{Flags:AutoMap}, Resource<roaring_bitmap>{Flags:AutoMap})->Resource<roaring_bitmap>
+Roaring::AndNotWithBinary(Resource<roaring_bitmap>{Flags:AutoMap}, String{Flags:AutoMap})->Resource<roaring_bitmap>
+
+Roaring::RunOptimize(Resource<roaring_bitmap>{Flags:AutoMap})->Resource<roaring_bitmap>
+```
+
+## Сериализация и десериализация
+
+Для создания `Resource<roaring_bitmap>` доступны две функции: `Deserialize` и `FromUint32List`. Вторая функция позволяет создавать Roaring bitmap из списков беззнаковых целых чисел, то есть без необходимости использовать библиотечный код Roaring bitmaps для создания бинарного представления.
+
+YDB не сохраняет данные с типом `Resource`, поэтому созданную битовую маску необходимо преобразовать в бинарное представление с помощью метода `Serialize`.
+
+Чтобы использовать полученную битовую маску, например, в условии `WHERE`, предусмотрен метод `Uint32List`, который возвращает список беззнаковых целых чисел из `Resource<roaring_bitmap>`.
+
+## Битовые операции
+
+В настоящий момент поддерживаются три модифицирующие бинарные операции с битовыми масками:
+
+- `Or`
+- `And`
+- `AndNot`
+
+Модифицирующие операции означают, что они изменяют `Resource<roaring_bitmap>`, переданный в первом аргументе. У каждой из этих операций есть версия с суффиксом `WithBinary`, которая позволяет работать с бинарным представлением, не прибегая к его десериализации в тип `Resource<roaring_bitmap>`. Реализация этих методов всё равно выполняет десериализацию для выполнения операции, но не создаёт промежуточный `Resource`, что позволяет экономить ресурсы.
+
+## Прочие операции
+
+Для получения кардинальности (количества бит, установленных в 1) предусмотрена функция `Cardinality`.
+
+После построения или модификации битовой маски её можно оптимизировать с помощью метода `RunOptimize`. Это связано с тем, что внутренний формат Roaring bitmap может использовать контейнеры с более эффективным представлением для разных последовательностей бит.
+
+## Примеры
+
+```yql
+$b = Roaring::FromUint32List(AsList(42));
+$b = Roaring::Or($b, Roaring::FromUint32List(AsList(56)));
+
+
+SELECT Roaring::Uint32List($b) AS `Or`; -- [42, 56]
+```
+
+
+```yql
+$b1 = Roaring::FromUint32List(AsList(10, 567, 42));
+$b2 = Roaring::FromUint32List(AsList(42));
+
+$b2ser = Roaring::Serialize($b2); -- результат можно сохранить в колонку с типом String
+
+SELECT Roaring::Cardinality(Roaring::AndWithBinary($b1, $b2ser)) AS Cardinality; -- 1
+
+SELECT Roaring::Uint32List(Roaring::And($b1, $b2)) AS `And`; -- [42]
+SELECT Roaring::Uint32List(Roaring::AndWithBinary($b1, $b2ser)) AS AndWithBinary; -- [42]
+```
+
+```yql
+$b1 = Roaring::FromUint32List(AsList(10, 567, 42));
+$b2 = Roaring::FromUint32List(AsList(42));
+
+$b2ser = Roaring::Serialize($b2); -- результат можно сохранить в колонку с типом String
+
+SELECT Roaring::Cardinality(Roaring::AndNotWithBinary($b1, $b2ser)) AS Cardinality; -- 2
+
+SELECT Roaring::Uint32List(Roaring::AndNot($b1, $b2)) AS AndNot; -- [10,567]
+SELECT Roaring::Uint32List(Roaring::AndNotWithBinary($b1, $b2ser)) AS AndNotWithBinary; -- [10,567]
+```
diff --git a/ydb/docs/ru/core/yql/reference/udf/list/toc_base.yaml b/ydb/docs/ru/core/yql/reference/udf/list/toc_base.yaml
index 9e2acf73c4..36e4bf5792 100644
--- a/ydb/docs/ru/core/yql/reference/udf/list/toc_base.yaml
+++ b/ydb/docs/ru/core/yql/reference/udf/list/toc_base.yaml
@@ -11,6 +11,7 @@ items:
 - { name: Pcre,                   href: pcre.md }
 - { name: Pire,                   href: pire.md }
 - { name: PostgreSQL,             href: postgres.md }
+- { name: Roaring,                href: roaring.md }
 - { name: Re2,                    href: re2.md }
 - { name: String,                 href: string.md }
 - { name: Unicode,                href: unicode.md }