Kouhei Sutou
null+****@clear*****
Mon Mar 27 15:28:09 JST 2017
Kouhei Sutou 2017-03-27 15:28:09 +0900 (Mon, 27 Mar 2017) New Revision: ba01782343c730c8c78718379f72a9c67cc71358 https://github.com/groonga/groonga/commit/ba01782343c730c8c78718379f72a9c67cc71358 Message: doc logical_select: add dynamic columns Added files: doc/source/example/reference/commands/logical_select/columns_name_flags.log doc/source/example/reference/commands/logical_select/columns_name_stage.log doc/source/example/reference/commands/logical_select/columns_name_type.log doc/source/example/reference/commands/logical_select/columns_name_value.log Modified files: doc/files.am doc/source/reference/commands/logical_select.rst doc/source/reference/commands/select.rst Modified: doc/files.am (+8 -0) =================================================================== --- doc/files.am 2017-03-27 14:56:58 +0900 (b8e68a2) +++ doc/files.am 2017-03-27 15:28:09 +0900 (282d57c) @@ -120,6 +120,10 @@ absolute_source_files = \ $(top_srcdir)/doc/source/example/reference/commands/logical_parameters/usage_get.log \ $(top_srcdir)/doc/source/example/reference/commands/logical_parameters/usage_register.log \ $(top_srcdir)/doc/source/example/reference/commands/logical_parameters/usage_set.log \ + $(top_srcdir)/doc/source/example/reference/commands/logical_select/columns_name_flags.log \ + $(top_srcdir)/doc/source/example/reference/commands/logical_select/columns_name_stage.log \ + $(top_srcdir)/doc/source/example/reference/commands/logical_select/columns_name_type.log \ + $(top_srcdir)/doc/source/example/reference/commands/logical_select/columns_name_value.log \ $(top_srcdir)/doc/source/example/reference/commands/logical_select/drilldown.log \ $(top_srcdir)/doc/source/example/reference/commands/logical_select/drilldown_calc_types.log \ $(top_srcdir)/doc/source/example/reference/commands/logical_select/drilldown_filter.log \ @@ -1015,6 +1019,10 @@ source_files_relative_from_doc_dir = \ source/example/reference/commands/logical_parameters/usage_get.log \ source/example/reference/commands/logical_parameters/usage_register.log \ source/example/reference/commands/logical_parameters/usage_set.log \ + source/example/reference/commands/logical_select/columns_name_flags.log \ + source/example/reference/commands/logical_select/columns_name_stage.log \ + source/example/reference/commands/logical_select/columns_name_type.log \ + source/example/reference/commands/logical_select/columns_name_value.log \ source/example/reference/commands/logical_select/drilldown.log \ source/example/reference/commands/logical_select/drilldown_calc_types.log \ source/example/reference/commands/logical_select/drilldown_filter.log \ Added: doc/source/example/reference/commands/logical_select/columns_name_flags.log (+76 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/commands/logical_select/columns_name_flags.log 2017-03-27 15:28:09 +0900 (d8f9eb9) @@ -0,0 +1,76 @@ +Execution example:: + + plugin_register functions/vector + # [[0, 1337566253.89858, 0.000355720520019531], true] + logical_select \ + --logical_table Entries \ + --shard_key created_at \ + --columns[vector].stage initial \ + --columns[vector].flags COLUMN_VECTOR \ + --columns[vector].type UInt32 \ + --columns[vector].value 'vector_new(1, 2, 3)' \ + --output_columns _id,vector + # [ + # [ + # 0, + # 1337566253.89858, + # 0.000355720520019531 + # ], + # [ + # [ + # [ + # 5 + # ], + # [ + # [ + # "_id", + # "UInt32" + # ], + # [ + # "vector", + # "UInt32" + # ] + # ], + # [ + # 1, + # [ + # 1, + # 2, + # 3 + # ] + # ], + # [ + # 2, + # [ + # 1, + # 2, + # 3 + # ] + # ], + # [ + # 3, + # [ + # 1, + # 2, + # 3 + # ] + # ], + # [ + # 1, + # [ + # 1, + # 2, + # 3 + # ] + # ], + # [ + # 2, + # [ + # 1, + # 2, + # 3 + # ] + # ] + # ] + # ] + # ] Added: doc/source/example/reference/commands/logical_select/columns_name_stage.log (+48 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/commands/logical_select/columns_name_stage.log 2017-03-27 15:28:09 +0900 (5766289) @@ -0,0 +1,48 @@ +Execution example:: + + logical_select \ + --logical_table Entries \ + --shard_key created_at \ + --columns[is_popular].stage initial \ + --columns[is_popular].type Bool \ + --columns[is_popular].value 'n_likes >= 10' \ + --filter is_popular \ + --output_columns _id,is_popular,n_likes + # [ + # [ + # 0, + # 1337566253.89858, + # 0.000355720520019531 + # ], + # [ + # [ + # [ + # 2 + # ], + # [ + # [ + # "_id", + # "UInt32" + # ], + # [ + # "is_popular", + # "Bool" + # ], + # [ + # "n_likes", + # "UInt32" + # ] + # ], + # [ + # 2, + # true, + # 10 + # ], + # [ + # 3, + # true, + # 15 + # ] + # ] + # ] + # ] Added: doc/source/example/reference/commands/logical_select/columns_name_type.log (+62 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/commands/logical_select/columns_name_type.log 2017-03-27 15:28:09 +0900 (87ba8cc) @@ -0,0 +1,62 @@ +Execution example:: + + logical_select \ + --logical_table Entries \ + --shard_key created_at \ + --columns[n_likes_string].stage initial \ + --columns[n_likes_string].type ShortText \ + --columns[n_likes_string].value n_likes \ + --output_columns _id,n_likes,n_likes_string + # [ + # [ + # 0, + # 1337566253.89858, + # 0.000355720520019531 + # ], + # [ + # [ + # [ + # 5 + # ], + # [ + # [ + # "_id", + # "UInt32" + # ], + # [ + # "n_likes", + # "UInt32" + # ], + # [ + # "n_likes_string", + # "ShortText" + # ] + # ], + # [ + # 1, + # 5, + # "5" + # ], + # [ + # 2, + # 10, + # "10" + # ], + # [ + # 3, + # 15, + # "15" + # ], + # [ + # 1, + # 3, + # "3" + # ], + # [ + # 2, + # 3, + # "3" + # ] + # ] + # ] + # ] Added: doc/source/example/reference/commands/logical_select/columns_name_value.log (+64 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/commands/logical_select/columns_name_value.log 2017-03-27 15:28:09 +0900 (7556cf9) @@ -0,0 +1,64 @@ +Execution example:: + + plugin_register functions/string + # [[0, 1337566253.89858, 0.000355720520019531], true] + logical_select \ + --logical_table Entries \ + --shard_key created_at \ + --columns[content_length].stage initial \ + --columns[content_length].type UInt32 \ + --columns[content_length].value 'string_length(content)' \ + --output_columns _id,content,content_length + # [ + # [ + # 0, + # 1337566253.89858, + # 0.000355720520019531 + # ], + # [ + # [ + # [ + # 5 + # ], + # [ + # [ + # "_id", + # "UInt32" + # ], + # [ + # "content", + # "Text" + # ], + # [ + # "content_length", + # "UInt32" + # ] + # ], + # [ + # 1, + # "Welcome! This is my first post!", + # 31 + # ], + # [ + # 2, + # "I started to use Groonga. It's very fast!", + # 41 + # ], + # [ + # 3, + # "I also started to use Mroonga. It's also very fast! Really fast!", + # 64 + # ], + # [ + # 1, + # "I migrated all Senna system!", + # 28 + # ], + # [ + # 2, + # "I also migrated all Tritonn system!", + # 35 + # ] + # ] + # ] + # ] Modified: doc/source/reference/commands/logical_select.rst (+198 -1) =================================================================== --- doc/source/reference/commands/logical_select.rst 2017-03-27 14:56:58 +0900 (c56bf89) +++ doc/source/reference/commands/logical_select.rst 2017-03-27 15:28:09 +0900 (a9d1e87) @@ -52,7 +52,37 @@ parameters are optional:: [query=null] [drilldown_filter=null] -``logical_select`` has the following named parameters for advanced +This command has the following named parameters for dynamic columns: + + * ``columns[${NAME}].stage=null`` + * ``columns[${NAME}].flags=COLUMN_SCALAR`` + * ``columns[${NAME}].type=null`` + * ``columns[${NAME}].value=null`` + * ``columns[${NAME}].window.sort_keys=null`` + * ``columns[${NAME}].window.group_keys=null`` + +You can use one or more alphabets, digits, ``_`` for ``${NAME}``. For +example, ``column1`` is a valid ``${NAME}``. This is the same rule as +normal column. See also :ref:`column-create-name`. + +Parameters that have the same ``${NAME}`` are grouped. + +For example, the following parameters specify one dynamic column: + + * ``--columns[name].stage initial`` + * ``--columns[name].type UInt32`` + * ``--columns[name].value 29`` + +The following parameters specify two dynamic columns: + + * ``--columns[name1].stage initial`` + * ``--columns[name1].type UInt32`` + * ``--columns[name1].value 29`` + * ``--columns[name2].stage filtered`` + * ``--columns[name2].type Float`` + * ``--columns[name2].value '_score * 0.1'`` + +This command has the following named parameters for advanced drilldown: * ``drilldowns[${LABEL}].keys=null`` @@ -63,6 +93,12 @@ drilldown: * ``drilldowns[${LABEL}].calc_types=NONE`` * ``drilldowns[${LABEL}].calc_target=null`` * ``drilldowns[${LABEL}].filter=null`` + * ``drilldowns[${LABEL}].columns[${NAME}].stage=null`` + * ``drilldowns[${LABEL}].columns[${NAME}].flags=COLUMN_SCALAR`` + * ``drilldowns[${LABEL}].columns[${NAME}].type=null`` + * ``drilldowns[${LABEL}].columns[${NAME}].value=null`` + * ``drilldowns[${LABEL}].columns[${NAME}].window.sort_keys=null`` + * ``drilldowns[${LABEL}].columns[${NAME}].window.group_keys=null`` .. deprecated:: 6.1.4 @@ -566,6 +602,167 @@ Here is an example: Not implemented yet. +.. _logical-select-dynamic-column-related-parameters: + +Dynamic column related parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 7.0.1 + +All dynamic column related parameters in :doc:`select` are +supported. See :ref:`select-dynamic-column-related-parameters` for +details. + +.. _logical-select-columns-name-stage: + +``columns[${NAME}].stage`` +"""""""""""""""""""""""""" + +.. versionadded:: 7.0.1 + +Corresponds to :ref:`logical-select-columns-name-stage` in +:doc:`select`. See :ref:`logical-select-columns-name-stage` for +details. + +This is required parameter. + +Here is a ``columns[${NAME}].stage`` example. It creates +``is_popular`` column at ``initial`` stage. You can use ``is_popular`` +in all parameters such as ``filter`` and ``output_columns``: + +.. groonga-command +.. include:: ../../example/reference/commands/logical_select/columns_name_stage.log +.. logical_select \ +.. --logical_table Entries \ +.. --shard_key created_at \ +.. --columns[is_popular].stage initial \ +.. --columns[is_popular].type Bool \ +.. --columns[is_popular].value 'n_likes >= 10' \ +.. --filter is_popular \ +.. --output_columns _id,is_popular,n_likes + +.. _logical-select-columns-name-flags: + +``columns[${NAME}].flags`` +"""""""""""""""""""""""""" + +.. versionadded:: 7.0.1 + +Corresponds to :ref:`logical-select-columns-name-flags` in +:doc:`select`. See :ref:`logical-select-columns-name-flags` for +details. + +The default value is ``COLUMN_SCALAR``. + +Here is a ``columns[${NAME}].flags`` example. It creates a vector +column by ``COLUMN_VECTOR`` flags. ``plugin_register +functions/vector`` is for using :doc:`/reference/functions/vector_new` +function: + +.. groonga-command +.. include:: ../../example/reference/commands/logical_select/columns_name_flags.log +.. plugin_register functions/vector +.. logical_select \ +.. --logical_table Entries \ +.. --shard_key created_at \ +.. --columns[vector].stage initial \ +.. --columns[vector].flags COLUMN_VECTOR \ +.. --columns[vector].type UInt32 \ +.. --columns[vector].value 'vector_new(1, 2, 3)' \ +.. --output_columns _id,vector + +.. _logical-select-columns-name-type: + +``columns[${NAME}].type`` +""""""""""""""""""""""""" + +.. versionadded:: 7.0.1 + +Corresponds to :ref:`logical-select-columns-name-type` in +:doc:`select`. See :ref:`logical-select-columns-name-type` for +details. + +This is required parameter. + +Here is a ``columns[${NAME}].type`` example. It creates a +``ShortText`` value column. Stored value is casted to ``ShortText`` +automatically. In this example, number is casted to ``ShortText``: + +.. groonga-command +.. include:: ../../example/reference/commands/logical_select/columns_name_type.log +.. logical_select \ +.. --logical_table Entries \ +.. --shard_key created_at \ +.. --columns[n_likes_string].stage initial \ +.. --columns[n_likes_string].type ShortText \ +.. --columns[n_likes_string].value n_likes \ +.. --output_columns _id,n_likes,n_likes_string + +.. _select-columns-name-value: + +``columns[${NAME}].value`` +"""""""""""""""""""""""""" + +.. versionadded:: 7.0.1 + +Corresponds to :ref:`logical-select-columns-name-value` in +:doc:`select`. See :ref:`logical-select-columns-name-value` for +details. + +You need to specify :doc:`/reference/window_function` as ``value`` +value and other window function related parameters when you use window +function. See :ref:`logical-select-window-function-related-parameters` +for details. + +This is required parameter. + +Here is a ``columns[${NAME}].value`` example. It creates a new dynamic +column that stores the number of characters of content. This example +uses :doc:`/reference/functions/string_length` function in +``functions/string`` plugin to compute string +length. :doc:`plugin_register` is used to register +``functions/string`` plugin: + +.. groonga-command +.. include:: ../../example/reference/commands/logical_select/columns_name_value.log +.. plugin_register functions/string +.. logical_select \ +.. --logical_table Entries \ +.. --shard_key created_at \ +.. --columns[content_length].stage initial \ +.. --columns[content_length].type UInt32 \ +.. --columns[content_length].value 'string_length(content)' \ +.. --output_columns _id,content,content_length + +.. _select-window-function-related-parameters: + +Window function related parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 7.0.1 + +All window function related parameters in :doc:`select` are +supported. See :ref:`select-window-function-related-parameters` for +details. + +.. _logical-select-columns-name-window-sort-keys: + +``columns[${NAME}].window.sort_keys`` +""""""""""""""""""""""""""""""""""""" + +.. versionadded:: 7.0.1 + +TODO + +.. _logical-select-columns-name-window-group-keys: + +``columns[${NAME}].window.group_keys`` +"""""""""""""""""""""""""""""""""""""" + +.. versionadded:: 7.0.1 + +TODO + .. _logical-select-drilldown-related-parameters: Drilldown related parameters Modified: doc/source/reference/commands/select.rst (+6 -3) =================================================================== --- doc/source/reference/commands/select.rst 2017-03-27 14:56:58 +0900 (585d8fd) +++ doc/source/reference/commands/select.rst 2017-03-27 15:28:09 +0900 (afed8a2) @@ -51,7 +51,7 @@ optional:: [sort_keys=null] [drilldown_sort_keys=null] -``select`` has the following named parameters for dynamic columns: +This command has the following named parameters for dynamic columns: * ``columns[${NAME}].stage=null`` * ``columns[${NAME}].flags=COLUMN_SCALAR`` @@ -81,7 +81,7 @@ The following parameters specify two dynamic columns: * ``--columns[name2].type Float`` * ``--columns[name2].value '_score * 0.1'`` -``select`` has the following named parameters for advanced drilldown: +This command has the following named parameters for advanced drilldown: * ``drilldowns[${LABEL}].keys=null`` * ``drilldowns[${LABEL}].sort_keys=null`` @@ -90,6 +90,7 @@ The following parameters specify two dynamic columns: * ``drilldowns[${LABEL}].limit=10`` * ``drilldowns[${LABEL}].calc_types=NONE`` * ``drilldowns[${LABEL}].calc_target=null`` + * ``drilldowns[${LABEL}].filter=null`` * ``drilldowns[${LABEL}].columns[${NAME}].stage=null`` * ``drilldowns[${LABEL}].columns[${NAME}].flags=COLUMN_SCALAR`` * ``drilldowns[${LABEL}].columns[${NAME}].type=null`` @@ -98,7 +99,9 @@ The following parameters specify two dynamic columns: * ``drilldowns[${LABEL}].columns[${NAME}].window.group_keys=null`` .. deprecated:: 6.0.3 - ``drilldown[...]`` syntax is deprecated, Use ``drilldowns[...]`` instead. + + ``drilldown[...]`` syntax is deprecated, Use ``drilldowns[...]`` + instead. You can use one or more alphabets, digits, ``_`` and ``.`` for ``${LABEL}``. For example, ``parent.sub1`` is a valid ``${LABEL}``. -------------- next part -------------- HTML����������������������������...Download