5.3. Server variables — Mroonga vmrn_version documentation

Skip to main content
`Ctrl`+`K`

# 5.3. Server variables

Here are the explanations of server variables that are introduced by Mroonga.

## 5.3.1. `mroonga_action_on_fulltext_query_error`

The default behavior of fulltext query error.

The default value of `mroonga_action_on_fulltext_query_error` is `ERROR_AND_LOG`. This is the conventional behavior which is equal to old version of mroonga.

Here is the list of `mroonga_action_on_fulltext_query_error` which you can use.

Value | Description
--- | ---
ERROR | Report an error. Logging is disabled.
ERROR_AND_LOG | Report an error. Logging is enabled. (This is the default)
IGNORE | Just ignore an error. Logging is disabled.
IGNORE_AND_LOG | Ignore an error, but logging is enabled. (Similar to InnoDB behavior)

Here is an example SQL to confirm the value of `mroonga_action_on_fulltext_query_error`:

    mysql> SHOW VARIABLES LIKE 'mroonga_action_on_fulltext_query_error';
    +----------------------------------------+---------------+
    | Variable_name                          | Value         |
    +----------------------------------------+---------------+
    | mroonga_action_on_fulltext_query_error | ERROR_AND_LOG |
    +----------------------------------------+---------------+
    1 row in set (0.00 sec)

## 5.3.2. `mroonga_boolean_mode_syntax_flags`

The flags to custom syntax in `MATCH () AGAINST ('...' IN BOOLEAN MODE)`.

This variable is system and session variable.

Here are available flags:

Flag | Description
--- | ---
`DEFAULT` | Equals to `SYNTAX_QUERY,ALLOW_LEADING_NOT`.
`SYNTAX_QUERY` | Uses query syntax in Groonga. Query syntax in Groonga is a compatible syntax with MySQL’s BOOLEAM MODE syntax. If neither `SYNTAX_QUERY` nor `SYNTAX_SCRIPT` aren’t specified, `SYNTAX_QUERY` is used.
`SYNTAX_SCRIPT` | Uses script syntax in Groonga. It’s JavaScript like syntax. You can use full Groonga features with this syntax. If both `SYNTAX_QUERY` and `SYNTAX_SCRIPT` are specified, `SYNTAX_SCRIPT` is used.
`ALLOW_COLUMN` | Allows `COLUMN:...` syntax in query syntax. It’s not compatible with MySQL’s BOOLEAM MODE syntax. You can use multiple indexes in one `MATCH () AGAINST ()` with this syntax. MySQL can use only one index in a query. You can avoid the restriction by this syntax. You can use not only full-text search operation but also other more operations such as equal operation and prefix search operation with this syntax. See query syntax in Groonga for details.
`ALLOW_UPDATE` | Allows updating value by `COLUMN:=NEW_VALUE` syntax in query syntax.
`ALLOW_LEADING_NOT` | Allows `-NOT_INCLUDED_KEYWORD ...` syntax in query syntax.

The default flags is `DEFAULT`. It is MySQL’s BOOLEAN MODE compatible syntax.

You can combine flags by separated by comma such as `SYNTAX_QUERY,ALLOW_LEADING_NOT`.

Here is an example SQL to use script syntax in Groonga:

    mysql> SET mroonga_boolean_mode_syntax_flags = "SYNTAX_SCRIPT";

## 5.3.3. `mroonga_database_path_prefix`

TODO:

## 5.3.4. `mroonga_default_parser`

Deprecated since version 5.04: Use mroonga_default_tokenizer instead.

The default parser of the full text search. The default value can be specified by `--with-default-parser=PARSER` configure argument, whose default value is `TokenBigram`.

Here is an example to use `TokenBigramSplitSymbolAlphaDigit` as a fulltext search parser. It is used by `body_index` fulltext index.

    1SET GLOBAL mroonga_default_parser=TokenBigramSplitSymbolAlphaDigit;
    2CREATE TABLE diaries (
    3  id INT PRIMARY KEY AUTO_INCREMENT,
    4  body TEXT,
    5  FULLTEXT INDEX body_index (body)
    6) DEFAULT CHARSET UTF8;

