7.3.64. table_remove — Groonga v14.0.9 documentation

Skip to main content
`Ctrl`+`K`

# 7.3.64. `table_remove`

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

Added in version 6.0.1: You can also remove tables and columns that reference the target table by using `dependent` parameter.

## 7.3.64.2. Syntax

This command takes two parameters:

    table_remove name
                 [dependent=no]

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

> - Removes a table with tables and columns that reference the target table

> - Decreases used resources

### 7.3.64.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.64.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",
    #         "lib/db.c",
    #         11455
    #       ]
    #     ]
    #   ],
    #   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",
    #         "lib/db.c",
    #         11463
    #       ]
    #     ]
    #   ],
    #   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.64.3.3. Removes a table with tables and columns that reference the target table

Added in version 6.0.1.

If you understand what you’ll do, you can also remove tables and columns that reference the target table with one `table_remove` command by using `--dependent yes` parameter.

`ReferencedTable` in the following schema is referenced from a table and a column:

Execution example:

    table_create ReferencedTable TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create Table1 TABLE_HASH_KEY ReferencedTable
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create Table2 TABLE_NO_KEY
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Table2 reference_column COLUMN_SCALAR ReferencedTable
    # [[0,1337566253.89858,0.000355720520019531],true]

You can’t remove `ReferencedTable` by default:

Execution example:

    table_remove ReferencedTable
    # [
    #   [
    #     -2,
    #     1337566253.89858,
    #     0.000355720520019531,
    #     "[table][remove] a table that references the table exists: <Table1._key> -> <ReferencedTable>",
    #     [
    #       [
    #         "is_removable_table",
    #         "lib/db.c",
    #         11455
    #       ]
    #     ]
    #   ],
    #   false
    # ]

You can remove `ReferencedTable`, `Table1` and `Table2.reference_column` by using `--dependent yes` parameter. `Table1` and `Table2.reference_column` reference `ReferencedTable`:

Execution example:

    table_remove ReferencedTable --dependent yes
    # [[0,1337566253.89858,0.000355720520019531],true]

### 7.3.64.3.4. 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.64.4. Parameters

This section describes all parameters.

### 7.3.64.4.1. Required parameters

There is only one required parameter.

#### 7.3.64.4.1.1. `name`

Specifies the table name to be removed.

See Usage how to use this parameter.

### 7.3.64.4.2. Optional parameters

There is only one optional parameter.

#### 7.3.64.4.2.1. `dependent`

Added in version 6.0.1.

Specifies whether tables and columns that reference the target table are also removed or not.

If this value is `yes`, tables and columns that reference the target table are also removed. Otherwise, they aren’t removed and an error is returned.

In other words, if there are any tables and columns that reference the target table, the target table isn’t removed by default.

You should use this parameter carefully. This is a danger parameter.

See Removes a table with tables and columns that reference the target table how to use this parameter.

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