Определение источника должно содержать настройки подключения, включая хост, порт, учетные данные пользователя или специфичные настройки драйвера.

Хост сервера базы данных для подключения. Обратите внимание, что клиентская библиотека MySQL выбирает, подключаться через TCP/IP или через UNIX-сокет, на основе имени хоста. В частности, "localhost" заставит использовать UNIX-сокет (это режим по умолчанию и, как правило, рекомендуемый), а "127.0.0.1" заставит использовать TCP/IP.

IP-порт сервера для подключения. Для mysql по умолчанию используется 3306, а для pgsql — 5432.

База данных SQL, которую следует использовать после установления соединения и в рамках которой выполнять дальнейшие запросы.

Имя пользователя, используемое для подключения.

Пароль пользователя, используемый при подключении. Если пароль содержит символ # (который можно использовать для добавления комментариев в файле конфигурации), его можно экранировать с помощью \.

Имя UNIX-сокета для подключения к локальным серверам баз данных. Обратите внимание, что фактическое использование этого значения зависит от настройки sql_host.

sql_sock = /var/lib/mysql/mysql.sock

Флаги подключения клиента MySQL. Необязательный параметр, значение по умолчанию — 0 (не устанавливать никаких флагов).

Этот параметр должен содержать целочисленное значение, представляющее сумму флагов. Значение будет передано в mysql_real_connect() как есть. Флаги перечислены в include-файле mysql_com.h. Флаги, представляющие особый интерес с точки зрения индексации, с их соответствующими значениями, следующие:

• CLIENT_COMPRESS = 32; может использовать протокол сжатия
• CLIENT_SSL = 2048; переключиться на SSL после рукопожатия
• CLIENT_SECURE_CONNECTION = 32768; новая аутентификация 4.1 Например, можно указать 2080 (2048+32) для использования как сжатия, так и SSL, или 32768 для использования только новой аутентификации. Изначально эта опция была введена, чтобы иметь возможность использовать сжатие, когда индексатор и mysqld находятся на разных хостах. Сжатие на каналах 1 Гбит/с, скорее всего, увеличит время индексации, хотя и уменьшает сетевой трафик, как в теории, так и на практике. Однако включение сжатия на каналах 100 Мбит/с может значительно улучшить время индексации (сообщалось об улучшении до 20-30% от общего времени индексации). Ваши результаты могут отличаться.

mysql_connect_flags = 32 # enable compression

• mysql_ssl_cert — путь к SSL-сертификату
• mysql_ssl_key — путь к файлу SSL-ключа
• mysql_ssl_ca — путь к сертификату CA

unpack_mysqlcompress_maxsize = 1M

Столбцы для распаковки с использованием алгоритма MySQL UNCOMPRESS(). Множественное значение, необязательный параметр, значение по умолчанию — пустой список столбцов.

Столбцы, указанные с помощью этой директивы, будут распакованы индексатором с использованием модифицированного алгоритма zlib, который используется функциями MySQL COMPRESS() и UNCOMPRESS(). При индексации на машине, отличной от базы данных, это позволяет разгрузить базу данных и сэкономить сетевой трафик. Эта функция доступна только если zlib и zlib-devel были доступны во время сборки.

unpack_mysqlcompress = body_compressed
unpack_mysqlcompress = description_compressed

По умолчанию для распаковки данных используется буфер размером 16 МБ. Это можно изменить, установив параметр unpack_mysqlcompress_maxsize.

При использовании unpack_mysqlcompress, из-за особенностей реализации, невозможно определить требуемый размер буфера из сжатых данных. Поэтому буфер должен быть предварительно выделен, и распакованные данные не могут превысить размер буфера.

unpack_zlib = col1
unpack_zlib = col2

Столбцы для распаковки с использованием zlib (также известного как deflate, gunzip). Множественное значение, необязательный параметр, значение по умолчанию — пустой список столбцов. Применяется только к типам источников mysql и pgsql.

