7.3.63. table_remove

7.3.63.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.

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

7.3.63.2. Syntax

This command takes two parameters:

table_remove name
             [dependent=no]

7.3.63.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.63.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.63.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",
#         9488
#       ]
#     ]
#   ],
#   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",
#         9494
#       ]
#     ]
#   ],
#   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.63.3.3. Removes a table with tables and columns that reference the target table

New 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",
#         "db.c",
#         9488
#       ]
#     ]
#   ],
#   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.63.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.63.4. Parameters

This section describes all parameters.

7.3.63.4.1. Required parameters

There is only one required parameter.

7.3.63.4.1.1. name

Specifies the table name to be removed.

See Usage how to use this parameter.

7.3.63.4.2. Optional parameters

There is only one optional parameter.

7.3.63.4.2.1. dependent

New 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.63.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.

previous

7.3.62. table_list

next

7.3.64. table_rename