Comments

The configuration file supports comments, with # character used as start comment section. The comment character can be present at the start of the line or inline.

Extra care should be considered when using # in character tokenization settings as everything after it will not be taken into consideration. To avoid this, use # UTF-8 which is U+23.

# can also be escaped using \. Escaping is required if # is present in database credential in source declarations.

Inheritance of index and source declarations

Both index and source declarations support inheritance. It allows a better organization of tables having similar settings or structure and reduces the size of the configuration.

For a parent table/source nothing needs to be specified.

For the child table/source the declaration will contain the table/source name followed by : and the parent name.

  1. table parent {
  2. path = /var/lib/manticore/parent
  3. ...
  4. }
  6. table child:parent {
  7. path = /var/lib/manticore/child
  8. ...
  9. }

The child will inherit the entire configuration of the parent. In the child declaration any setting declared will overwrite the inherited values. Please note that in case of multi-value settings, defining a single value in child will clear out all inherited values. For example in the parent there are several sql_query_pre declaration and the child has a single sql_query_pre declaration, all the sql_query_pre inherited declarations are cleared. If you need to override some of the inherited values from parent, they need to be explicitly declared in the child. This is also available if you don’t need a value from parent. For example if the value of sql_query_pre from parent is not needed, then in the child you can declare the directive with an empty value like sql_query_pre=. This also means that existing values of a multi-value setting will not be copied if the child declares one value for that setting. The inheritance behavior applies to fields and attributes and not just table options. If, for example, the parent has 2 integer attributes and the child needs a new integer attribute, the integer attributes declaration from parent must be copied in the child configuration.

Setting variables online

SET

  1. SET [GLOBAL] server_variable_name = value
  2. SET [INDEX index_name] GLOBAL @user_variable_name = (int_val1 [, int_val2, ...])
  3. SET NAMES value [COLLATE value]
  4. SET @@dummy_variable = ignored_value

SET statement modifies a variable value. The variable names are case-insensitive. No variable value changes survive server restart.

SET NAMES statement and SET @@variable_name syntax, both introduced do nothing. They were implemented to maintain compatibility with 3rd party MySQL client libraries, connectors, and frameworks that may need to run this statement when connecting.

There are the following classes of the variables:

  1. per-session server variable: set var_name = value
  2. global server variable: set global var_name = value
  3. global user variable: set global @var_name = (value)
  4. global distributed variable: set index dist_index_name global @var_name = (value)

Global user variables are shared between concurrent sessions. Currently, the only supported value type is the list of BIGINTs, and these variables can only be used along with IN() for filtering purpose. The intended usage scenario is uploading huge lists of values to searchd (once) and reusing them (many times) later, saving on network overheads. Global user variables might be either transferred to all agents of distributed table or set locally in case of local table defined at distributed table. Example:

  1. // in session 1
  2. mysql> SET GLOBAL @myfilter=(2,3,5,7,11,13);
  3. Query OK, 0 rows affected (0.00 sec)
  5. // later in session 2
  6. mysql> SELECT * FROM test1 WHERE group_id IN @myfilter;
  7. +------+--------+----------+------------+-----------------+------+
  8. | id   | weight | group_id | date_added | title           | tag  |
  9. +------+--------+----------+------------+-----------------+------+
  10. |    3 |      1 |        2 | 1299338153 | another doc     | 15   |
  11. |    4 |      1 |        2 | 1299338153 | doc number four | 7,40 |
  12. +------+--------+----------+------------+-----------------+------+
  13. 2 rows in set (0.02 sec)

