Kouhei Sutou
null+****@clear*****
Tue Jan 26 18:43:10 JST 2016
Kouhei Sutou 2016-01-26 18:43:10 +0900 (Tue, 26 Jan 2016) New Revision: 723860636a231f8240b3474ae3f520cf6c2c693b https://github.com/groonga/groonga/commit/723860636a231f8240b3474ae3f520cf6c2c693b Message: doc: document alias Added files: doc/example/reference/alias/existing_name.log doc/example/reference/alias/register.log doc/example/reference/alias/schema.log doc/example/reference/alias/select_age.log doc/example/reference/alias/select_age_after_rename.log doc/example/reference/alias/select_age_by_alias.log doc/example/reference/alias/table_and_column.log doc/source/reference/alias.rst Modified files: doc/files.am Added: doc/example/reference/alias/existing_name.log (+38 -0) 100644 =================================================================== --- /dev/null +++ doc/example/reference/alias/existing_name.log 2016-01-26 18:43:10 +0900 (ba6e867) @@ -0,0 +1,38 @@ +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 + # ] + # ] + # ] + # ] Added: doc/example/reference/alias/register.log (+4 -0) 100644 =================================================================== --- /dev/null +++ doc/example/reference/alias/register.log 2016-01-26 18:43:10 +0900 (844ca01) @@ -0,0 +1,4 @@ +Execution example:: + + config_set alias.column Aliases.real_name + # [[0, 1337566253.89858, 0.000355720520019531], true] Added: doc/example/reference/alias/schema.log (+12 -0) 100644 =================================================================== --- /dev/null +++ doc/example/reference/alias/schema.log 2016-01-26 18:43:10 +0900 (2833867) @@ -0,0 +1,12 @@ +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] Added: doc/example/reference/alias/select_age.log (+36 -0) 100644 =================================================================== --- /dev/null +++ doc/example/reference/alias/select_age.log 2016-01-26 18:43:10 +0900 (d1b6819) @@ -0,0 +1,36 @@ +Execution example:: + + select Users --filter 'age < 20' + # [ + # [ + # 0, + # 1337566253.89858, + # 0.000355720520019531 + # ], + # [ + # [ + # [ + # 1 + # ], + # [ + # [ + # "_id", + # "UInt32" + # ], + # [ + # "_key", + # "ShortText" + # ], + # [ + # "age", + # "UInt8" + # ] + # ], + # [ + # 1, + # "alice", + # 14 + # ] + # ] + # ] + # ] Added: doc/example/reference/alias/select_age_after_rename.log (+21 -0) 100644 =================================================================== --- /dev/null +++ doc/example/reference/alias/select_age_after_rename.log 2016-01-26 18:43:10 +0900 (e797f10) @@ -0,0 +1,21 @@ +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 + # ] + # ] + # ], + # [] + # ] Added: doc/example/reference/alias/select_age_by_alias.log (+41 -0) 100644 =================================================================== --- /dev/null +++ doc/example/reference/alias/select_age_by_alias.log 2016-01-26 18:43:10 +0900 (f236f77) @@ -0,0 +1,41 @@ +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 + # ] + # ] + # ] + # ] Added: doc/example/reference/alias/table_and_column.log (+6 -0) 100644 =================================================================== --- /dev/null +++ doc/example/reference/alias/table_and_column.log 2016-01-26 18:43:10 +0900 (37eb973) @@ -0,0 +1,6 @@ +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] Modified: doc/files.am (+28 -0) =================================================================== --- doc/files.am 2016-01-26 16:17:30 +0900 (d5d9d33) +++ doc/files.am 2016-01-26 18:43:10 +0900 (dac7c05) @@ -73,9 +73,17 @@ absolute_source_files = \ $(top_srcdir)/doc/source/example/reference/commands/io_flush/target_name_column.log \ $(top_srcdir)/doc/source/example/reference/commands/io_flush/target_name_database.log \ $(top_srcdir)/doc/source/example/reference/commands/io_flush/target_name_table.log \ + $(top_srcdir)/doc/source/example/reference/commands/lock_acquire/column.log \ + $(top_srcdir)/doc/source/example/reference/commands/lock_acquire/database.log \ + $(top_srcdir)/doc/source/example/reference/commands/lock_acquire/database_release.log \ + $(top_srcdir)/doc/source/example/reference/commands/lock_acquire/table.log \ $(top_srcdir)/doc/source/example/reference/commands/lock_clear/column.log \ $(top_srcdir)/doc/source/example/reference/commands/lock_clear/database.log \ $(top_srcdir)/doc/source/example/reference/commands/lock_clear/table.log \ + $(top_srcdir)/doc/source/example/reference/commands/lock_release/column.log \ + $(top_srcdir)/doc/source/example/reference/commands/lock_release/database.log \ + $(top_srcdir)/doc/source/example/reference/commands/lock_release/database_release.log \ + $(top_srcdir)/doc/source/example/reference/commands/lock_release/table.log \ $(top_srcdir)/doc/source/example/reference/commands/logical_count/count_shutdown.log \ $(top_srcdir)/doc/source/example/reference/commands/logical_count/setup_data.log \ $(top_srcdir)/doc/source/example/reference/commands/logical_count/setup_schema.log \ @@ -586,6 +594,7 @@ absolute_source_files = \ $(top_srcdir)/doc/source/news/4.x.rst \ $(top_srcdir)/doc/source/news/senna.rst \ $(top_srcdir)/doc/source/reference.rst \ + $(top_srcdir)/doc/source/reference/alias.rst \ $(top_srcdir)/doc/source/reference/api.rst \ $(top_srcdir)/doc/source/reference/api/global_configurations.rst \ $(top_srcdir)/doc/source/reference/api/grn_cache.rst \ @@ -642,7 +651,9 @@ absolute_source_files = \ $(top_srcdir)/doc/source/reference/commands/dump.rst \ $(top_srcdir)/doc/source/reference/commands/io_flush.rst \ $(top_srcdir)/doc/source/reference/commands/load.rst \ + $(top_srcdir)/doc/source/reference/commands/lock_acquire.rst \ $(top_srcdir)/doc/source/reference/commands/lock_clear.rst \ + $(top_srcdir)/doc/source/reference/commands/lock_release.rst \ $(top_srcdir)/doc/source/reference/commands/log_level.rst \ $(top_srcdir)/doc/source/reference/commands/log_put.rst \ $(top_srcdir)/doc/source/reference/commands/log_reopen.rst \ @@ -856,9 +867,17 @@ source_files_relative_from_doc_dir = \ source/example/reference/commands/io_flush/target_name_column.log \ source/example/reference/commands/io_flush/target_name_database.log \ source/example/reference/commands/io_flush/target_name_table.log \ + source/example/reference/commands/lock_acquire/column.log \ + source/example/reference/commands/lock_acquire/database.log \ + source/example/reference/commands/lock_acquire/database_release.log \ + source/example/reference/commands/lock_acquire/table.log \ source/example/reference/commands/lock_clear/column.log \ source/example/reference/commands/lock_clear/database.log \ source/example/reference/commands/lock_clear/table.log \ + source/example/reference/commands/lock_release/column.log \ + source/example/reference/commands/lock_release/database.log \ + source/example/reference/commands/lock_release/database_release.log \ + source/example/reference/commands/lock_release/table.log \ source/example/reference/commands/logical_count/count_shutdown.log \ source/example/reference/commands/logical_count/setup_data.log \ source/example/reference/commands/logical_count/setup_schema.log \ @@ -1369,6 +1388,7 @@ source_files_relative_from_doc_dir = \ source/news/4.x.rst \ source/news/senna.rst \ source/reference.rst \ + source/reference/alias.rst \ source/reference/api.rst \ source/reference/api/global_configurations.rst \ source/reference/api/grn_cache.rst \ @@ -1425,7 +1445,9 @@ source_files_relative_from_doc_dir = \ source/reference/commands/dump.rst \ source/reference/commands/io_flush.rst \ source/reference/commands/load.rst \ + source/reference/commands/lock_acquire.rst \ source/reference/commands/lock_clear.rst \ + source/reference/commands/lock_release.rst \ source/reference/commands/log_level.rst \ source/reference/commands/log_put.rst \ source/reference/commands/log_reopen.rst \ @@ -1721,6 +1743,7 @@ html_files_relative_from_locale_dir = \ html/_sources/news/4.x.txt \ html/_sources/news/senna.txt \ html/_sources/reference.txt \ + html/_sources/reference/alias.txt \ html/_sources/reference/api.txt \ html/_sources/reference/api/global_configurations.txt \ html/_sources/reference/api/grn_cache.txt \ @@ -1777,7 +1800,9 @@ html_files_relative_from_locale_dir = \ html/_sources/reference/commands/dump.txt \ html/_sources/reference/commands/io_flush.txt \ html/_sources/reference/commands/load.txt \ + html/_sources/reference/commands/lock_acquire.txt \ html/_sources/reference/commands/lock_clear.txt \ + html/_sources/reference/commands/lock_release.txt \ html/_sources/reference/commands/log_level.txt \ html/_sources/reference/commands/log_put.txt \ html/_sources/reference/commands/log_reopen.txt \ @@ -1965,6 +1990,7 @@ html_files_relative_from_locale_dir = \ html/news/senna.html \ html/objects.inv \ html/reference.html \ + html/reference/alias.html \ html/reference/api.html \ html/reference/api/global_configurations.html \ html/reference/api/grn_cache.html \ @@ -2021,7 +2047,9 @@ html_files_relative_from_locale_dir = \ html/reference/commands/dump.html \ html/reference/commands/io_flush.html \ html/reference/commands/load.html \ + html/reference/commands/lock_acquire.html \ html/reference/commands/lock_clear.html \ + html/reference/commands/lock_release.html \ html/reference/commands/log_level.html \ html/reference/commands/log_put.html \ html/reference/commands/log_reopen.html \ Added: doc/source/reference/alias.rst (+163 -0) 100644 =================================================================== --- /dev/null +++ doc/source/reference/alias.rst 2016-01-26 18:43:10 +0900 (f2e2251) @@ -0,0 +1,163 @@ +.. -*- 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 aliased name 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 table/column name is +referred. It means that you can't override existing table/column 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` -------------- next part -------------- HTML����������������������������...Download