7.3.65. `table_rename`#

7.3.65.1. Summary#

table_rename command renames a table.

It is a light operation. It just changes a relationship between name and the table object. It doesn’t copy table and its column values.

It is a dangerous operation. You must stop all operations including read operations while you run table_rename. If the following case is occurred, Groonga process may be crashed:

Starts an operation (like select) that accesses the table to be renamed by the current table name. The current table name is called as the old table name in the below because the table name is renamed.

Runs table_rename. The select is still running.

The select accesses the table to be renamed by the old table name. But the select can’t find the table by the old name because the table has been renamed to the new table name. It may crash the Groonga process.

7.3.65.2. Syntax#

This command takes two parameters.

All parameters are required:

table_rename name new_name

7.3.65.3. Usage#

Here is a simple example of table_rename command.

Execution example:

table_create Users TABLE_PAT_KEY ShortText
# [[0,1337566253.89858,0.000355720520019531],true]
column_create Users score COLUMN_SCALAR Int32
# [[0,1337566253.89858,0.000355720520019531],true]
load --table Users
[
{"_key": "Alice",  "score": 2},
{"_key": "Bob",    "score": 0},
{"_key": "Carlos", "score": -1}
]
# [[0,1337566253.89858,0.000355720520019531],3]
table_rename Users Players
# [[0,1337566253.89858,0.000355720520019531],true]
table_list
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         "id",
#         "UInt32"
#       ],
#       [
#         "name",
#         "ShortText"
#       ],
#       [
#         "path",
#         "ShortText"
#       ],
#       [
#         "flags",
#         "ShortText"
#       ],
#       [
#         "domain",
#         "ShortText"
#       ],
#       [
#         "range",
#         "ShortText"
#       ],
#       [
#         "default_tokenizer",
#         "ShortText"
#       ],
#       [
#         "normalizer",
#         "ShortText"
#       ]
#     ],
#     [
#       256,
#       "Players",
#       "${DB_PATH}.0000100",
#       "TABLE_PAT_KEY|PERSISTENT",
#       "ShortText",
#       null,
#       null,
#       null
#     ]
#   ]
# ]
select Players
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         3
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "score",
#           "Int32"
#         ]
#       ],
#       [
#         1,
#         "Alice",
#         2
#       ],
#       [
#         2,
#         "Bob",
#         0
#       ],
#       [
#         3,
#         "Carlos",
#         -1
#       ]
#     ]
#   ]
# ]

7.3.65.4. Parameters#

This section describes parameters of table_rename.

7.3.65.4.1. Required parameters#

All parameters are required.

7.3.65.4.1.1. `name`#

Specifies the table name to be renamed.

7.3.65.4.1.2. `new_name`#

Specifies the new table name.

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

7.3.65. table_rename#