Per-session and global server variables affect certain server settings in the respective scope. Known per-session server variables are:

  • AUTOCOMMIT = {0 | 1} Whether any data modification statement should be implicitly wrapped by BEGIN and COMMIT.
  • COLLATION_CONNECTION = collation_name Selects the collation to be used for ORDER BY or GROUP BY on string values in the subsequent queries. Refer to Collations for a list of known collation names.
  • CHARACTER_SET_RESULTS = charset_name Does nothing; a placeholder to support frameworks, clients, and connectors that attempt to automatically enforce a charset when connecting to a Manticore server.
  • SQL_AUTO_IS_NULL = value Does nothing; a placeholder to support frameworks, clients, and connectors that attempt to automatically enforce a charset when connecting to a Manticore server.
  • SQL_MODE = <value> Does nothing; a placeholder to support frameworks, clients, and connectors that attempt to automatically enforce a charset when connecting to a Manticore server.
  • WAIT_TIMEOUT = <value> Set connection timeout, either per session or global. Global can only be set on a VIP connection.
  • PROFILING = {0 | 1} Enables query profiling in the current session. Defaults to 0. See also show profile
  • MAX_THREADS_PER_QUERY = <POSITIVE_INT_VALUE> Redefines max_threads_per_query in the runtime. Per-session variable influences only the queries run in the same session (connection), i.e. up to disconnect. Value 0 means ‘no limit’. If both per-session and the global variables are set, the per-session one has a higher priority.
  • ro = {1 | 0} switch session to read-only mode or back. In show variables output the variable displayed with name session_read_only.

Known global server variables are:

  • QUERY_LOG_FORMAT = {plain | sphinxql} Changes the current log format.
  • LOG_LEVEL = {info | debug | replication | debugv | debugvv} Changes the current log verboseness level.
  • QCACHE_MAX_BYTES = <value> Changes the query_cache RAM use limit to a given value.
  • QCACHE_THRESH_MSEC = <value> Changes the query_cache> minimum wall time threshold to a given value.
  • QCACHE_TTL_SEC = <value> Changes the query_cache TTL for a cached result to a given value.
  • MAINTENANCE = {0 | 1} When set to 1, puts the server in maintenance mode. Only clients with vip connections can execute queries in this mode. All new non-vip incoming connections are refused. Existing connections are left intact.
  • GROUPING_IN_UTC = {0 | 1} When set to 1, cause timed grouping functions (day(), month(), year(), yearmonth(), yearmonthday()) to be calculated in utc. Read the doc for grouping_in_utc config params for more details.

  • QUERY_LOG_MIN_MSEC = <value> Changes the query_log_min_msec searchd settings value. In this case it expects value exactly in milliseconds and doesn’t parse time suffixes, as in config.

    Warning: this is very specific and ‘hard’ variable; filtered out messages will be just dropped and not written into the log at all. Better just filter your log with something like ‘grep’, in this case you’ll have at least full original log as backup.

  • LOG_DEBUG_FILTER = <string value> Filters out redundant log messages. If the value is set, then all logs with level > INFO (i.e., DEBUG, DEBUGV, etc.) will be compared with the string and output only in the case they starts with given value.

  • MAX_THREADS_PER_QUERY = <POSITIVE_INT_VALUE> Redefines max_threads_per_query in the runtime. As global it changes behaviour for all sessions. Value 0 means ‘no limit’. If both per-session and the global variables are set, the per-session one has a higher priority.
  • NET_WAIT = {-1 | 0 | POSITIVE_INT_VALUE} Changes the net_wait_tm searchd settings value.
  • IOSTATS = {0 | 1} Enable or disable I/O operations (except for attributes) reporting in query log.
  • CPUSTATS= {1|0} Turns on/off cpu time tracking.
  • COREDUMP= {1|0} Turns on/off saving a core file or a minidump of the server on crash. More details here.
  • PSEUDO_SHARDING = {1|0} Turns on/off search pseudo-sharding.
  • SECONDARY_INDEXES = {1|0} Turns on/off secondary indexes for search queries.
  • ES_COMPAT = {on/off/dashboards} When set to on (default) Elasticsearch-like write requests are supported, off disables the support, and dashboards enables the support, but also enables support for requests from Kibana (this functionality is experimental).

Examples:

  1. mysql> SET autocommit=0;
  2. Query OK, 0 rows affected (0.00 sec)
  4. mysql> SET GLOBAL query_log_format=sphinxql;
  5. Query OK, 0 rows affected (0.00 sec)
  7. mysql> SET GLOBAL @banned=(1,2,3);
  8. Query OK, 0 rows affected (0.01 sec)
  10. mysql> SET INDEX users GLOBAL @banned=(1,2,3);
  11. Query OK, 0 rows affected (0.01 sec)

To make user variables persistent make sure sphinxql_state is enabled.