## 5.3.5. `mroonga_default_tokenizer`

Added in version 5.04.

The default tokenizer of the full text search. The default value can be specified by `--with-default-tokenizer=TOKENIZER` configure argument, whose default value is `TokenBigram`.

Here is an example to use `TokenBigramSplitSymbolAlphaDigit` as a fulltext index tokenizer. It is used by `body_index` fulltext index.

    1SET GLOBAL mroonga_default_tokenizer=TokenBigramSplitSymbolAlphaDigit;
    2CREATE TABLE diaries (
    3  id INT PRIMARY KEY AUTO_INCREMENT,
    4  body TEXT,
    5  FULLTEXT INDEX body_index (body)
    6) DEFAULT CHARSET UTF8;

## 5.3.6. `mroonga_default_wrapper_engine`

TODO:

## 5.3.7. `mroonga_dry_write`

Whether really write data to Groonga database or not. The default value is `OFF` that means data are really written to Groonga database. Usually we don’t need to change the value of this variable. This variable is useful for benchmark because we can measure processing time MySQL and Mroonga. It doesn’t include Groonga’s processing time.

Here is an example SQL to disable writing data to Groonga database:

    mysql> SHOW VARIABLES LIKE 'mroonga_dry_write';
    +-------------------+-------+
    | Variable_name     | Value |
    +-------------------+-------+
    | mroonga_dry_write | OFF   |
    +-------------------+-------+
    1 row in set (0.00 sec)

    mysql> SET mroonga_dry_write = true;
    Query OK, 0 rows affected (0.00 sec)

    mysql> SHOW VARIABLES LIKE 'mroonga_dry_write';
    +-------------------+-------+
    | Variable_name     | Value |
    +-------------------+-------+
    | mroonga_dry_write | ON    |
    +-------------------+-------+
    1 row in set (0.00 sec)

## 5.3.8. `mroonga_enable_optimization`

Whether enable optimization or not. The default value is `ON` that means optimization is enabled. Usually we don’t need to change the value of this variable. This variable is useful for benchmark.

Here is an example SQL to disable optimization:

    mysql> SHOW VARIABLES LIKE 'mroonga_enable_optimization';
    +-----------------------------+-------+
    | Variable_name               | Value |
    +-----------------------------+-------+
    | mroonga_enable_optimization | ON    |
    +-----------------------------+-------+
    1 row in set (0.00 sec)

    mysql> SET mroonga_enable_optimization = false;
    Query OK, 0 rows affected (0.00 sec)

    mysql> SHOW VARIABLES LIKE 'mroonga_enable_optimization';
    +-----------------------------+-------+
    | Variable_name               | Value |
    +-----------------------------+-------+
    | mroonga_enable_optimization | OFF   |
    +-----------------------------+-------+
    1 row in set (0.00 sec)

## 5.3.9. `mroonga_libgroonga_support_lz4`

The status of libgroonga supports LZ4.

Here is an example SQL to confirm the status of libgroonga supports LZ4:

    mysql> SHOW GLOBAL VARIABLES LIKE 'mroonga_libgroonga_support_lz4';
    +--------------------------------+-------+
    | Variable_name                  | Value |
    +--------------------------------+-------+
    | mroonga_libgroonga_support_lz4 | ON    |
    +--------------------------------+-------+

## 5.3.10. `mroonga_libgroonga_support_zlib`

The status of libgroonga supports zlib.

Here is an example SQL to confirm the status of libgroonga supports zlib:

    mysql> SHOW GLOBAL VARIABLES LIKE 'mroonga_libgroonga_support_zlib';
    +---------------------------------+-------+
    | Variable_name                   | Value |
    +---------------------------------+-------+
    | mroonga_libgroonga_support_zlib | ON    |
    +---------------------------------+-------+

## 5.3.11. `mroonga_libgroonga_support_zstd`

The status of libgroonga supports Zstandard.

