# Миграция с Sphinx Search

## Sphinx 2.x -> Manticore 2.x
Manticore Search 2.x поддерживает совместимость с Sphinxsearch 2.x и может загружать существующие таблицы, созданные Sphinxsearch. В большинстве случаев обновление сводится к замене бинарных файлов.

Вместо sphinx.conf (на Linux обычно находится в `/etc/sphinxsearch/sphinx.conf`) Manticore по умолчанию использует `/etc/manticoresearch/manticore.conf`. Также он запускается под другим пользователем и использует другие папки.

Название службы systemd изменилось с `sphinx/sphinxsearch` на `manticore`, и служба запускается под пользователем `manticore` (Sphinx использовал `sphinx` или `sphinxsearch`). Также используется другая папка для файла PID.

Папки, используемые по умолчанию: `/var/lib/manticore`, `/var/log/manticore`, `/var/run/manticore`. Вы все еще можете использовать существующую конфигурацию Sphinx, но необходимо вручную изменить права доступа к папкам `/var/lib/sphinxsearch` и `/var/log/sphinxsearch`. Или просто глобально переименовать 'sphinx' в 'manticore' в системных файлах. Если вы используете другие папки (для данных, файлов wordforms и т.п.), владение ими также должно быть изменено на пользователя `manticore`. Путь к `pid_file` следует изменить в соответствии с manticore.service на `/run/manticore/searchd.pid`.

Если вы хотите использовать папку Manticore вместо этого, файлы таблиц должны быть перемещены в новую папку данных (`/var/lib/manticore`), и права доступа должны быть изменены на пользователя `manticore`.

## Sphinx 2.x / Manticore 2.x -> Manticore 3.x
Обновление с Sphinx / Manticore 2.x до 3.x не является простой задачей, так как движок хранения таблиц претерпел значительные изменения, и новый searchd не может загрузить старые таблицы и автоматически обновить их до нового формата.

