7.18. Alias

New in version 5.1.2.

You can refer a table and column by multiple names by using alias feature.

7.18.1. Summary

The alias feature is useful for the following cases:

  • You want to rename a table but you can't change some Groonga clients that uses the current table name.
  • You want to change column type without downtime.

In the former case, some Groonga clients can use the current table name after you rename a table. Because the alias feature maps the current table name to the renamed new table name.

In the latter case, all Groonga clients access the column by aliased name such as aliased_column. aliased_column refers current_column. You create a new column new_column with new type and copy data from current_column by column_copy. You change aliased_column to refer new_column from current_column. Now, all Groonga clients access new_column by aliased_column without stopping search requests.

7.18.2. Usage

You manage alias to real name mapping by a normal table and a normal column.

You can use any table type except TABLE_NO_KEY for the table. TABLE_HASH_KEY is recommended because exact key match search is only used for the alias feature. TABLE_HASH_KEY is the fastest table type for exact key match search.

The column must be Scalar column and type is ShortText. You can also use Text and LongText types but they are meaningless. Because the max table/column name size is 4KiB. ShortText can store 4KiB data.

Here are example definitions of table and column for managing aliases:

Execution example:

table_create Aliases TABLE_HASH_KEY ShortText
# [[0, 1337566253.89858, 0.000355720520019531], true]
column_create Aliases real_name COLUMN_SCALAR ShortText
# [[0, 1337566253.89858, 0.000355720520019531], true]

You need to register the table and column by Configuration. The alias feature uses alias.column configuration item. You can register the table and column by the following config_set:

Execution example:

config_set alias.column Aliases.real_name
# [[0, 1337566253.89858, 0.000355720520019531], true]

Here are schema and data to show how to use alias:

Execution example:

table_create Users TABLE_HASH_KEY ShortText
# [[0, 1337566253.89858, 0.000355720520019531], true]
column_create Users age COLUMN_SCALAR UInt8
# [[0, 1337566253.89858, 0.000355720520019531], true]
load --table Users
[
{"_key": "alice", "age": 14},
{"_key": "bob",   "age": 29}
]
# [[0, 1337566253.89858, 0.000355720520019531], 2]

You can use Users.age in select:

Execution example:

select Users --filter 'age < 20'
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "age",
#           "UInt8"
#         ]
#       ],
#       [
#         1,
#         "alice",
#         14
#       ]
#     ]
#   ]
# ]

You can't use Users.age when you rename Users.age to Users.years by column_rename:

Execution example:

column_rename Users age years
# [[0, 1337566253.89858, 0.000355720520019531], true]
select Users --filter 'age < 20'
# [
#   [
#     -63,
#     1337566253.89858,
#     0.000355720520019531,
#     "Syntax error: <age| |< 20>",
#     [
#       [
#         "yy_syntax_error",
#         "grn_ecmascript.lemon",
#         34
#       ]
#     ]
#   ],
#   []
# ]

But you can use Users.age by registering Users.age to Users.years mapping to Aliases.

Execution example:

load --table Aliases
[
{"_key": "Users.age", "real_name": "Users.years"}
]
# [[0, 1337566253.89858, 0.000355720520019531], 1]
select Users --filter 'age < 20'
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "years",
#           "UInt8"
#         ]
#       ],
#       [
#         1,
#         "alice",
#         14
#       ]
#     ]
#   ]
# ]

Now, you can use Users.age as alias of Users.years.

7.18.3. How to resolve alias

This section describes how to resolve alias.

Groonga uses the alias feature when nonexistent object name (table name, column name, command name, function name and so on) is referred. It means that you can't override existing object (table, column, command, function and so on) by the alias feature.

For example, alias isn't resolved in the following example because Users.years exists:

Execution example:

column_rename Users years years_old
# [[0, 1337566253.89858, 0.000355720520019531], true]
select Users --filter 'age < 20'
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "years_old",
#           "UInt8"
#         ]
#       ],
#       [
#         1,
#         "alice",
#         14
#       ]
#     ]
#   ]
# ]

Alias is resolved recursively. If you rename Users.years to Users.years_old and you refer Users.age, Groonga replaces Users.age with Users.years and then Users.years with Users.years_old. Because Aliases table has the following records:

_key real_name
Users.age Users.years
Users.years Users.years_old

Here is an example to Users.age is resolved recursively:

Execution example:

column_rename Users years years_old
# [[0, 1337566253.89858, 0.000355720520019531], true]
select Users --filter 'age < 20'
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "years_old",
#           "UInt8"
#         ]
#       ],
#       [
#         1,
#         "alice",
#         14
#       ]
#     ]
#   ]
# ]