7.3.23. io_flush — Groonga v7.0.6 documentation

# groonga - An open-source fulltext search engine and column store.

- 日本語

# 7.3.23. `io_flush`

## 7.3.23.1. Summary

New in version 5.0.5.

`io_flush` flushes all changes in memory to disk explicitly. Normally, you don't need to use `io_flush` explicitly. Because flushing is done automatically by OS. And flushing by OS is effective.

You need to use `io_flush` explicitly when your system may often crash unexpectedly or you may not shutdown your Groonga process in a normal way. (For example, using shutdown is a normal shutdown process.) It's better that you use `io_flush` after you change your Groonga database for the case. Here are commands that change your Groonga database:

> - load
> - delete
> - truncate
> - table_create
> - table_remove
> - table_rename
> - column_create
> - column_remove
> - column_rename
> - plugin_register
> - plugin_unregister
> - logical_table_remove

If you're using scorer parameter in select to change existing column values, select is added to the above list.

Note that `io_flush` may be a heavy process. If there are many changes in memory, flushing them to disk is a heavy process.

## 7.3.23.2. Syntax

This command takes three parameters.

All parameters are optional:

    io_flush [target_name=null]
             [recursive=yes]
             [only_opened=no]

New in version 7.0.4: only_opened is added.

## 7.3.23.3. Usage

You can flush all changes in memory to disk with no arguments:

Execution example:

    io_flush
    # [[0, 1337566253.89858, 0.000355720520019531], true]

If you know what is changed, you can narrow flush targets. Here is a correspondence table between command and flush targets.

Command | Flush targets | `io_flush` arguments
--- | --- | ---
load and delete | Target table and its columns. If there are one or more reference columns in these columns, referenced tables are also flush targets. If there are one or more indexed columns in these columns, tables of corresponding index columns and corresponding index columns are also flush targets. | Table and its columns:
    io_flush --target_name TABLE_NAME
A referenced table:
    io_flush --target_name REFERENCED_TABLE_NAME --recursive no
A table of an index column:
    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN --recursive no
An index column:
    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN.INDEX_COLUMN
truncate | Target table and its columns. If there are one or more reference columns in these columns, referenced tables are also flush targets. If there are one or more indexed columns in these columns, tables of corresponding index columns and corresponding index columns are also flush targets. Database is also flush target. | Table and its columns:
    io_flush --target_name TABLE_NAME
A referenced table:
    io_flush --target_name REFERENCED_TABLE_NAME --recursive no
A table of an index column:
    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN --recursive no
An index column:
    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN.INDEX_COLUMN
Database:
    io_flush --recursive no
table_create | Target table and database. | Table:
    io_flush --target_name TABLE_NAME
Database:
    io_flush --recursive no
table_remove, table_rename and logical_table_remove | Database. | Database:
    io_flush --recursive no
column_create | Target column and database. | Table:
    io_flush --target_name TABLE_NAME.COLUMN_NAME
Database:
    io_flush --recursive no
column_remove and column_rename | Database. | Database:
    io_flush --recursive no
plugin_register and plugin_unregister | Database. | Database:
    io_flush --recursive no

## 7.3.23.4. Parameters

This section describes all parameters.

### 7.3.23.4.1. Required parameters

There is no required parameter.

### 7.3.23.4.2. Optional parameters

There are optional parameters.

#### 7.3.23.4.2.1. `target_name`

Specifies a flush target object name. Target object is one of database, table or column.

If you omit this parameter, database is flush target object:

Execution example:

    io_flush
    # [[0, 1337566253.89858, 0.000355720520019531], true]

If you specify table name, the table is flush target object:

Execution example:

    table_create Users TABLE_HASH_KEY ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    io_flush --target_name Users
    # [[0, 1337566253.89858, 0.000355720520019531], true]

If you specify column name, the column is flush target object:

Execution example:

    column_create Users age COLUMN_SCALAR UInt8
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    io_flush --target_name Users.age
    # [[0, 1337566253.89858, 0.000355720520019531], true]

#### 7.3.23.4.2.2. `recursive`

Specifies whether child objects of the flush target object are also flush target objects.

Child objects of database is all tables and all columns.

Child objects of table is all its columns.

Child objects of column is nothing.

If you specify `yes` to only_opened, `recursive` is ignored.

`recursive` value must be `yes` or `no`. `yes` means that all of the specified flush target object and child objects are flush target objects. `no` means that only the specified flush target object is flush target object.

The following `io_flush` flushes all changes in database, all tables and all columns:

Execution example:

    io_flush --recursive yes
    # [[0, 1337566253.89858, 0.000355720520019531], true]

The following `io_flush` flushes all changes only in database:

Execution example:

    io_flush --recursive no
    # [[0, 1337566253.89858, 0.000355720520019531], true]

If you specify other value (not `yes` neither `no`) or omit `recursive` parameter, `yes` is used.

`yes` is used in the following case because invalid `recursive` argument is specified:

Execution example:

    io_flush --recursive invalid
    # [[0, 1337566253.89858, 0.000355720520019531], true]

`yes` is used in the following case because `recursive` parameter isn't specified:

Execution example:

    io_flush
    # [[0, 1337566253.89858, 0.000355720520019531], true]

#### 7.3.23.4.2.3. `only_opened`

New in version 7.0.4.

Specifies whether opened objects are only flushed.

If there is only one process that changes the target database, flush performance will be improved by specifying `yes` to `only_opened`. It skips needless flushes.

You can't specify target_name with `only_opened` option. If you specify target_name, `only_opened` is ignored.

If you specify `yes` to `only_opened`, recursive is ignored.

`only_opened` value must be `yes` or `no`. `yes` means that opened objects are only flushed. `no` means that all target objects are flushed even they aren't opened.

The following `io_flush` flushes all changes in database, all tables and all columns:

Execution example:

    io_flush --only_opened yes
    # [[0, 1337566253.89858, 0.000355720520019531], true]

## 7.3.23.5. Return value

The command returns `true` as body on success such as:

    [HEADER, true]

If the command fails, error details are in `HEADER`.

See Output format for `HEADER`.