Столбцы, указанные с помощью этой директивы, будут распакованы indexer с использованием стандартного алгоритма zlib (называемого deflate и также реализованного в gunzip). При индексации на машине, отличной от базы данных, это позволяет разгрузить базу данных и сэкономить сетевой трафик. Эта функция доступна только если zlib и zlib-devel были доступны во время сборки.

Флаг аутентификации Windows для MS SQL. Определяет, использовать ли учетные данные текущей учетной записи Windows для аутентификации при подключении к MS SQL Server.

mssql_winauth = 1

Источники, использующие ODBC, требуют наличия строки DSN (Data Source Name, имя источника данных), которую можно задать с помощью odbc_dsn.

odbc_dsn = Driver={Oracle ODBC Driver};Dbq=myDBName;Uid=myUsername;Pwd=myPassword

Обратите внимание, что формат зависит от используемого конкретного драйвера ODBC.

Для всех SQL-драйверов построение простой таблицы, как правило, происходит следующим образом.

• Устанавливается соединение с базой данных.
• Выполняются запросы sql_query_pre_all для выполнения необходимой начальной настройки, например, установки кодировки на соединение в MySQL. Эти запросы выполняются до всего процесса индексирования, а также после переподключения для индексирования атрибутов MVA и связанных полей.
• Выполняется предварительный запрос sql_query_pre для выполнения необходимой начальной настройки, например, создания временных таблиц или ведения счетчиков. Эти запросы выполняются один раз за весь процесс индексирования.
• Выполняется предварительный запрос sql_query_pre для выполнения необходимой начальной настройки, например, создания временных таблиц или ведения счетчиков. Эти запросы выполняются один раз за весь процесс индексирования.
• Выполняется основной запрос sql_query, результаты которого обрабатываются.
• Выполняется пост-запрос sql_query_post для выполнения необходимой очистки.
• Соединение с базой данных закрывается.
• Индексатор выполняет фазу сортировки (точнее говоря, специфическую для типа таблицы постобработку).
• Соединение с базой данных устанавливается снова.
• Выполняется запрос постобработки sql_query_post_index для выполнения необходимой окончательной очистки.
• Соединение с базой данных снова закрывается.

Пример источника, выбирающего данные из MYSQL:

source mysource {
  type             = mysql
  path             = /path/to/realtime
  sql_host         = localhost
  sql_user         = myuser
  sql_pass         = mypass
  sql_db           = mydb
  sql_query_pre    = SET CHARACTER_SET_RESULTS=utf8
  sql_query_pre    = SET NAMES utf8
  sql_query        =  SELECT id, title, description, category_id  FROM mytable
  sql_query_post   = DROP TABLE view_table
  sql_query_post_index = REPLACE INTO counters ( id, val ) \
    VALUES ( 'max_indexed_id', $maxid )
  sql_attr_uint    = category_id
  sql_field_string = title
 }
table mytable {
  type   = plain
  source = mysource
  path   = /path/to/mytable
  ...
 }

Это запрос, используемый для извлечения документов из SQL-сервера. Может быть объявлен только один sql_query, и его наличие обязательно. См. также Обработка полученных данных

Предварительный запрос выборки или pre-query. Это настройка с множественным значением, необязательная, по умолчанию – пустой список запросов. Предварительные запросы выполняются перед sql_query в том порядке, в каком они указаны в конфигурационном файле. Результаты предварительных запросов игнорируются.

Предварительные запросы полезны во многих случаях. Они могут использоваться для установки кодировки, отметки записей, которые будут индексированы, обновления внутренних счетчиков, установки различных параметров и переменных SQL-сервера, связанных с соединением, и так далее.

Вероятно, наиболее частое использование предварительного запроса – указание кодировки, которую сервер будет использовать для возвращаемых строк. Обратите внимание, что Manticore принимает только текст в кодировке UTF-8. Два специфических для MySQL примера установки кодировки:

sql_query_pre = SET CHARACTER_SET_RESULTS=utf8
sql_query_pre = SET NAMES utf8

Также, специфично для источников MySQL, полезно отключить кэш запросов (только для соединения индексатора) в предварительном запросе, поскольку индексационные запросы все равно часто не будут выполняться повторно, и нет смысла кэшировать их результаты. Это может быть сделано так:

