1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
.. -*- rst -*-
.. highlightlang:: none
.. groonga-command
.. database: alias
Alias
=====
.. versionadded:: 5.1.2
You can refer a table and column by multiple names by using alias
feature.
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
:doc:`/reference/commands/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.
Usage
-----
You manage alias to real name mapping by a normal table and a normal
column.
You can use any table type except :ref:`table-no-key` for the
table. :ref:`table-hash-key` is recommended because exact key match
search is only used for the alias feature. :ref:`table-hash-key` is
the fastest table type for exact key match search.
The column must be :doc:`/reference/columns/scalar` 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:
.. groonga-command
.. include:: ../example/reference/alias/table_and_column.log
.. table_create Aliases TABLE_HASH_KEY ShortText
.. column_create Aliases real_name COLUMN_SCALAR ShortText
You need to register the table and column by :doc:`configuration`.
The alias feature uses ``alias.column`` configuration item. You can
register the table and column by the following
:doc:`/reference/commands/config_set`:
.. groonga-command
.. include:: ../example/reference/alias/register.log
.. config_set alias.column Aliases.real_name
Here are schema and data to show how to use alias:
.. groonga-command
.. include:: ../example/reference/alias/schema.log
.. table_create Users TABLE_HASH_KEY ShortText
.. column_create Users age COLUMN_SCALAR UInt8
..
.. load --table Users
.. [
.. {"_key": "alice", "age": 14},
.. {"_key": "bob", "age": 29}
.. ]
You can use ``Users.age`` in :doc:`/reference/commands/select`:
.. groonga-command
.. include:: ../example/reference/alias/select_age.log
.. select Users --filter 'age < 20'
You can't use ``Users.age`` when you rename ``Users.age`` to
``Users.years`` by :doc:`/reference/commands/column_rename`:
.. groonga-command
.. include:: ../example/reference/alias/select_age_after_rename.log
.. column_rename Users age years
.. select Users --filter 'age < 20'
But you can use ``Users.age`` by registering ``Users.age`` to
``Users.years`` mapping to ``Aliases``.
.. groonga-command
.. include:: ../example/reference/alias/select_age_by_alias.log
.. load --table Aliases
.. [
.. {"_key": "Users.age", "real_name": "Users.years"}
.. ]
..
.. select Users --filter 'age < 20'
Now, you can use ``Users.age`` as alias of ``Users.years``.
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:
.. groonga-command
.. include:: ../example/reference/alias/existing_name.log
.. load --table Aliases
.. [
.. {"_key": "Users.years", "real_name": "Users.years_old"}
.. ]
..
.. select Users --filter 'years < 20'
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:
.. list-table::
:header-rows: 1
* - ``_key``
- ``real_name``
* - ``Users.age``
- ``Users.years``
* - ``Users.years``
- ``Users.years_old``
Here is an example to ``Users.age`` is resolved recursively:
.. groonga-command
.. include:: ../example/reference/alias/existing_name.log
.. column_rename Users years years_old
.. select Users --filter 'age < 20'
See also
--------
* :doc:`/reference/configuration`
* :doc:`/reference/commands/config_set`
* :doc:`/reference/commands/table_create`
* :doc:`/reference/commands/column_create`
* :doc:`/reference/commands/select`
|
