Kouhei Sutou
null+****@clear*****
Tue Jun 26 17:27:46 JST 2018
Kouhei Sutou 2018-06-26 17:27:46 +0900 (Tue, 26 Jun 2018) New Revision: 4c129a71ad151544fda9e59c247d72946798bd6a https://github.com/groonga/groonga/commit/4c129a71ad151544fda9e59c247d72946798bd6a Message: doc vector_find: add TODO: * Translation Added files: doc/source/example/reference/functions/vector_find/usage_find.log doc/source/example/reference/functions/vector_find/usage_find_operator.log doc/source/example/reference/functions/vector_find/usage_register.log doc/source/example/reference/functions/vector_find/usage_setup_data.log doc/source/example/reference/functions/vector_find/usage_setup_schema.log doc/source/reference/functions/vector_find.rst Modified files: doc/files.am doc/source/reference/functions/vector_size.rst doc/source/reference/functions/vector_slice.rst Modified: doc/files.am (+13 -0) =================================================================== --- doc/files.am 2018-06-26 17:13:52 +0900 (4c5e0e460) +++ doc/files.am 2018-06-26 17:27:46 +0900 (e7e2f4673) @@ -428,6 +428,11 @@ absolute_source_files = \ $(top_srcdir)/doc/source/example/reference/functions/sub_filter/usage_setup_schema.log \ $(top_srcdir)/doc/source/example/reference/functions/sub_filter/usage_with_sub_filter.log \ $(top_srcdir)/doc/source/example/reference/functions/sub_filter/usage_without_sub_filter.log \ + $(top_srcdir)/doc/source/example/reference/functions/vector_find/usage_find.log \ + $(top_srcdir)/doc/source/example/reference/functions/vector_find/usage_find_operator.log \ + $(top_srcdir)/doc/source/example/reference/functions/vector_find/usage_register.log \ + $(top_srcdir)/doc/source/example/reference/functions/vector_find/usage_setup_data.log \ + $(top_srcdir)/doc/source/example/reference/functions/vector_find/usage_setup_schema.log \ $(top_srcdir)/doc/source/example/reference/functions/vector_size/usage_only.log \ $(top_srcdir)/doc/source/example/reference/functions/vector_size/usage_setup_data.log \ $(top_srcdir)/doc/source/example/reference/functions/vector_size/usage_setup_schema.log \ @@ -889,6 +894,7 @@ absolute_source_files = \ $(top_srcdir)/doc/source/reference/functions/time_classify_second.rst \ $(top_srcdir)/doc/source/reference/functions/time_classify_week.rst \ $(top_srcdir)/doc/source/reference/functions/time_classify_year.rst \ + $(top_srcdir)/doc/source/reference/functions/vector_find.rst \ $(top_srcdir)/doc/source/reference/functions/vector_new.rst \ $(top_srcdir)/doc/source/reference/functions/vector_size.rst \ $(top_srcdir)/doc/source/reference/functions/vector_slice.rst \ @@ -1395,6 +1401,11 @@ source_files_relative_from_doc_dir = \ source/example/reference/functions/sub_filter/usage_setup_schema.log \ source/example/reference/functions/sub_filter/usage_with_sub_filter.log \ source/example/reference/functions/sub_filter/usage_without_sub_filter.log \ + source/example/reference/functions/vector_find/usage_find.log \ + source/example/reference/functions/vector_find/usage_find_operator.log \ + source/example/reference/functions/vector_find/usage_register.log \ + source/example/reference/functions/vector_find/usage_setup_data.log \ + source/example/reference/functions/vector_find/usage_setup_schema.log \ source/example/reference/functions/vector_size/usage_only.log \ source/example/reference/functions/vector_size/usage_setup_data.log \ source/example/reference/functions/vector_size/usage_setup_schema.log \ @@ -1856,6 +1867,7 @@ source_files_relative_from_doc_dir = \ source/reference/functions/time_classify_second.rst \ source/reference/functions/time_classify_week.rst \ source/reference/functions/time_classify_year.rst \ + source/reference/functions/vector_find.rst \ source/reference/functions/vector_new.rst \ source/reference/functions/vector_size.rst \ source/reference/functions/vector_slice.rst \ @@ -2261,6 +2273,7 @@ html_files_relative_from_locale_dir = \ html/reference/functions/time_classify_second.html \ html/reference/functions/time_classify_week.html \ html/reference/functions/time_classify_year.html \ + html/reference/functions/vector_find.html \ html/reference/functions/vector_new.html \ html/reference/functions/vector_size.html \ html/reference/functions/vector_slice.html \ Added: doc/source/example/reference/functions/vector_find/usage_find.log (+62 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/functions/vector_find/usage_find.log 2018-06-26 17:27:46 +0900 (9a92f2473) @@ -0,0 +1,62 @@ +Execution example:: + + select \ + --table Memos \ + --output_columns 'tags, vector_find(tags, "mroonga")' + # [ + # [ + # 0, + # 1337566253.89858, + # 0.000355720520019531 + # ], + # [ + # [ + # [ + # 5 + # ], + # [ + # [ + # "tags", + # "ShortText" + # ], + # [ + # "vector_find", + # null + # ] + # ], + # [ + # [ + # "groonga" + # ], + # null + # ], + # [ + # [ + # "mroonga", + # "groonga" + # ], + # "mroonga" + # ], + # [ + # [ + # "groonga" + # ], + # null + # ], + # [ + # [ + # "droonga", + # "groonga" + # ], + # null + # ], + # [ + # [ + # "groonga", + # "http" + # ], + # null + # ] + # ] + # ] + # ] Added: doc/source/example/reference/functions/vector_find/usage_find_operator.log (+62 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/functions/vector_find/usage_find_operator.log 2018-06-26 17:27:46 +0900 (ed1398a03) @@ -0,0 +1,62 @@ +Execution example:: + + select \ + --table Memos \ + --output_columns 'tags, vector_find(tags, "roonga", "@")' + # [ + # [ + # 0, + # 1337566253.89858, + # 0.000355720520019531 + # ], + # [ + # [ + # [ + # 5 + # ], + # [ + # [ + # "tags", + # "ShortText" + # ], + # [ + # "vector_find", + # null + # ] + # ], + # [ + # [ + # "groonga" + # ], + # "groonga" + # ], + # [ + # [ + # "mroonga", + # "groonga" + # ], + # "mroonga" + # ], + # [ + # [ + # "groonga" + # ], + # "groonga" + # ], + # [ + # [ + # "droonga", + # "groonga" + # ], + # "droonga" + # ], + # [ + # [ + # "groonga", + # "http" + # ], + # "groonga" + # ] + # ] + # ] + # ] Added: doc/source/example/reference/functions/vector_find/usage_register.log (+4 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/functions/vector_find/usage_register.log 2018-06-26 17:27:46 +0900 (0872016e9) @@ -0,0 +1,4 @@ +Execution example:: + + plugin_register functions/vector + # [[0, 1337566253.89858, 0.000355720520019531], true] Added: doc/source/example/reference/functions/vector_find/usage_setup_data.log (+11 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/functions/vector_find/usage_setup_data.log 2018-06-26 17:27:46 +0900 (368fe8697) @@ -0,0 +1,11 @@ +Execution example:: + + load --table Memos + [ + {"_key": "Groonga is fast", "tags": ["groonga"]}, + {"_key": "Mroonga is fast", "tags": ["mroonga", "groonga"]}, + {"_key": "Groonga is very good!", "tags": ["groonga"]}, + {"_key": "Droonga is fast", "tags": ["droonga", "groonga"]}, + {"_key": "Groonga is a HTTP server", "tags": ["groonga", "http"]} + ] + # [[0, 1337566253.89858, 0.000355720520019531], 5] Added: doc/source/example/reference/functions/vector_find/usage_setup_schema.log (+6 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/functions/vector_find/usage_setup_schema.log 2018-06-26 17:27:46 +0900 (b74e66493) @@ -0,0 +1,6 @@ +Execution example:: + + table_create Memos TABLE_HASH_KEY ShortText + # [[0, 1337566253.89858, 0.000355720520019531], true] + column_create Memos tags COLUMN_VECTOR ShortText + # [[0, 1337566253.89858, 0.000355720520019531], true] Added: doc/source/reference/functions/vector_find.rst (+195 -0) 100644 =================================================================== --- /dev/null +++ doc/source/reference/functions/vector_find.rst 2018-06-26 17:27:46 +0900 (e55825c5a) @@ -0,0 +1,195 @@ +.. -*- rst -*- + +.. highlightlang:: none + +.. groonga-command +.. database: functions_vector_find + +``vector_find`` +=============== + +Summary +------- + +.. versionadded:: 8.0.4 + +It finds the first element that matches the given condition from the +given vector. If no element is found, ``null`` is returned. + +You can use not only equal condition but also less than condition, +prefix equal condition and so on. + +To enable this function, register ``functions/vector`` plugin by +the following command:: + + plugin_register functions/vector + +.. _vector-find-syntax: + +Syntax +------ + +``vector_find`` has two or three parameters:: + + vector_find(vector, value); + vector_find(vector, value, operator); + +If you omit the third argument, each element in the ``vector`` is +compared with ``value`` by equality comparison. + +.. _vector-find-usage: + +Usage +----- + +You need to register ``functions/vector`` plugin at first: + +.. groonga-command +.. include:: ../../example/reference/functions/vector_find/usage_register.log +.. plugin_register functions/vector + +Here is a schema definition and sample data. + +Sample schema: + +.. groonga-command +.. include:: ../../example/reference/functions/vector_find/usage_setup_schema.log +.. table_create Memos TABLE_HASH_KEY ShortText +.. column_create Memos tags COLUMN_VECTOR ShortText + +Sample data: + +.. groonga-command +.. include:: ../../example/reference/functions/vector_find/usage_setup_data.log +.. load --table Memos +.. [ +.. {"_key": "Groonga is fast", "tags": ["groonga"]}, +.. {"_key": "Mroonga is fast", "tags": ["mroonga", "groonga"]}, +.. {"_key": "Groonga is very good!", "tags": ["groonga"]}, +.. {"_key": "Droonga is fast", "tags": ["droonga", "groonga"]}, +.. {"_key": "Groonga is a HTTP server", "tags": ["groonga", "http"]} +.. ] + +Here is a simple usage of ``vector_find`` that searches an element in +``tags`` column and returns the first found element: + +.. groonga-command +.. include:: ../../example/reference/functions/vector_find/usage_find.log +.. select \ +.. --table Memos \ +.. --output_columns 'tags, vector_find(tags, "mroonga")' + +It returns ``"mroonga"`` when the ``tags`` column value includes +``"mroonga"`` element. It returns ``null`` otherwise. + +You can custom how to compare with each value by the third argument. +Here is a usage to use full text search to find an element: + +.. groonga-command +.. include:: ../../example/reference/functions/vector_find/usage_find_operator.log +.. select \ +.. --table Memos \ +.. --output_columns 'tags, vector_find(tags, "roonga", "@")' + +It returns ``"groonga"``, ``"mroonga"`` or ``"droonga"`` when the +``tags`` column value includes one of them. The returned value is the +first found element. For example, ``"droonga"`` is returned for +``["droonga", "groonga"]``. ``"groonga"`` isn't returned because the +first element ``"droonga"`` is found before the second element +``"groonga"`` is searched. + +It returns ``null`` when ``tags`` column value doesn't include them. + +.. _vector-find-parameters: + +Parameters +---------- + +It requires two parameters. + +It has one optional parameter. + +.. _vector-find-required-parameters: + +Required parameters +^^^^^^^^^^^^^^^^^^^ + +``vector`` and ``value`` are required. + +.. _vector-find-vector: + +``vector`` +"""""""""" + +Specifies a vector value to be searched an element. + +.. _vector-find-value: + +``value`` +""""""""" + +Specifies a value to be used as a condition. + +.. _vector-find-optional-parameters: + +Optional parameters +^^^^^^^^^^^^^^^^^^^ + +``operator`` is optional. + +.. _vector-find-operator: + +``operator`` +"""""""""""" + +Specifies an operator to determine how to compare each value with +:ref:`vector-find-value`. + +Here are available operators. The default is ``EQUAL`` operator. It +does equality comparison. + +.. list-table:: + :header-rows: 1 + + * - Mode + - Aliases + - Description + * - ``EQUAL`` + - ``==`` + - It uses :ref:`query-syntax-equal-condition` as the default mode. + + It's the default. + * - ``NOT_EQUAL`` + - ``!=`` + - It uses :ref:`query-syntax-not-equal-condition` as the default mode. + * - ``LESS`` + - ``<`` + - It uses :ref:`query-syntax-less-than-condition` as the default mode. + * - ``GREATER`` + - ``>`` + - It uses :ref:`query-syntax-greater-than-condition` as the default mode. + * - ``LESS_EQUAL`` + - ``<=`` + - It uses :ref:`query-syntax-less-than-or-equal-condition` as the + default mode. + * - ``GREATER_EQUAL`` + - ``>=`` + - It uses :ref:`query-syntax-greater-than-or-equal-condition` as the + default mode. + * - ``MATCH`` + - ``@`` + - It uses :ref:`query-syntax-full-text-search-condition` as the + default mode. + * - ``PREFIX`` + - ``^``, ``@^`` + - It uses :ref:`query-syntax-prefix-search-condition` as the default + mode. + * - ``REGEXP`` + - ``~``, ``@~`` + - It uses :ref:`query-syntax-regular-expression-condition` as the default + mode. + +Return value +------------ + +The matched element on match, ``null`` otherwise. Modified: doc/source/reference/functions/vector_size.rst (+2 -1) =================================================================== --- doc/source/reference/functions/vector_size.rst 2018-06-26 17:13:52 +0900 (0aa8bf7f2) +++ doc/source/reference/functions/vector_size.rst 2018-06-26 17:27:46 +0900 (ff4c936ff) @@ -15,7 +15,8 @@ Summary ``vector_size`` returns the value of vector column size. -To enable this function, register ``functions/vector`` plugin by following the command:: +To enable this function, register ``functions/vector`` plugin by +the following command:: plugin_register functions/vector Modified: doc/source/reference/functions/vector_slice.rst (+2 -1) =================================================================== --- doc/source/reference/functions/vector_slice.rst 2018-06-26 17:13:52 +0900 (eacc40ac5) +++ doc/source/reference/functions/vector_slice.rst 2018-06-26 17:27:46 +0900 (12c4a4fc9) @@ -13,7 +13,8 @@ Summary .. versionadded:: 6.0.7 -To enable this function, register ``functions/vector`` plugin by following the command:: +To enable this function, register ``functions/vector`` plugin by +the following command:: plugin_register functions/vector -------------- next part -------------- HTML����������������������������... URL: https://lists.osdn.me/mailman/archives/groonga-commit/attachments/20180626/f84a15a2/attachment-0001.htm
