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

- 日本語

# 7.3.55. `table_remove`

## 7.3.55.1. 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.

## 7.3.55.2. Syntax

This command takes only one required parameter:

    table_remove name

## 7.3.55.3. 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

### 7.3.55.3.1. 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:

Execution example:

    table_create Entries TABLE_HASH_KEY UInt32
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries title COLUMN_SCALAR ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries content COLUMN_SCALAR Text
    # [[0, 1337566253.89858, 0.000355720520019531], true]

Here are commands that create an index for `Entries` table's key:

Execution example:

    table_create EntryKeys TABLE_HASH_KEY UInt32
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create EntryKeys key_index COLUMN_INDEX Entries _key
    # [[0, 1337566253.89858, 0.000355720520019531], true]

Here are commands that create an index for `Entries` table's column:

Execution example:

    table_create Terms TABLE_PAT_KEY ShortText \
      --default_tokenizer TokenBigram \
      --normalizer NormalizerAuto
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Terms content_index COLUMN_INDEX Entries content
    # [[0, 1337566253.89858, 0.000355720520019531], true]

Let's confirm the current schema before running `table_remove`:

Execution example:

    dump
    # table_create Entries TABLE_HASH_KEY UInt32
    # column_create Entries content COLUMN_SCALAR Text
    # column_create Entries title COLUMN_SCALAR ShortText
    #
    # table_create EntryKeys TABLE_HASH_KEY UInt32
    #
    # table_create Terms TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
    #
    # column_create EntryKeys key_index COLUMN_INDEX Entries _key
    # column_create Terms content_index COLUMN_INDEX Entries content

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

Execution example:

    table_remove Entries
    # [[0, 1337566253.89858, 0.000355720520019531], true]

Here is schema after `table_remove`. Only `EntryKeys` and `Terms` exist:

Execution example:

    dump
    # table_create EntryKeys TABLE_HASH_KEY UInt32
    #
    # table_create Terms TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto

### 7.3.55.3.2. 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:

Execution example:

    table_create ReferencedByTable TABLE_HASH_KEY ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_create ReferenceTable TABLE_HASH_KEY ReferencedByTable
    # [[0, 1337566253.89858, 0.000355720520019531], true]

`table_remove` against `ReferencedByTable` is failed:

Execution example:

    table_remove ReferencedByTable
    # [
    #   [
    #     -2,
    #     1337566253.89858,
    #     0.000355720520019531,
    #     "[table][remove] a table that references the table exists: <ReferenceTable._key> -> <ReferencedByTable>",
    #     [
    #       [
    #         "is_removable_table",
    #         "db.c",
    #         8480
    #       ]
    #     ]
    #   ],
    #   false
    # ]

You need to remove `ReferenceTable` before you remove `ReferencedByTable`:

Execution example:

    table_remove ReferenceTable
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_remove ReferencedByTable
    # [[0, 1337566253.89858, 0.000355720520019531], true]

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:

Execution example:

    table_create ReferencedByColumn TABLE_HASH_KEY ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_create Table TABLE_NO_KEY
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Table reference_column COLUMN_SCALAR ReferencedByColumn
    # [[0, 1337566253.89858, 0.000355720520019531], true]

`table_remove` against `ReferencedByColumn` is failed:

Execution example:

    table_remove ReferencedByColumn
    # [
    #   [
    #     -2,
    #     1337566253.89858,
    #     0.000355720520019531,
    #     "[table][remove] a column that references the table exists: <Table.reference_column> -> <ReferencedByColumn>",
    #     [
    #       [
    #         "is_removable_table",
    #         "db.c",
    #         8500
    #       ]
    #     ]
    #   ],
    #   false
    # ]

You need to remove `Table.reference_column` before you remove `ReferencedByColumn`:

Execution example:

    column_remove Table reference_column
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_remove ReferencedByColumn
    # [[0, 1337566253.89858, 0.000355720520019531], true]

### 7.3.55.3.3. Decreases used resources

`table_remove` opens all tables and columns in database to check 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 thread_limit.

The feature is used in the following case:

Execution example:

    table_create Entries TABLE_NO_KEY
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    thread_limit 2
    # [[0, 1337566253.89858, 0.000355720520019531], 1]
    table_remove Entries
    # [[0, 1337566253.89858, 0.000355720520019531], true]

The feature isn't used in the following case:

Execution example:

    table_create Entries TABLE_NO_KEY
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    thread_limit 2
    # [[0, 1337566253.89858, 0.000355720520019531], 1]
    table_remove Entries
    # [[0, 1337566253.89858, 0.000355720520019531], true]

## 7.3.55.4. Parameters

This section describes all parameters.

### 7.3.55.4.1. Required parameters

There is only one required parameters.

#### 7.3.55.4.1.1. `name`

Specifies the table name to be removed.

See Usage how to use this parameter.

## 7.3.55.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`.