sql_query_pre = SET SESSION query_cache_type=OFF

Пост-запрос выборки. Эта настройка необязательна, значение по умолчанию – пустое.

Этот запрос выполняется сразу после успешного завершения sql_query. Если при выполнении пост-запроса возникают ошибки, они регистрируются как предупреждения, но индексирование не прерывается. Его результирующий набор игнорируется. Обратите внимание, что в момент выполнения этого запроса индексирование еще не завершено, и оно все еще может завершиться ошибкой. Поэтому из этого запроса не следует выполнять постоянные обновления. Например, обновления вспомогательной таблицы, которые перманентно изменяют последний успешно индексированный ID, не должны выполняться из sql_query_post; вместо этого они должны выполняться из запроса sql_query_post_index.

Запрос постобработки. Эта настройка необязательна, значение по умолчанию – пустое.

Этот запрос выполняется, когда индексирование полностью и успешно завершено. Если этот запрос вызывает ошибки, они регистрируются как предупреждения, но индексирование не прерывается. Его результирующий набор игнорируется. В тексте запроса можно использовать макрос $maxid; он будет расширен до максимального ID документа, который был фактически извлечен из базы данных во время индексирования. Если документы не индексировались, $maxid будет расширен до 0.

Пример:

sql_query_post_index = REPLACE INTO counters ( id, val ) \
    VALUES ( 'max_indexed_id', $maxid )

Разница между sql_query_post и sql_query_post_index в том, что sql_query_post выполняется сразу после получения Manticore всех документов, однако индексирование все еще может завершиться неудачей по другой причине. Напротив, к моменту выполнения sql_query_post_index гарантируется, что таблица была успешно создана. Соединение с базой данных разрывается и устанавливается заново, поскольку фаза сортировки может быть очень долгой и в противном случае просто прервется по тайм-ауту.

По умолчанию, первый столбец из результирующего набора sql_query индексируется как идентификатор документа.

Идентификатор документа ДОЛЖЕН быть самым первым полем, и он ДОЛЖЕН БЫТЬ УНИКАЛЬНЫМ ЗНАКОВЫМ (НЕНУЛЕВЫМ) ЦЕЛЫМ ЧИСЛОМ в диапазоне от -9223372036854775808 до 9223372036854775807.

Вы можете указать до 256 полнотекстовых полей и произвольное количество атрибутов. Все столбцы, которые не являются ни идентификатором документа (первым), ни атрибутами, будут проиндексированы как полнотекстовые поля.

Объявляет 64-битное знаковое целое число.

Объявляет булевый атрибут. Эквивалентен целочисленному атрибуту с размером в 1 бит.

Объявляет атрибут с плавающей точкой.

Значения будут храниться в формате одинарной точности, 32-битном IEEE 754. Представленный диапазон составляет приблизительно от 1e-38 до 1e+38. Количество десятичных цифр, которые могут быть точно сохранены, составляет приблизительно 7.

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

Объявляет JSON-атрибут.

При индексации JSON-атрибутов Manticore ожидает текстовое поле с данными в формате JSON. JSON-атрибуты поддерживают произвольные JSON-данные без ограничений на уровень вложенности или типы.

Объявляет многозначный атрибут (MVA).

Обычные атрибуты позволяют прикреплять только 1 значение к каждому документу. Однако бывают случаи (например, теги или категории), когда желательно прикрепить несколько значений одного и того же атрибута и иметь возможность применять фильтрацию или группировку к спискам значений.

MVA может получать значения из столбца (как и остальные типы данных) — в этом случае столбец в результирующем наборе должен предоставлять строку с несколькими целыми значениями, разделенными запятыми — или путем выполнения отдельного запроса для получения значений.

При выполнении запроса движок запускает запрос, группирует результаты по ID и присваивает значения соответствующим документам в таблице. Значения с ID, не найденным в таблице, отбрасываются. Перед выполнением запроса будут выполнены все определенные sql_query_pre_all.

Формат объявления для sql_attr_multi следующий:

