--- metadata: - name: generator content: Diplodoc Platform v5.56.0 alternate: - https://ydb.tech/docs/en/dev/bloom-skip-indexes.md?version=main - https://ydb.tech/docs/ru/dev/bloom-skip-indexes.md?version=main - href: ru/dev/bloom-skip-indexes.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt sourcePath: ru/core/dev/bloom-skip-indexes.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Блум-индексы Блум-индексы — [локальные](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#local-index) вспомогательные структуры на основе [фильтра Блума](https://ru.wikipedia.org/wiki/Фильтр_Блума), которые ускоряют селективные запросы за счёт пропуска фрагментов данных, в которых искомое значение гарантированно отсутствует. В отличие от глобальных [вторичных индексов](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#secondary-index), они работают как фильтры чтения основной таблицы и уменьшают объём данных, которые нужно фактически читать. ## Типы {#types} Поддерживаются два типа: * `bloom_filter` — фильтр по точным значениям индексируемой колонки; подходит для условий равенства и `IN` (см. [когда применять](https://ydb.tech/docs/ru/concepts/query_execution/local_indexes.md?version=main#bloom-skip-indexes)). * `bloom_ngram_filter` — фильтр по n-граммам строковой колонки (`String`, `Utf8`); подходит для поиска подстрок и шаблонов `LIKE` в [колоночных таблицах](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#column-oriented-table). ### Локальные блум-индексы {#row-vs-column} Тип `bloom_filter` поддерживается как в [строковых](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#row-oriented-table) (OLTP), так и в [колоночных](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#column-oriented-table) (OLAP) таблицах, но реализация различается: * В строковых таблицах фильтр строится как префиксный фильтр Блума по левому префиксу [первичного ключа](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#primary-key). Индексируемые колонки должны образовывать непрерывное ведущее подмножество колонок первичного ключа. Это ускоряет точечные чтения и сканы по диапазону, ограничивающие ведущие колонки ключа. Для создания префиксного фильтра Блума используйте [ALTER TABLE ... ADD INDEX](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#local-bloom), для удаления — [ALTER TABLE ... DROP INDEX](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#drop-index). * В колоночных таблицах фильтр строится по значениям индексируемой колонки в каждом фрагменте данных (порции). Он применяется при аналитических сканах для пропуска фрагментов, не содержащих искомое значение. Тип `bloom_ngram_filter` поддерживается только в колоночных таблицах. ## Параметры и значения по умолчанию {#parameters} Полный перечень параметров `WITH (...)` и значений по умолчанию: * `bloom_filter` * `false_positive_probability` — целевая [вероятность ложноположительного срабатывания](https://ru.wikipedia.org/wiki/Фильтр_Блума#Вероятность_ложных_срабатываний) фильтра: доля фрагментов, которые фильтр не отсечёт, хотя искомого значения в них нет (диапазон `(0, 1)`). Меньшее значение уменьшает число лишних чтений, но увеличивает размер индекса. * Если параметр не указан, для [строковых таблиц](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#row-oriented-table) используется `0.0001`, для [колоночных](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#column-oriented-table) — `0.1`. Более строгий порог по умолчанию в строковых таблицах соответствует OLTP-сценарию точечных чтений; в колоночных — аналитическим сканам, где допустим больший компромисс между размером индекса и отсечением фрагментов. * Индексируемые колонки — типы YQL, для которых определено сравнение на равенство, кроме `Yson`, `Json` и `JsonDocument` (см. [операторы сравнения](https://ydb.tech/docs/ru/yql/reference/syntax/expressions.md?version=main#comparison-operators)). В колоночной таблице допускается одна колонка; в строковой — несколько. На строковых таблицах индексируемые колонки должны образовывать левый префикс [первичного ключа](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#primary-key). * `bloom_ngram_filter` (колонки `String`, `Utf8`; только [колоночные таблицы](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#column-oriented-table)) * `ngram_size` — размер n-граммы, целое число от `3` до `8` (по умолчанию `3`). * `false_positive_probability` — целевая [вероятность ложноположительного срабатывания](https://ru.wikipedia.org/wiki/Фильтр_Блума#Вероятность_ложных_срабатываний) (диапазон `(0, 1)`; по умолчанию `0.1`). * `case_sensitive` — учёт регистра при построении n-грамм: `true` или `false` (по умолчанию `true`). Синтаксис создания: [CREATE TABLE](https://ydb.tech/docs/ru/yql/reference/syntax/create_table/bloom_skip_index.md?version=main), [ALTER TABLE ADD INDEX](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#local-bloom). Изменение параметров после создания: [ALTER INDEX](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#alter-index). ## Примеры {#examples} Создание таблицы с индексом `bloom_filter`: ```yql CREATE TABLE events ( id Uint64, resource_id Utf8, message Utf8, PRIMARY KEY (id), INDEX idx_bloom LOCAL USING bloom_filter ON (resource_id) WITH (false_positive_probability = 0.01) ); ``` Добавление `bloom_ngram_filter` к существующей таблице: ```yql ALTER TABLE events ADD INDEX idx_ngram LOCAL USING bloom_ngram_filter ON (message) WITH ( ngram_size = 3, false_positive_probability = 0.01, case_sensitive = true ); ``` Создание строковой (OLTP) таблицы с префиксными фильтрами Блума по префиксам первичного ключа. В строковых таблицах индексируемые колонки должны образовывать левый префикс первичного ключа: ```yql CREATE TABLE orders ( customer_id Utf8, order_id Utf8, amount Decimal(10,2), PRIMARY KEY (customer_id, order_id), -- Префиксный фильтр Блума по первой колонке ключа INDEX idx_customer LOCAL USING bloom_filter ON (customer_id) WITH (false_positive_probability = 0.001), -- Префиксный фильтр Блума по всему первичному ключу INDEX idx_full_key LOCAL USING bloom_filter ON (customer_id, order_id) ); ``` Изменение параметров: ```yql ALTER TABLE events ALTER INDEX idx_ngram SET ( ngram_size = 4, false_positive_probability = 0.005, case_sensitive = false ); ``` ## Настройка параметров {#tuning} Если после развёртывания индекса запросы всё ещё читают слишком много данных, попробуйте уменьшить `false_positive_probability`. Если индекс занимает слишком много места — попробуйте увеличить его. Значения меняются через [`ALTER INDEX`](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#alter-index), см. [пример](#examples). Рекомендации: * Начните с `false_positive_probability = 0.01`, затем корректируйте по фактическим метрикам чтения и размеру индекса. * `ngram_size` для `bloom_ngram_filter` обычно начинают с `3`; увеличение значения может сделать фильтрацию строже для более длинных подстрок. * Меняйте параметры по одному и сравнивайте результат на одной и той же нагрузке. ## Особенности и ограничения {#limitations} * Индекс всегда [локальный](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#local-index) (`LOCAL`); [глобального](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#secondary-index) варианта нет. * В запросах не используется синтаксис `VIEW ` (в отличие, например, от [полнотекстовых индексов](https://ydb.tech/docs/ru/dev/fulltext-indexes.md?version=main)). * Фильтр применяется при чтении только к тем фрагментам данных, для которых при записи или [слиянии порций](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#compaction) уже сохранён блок индекса, для остальных фрагментов пропуск по этому индексу не выполняется. * На [строковых таблицах](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#row-oriented-table) `bloom_filter` реализован как **префиксный фильтр Блума**: индексируемые колонки должны образовывать левый префикс [первичного ключа](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#primary-key). Фильтр строится по этому префиксу ключа и ускоряет точечные чтения и сканы по диапазону, ограничивающие префикс. Два индекса `bloom_filter` с одинаковой длиной префикса не допускаются. {% note info "Ограничения" %} * Секции `COVER (...)` и дополнительные колонки индекса не поддерживаются. * Для колоночных таблиц индексируемая колонка должна быть одна. Для строковых таблиц допускается несколько индексируемых колонок. * Для строковых таблиц тип индекса `bloom_ngram_filter` не поддерживается. * На строковых таблицах индексируемые колонки `bloom_filter` должны образовывать левый префикс [первичного ключа](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#primary-key). Наборы колонок, не являющиеся префиксом, отклоняются. * На строковых таблицах два индекса `bloom_filter` не могут иметь одинаковую длину префикса (один и тот же набор ведущих колонок первичного ключа). {% endnote %} ## Дополнительные материалы {#see-also} * [Вторичные индексы](https://ydb.tech/docs/ru/dev/secondary-indexes.md?version=main) * [Справочник YQL: CREATE TABLE](https://ydb.tech/docs/ru/yql/reference/syntax/create_table/bloom_skip_index.md?version=main) * [Справочник YQL: SELECT](https://ydb.tech/docs/ru/yql/reference/syntax/select/index.md?version=main) * [Справочник YQL: ALTER TABLE](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#local-bloom) * [Быстрый старт](https://ydb.tech/docs/ru/recipes/bloom-skip-indexes/bloom-skip-index-quickstart.md?version=main)