7.3.25. io_flush#

7.3.25.1. Summary#

Added 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:

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.

Added in version 8.0.8: io_flush locks Groonga database while flushing. It means that you can’t run the following commands while io_flush:

7.3.25.2. Syntax#

This command takes three parameters.

All parameters are optional:

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

Added in version 7.0.4: only_opened is added.

Added in version 9.0.2: --recursive dependent option is added. It is recommended way to flush target object and its related objects since 9.0.2. See recursive about details.

7.3.25.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 for Groonga 9.0.2 or later.

Note

There is a different recommended way which depends on Groonga version. If Groonga is 9.0.1 or earlier ( --recursive dependent is not available ), you need to flush related objects explicitly, otherwise, using --recursive dependent is a recommended way not to forget flush target objects.

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.

Use --recursive dependent to flush target table and its columns, referenced tables and tables of corresponding index columns and corresponding index columns at once:

io_flush --target_name TABLE_NAME --recursive dependent

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.

Use --recursive dependent to flush target table and its columns, referenced tables and tables of corresponding index columns and corresponding index columns at once:

io_flush --target_name TABLE_NAME --recursive dependent

table_create

Target table and database.

Table:

io_flush --target_name TABLE_NAME --recursive dependent

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 --recursive dependent

column_remove and column_rename

Database.

Database:

io_flush --recursive no

plugin_register and plugin_unregister

Database.

Database:

io_flush --recursive no

If Groonga is 9.0.1 or earlier ( --recursive dependent is not available ), flush objects explicitly. Here is a correspondence table between command and flush targets for Groonga 9.0.1 or earlier.

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.25.4. Parameters#

This section describes all parameters.

7.3.25.4.1. Required parameters#

There is no required parameter.

7.3.25.4.2. Optional parameters#

There are optional parameters.

7.3.25.4.2.1. target_name#

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

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

Execution example:

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

If you specify a table name, the table is the 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 a column name, the column is the 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.25.4.2.2. recursive#

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

Child objects of database are all tables and all columns.

Child objects of table are all its columns.

Child objects of column are nothing.

If you specify yes to only_opened, recursive is ignored.

recursive value must be yes, no or dependent. yes means that all of the specified target object and child objects are the target objects. no means that only the specified target object is the target object. dependent means that all of the specified target object, child objects, corresponding table of index column and corresponding index column are the target objects.

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]

Since 9.0.2, --recursive dependent is added to flush not only target object and child objects, but also related objects. The related objects are:

  • A referenced table

  • A related index column (There is source column in target TABLE_NAME)

  • A table of related index column (There is source column in target TABLE_NAME)

It is useful not to forget flushing related objects.

For example, --recursive dependent is specified for TABLE_NAME, this option executes equivalent to the following commands internally.

  • Flush table and its columns:

    io_flush --target_name TABLE_NAME --recursive yes

  • Flush a referenced table:

    io_flush --target_name REFERENCED_TABLE_NAME --recursive no

  • Flush a related index column (There is source column in TABLE_NAME):

    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN.INDEX_COLUMN

  • Flush a table of related index column (There is source column in TABLE_NAME):

    io_flush --target_name TABLE_NAME_OF_INDEX_COLUMN --recursive no

To confirm whether all target objects are flushed correctly, you can check query log:

> io_flush --recursive "dependent" --target_name "Users"
:000000000000000 flush[Users]
:000000000000000 flush[Terms]
:000000000000000 flush[Terms.users_name]
:000000000000000 flush[Users.name]
:000000000000000 flush[(anonymous:table:dat_key)]
:000000000000000 flush[(anonymous:column:var_size)]
:000000000000000 flush[(anonymous:table:hash_key)]
:000000000000000 flush[(anonymous:column:var_size)]
:000000000000000 flush[(DB)]
<000000000000000 rc=0

In above example, specified not only Users table, related lexicon table Terms and index column Terms.users_name (data source is Users.name) are also flushed.

flush[(anonymous:...)] and flush[(DB)] means that Groonga’s internal objects are also flushed.

Log

Description

flush[(anonymous:table:dat_key)]

The internal object names in DB are flushed. If GRN_DB_KEY=pat is set, TABLE_PAT_KEY is used instead.

flush[(anonymous:column:var_size)] (logged as first (anonymous:column:var_size) object)

The internal object metadata (builtin types, token filter and so on) are flushed.

This is a variable sized column which stores the above internal object metadata.

flush[(anonymous:table:hash_key)]

The internal configuration objects (which is set by config_set) are flushed.

flush[(anonymous:column:var_size)] (logged as second (anonymous:column:var_size) object)

The internal object metadata (options about internal objects such as specified tokenizer options) are flushed.

This is a variable sized column which stores the above internal object metadata.

flush[(DB)]

The DB changes (lock acquired during io_flush) are flushed.

7.3.25.4.2.3. only_opened#

Added 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.25.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.