# groonga - オープンソースのカラムストア機能付き全文検索エンジン

- English

# 7.3.23. `io_flush`

## 7.3.23.1. 概要

バージョン 5.0.5 で追加.

`io_flush` はメモリー上のすべての変更を明示的にディスクに書き出します。通常、明示的に `io_flush` を使う必要はありません。なぜなら、OSが自動的に書き出してくれるからです。また、OSが書き出した方が効率的だからです。

いくつか明示的に `io_flush` を使う必要があるケースがあります。1つは、システムが不意にクラッシュすることがよくあるケースです。もう1つは、Groongaプロセスを通常の終了プロセスで終了できない可能性があるケースです。（通常の終了プロセスとは、例えば、 shutdown を使った終了プロセスです。）これらのケースでは、Groongaデータベースに変更を加えた後に `io_flush` を使うとよいです。以下はGroongaデータベースに変更を加えるコマンドのリストです。

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

もし、 select の scorer パラメーターをカラムの値を変更するために使っているなら、 select もこのリストに入ります。

`io_flush` は重い処理になる可能性があることに注意してください。もし、メモリー上に多くの変更があるなら、それらをディスクに書き出す処理は重い処理になります。

バージョン 8.0.8 で追加: `io_flush` はフラッシュ中はGroongaのデータベースをロックします。つまり、 `io_flush` 中は次のコマンドを実行できないということです。

> - column_create
> - column_remove
> - column_rename
> - logical_table_remove
> - object_remove
> - plugin_register
> - plugin_unregister
> - table_create
> - table_remove
> - table_rename

## 7.3.23.2. 構文

このコマンドの引数は3つです。

すべての引数は省略可能です:

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

バージョン 7.0.4 で追加: only_opened が追加されました。

## 7.3.23.3. 使い方

引数無しで実行するとメモリー上のすべての変更をディスクに書き出すことができます。

実行例:

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

もし変更点を把握しているなら、書き出し対象を狭めることができます。以下はコマンドと書き出し対象の対応表です。

コマンド | 書き出し対象 | `io_flush` の引数
--- | --- | ---
load と delete | テーブルとそのテーブルのカラム。 カラムの中に参照カラムがある場合、参照されているテーブルも書き出し対象になる。 インデックスが張られているカラムがある場合、対応するインデックスカラムとそのインデックスカラムのテーブルも書き出し対象になる。 | テーブルとそのテーブルのカラム:
    io_flush --target_name TABLE_NAME
参照されているテーブル:
    io_flush --target_name REFERENCED_TABLE_NAME --recursive no
インデックスカラムのテーブル:
    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN --recursive no
インデックスカラム:
    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN.INDEX_COLUMN
truncate | テーブルとそのテーブルのカラム。 カラムの中に参照カラムがある場合、参照されているテーブルも書き出し対象になる。 インデックスが張られているカラムがある場合、対応するインデックスカラムとそのインデックスカラムのテーブルも書き出し対象になる。 データベースも書き出し対象。 | テーブルとそのテーブルのカラム:
    io_flush --target_name TABLE_NAME
参照されているテーブル:
    io_flush --target_name REFERENCED_TABLE_NAME --recursive no
インデックスカラムのテーブル:
    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN --recursive no
インデックスカラム:
    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN.INDEX_COLUMN
データベース:
    io_flush --recursive no
table_create | 処理対象のテーブルとデータベース。 | テーブル:
    io_flush --target_name TABLE_NAME
データベース:
    io_flush --recursive no
table_remove と table_rename と logical_table_remove | データベース。 | データベース:
    io_flush --recursive no
column_create | 処理対象のカラムとデータベース。 | テーブル:
    io_flush --target_name TABLE_NAME.COLUMN_NAME
データベース:
    io_flush --recursive no
column_remove と column_rename | データベース。 | データベース:
    io_flush --recursive no
plugin_register と plugin_unregister | データベース。 | データベース:
    io_flush --recursive no

## 7.3.23.4. 引数

このセクションではすべての引数について説明します。

### 7.3.23.4.1. 必須引数

必須の引数はありません。

### 7.3.23.4.2. 省略可能引数

いくつか省略可能な引数があります。

#### 7.3.23.4.2.1. `target_name`

書き出し対象オブジェクトの名前を指定します。書き出し対象オブジェクトはデータベース、テーブル、カラムのどれかです。

このパラメーターを省略すると、データベースが書き出し対象オブジェクトになります。

実行例:

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

テーブル名を指定すると、そのテーブルが書き出し対象オブジェクトになります。

実行例:

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

カラム名を指定すると、そのカラムが書き出し対象オブジェクトになります。

実行例:

    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`

書き出し対象オブジェクトの子オブジェクトも書き出し対象にするかどうかを指定します。

データベースの子オブジェクトはすべてのテーブルとすべてのカラムです。

テーブルの子オブジェクトはそのテーブルのすべてのカラムです。

カラムの子オブジェクトはありません。

only_opened に `yes` を指定すると `recursive` は無視されます。

`recursive` の値は `yes` または `no` でなければいけません。 `yes` は指定した書き出し対象オブジェクトとその子オブジェクトすべてを書き出し対象オブジェクトにするという意味です。 `no` は指定した書き出し対象オブジェクトのみを書き出し対象オブジェクトにするという意味です。

次の `io_flush` はデータベースとすべてのテーブルとすべてのカラムのすべての変更を書き出します。

実行例:

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

次の `io_flush` はデータベースの変更だけを書き出します。

実行例:

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

他の値（つまり、 `yes` でも `no` でもない値）を指定した場合、または `recursive` パラメーターを指定しない場合は `yes` が使われます。

`recursive` 引数の値が不正なので、次のケースでは `yes` が使われます。

実行例:

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

`recursive` パラメーターが指定されていないので、次のケースでは `yes` が使われます。

実行例:

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

#### 7.3.23.4.2.3. `only_opened`

バージョン 7.0.4 で追加.

すでに開かれているオブジェクトだけフラッシュするかどうかを指定します。

対象のデータベースを変更するプロセスが1つだけの場合、 `only_opened` に `yes` を指定することでフラッシュの性能が改善する可能性があります。これは、不要なフラッシュを省略するからです。

target_name と `only_opened` オプションを一緒に指定することはできません。もし、 target_name を指定した場合は `only_opened` は無視されます。

`only_opened` に `yes` を指定した場合、 recursive は無視されます。

`only_opened` の値は `yes` または `no` でなければいけません。 `yes` の場合はすでに開かれているオブジェクトだけフラッシュします。 `no` の場合は開いているかどうかに関わらず、対象のオブジェクトをフラッシュします。

次の `io_flush` はデータベースとすべてのテーブルとすべてのカラムのすべての変更を書き出します。

実行例:

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

## 7.3.23.5. 戻り値

このコマンドが成功したときは以下のようにボディは `true` になります:

    [HEADER, true]

このコマンドが失敗すると、 `HEADER` にエラーの詳細が含まれます。

`HEADER` については 出力形式 を参照してください。