.. -*- rst -*-

.. highlightlang:: none

.. groonga-command
.. database: commands_table_remove

``table_remove``
================

Summary
-------

``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
------

This command takes only one required parameter::

  table_remove name

.. _table-remove-usage:

Usage
-----

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.

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]

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

See :doc:`/reference/command/output_format` for ``HEADER``.