Here is an example SQL to confirm the status of libgroonga supports Zstandard:

    mysql> SHOW GLOBAL VARIABLES LIKE 'mroonga_libgroonga_support_zstd';
    +---------------------------------+-------+
    | Variable_name                   | Value |
    +---------------------------------+-------+
    | mroonga_libgroonga_support_zstd | ON    |
    +---------------------------------+-------+

## 5.3.12. `mroonga_libgroonga_support_mecab`

The status of libgroonga supports MeCab.

Here is an example SQL to confirm the status of libgroonga supports MeCab.

    mysql> SHOW GLOBAL VARIABLES LIKE 'mroonga_libgroonga_support_mecab';
    +----------------------------------+-------+
    | Variable_name                    | Value |
    +----------------------------------+-------+
    | mroonga_libgroonga_support_mecab | ON    |
    +----------------------------------+-------+

## 5.3.13. `mroonga_libgroonga_version`

The version string of the groonga library.

Here is an example SQL to confirm the using groonga library version:

    mysql> SHOW VARIABLES LIKE 'mroonga_libgroonga_version';
    +----------------------------+------------------+
    | Variable_name              | Value            |
    +----------------------------+------------------+
    | mroonga_libgroonga_version | 1.2.8-9-gbf05b82 |
    +----------------------------+------------------+
    1 row in set (0.00 sec)

## 5.3.14. `mroonga_lock_timeout`

TODO:

## 5.3.15. `mroonga_log_file`

The path of the log file of Mroonga. The default value is `groonga.log`.

Here is an example transcript to change log file to `/tmp/mroonga.log`:

    mysql> SHOW VARIABLES LIKE 'mroonga_log_file';
    +------------------+-------------+
    | Variable_name    | Value       |
    +------------------+-------------+
    | mroonga_log_file | groonga.log |
    +------------------+-------------+
    1 row in set (0.00 sec)

    mysql> SET GLOBAL mroonga_log_file = "/tmp/mroonga.log";
    Query OK, 0 rows affected (0.00 sec)

    mysql> SHOW VARIABLES LIKE 'mroonga_log_file';
    +------------------+------------------+
    | Variable_name    | Value            |
    +------------------+------------------+
    | mroonga_log_file | /tmp/mroonga.log |
    +------------------+------------------+
    1 row in set (0.00 sec)

## 5.3.16. `mroonga_log_level`

The output level of Mroonga log file. The default value is `NOTICE`.

Here is the list of `mroonga_log_level` which you can use.

Log level | Description
--- | ---
`NONE` | No logging output.
`EMERG` | Logging emergency messages such as database corruption.
`ALERT` | Logging alert messages such as internal error.
`CRIT` | Logging critical message such as deadlock.
`ERROR` | Logging error messages such as API error which Mroonga use.
`WARNING` | Logging warning messages such as invalid argument.
`NOTICE` | Logging notice messages such as configuration or status changed.
`INFO` | Logging informative messages such as file system operation.
`DEBUG` | Logging debug messages. Recommend to use for Mroonga developer or bug reporter.
`DUMP` | Logging dump messages.

Here is an example transcript to change log level to `DEBUG` that logs many messages for debugging:

    mysql> SHOW VARIABLES LIKE 'mroonga_log_level';
    +-------------------+--------+
    | Variable_name     | Value  |
    +-------------------+--------+
    | mroonga_log_level | NOTICE |
    +-------------------+--------+
    1 row in set (0.00 sec)

    mysql> SET GLOBAL mroonga_log_level = "debug";
    Query OK, 0 rows affected (0.00 sec)

    mysql> SHOW VARIABLES LIKE 'mroonga_log_level';
    +-------------------+-------+
    | Variable_name     | Value |
    +-------------------+-------+
    | mroonga_log_level | DEBUG |
    +-------------------+-------+
    1 row in set (0.00 sec)

## 5.3.17. `mroonga_query_log_file`

The path of the query log file of Mroonga. The default value is empty.

If this value is empty, the query log is not stored to file. If this value is not empty, query log is stored to the specified file.