sql_attr_multi = ATTR-TYPE ATTR-NAME 'from' SOURCE-TYPE \
    [;QUERY] \
    [;RANGED-QUERY]

где

• ATTR-TYPE — это uint, bigint или timestamp.
• SOURCE-TYPE — это field, query, ranged-query или ranged-main-query.
• QUERY — это необязательный SQL-запрос, используемый для получения всех пар (docid, attrvalue).
• RANGED-QUERY — это необязательный SQL-запрос, используемый для получения минимального и максимального значений ID, аналогично sql_query_range.
• Обратные слеши включены только для ясности; все также можно объявить в одной строке.

Используется с SOURCE-TYPE типа ranged-query. Если используется SOURCE-TYPE ranged-main-query, то опустите RANGED-QUERY, и он автоматически будет использовать тот же запрос из sql_query_range (полезная опция в сложных настройках наследования, чтобы избежать многократного ручного дублирования одного и того же запроса).

sql_attr_multi = uint tag from field
sql_attr_multi = uint tag from query; SELECT id, tag FROM tags
sql_attr_multi = bigint tag from ranged-query; \
    SELECT id, tag FROM tags WHERE id>=$start AND id<=$end; \
    SELECT MIN(id), MAX(id) FROM tags

Объявляет строковый атрибут. Максимальный размер каждого значения фиксирован и составляет 4 ГБ.

Объявляет временную метку UNIX.

Временные метки могут хранить даты и время в диапазоне от 1 января 1970 года до 19 января 2038 года с точностью до секунды. Ожидаемое значение столбца должно быть временной меткой в формате UNIX, то есть 32-битным беззнаковым целым числом секунд, прошедших с полуночи 1 января 1970 года по GMT. Временные метки внутренне хранятся и обрабатываются как целые числа везде. Помимо работы с временными метками как с целыми числами, вы также можете использовать их с различными функциями, основанными на датах, такими как режим сортировки по временным сегментам или извлечение дня/недели/месяца/года для GROUP BY.

Обратите внимание, что типы столбцов DATE или DATETIME в MySQL не могут быть напрямую использованы в качестве атрибутов временной метки в Manticore; вам нужно явно преобразовать такие столбцы с помощью функции UNIX_TIMESTAMP (если данные находятся в диапазоне).

Обратите внимание, что временные метки не могут представлять даты до 1 января 1970 года, и UNIX_TIMESTAMP() в MySQL не вернет ничего ожидаемого. Если вам нужно работать только с датами, а не со временем, рассмотрите функцию TO_DAYS() в MySQL.

Объявляет беззнаковый целочисленный атрибут.

Вы можете указать количество бит для целочисленных атрибутов, добавив ':BITCOUNT' к имени атрибута (см. пример ниже). Атрибуты с размером меньше стандартного 32-битного, или битовые поля, работают медленнее.

sql_attr_uint = group_id
sql_attr_uint = forum_id:9 # 9 bits for forum_id

Объявляет комбинированное строковое поле/атрибут. Значения будут проиндексированы как полнотекстовое поле, но также сохранены в строковом атрибуте с тем же именем. Обратите внимание, что это следует использовать только тогда, когда вы уверены, что хотите, чтобы поле было доступно для поиска как в полнотекстовом режиме, так и в качестве атрибута (с возможностью сортировки и группировки по нему). Если вы просто хотите иметь возможность получить исходное значение поля, вам не нужно ничего для этого делать, если вы явно не удалили поле из списка хранимых полей через stored_fields.

sql_field_string = name

Объявляет поле на основе файла.

Эта директива заставляет индексатор интерпретировать содержимое поля как имя файла, загружать и обрабатывать указанный файл. Файлы размером больше max_file_field_buffer пропускаются. Любые ошибки во время загрузки файла (ошибки ввода-вывода, превышение лимитов и т.д.) будут сообщены как предупреждения индексации и не приведут к досрочному завершению индексации. Для таких файлов контент индексироваться не будет.

sql_file_field = field_name

Запрос на получение присоединенного/полезного поля. Многозначный, необязательный, по умолчанию — пустой список запросов.

