doc: update table_remove

doc/source/reference/commands/table_remove.rst

@@ -2,46 +2,237 @@
 
 .. highlightlang:: none
 
+.. groonga-command
+.. database: commands_table_remove
+
 ``table_remove``
 ================
 
 Summary
 -------
 
-table_remove - テーブルの削除
-
-groonga組込コマンドの一つであるtable_removeについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。
-
-table_removeはテーブルと定義されているカラムを削除します。カラムに付随するインデックスも再帰的に削除されます。
+``table_remove`` removes a table and its columns. If there are one or
+more indexes against key of the table and its columns, they are also
+removed.
 
 Syntax
 ------
-::
 
- table_remove name
+This command takes only one required parameter::
+
+  table_remove name
+
+.. _table-remove-usage:
 
 Usage
 -----
-::
 
- table_remove Entry
+You just specify table name that you want to remove. ``table_remove``
+removes the table and its columns. If the table and its columns are
+indexed, all index columns for the table and its columns are also
+removed.
+
+This section describes about the followings:
+
+  * Basic usage
+  * Unremovable cases
+  * Decreases used resources
+
+.. _table-remove-basic-usage:
+
+Basic usage
+^^^^^^^^^^^
+
+Let's think about the following case:
+
+  * There is one table ``Entries``.
+  * ``Entries`` table has some columns.
+  * ``Entries`` table's key is indexed.
+  * A column of ``Entries`` is indexed.
+
+Here are commands that create ``Entries`` table:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/basic_usage_create_entries_table.log
+.. table_create Entries TABLE_HASH_KEY UInt32
+.. column_create Entries title COLUMN_SCALAR ShortText
+.. column_create Entries content COLUMN_SCALAR Text
+
+Here are commands that create an index for ``Entries`` table's key:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/basic_usage_create_index_for_entries_table.log
+.. table_create EntryKeys TABLE_HASH_KEY UInt32
+.. column_create EntryKeys key_index COLUMN_INDEX Entries _key
+
+Here are commands that create an index for ``Entries`` table's column:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/basic_usage_create_index_for_entries_table_column.log
+.. table_create Terms TABLE_PAT_KEY ShortText \
+..   --default_tokenizer TokenBigram \
+..   --normalizer NormalizerAuto
+.. column_create Terms content_index COLUMN_INDEX Entries content
+
+Let's confirm the current schema before running ``table_remove``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/basic_usage_dump_before_table_remove.log
+.. dump
+
+If you remove ``Entries`` table, the following tables and columns are
+removed:
+
+  * ``Entries``
+  * ``Entries.title``
+  * ``Entries.context``
+  * ``EntryKeys.key_index``
+  * ``Terms.content_index``
+
+The following tables (lexicons) aren't removed:
+
+  * ``EntryKeys``
+  * ``Terms``
+
+Let's run ``table_remove``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/basic_usage_table_remove.log
+.. table_remove Entries
+
+Here is schema after ``table_remove``. Only ``EntryKeys`` and
+``Terms`` exist:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/basic_usage_dump_after_table_remove.log
+.. dump
+
+.. _table-remove-unremovable-cases:
+
+Unremovable cases
+^^^^^^^^^^^^^^^^^
+
+There are some unremovable cases:
+
+  * One or more tables use the table as key type.
+  * One or more columns use the table as value type.
+
+Both cases blocks dangling references. If the table is referenced as
+type and the table is removed, tables and columns that refer the table
+are broken.
 
- [true]
+If the target table satisfies one of them, ``table_remove`` is
+failed. The target table and its columns aren't removed.
+
+Here is an example for the table is used as key type case.
+
+The following commands create a table to be removed and a table that
+uses the table to be removed as key type:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/unremovable_cases_key_type_create.log
+.. table_create ReferencedByTable TABLE_HASH_KEY ShortText
+.. table_create ReferenceTable TABLE_HASH_KEY ReferencedByTable
+
+``table_remove`` against ``ReferencedByTable`` is failed:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/unremovable_cases_key_type_remove_fail.log
+.. table_remove ReferencedByTable
+
+You need to remove ``ReferenceTable`` before you remove
+``ReferencedByTable``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/unremovable_cases_key_type_remove_success.log
+.. table_remove ReferenceTable
+.. table_remove ReferencedByTable
+
+Here is an example for the table is used as value type case.
+
+The following commands create a table to be removed and a column that
+uses the table to be removed as value type:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/unremovable_cases_value_type_create.log
+.. table_create ReferencedByColumn TABLE_HASH_KEY ShortText
+.. table_create Table TABLE_NO_KEY
+.. column_create Table reference_column COLUMN_SCALAR ReferencedByColumn
+
+``table_remove`` against ``ReferencedByColumn`` is failed:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/unremovable_cases_value_type_remove_fail.log
+.. table_remove ReferencedByColumn
+
+You need to remove ``Table.reference_column`` before you remove
+``ReferencedByColumn``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/unremovable_cases_value_type_remove_success.log
+.. column_remove Table reference_column
+.. table_remove ReferencedByColumn
+
+Decreases used resources
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``table_remove`` opens all tables and columns in database to check
+:ref:`table-remove-unremovable-cases`.
+
+If you have many tables and columns, ``table_remove`` may use many
+resources. There is a workaround to avoid the case.
+
+``table_remove`` closes temporary opened tables and columns for
+checking when the max number of threads is ``1``.
+
+You can confirm and change the current max number of threads by
+:doc:`thread_limit`.
+
+.. groonga-command
+.. thread_limit 4
+
+The feature is used in the following case:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/decreases_used_resources_close_temporary_opened_objects.log
+.. table_create Entries TABLE_NO_KEY
+.. thread_limit 1
+.. table_remove Entries
+
+The feature isn't used in the following case:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_remove/decreases_used_resources_close_temporary_opened_objects.log
+.. table_create Entries TABLE_NO_KEY
+.. thread_limit 2
+.. table_remove Entries
 
 Parameters
 ----------
 
+This section describes all parameters.
+
+Required parameters
+^^^^^^^^^^^^^^^^^^^
+
+There is only one required parameters.
+
+.. _table-remove-name:
+
 ``name``
-  削除対象のカラムが定義されているテーブルの名前を指定します。
+""""""""
+
+Specifies the table name to be removed.
+
+See :ref:`table-remove-usage` how to use this parameter.
 
 Return value
 ------------
 
-::
-
- [成功かどうかのフラグ]
+The command returns ``true`` as body on success such as::
 
-``成功かどうかのフラグ``
+  [HEADER, true]
 
-  エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。
+If the command fails, error details are in ``HEADER``.
 
+See :doc:`/reference/command/output_format` for ``HEADER``.