Here is an example transcript to change query log file to `/tmp/mroonga_query.log`:

    mysql> SHOW VARIABLES LIKE 'mroonga_query_log_file';
    +------------------------+-------+
    | Variable_name          | Value |
    +------------------------+-------+
    | mroonga_query_log_file |       |
    +------------------------+-------+
    1 row in set (0.00 sec)

    mysql> SET GLOBAL mroonga_query_log_file = "/tmp/mroonga.log";
    Query OK, 0 rows affected (0.00 sec)

    mysql> SHOW VARIABLES LIKE 'mroonga_query_log_file';
    +------------------------+------------------+
    | Variable_name          | Value            |
    +------------------------+------------------+
    | mroonga_query_log_file | /tmp/mroonga.log |
    +------------------------+------------------+
    1 row in set (0.00 sec)

## 5.3.18. `mroonga_n_workers`

Added in version 15.00.

Specify the number of Groonga’s internal processing in parallel.

In Mroonga, when parallel processing is enabled, `CREATE INDEX` is processed in parallel, which is expected to speed up the process.

Here is the list of values which you can use. The default value is `0`.

Value | Description
--- | ---
`0` or `1` | Execute in serial.
`2` or more | Execute in parallel with at most the specified number of threads.
`-1` | Execute in parallel with the threads of at most the number of CPU cores.

Here is an example SQL to change the number of parallels to `2`:

    mysql> SHOW VARIABLES LIKE 'mroonga_n_workers';
    +-------------------+-------+
    | Variable_name     | Value |
    +-------------------+-------+
    | mroonga_n_workers | 0     |
    +-------------------+-------+
    1 row in set (0.001 sec)

    mysql> SET GLOBAL mroonga_n_workers = 2;
    Query OK, 0 rows affected (0.000 sec)

    mysql> SHOW VARIABLES LIKE 'mroonga_n_workers';
    +-------------------+-------+
    | Variable_name     | Value |
    +-------------------+-------+
    | mroonga_n_workers | 2     |
    +-------------------+-------+
    1 row in set (0.001 sec)

Only available in `GLOBAL`.

If set with `SET GLOBAL`, it will enable from the next session. Note that this is not enabled for the current session. If you set it persistently, we recommend that you use `my.cnf` to set it.

## 5.3.19. `mroonga_match_escalation_threshold`

The threshold to determin whether match method is escalated. See search specification for Groonga about match method escalation.

The default value is the same as Groonga’s default value. It’s 0 for the default installation. The dafault value can be configured in my.cnf or by `SET GLOBAL mroonga_match_escalation_threshold = THRESHOLD;`. Because this variable’s scope is both global and session.

Here is an example to use -1 as a threshold to determin whether match method is escalated. -1 means that never escalated.

    1SET GLOBAL mroonga_match_escalation_threshold = -1;

Here is an another example to show behavior change by the variable value.

     1CREATE TABLE diaries (
     2  id INT PRIMARY KEY AUTO_INCREMENT,
     3  title TEXT,
     4  tags TEXT,
     5  FULLTEXT INDEX tags_index (tags) COMMENT 'tokenizer "TokenDelimit"'
     6) ENGINE=mroonga DEFAULT CHARSET=UTF8;
     7
     8-- Test data
     9INSERT INTO diaries (title, tags) VALUES ("Hello groonga!", "groonga install");
    10INSERT INTO diaries (title, tags) VALUES ("Hello mroonga!", "mroonga install");
    11
    12-- Matches all records that have "install" tag.
    13SELECT * FROM diaries WHERE MATCH (tags) AGAINST ("install" IN BOOLEAN MODE);
    14-- id        title   tags
    15-- 1 Hello groonga!  groonga install
    16-- 2 Hello mroonga!  mroonga install
    17
    18-- Matches no records by "gr" tag search because no "gr" tag is used.
    19-- But matches a record that has "groonga" tag because search
    20-- method is escalated and prefix search with "gr" is used.
    21-- The default threshold is 0. It means that no records are matched then
    22-- search method is escalated.
    23SELECT * FROM diaries WHERE MATCH (tags) AGAINST ("gr" IN BOOLEAN MODE);
    24-- id        title   tags
    25-- 1 Hello groonga!  groonga install
    26
    27-- Disables escalation.
    28SET mroonga_match_escalation_threshold = -1;
    29-- No records are matched.
    30SELECT * FROM diaries WHERE MATCH (tags) AGAINST ("gr" IN BOOLEAN MODE);
    31-- id        title   tags
    32
    33-- Enables escalation again.
    34SET mroonga_match_escalation_threshold = 0;
    35-- Matches a record by prefix search with "gr".
    36SELECT * FROM diaries WHERE MATCH (tags) AGAINST ("gr" IN BOOLEAN MODE);
    37-- id        title   tags
    38-- 1 Hello groonga!  groonga install