sql_joined_field позволяет использовать две различные функции: присоединенные поля и полезные данные (поля с полезной нагрузкой). Его синтаксис следующий:

sql_joined_field = FIELD-NAME 'from'  ( 'query' | 'payload-query' | 'ranged-query' | 'ranged-main-query' ); \
        QUERY [ ; RANGE-QUERY ]

где

• FIELD-NAME — это имя присоединенного/полезного поля
• QUERY — это SQL-запрос, который должен получить значения для дальнейшей обработки
• RANGE-QUERY — это необязательный SQL-запрос, который получает диапазон значений для обработки

Joined fields позволяют избежать использования операторов JOIN и/или GROUP_CONCAT в основном запросе выбора документов (sql_query). Это может быть полезно, когда JOIN на стороне SQL медленный, или его нужно выполнить на стороне Manticore, либо просто для имитации специфичной для MySQL функции GROUP_CONCAT, если ваш сервер базы данных её не поддерживает.

Запрос должен возвращать ровно 2 столбца: ID документа и текст, который нужно добавить к объединённому полю. ID документов могут повторяться, но должны идти в порядке возрастания. Все текстовые строки, полученные для данного ID, будут конкатенированы вместе, и результат конкатенации будет индексироваться как полное содержимое объединённого поля. Строки будут конкатенированы в том порядке, в котором они возвращаются запросом, между ними будет вставлен пробел для разделения. Например, если запрос для объединённого поля возвращает следующие строки:

( 1, 'red' )
( 1, 'right' )
( 1, 'hand' )
( 2, 'mysql' )
( 2, 'manticore' )

то результат индексирования будет эквивалентен добавлению нового текстового поля со значением 'red right hand' для документа 1 и 'mysql sphinx' для документа 2, включая позиции ключевых слов внутри поля в порядке их поступления из запроса. Если строки должны идти в определённом порядке, это должно быть явно определено в запросе.

Объединённые поля индексируются только иначе. Других отличий между объединёнными полями и обычными текстовыми полями нет.

Перед выполнением запроса объединённых полей будут выполнены любые заданные наборы sql_query_pre_all, если они существуют. Это позволяет установить нужную кодировку и прочие параметры в контексте объединённых полей.

Когда один запрос недостаточно эффективен или не работает из-за ограничений драйвера базы данных, можно использовать запросы на диапазоне. Они работают аналогично запросам на диапазоне в основном цикле индексирования. Диапазон будет запрошен и получен заранее один раз, затем будет выполнено несколько запросов с разными подстановками $start и $end для извлечения фактических данных.

При использовании запроса ranged-main-query опустите ranged-query, и будет автоматически использован тот же запрос, что и в sql_query_range (удобная опция в сложных схемах наследования, чтобы не дублировать один и тот же запрос множество раз вручную).

source min {
    type = mysql
    sql_host = localhost
    sql_user = test
    sql_pass =
    sql_db = test
    sql_query = select 1, 'Nike bag' f \
    UNION select 2, 'Adidas bag' f \
    UNION select 3, 'Reebok bag' f \
    UNION select 4, 'Nike belt' f
    sql_joined_field = tag from payload-query; select 1 id, 'nike' tag, 10 weight \
    UNION select 4 id, 'nike' tag, 10 weight;
}
index idx {
    path = idx
    source = min
}

mysql> select * from idx;
+------+------------+------+
| id   | f          | tag  |
+------+------------+------+
|    1 | Nike bag   | nike |
|    2 | Adidas bag |      |
|    3 | Reebok bag |      |
|    4 | Nike belt  | nike |
+------+------------+------+
4 rows in set (0.00 sec)

mysql> select *, weight() from idx where match('nike|adidas');
+------+------------+------+----------+
| id   | f          | tag  | weight() |
+------+------------+------+----------+
|    1 | Nike bag   | nike |    11539 |
|    4 | Nike belt  | nike |    11539 |
|    2 | Adidas bag |      |     1597 |
+------+------------+------+----------+
3 rows in set (0.01 sec)

