8.3.10. column_rename

8.3.10.1. Summary

column_rename command renames a column.

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

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

  • Starts an operation (like select) that accesses the column to be renamed by the current column name. The current column name is called as the old column name in the below because the column name is renamed.
  • Runs column_rename. The select is still running.
  • The select accesses the column to be renamed by the old column name. But the select can't find the column by the old name because the column has been renamed to the new column name. It may crash the Groonga process.

8.3.10.2. Syntax

column_rename command takes three parameters. All parameters are required:

column_rename table name new_name

8.3.10.3. Usage

Here is a simple example of column_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]
column_rename Users score point
# [[0, 1337566253.89858, 0.000355720520019531], true]
column_list Users
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         "id",
#         "UInt32"
#       ],
#       [
#         "name",
#         "ShortText"
#       ],
#       [
#         "path",
#         "ShortText"
#       ],
#       [
#         "type",
#         "ShortText"
#       ],
#       [
#         "flags",
#         "ShortText"
#       ],
#       [
#         "domain",
#         "ShortText"
#       ],
#       [
#         "range",
#         "ShortText"
#       ],
#       [
#         "source",
#         "ShortText"
#       ]
#     ],
#     [
#       256,
#       "_key",
#       "",
#       "",
#       "COLUMN_SCALAR",
#       "Users",
#       "ShortText",
#       []
#     ],
#     [
#       257,
#       "point",
#       "/tmp/groonga-databases/commands_column_rename.0000101",
#       "fix",
#       "COLUMN_SCALAR|PERSISTENT",
#       "Users",
#       "Int32",
#       []
#     ]
#   ]
# ]
select Users
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         3
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "point",
#           "Int32"
#         ]
#       ],
#       [
#         1,
#         "Alice",
#         2
#       ],
#       [
#         2,
#         "Bob",
#         0
#       ],
#       [
#         3,
#         "Carlos",
#         -1
#       ]
#     ]
#   ]
# ]

8.3.10.4. Parameters

This section describes parameters of column_rename.

8.3.10.4.1. Required parameters

All parameters are required.

8.3.10.4.1.1. table

It specifies the name of table that has the column to be renamed.

8.3.10.4.1.2. name

It specifies the column name to be renamed.

8.3.10.4.1.3. new_name

It specifies the new column name.

8.3.10.5. Return value

[HEADER, SUCCEEDED_OR_NOT]

HEADER

See Output format about HEADER.

SUCCEEDED_OR_NOT

It is true on success, false otherwise.