## 5.3.20. `mroonga_max_n_records_for_estimate`

Added in version 5.02.

TODO:

## 5.3.21. `mroonga_enable_operations_recording`

Whether recording operations for recover is enabled or not. The default value is `OFF` that means operations are not recorded to Groonga database. It needs to reopen the database with `FLUSH TABLES` in order to reflect the variable is changed.

Here is an example SQL to disable operations recording:

    mysql> SET GLOBAL mroonga_enable_operations_recording = false;
    Query OK, 0 rows affected (0.00 sec)

    mysql> FLUSH TABLES;
    Query OK, 0 rows affected (0.00 sec)

    mysql> SHOW GLOBAL VARIABLES LIKE 'mroonga_enable_operations_recording';
    +-------------------------------------+-------+
    | Variable_name                       | Value |
    +-------------------------------------+-------+
    | mroonga_enable_operations_recording | OFF   |
    +-------------------------------------+-------+

## 5.3.22. `mroonga_vector_column_delimiter`

The delimiter when outputting a vector column. The default value is a white space.

Here is an example SQL to change the delimiter to a semicolon from a white space:

    mysql> SHOW VARIABLES LIKE 'mroonga_vector_column_delimiter';
    +---------------------------------+-------+
    | Variable_name                   | Value |
    +---------------------------------+-------+
    | mroonga_vector_column_delimiter |       |
    +---------------------------------+-------+
    1 row in set (0.00 sec)

    mysql> SET GLOBAL mroonga_vector_column_delimiter = ';';
    Query OK, 0 rows affected (0.00 sec)

    mysql> SHOW GLOBAL VARIABLES LIKE 'mroonga_vector_column_delimiter';
    +---------------------------------+-------+
    | Variable_name                   | Value |
    +---------------------------------+-------+
    | mroonga_vector_column_delimiter | ;     |
    +---------------------------------+-------+

## 5.3.23. `mroonga_version`

The version string of Mroonga.

Here is an example SQL to confirm the running mroonga version:

    mysql> SHOW VARIABLES LIKE 'mroonga_version';
    +-----------------+-------+
    | Variable_name   | Value |
    +-----------------+-------+
    | mroonga_version | 1.10  |
    +-----------------+-------+
    1 row in set (0.00 sec)

## 5.3.24. `mroonga_condition_push_down_type`

Added in version 7.10.

It controls how to enable condition push down support.

The default value is `ONE_FULL_TEXT_SEARCH`. It means that condition push down is enabled only when `WHERE` clause has one `MATCH AGAINST` condition.

Here are available values:

Value | Description
--- | ---
NONE | Never use condition push down.
ALL | Always use condition push down. It’s experimental for now.
ONE_FULL_TEXT_SEARCH | Use condition push down only when one `MATCH AGAINST` condition exists in `WHERE`. It’s the default.

Here is an example SQL to confirm the current value:

    mysql> SHOW VARIABLES LIKE 'mroonga_condition_push_down_type';
    +----------------------------------+----------------------+
    | Variable_name                    | Value                |
    +----------------------------------+----------------------+
    | mroonga_condition_push_down_type | ONE_FULL_TEXT_SEARCH |
    +----------------------------------+----------------------+
    1 row in set (0.00 sec)