Manticore Search 3 получил переработанный движок хранения таблиц. Таблицы, созданные в Manticore/Sphinx 2.x, не могут быть загружены Manticore Search 3 без [конвертации](../Installation/Migration_from_Sphinx.md#index_converter). Из-за ограничения в 4GB в версии 2.x real-time таблица могла иметь несколько дисковых кусков после операции оптимизации. После обновления до 3.x эти таблицы теперь могут быть оптимизированы до одного дискового куска с помощью обычной команды [OPTIMIZE](../Securing_and_compacting_a_table/Compacting_a_table.md#OPTIMIZE-TABLE). Также изменились файлы индексов. Единственный компонент, который не претерпел структурных изменений — это файл `.spp` (списки попаданий). `.sps` (строки/json) и `.spm` (MVA) теперь содержатся в `.spb` (атрибуты переменной длины). В новом формате присутствует файл `.spm`, но он используется для карты строк (ранее он предназначался для MVA атрибутов). Добавлены новые расширения — `.spt` (поиск docid), `.sphi` (гистограммы вторичных индексов), `.spds` (хранение документов). Если вы используете скрипты, которые манипулируют файлами таблиц, их следует адаптировать под новые расширения файлов.

Процедура обновления может отличаться в зависимости от вашей конфигурации (количество серверов в кластере, наличие высокой доступности и т.п.), но в целом она включает создание новых версий таблиц 3.x и замену существующих, а также замену старых бинарных файлов 2.x на новые.

Есть два специальных требования:

* Real-time таблицы необходимо сбросить с помощью [FLUSH RAMCHUNK](../Securing_and_compacting_a_table/Flushing_RAM_chunk_to_a_new_disk_chunk.md#FLUSH-RAMCHUNK)
* Plain таблицы с kill-листами требуют добавления новой директивы в конфигурацию таблицы (см. [killlist_target](../Creating_a_table/Local_tables/Plain_and_real-time_table_settings.md#killlist_target))

Manticore Search 3 включает новый инструмент - [index_converter](../Installation/Migration_from_Sphinx.md#index_converter) - который может конвертировать таблицы Sphinx 2.x / Manticore 2.x в формат 3.x. `index_converter` поставляется в отдельном пакете, который необходимо установить первым. Используйте tool для выполнения конвертации и создания версий ваших таблиц 3.x. `index_converter` может записывать новые файлы в существующую папку данных и делать резервные копии старых файлов или записывать новые файлы в выбранную папку.

## Базовая инструкция по обновлению

Если у вас один сервер:

* Установите пакет manticore-converter
* Используйте index_converter для создания новых версий таблиц в другой папке, отличной от существующей папки данных (с помощью опции `--output-dir`)
* Остановите существующий Manticore/Sphinx, обновите до 3.0, переместите новые таблицы в папку данных и запустите Manticore

Чтобы свести к минимуму время простоя, вы можете скопировать таблицы 2.x, конфигурацию (вам нужно будет изменить пути для таблиц, логов и портов) и бинарники в отдельное место и запустить это на отдельном порте. Направьте ваше приложение на него. После обновления до 3.0 и запуска нового сервера вы можете переключить приложение обратно на обычные порты. Если все работает корректно, остановите копию 2.x и удалите файлы, чтобы освободить место.

Если у вас есть запасной сервер (например, тестовый или staging сервер), вы можете сначала выполнить обновление таблиц там и даже установить Manticore 3 для проведения нескольких тестов. Если все в порядке, скопируйте новые файлы таблиц на продуктивный сервер. Если у вас несколько серверов, которые можно временно вывести из производства, выполните обновление поочередно на каждом. Для распределенных конфигураций searchd 2.x может работать как мастер с узлами 3.x, поэтому можно сначала обновить узлы данных, а затем мастер-узел.

Изменений в способе подключения клиентов к движку, режиме запросов или поведении запросов не было.

## kill-листы в Sphinx / Manticore 2.x против Manticore 3.x
[Kill-листы](../Data_creation_and_modification/Adding_data_from_external_storages/Adding_data_to_tables/Killlist_in_plain_tables.md) были переработаны в Manticore Search 3. В предыдущих версиях kill-листы применялись к результирующему набору, предоставленному каждой ранее обработанной таблицей во время запроса.

Таким образом, в 2.x порядок таблиц во время выполнения запроса имел значение. Например, если в delta таблице был kill-лист, чтобы применить его к основной таблице, порядок должен был быть основной, а затем delta (либо в распределенной таблице, либо в операторе FROM).

В Manticore 3 kill-листы применяются к таблице при её загрузке во время запуска searchd или при её ротировании. Новая директива `killlist_target` в конфигурации таблицы указывает целевые таблицы и определяет, какие doc id из исходной таблицы должны использоваться для подавления. Это могут быть id из заданного kill-листа, реальные doc id таблицы или и то, и другое.

Документы из kill-листов удаляются из целевых таблиц, они не возвращаются в результатах, даже если поиск не включает таблицу, которая предоставила kill-листы. Поэтому порядок таблиц для поиска теперь не имеет значения. Теперь `delta, main` и `main, delta` дадут одинаковые результаты.

В предыдущих версиях таблицы ротировались в порядке, заданном в конфигурационном файле. В Manticore 3 порядок ротирования таблиц стал гораздо умнее и работает в соответствии с killlist targets. До начала ротирования таблиц сервер ищет цепочки таблиц по определениям `killlist_target`. Затем он сначала ротирует таблицы, на которые нигде не ссылаются как на цели kill-листов. Далее будут ротированы таблицы, целью которых являются уже ротированные таблицы, и так далее. Например, если выполнить `indexer --all` и у нас есть 3 таблицы: main, delta_big (которая направлена на main) и delta_small (с целью delta_big), сначала ротируется delta_small, затем delta_big и в конце main. Это обеспечит, что при ротировании зависимой таблицы она получает самый актуальный kill-лист из других таблиц.

## Ключи конфигурации удалённые в Manticore 3.x
* `docinfo` - теперь всё extern
* `inplace_docinfo_gap` - больше не нужен
* `mva_updates_pool` - MVAs больше не имеют выделенного пула для обновлений, так как теперь они могут обновляться непосредственно в блобе (см. ниже).

## Обновление атрибутов переменной длины в Manticore 3.x
Строковые, JSON и MVA атрибуты можно обновлять в Manticore 3.x с помощью оператора `UPDATE`.

В версии 2.x строковые атрибуты требовали `REPLACE`, для JSON было возможно обновлять только скалярные свойства (так как они были фиксированной длины), а MVAs можно было обновлять с помощью пула MVA. Теперь обновления выполняются непосредственно в компоненте блоба. Одним из настроек, которую, возможно, придётся настраивать, является [attr_update_reserve](../Data_creation_and_modification/Updating_documents/UPDATE.md#attr_update_reserve), которая позволяет изменять выделенное дополнительное пространство в конце блоба, используемое для избежания частого изменения размера в случае, если новые значения больше существующих в блобе.

## Идентификаторы документов в Manticore 3.x и новее
В файловом формате таблиц Manticore 3.x идентификаторы документов ушли от старого беззнакового представления Sphinx 2.x и стали доступны через знаковый интерфейс `bigint` на 64 бита. Текущие версии Manticore поддерживают беззнаковые значения идентификаторов документов на 64 бита и отклоняют отрицательные идентификаторы документов при индексации или вставке. В интерфейсе MySQL/SQL идентификаторы больше `2^63-1` по-прежнему можно отображать и фильтровать по их знаковому представлению; используйте `UINT64(id)`, чтобы увидеть фактическое беззнаковое значение.

## RT режим в Manticore 3.x
Читайте здесь про [RT режим](../Read_this_first.md#Real-time-mode-vs-plain-mode)

## Специальные суффиксы с Manticore 3.x
Manticore 3.x распознаёт и парсит специальные суффиксы, что облегчает использование числовых значений со специальным значением. Общая форма — целое число + литерал, например 10k или 100d, но не 40.3s (потому что 40.3 не целое), или не 2d 4h (потому что это два значения, а не одно). Литералы не чувствительны к регистру, так что 10W это то же, что и 10w. В настоящее время поддерживаются 2 типа таких суффиксов:

* Суффиксы размера — могут использоваться в параметрах, определяющих размер чего-либо (буфер памяти, диск, лимит ОЗУ и т.д.) в байтах. «Голые» числа в таких местах означают буквально размер в байтах (октетах). Суффиксы размера: `k` для килобайт (1k=1024), `m` для мегабайт (1m=1024k), `g` для гигабайт (1g=1024m) и `t` для терабайт (1t=1024g).
* Суффиксы времени — могут использоваться в параметрах, задающих промежутки времени, такие как задержки, тайм-ауты и т.п. «Голые» значения для таких параметров обычно имеют задокументированную шкалу, и надо знать, означает ли число, скажем, 100 «100 секунд» или «100 миллисекунд». Вместо того чтобы гадать, можно просто написать значение с суффиксом, и оно будет однозначно определено по суффиксу. Суффиксы времени: `us` для микросекунд (useconds), `ms` для миллисекунд, `s` для секунд, `m` для минут, `h` для часов, `d` для дней и `w` для недель.

## index_converter

`index_converter` — это инструмент для конвертации таблиц, созданных с помощью Sphinx/Manticore Search 2.x, в формат таблиц Manticore Search 3.x. Инструмент может использоваться несколькими разными способами:

#### Конвертация по одной таблице за раз

```ini
$ index_converter --config /home/myuser/manticore.conf --index tablename
```

#### Конвертация всех таблиц

```ini
$ index_converter --config /home/myuser/manticore.conf --all
```

#### Конвертация таблиц, найденных в папке

```ini
$ index_converter  --path /var/lib/manticoresearch/data --all
```

Новая версия таблицы по умолчанию записывается в ту же папку. Файлы предыдущей версии сохраняются с расширением `.old` в имени. Исключением является файл `.spp` (hitlists), который является единственным компонентом таблицы, не изменившимся в новом формате.

Можно сохранить новую версию таблицы в другую папку с помощью опции `--output-dir`

```ini
$ index_converter --config /home/myuser/manticore.conf --all --output-dir /new/path
```

#### Конвертация kill-листов

Особый случай — таблицы, содержащие kill-листы. Поскольку изменилось поведение kill-листов (см. [killlist_target](../Creating_a_table/Local_tables/Plain_and_real-time_table_settings.md#killlist_target)), дельта-таблица должна знать, какие таблицы являются целевыми для применения kill-листов. Существует 3 способа подготовить конвертированную таблицу для установки целей kill-листов:

* Использовать `--killlist-target` при конвертации таблицы
  ```ini
  $ index_converter --config /home/myuser/manticore.conf --index deltaindex --killlist-target mainindex:kl
  ```
* Добавить killlist_target в конфигурацию перед конвертацией
* Использовать команду [ALTER ... KILLIST_TARGET](../Data_creation_and_modification/Adding_data_from_external_storages/Adding_data_to_tables/Killlist_in_plain_tables.md#killlist_target) после конвертации

#### Полный список опций index_converter

Вот полный список опций `index_converter`:

* `--config <file>` (`-c <file>` сокращенно) указывает index_converter использовать данный файл в качестве конфигурации. Обычно он ищет manticore.conf в каталоге установки (например, `/usr/local/manticore/etc/manticore.conf`, если установлен в `/usr/local/sphinx`), а затем в текущем каталоге, в котором вы находитесь при вызове index_converter из командной оболочки.
* `--index` указывает, какая таблица должна быть конвертирована
* `--path` - вместо использования конфигурационного файла можно указать путь, содержащий таблицу(ы)
* `--strip-path` - удаляет путь из имен файлов, к которым обращаются таблицы: stopwords, exceptions и wordforms
* `--large-docid` - позволяет конвертировать документы с `ids` больше `2^63` и выводит предупреждение; иначе преобразование завершается ошибкой на большом идентификаторе. Эта опция была добавлена для совместимости с форматом Manticore 3.x, поскольку в Sphinx/Manticore 2.x использовались беззнаковые значения `doc id`, которые могли превышать диапазон отображения знакового 64-битного числа.
* `--output-dir <dir>` - записывает новые файлы в выбранную папку вместо того, чтобы сохранять рядом с существующими файлами таблицы. При использовании этой опции существующие файлы таблиц останутся нетронутыми в их исходном расположении.
* `--all` - конвертирует все таблицы из конфигурации
* `--killlist-target <targets>` задает целевые таблицы, к которым будут применяться kill-листы. Эта опция должна использоваться только совместно с параметром `--index`

<!-- proofread -->