mysql> select *, weight() from idx where match('"nike bag"|"adidas bag"');
+------+------------+------+----------+
| id   | f          | tag  | weight() |
+------+------------+------+----------+
|    2 | Adidas bag |      |     2565 |
|    1 | Nike bag   | nike |     2507 |
+------+------------+------+----------+
2 rows in set (0.00 sec)

sql_column_buffers = <colname>=<size>[K|M] [, ...]

Размеры буферов для отдельных столбцов. Необязательно, по умолчанию пусто (размеры определяются автоматически). Применяется только к источникам odbc и mssql.

Драйверы ODBC и MS SQL иногда не могут вернуть максимально возможный реальный размер столбца. Например, столбцы NVARCHAR(MAX) всегда сообщают длину 2147483647 байт для indexer, хотя фактическая используемая длина скорее всего значительно меньше. Однако при этом буферы приема всё равно должны быть выделены заранее, и их размер нужно определить. Если драйвер вообще не сообщает длину столбца, Manticore выделяет по умолчанию буферы размером 1 КБ для каждого несимвольного столбца и 1 МБ для каждого символьного столбца. Сообщённая драйвером длина столбца также ограничивается максимальным размером 8 МБ, таким образом, если драйвер сообщает (почти) 2 ГБ длины, она будет усечена — вместо этого будет выделен буфер 8 МБ для данного столбца. Эти жёстко заданные пределы можно переопределить с помощью директивы sql_column_buffers, чтобы либо сэкономить память на фактически более коротких столбцах, либо преодолеть 8 МБ лимит для действительно более длинных столбцов. Значения директивы должны быть списком, разделённым запятыми, из выбранных имён столбцов и размеров:

Пример:

sql_query = SELECT id, mytitle, mycontent FROM documents
sql_column_buffers = mytitle=64K, mycontent=10M

Основной запрос, который должен извлечь все документы, может наложить блокировку чтения на всю таблицу и задержать параллельные запросы (например, INSERTы в таблицу MyISAM), расходовать много памяти на результирующий набор и т.д. Чтобы избежать этого, Manticore поддерживает так называемые диапазонные запросы. С помощью диапазонных запросов Manticore сначала получает минимальные и максимальные ID документов из таблицы, а затем подставляет различные интервалы ID в основной текст запроса и выполняет модифицированный запрос для извлечения другой части документов. Вот пример.

Пример использования диапазонного запроса:

sql_query_range = SELECT MIN(id),MAX(id) FROM documents
sql_range_step = 1000
sql_query = SELECT * FROM documents WHERE id>=$start AND id<=$end

Если таблица содержит ID документов от 1 до, скажем, 2345, то sql_query будет выполнен три раза:

1. с заменой $start на 1 и $end на 1000;
2. с заменой $start на 1001 и $end на 2000;
3. с заменой $start на 2001 и $end на 2345.

Очевидно, что для таблицы из 2000 строк это не особо большая разница, но при индексации таблицы с 10 миллионами строк диапазонные запросы могут оказаться полезными.

Определяет диапазонный запрос. Запрос, указанный в этой опции, должен получить минимальные и максимальные ID документов, которые будут использоваться в качестве границ диапазона. Он должен возвращать ровно два целочисленных поля: сначала min ID, потом max ID; имена полей игнорируются. При включении данной опции sql_query должен содержать макросы $start и $end. Обратите внимание, что интервалы, указанные как $start..$end, не будут пересекаться, поэтому вам не следует исключать из запроса документы, ID которых точно равен $start или $end.

Этот параметр задает шаг диапазонного запроса. Значение по умолчанию — 1024.

Эта директива может использоваться для ограничения скорости диапазонного запроса. По умолчанию ограничений нет. Значения для sql_ranged_throttle указываются в миллисекундах.

Ограничение скорости может быть полезно, когда индексатор создаёт слишком большую нагрузку на сервер баз данных. Оно заставляет индексатор приостанавливаться на заданное время один раз за каждый шаг диапазонного запроса. Эта пауза выполняется безусловно и происходит до выполнения запроса на выборку.

sql_ranged_throttle = 1000 # sleep for 1 sec before each query step