Kouhei Sutou
null+****@clear*****
Wed Apr 19 18:16:19 JST 2017
Kouhei Sutou 2017-04-19 18:16:19 +0900 (Wed, 19 Apr 2017) New Revision: 693f167cbbe32384ecb183c3b63b5ae2508e587c https://github.com/groonga/groonga/commit/693f167cbbe32384ecb183c3b63b5ae2508e587c Message: doc in_records: add Added files: doc/source/example/reference/functions/in_records/usage_search.log doc/source/example/reference/functions/in_records/usage_setup_conditions.log doc/source/example/reference/functions/in_records/usage_setup_data.log doc/source/example/reference/functions/in_records/usage_setup_schema.log doc/source/reference/functions/in_records.rst Modified files: doc/files.am doc/locale/ja/LC_MESSAGES/reference.po doc/source/reference/functions/query.rst Modified: doc/files.am (+12 -0) =================================================================== --- doc/files.am 2017-04-19 18:15:02 +0900 (9904ce5) +++ doc/files.am 2017-04-19 18:16:19 +0900 (ddd8189) @@ -358,6 +358,10 @@ absolute_source_files = \ $(top_srcdir)/doc/source/example/reference/functions/html_untag/usage_html_untag.log \ $(top_srcdir)/doc/source/example/reference/functions/html_untag/usage_setup_data.log \ $(top_srcdir)/doc/source/example/reference/functions/html_untag/usage_setup_schema.log \ + $(top_srcdir)/doc/source/example/reference/functions/in_records/usage_search.log \ + $(top_srcdir)/doc/source/example/reference/functions/in_records/usage_setup_conditions.log \ + $(top_srcdir)/doc/source/example/reference/functions/in_records/usage_setup_data.log \ + $(top_srcdir)/doc/source/example/reference/functions/in_records/usage_setup_schema.log \ $(top_srcdir)/doc/source/example/reference/functions/in_values/usage_only.log \ $(top_srcdir)/doc/source/example/reference/functions/in_values/usage_setup_data.log \ $(top_srcdir)/doc/source/example/reference/functions/in_values/usage_setup_schema.log \ @@ -818,6 +822,7 @@ absolute_source_files = \ $(top_srcdir)/doc/source/reference/functions/highlight_full.rst \ $(top_srcdir)/doc/source/reference/functions/highlight_html.rst \ $(top_srcdir)/doc/source/reference/functions/html_untag.rst \ + $(top_srcdir)/doc/source/reference/functions/in_records.rst \ $(top_srcdir)/doc/source/reference/functions/in_values.rst \ $(top_srcdir)/doc/source/reference/functions/now.rst \ $(top_srcdir)/doc/source/reference/functions/number_classify.rst \ @@ -1269,6 +1274,10 @@ source_files_relative_from_doc_dir = \ source/example/reference/functions/html_untag/usage_html_untag.log \ source/example/reference/functions/html_untag/usage_setup_data.log \ source/example/reference/functions/html_untag/usage_setup_schema.log \ + source/example/reference/functions/in_records/usage_search.log \ + source/example/reference/functions/in_records/usage_setup_conditions.log \ + source/example/reference/functions/in_records/usage_setup_data.log \ + source/example/reference/functions/in_records/usage_setup_schema.log \ source/example/reference/functions/in_values/usage_only.log \ source/example/reference/functions/in_values/usage_setup_data.log \ source/example/reference/functions/in_values/usage_setup_schema.log \ @@ -1729,6 +1738,7 @@ source_files_relative_from_doc_dir = \ source/reference/functions/highlight_full.rst \ source/reference/functions/highlight_html.rst \ source/reference/functions/html_untag.rst \ + source/reference/functions/in_records.rst \ source/reference/functions/in_values.rst \ source/reference/functions/now.rst \ source/reference/functions/number_classify.rst \ @@ -2101,6 +2111,7 @@ html_files_relative_from_locale_dir = \ html/_sources/reference/functions/highlight_full.txt \ html/_sources/reference/functions/highlight_html.txt \ html/_sources/reference/functions/html_untag.txt \ + html/_sources/reference/functions/in_records.txt \ html/_sources/reference/functions/in_values.txt \ html/_sources/reference/functions/now.txt \ html/_sources/reference/functions/number_classify.txt \ @@ -2373,6 +2384,7 @@ html_files_relative_from_locale_dir = \ html/reference/functions/highlight_full.html \ html/reference/functions/highlight_html.html \ html/reference/functions/html_untag.html \ + html/reference/functions/in_records.html \ html/reference/functions/in_values.html \ html/reference/functions/now.html \ html/reference/functions/number_classify.html \ Modified: doc/locale/ja/LC_MESSAGES/reference.po (+203 -4) =================================================================== --- doc/locale/ja/LC_MESSAGES/reference.po 2017-04-19 18:15:02 +0900 (8185658) +++ doc/locale/ja/LC_MESSAGES/reference.po 2017-04-19 18:16:19 +0900 (6bd9884) @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: 1.2.1\n" "Report-Msgid-Bugs-To: \n" -"PO-Revision-Date: 2017-04-10 14:49+0900\n" +"PO-Revision-Date: 2017-04-19 18:14+0900\n" "Last-Translator: Masafumi Yokoyama <yokoyama �� clear-code.com>\n" "Language-Team: Japanese\n" "Language: ja\n" @@ -19363,6 +19363,208 @@ msgstr "" "``html_untag`` はHTMLテキストからHTMLタグを除去したタグなしのテキストを返しま" "す。" +msgid "``in_records``" +msgstr "" + +msgid "" +"You can use ``in_records`` for using an existing table as condition " +"patterns. Each record in the existing table is treated as a condition " +"pattern." +msgstr "" +"``in_records`` を使うと既存のテーブルを条件のパターンとして使うことができま" +"す。テーブル内の各レコードがそれぞれ条件のパターンになります。" + +msgid "" +"You may be able to reduce multiple queries to only one query by " +"``in_records``." +msgstr "" +"``in_records`` を使うと複数のクエリーを1つのクエリーにできるかもしれません。" + +msgid "" +"``in_records`` is similar to :doc:`sub_filter`. Here are differences of them:" +msgstr "" +"``in_records`` は :doc:`sub_filter` に似ています。2つの違いは次の通りです。" + +msgid "" +"``sub_filter`` requires a reference column to condition table but " +"``in_records`` doesn't require." +msgstr "" +"``sub_filter`` では条件テーブルを参照するカラムが必須ですが、 ``in_records`` " +"では必要ありません。" + +msgid "" +"``sub_filter`` requires an index column for the reference column but " +"``in_records`` doesn't require." +msgstr "" +"``sub_filter`` では上述の参照カラム用のインデックスカラムが必須ですが、 " +"``in_records`` ではインデックスカラムは必要ありません。" + +msgid "" +"``sub_filter`` can use all logical operations but ``in_records`` can use " +"only AND logical operation in one pattern." +msgstr "" +"``sub_filter`` ではすべての論理演算を使えますが、 ``in_records`` では1つのパ" +"ターン内でAND論理演算しか使えません。" + +msgid "" +"``sub_filter`` can use only the value of one reference column for condition " +"but ``in_records`` can use one or more values for condition. You can use " +"multiple columns, functions and so on for multiple values." +msgstr "" +"``sub_filter`` では条件に1つの参照カラムの値しか使えませんが、 " +"``in_records`` では条件に1つ以上の値を使えます。複数の値を指定するために複数" +"のカラムや関数などを使えます。" + +msgid "" +"``sub_filter`` uses index search but ``in_records`` uses sequential search." +msgstr "" +"``sub_filter`` ではインデックスサーチを使いますが、 ``in_records`` ではシーケ" +"ンシャルサーチを使います。" + +msgid "``in_records`` has four or more parameters::" +msgstr "``in_records`` には4つ以上のパラメーターがあります。::" + +msgid "Here is a schema definition and sample data." +msgstr "使い方を示すために使うスキーマ定義とサンプルデータは以下の通りです。" + +msgid "Sample conditions:" +msgstr "サンプル条件：" + +msgid "" +"Here is a simple usage of ``in_records`` that searches by records in " +"``Conditions`` table. Each record is used as a condition:" +msgstr "" +"以下は ``Conditions`` テーブル内のレコードで検索をする ``in_records`` の使用" +"例です。各レコードを条件として使います。" + +msgid "The ``filter`` tries the following three conditions for each record:" +msgstr "この ``filter`` は各レコードに対して次の3つの条件で絞り込みます。" + +msgid "``Memos.user`` matches (``@``) ``Conditions.user_pattern``." +msgstr "" +"``Memos.user`` が ``Conditions.user_pattern`` にマッチ（ ``@`` ）するか。" + +msgid "``Memos.tag`` equals (``==``) ``Conditions.tag``." +msgstr "``Memos.tag`` は ``Conditions.tag`` と等しい（ ``==`` ）か。" + +msgid "" +"The number of characters in ``Memos._key`` is less than or equals to " +"``Conditions.max_length``." +msgstr "``Memos._key`` の文字数が ``Conditions.max_length`` 以下か。" + +msgid "" +"If at least one record in ``Conditions`` table returns true for the all " +"three conditions, the record in ``Memos`` is matched." +msgstr "" +"``Conditions`` テーブル内の少なくとも1つのレコードがこれら3つの条件すべてで真" +"を返せば ``Memos`` テーブルのそのレコードはマッチします。" + +msgid "The first record in ``Conditions`` table use the following conditions:" +msgstr "``Conditions`` テーブルの最初のレコードは次の条件を使います。" + +msgid "``Memos.user`` has ``\"lic\"`` substring." +msgstr "``Memos.user`` には部分文字列として ``\"lic\"`` がある。" + +msgid "``Memos.tag`` is ``\"groonga\"``." +msgstr "``Memos.tag`` は ``\"groonga\"`` である。" + +msgid "" +"The number of characters in ``Memos._key`` is less than or equals to ``20``." +msgstr "``Memos._key`` の文字数が ``20`` 以下である。" + +msgid "This condition matches the following records:" +msgstr "この条件は次のレコードにマッチします。" + +msgid "" +"``{\"_key\": \"Groonga is fast\", \"user\": \"alice\", \"tag\": \"groonga\"}" +"``" +msgstr "" + +msgid "The second record in ``Conditions`` table use the following conditions:" +msgstr "``Conditions`` テーブルの2つめのレコードは次の条件を使います。" + +msgid "``Memos.user`` has ``\"dav\"`` substring." +msgstr "``Memos.user`` には部分文字列として ``\"dav\"`` がある。" + +msgid "``Memos.tag`` is ``\"droonga\"``." +msgstr "``Memos.tag`` は ``\"droonga\"`` である。" + +msgid "" +"The number of characters in ``Memos._key`` is less than or equals to ``50``." +msgstr "``Memos._key`` の文字数が ``50`` 以下である。" + +msgid "" +"``{\"_key\": \"Droonga is fast\", \"user\": \"david\", \"tag\": \"droonga\"}" +"``" +msgstr "" + +msgid "The result has the all above records." +msgstr "検索結果には前述のすべてのレコードが含まれます。" + +msgid "``in_records`` requires four or more parameters." +msgstr "``in_records`` には4つ以上のパラメーターが必須です。" + +msgid "" +"``condition_table`` and tuples of ``value``, ``mode_name`` and " +"``condition_column_name`` are required. You can specify multiple tuples of " +"``value``, ``mode_name`` and ``condition_column_name``" +msgstr "" +"``condition_table`` と「 ``value`` 、 ``mode_name`` 、 " +"``condition_column_name`` 」のセットです。「 ``value`` 、 ``mode_name`` 、 " +"``condition_column_name`` 」のセットは複数回指定できます。" + +msgid "``condition_table``" +msgstr "" + +msgid "Specifies a table that has conditions as its records." +msgstr "レコードとして条件が入っているテーブルを指定します。" + +msgid "Specifies a value to be compared." +msgstr "比較対象の値を指定します。" + +msgid "``mode_name``" +msgstr "" + +msgid "" +"Specifies a mode name that specifies how to compare :ref:`in-records-value` " +"with a value of :ref:`in-records-condition-column-name`." +msgstr "" +":ref:`in-records-value` と :ref:`in-records-condition-column-name` の値の比較" +"方法（モード名）を指定します。" + +msgid "" +"See :ref:`query-default-mode` for available mode names. All mode names " +"except ``NEAR``, ``SIMILAR`` and ``SUFFIX`` are supported." +msgstr "" +"利用可能なモード名は :ref:`query-default-mode` を見てください。 ``NEAR`` 、 " +"``SIMILAR`` と ``SUFFIX`` 以外のすべてのモード名をサポートしています。" + +msgid "``condition_column_name``" +msgstr "" + +msgid "" +"Specifies a column name of :ref:`in-records-condition-table` to be used as " +"condition." +msgstr "" +"条件として使う :ref:`in-records-condition-table` のカラム名を指定します。" + +msgid "There are no optional parameter." +msgstr "省略可能な引数はありません。" + +msgid "" +"``in_records`` returns whether the record is matched one of records of the " +"specified condition table or not." +msgstr "" +"``in_records`` は対象レコードが指定した条件テーブル内の1つ以上のレコード（パ" +"ターン）にマッチするかどうかを返します。" + +msgid "" +"If the record is matched, it returns ``true``. Otherwise, it returns " +"``false``." +msgstr "" +"もし該当レコードがマッチすれば、 ``true`` を返します。そうでなければ " +"``false`` を返します。" + msgid "``in_values``" msgstr "" @@ -19381,9 +19583,6 @@ msgid "" msgstr "" "``query`` は2以上の引数 - ``target_value`` と 複数の ``value`` が必要です。" -msgid "Here is a schema definition and sample data." -msgstr "使い方を示すために使うスキーマ定義とサンプルデータは以下の通りです。" - msgid "" "Here is the simple usage of ``in_values`` function which selects the records " "- the value of ``tag`` column is \"groonga\" or \"mroonga\" or \"droonga\"." Added: doc/source/example/reference/functions/in_records/usage_search.log (+50 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/functions/in_records/usage_search.log 2017-04-19 18:16:19 +0900 (8f0a75b) @@ -0,0 +1,50 @@ +Execution example:: + + plugin_register functions/string + # [[0, 1337566253.89858, 0.000355720520019531], true] + select \ + --table Memos \ + --filter 'in_records(Conditions, \ + user, "@", "user_pattern", \ + tag, "==", "tag", \ + string_length(_key), "<=", "max_length")' \ + --sort_by _id \ + --output_columns _key,user,tag + # [ + # [ + # 0, + # 1337566253.89858, + # 0.000355720520019531 + # ], + # [ + # [ + # [ + # 2 + # ], + # [ + # [ + # "_key", + # "ShortText" + # ], + # [ + # "user", + # "ShortText" + # ], + # [ + # "tag", + # "Tags" + # ] + # ], + # [ + # "Groonga is fast", + # "alice", + # "groonga" + # ], + # [ + # "Droonga is fast", + # "david", + # "droonga" + # ] + # ] + # ] + # ] Added: doc/source/example/reference/functions/in_records/usage_setup_conditions.log (+8 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/functions/in_records/usage_setup_conditions.log 2017-04-19 18:16:19 +0900 (211d12d) @@ -0,0 +1,8 @@ +Execution example:: + + load --table Conditions + [ + {"_key": "lic + groonga", "user_pattern": "lic", "tag": "groonga", max_length: 20}, + {"_key": "dav + droonga", "user_pattern": "dav", "tag": "droonga", max_length: 50} + ] + # [[0, 1337566253.89858, 0.000355720520019531], 2] Added: doc/source/example/reference/functions/in_records/usage_setup_data.log (+11 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/functions/in_records/usage_setup_data.log 2017-04-19 18:16:19 +0900 (6a66840) @@ -0,0 +1,11 @@ +Execution example:: + + load --table Memos + [ + {"_key": "Groonga is fast", "user": "alice", "tag": "groonga"}, + {"_key": "Mroonga is fast", "user": "alice", "tag": "mroonga"}, + {"_key": "Groonga is very good!", "user": "alice", "tag": "groonga"}, + {"_key": "Droonga is fast", "user": "david", "tag": "droonga"}, + {"_key": "Groonga is a HTTP server", "user": "david", "tag": "groonga"} + ] + # [[0, 1337566253.89858, 0.000355720520019531], 5] Added: doc/source/example/reference/functions/in_records/usage_setup_schema.log (+18 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/functions/in_records/usage_setup_schema.log 2017-04-19 18:16:19 +0900 (513989b) @@ -0,0 +1,18 @@ +Execution example:: + + table_create Tags TABLE_PAT_KEY ShortText + # [[0, 1337566253.89858, 0.000355720520019531], true] + table_create Conditions TABLE_PAT_KEY ShortText + # [[0, 1337566253.89858, 0.000355720520019531], true] + column_create Conditions user_pattern COLUMN_SCALAR ShortText + # [[0, 1337566253.89858, 0.000355720520019531], true] + column_create Conditions tag COLUMN_SCALAR Tags + # [[0, 1337566253.89858, 0.000355720520019531], true] + column_create Conditions max_length COLUMN_SCALAR UInt32 + # [[0, 1337566253.89858, 0.000355720520019531], true] + table_create Memos TABLE_HASH_KEY ShortText + # [[0, 1337566253.89858, 0.000355720520019531], true] + column_create Memos user COLUMN_SCALAR ShortText + # [[0, 1337566253.89858, 0.000355720520019531], true] + column_create Memos tag COLUMN_SCALAR Tags + # [[0, 1337566253.89858, 0.000355720520019531], true] Added: doc/source/reference/functions/in_records.rst (+195 -0) 100644 =================================================================== --- /dev/null +++ doc/source/reference/functions/in_records.rst 2017-04-19 18:16:19 +0900 (eea5cce) @@ -0,0 +1,195 @@ +.. -*- rst -*- + +.. highlightlang:: none + +.. groonga-command +.. database: functions_in_records + +``in_records`` +============== + +Summary +------- + +.. versionadded:: 7.0.2 + +You can use ``in_records`` for using an existing table as condition patterns. Each record in the existing table is treated as a condition pattern. + +You may be able to reduce multiple queries to only one query by ``in_records``. + +``in_records`` is similar to :doc:`sub_filter`. Here are differences of them: + + * ``sub_filter`` requires a reference column to condition table but ``in_records`` doesn't require. + + * ``sub_filter`` requires an index column for the reference column but ``in_records`` doesn't require. + + * ``sub_filter`` can use all logical operations but ``in_records`` can use only AND logical operation in one pattern. + + * ``sub_filter`` can use only the value of one reference column for condition but ``in_records`` can use one or more values for condition. You can use multiple columns, functions and so on for multiple values. + + * ``sub_filter`` uses index search but ``in_records`` uses sequential search. + +.. _in-records-syntax: + +Syntax +------ + +``in_records`` has four or more parameters:: + + in_records(condition_table, + value1, mode1, condition_column_name1, + ..., + valueN, modeN, condition_column_nameN) + +.. _in-records-usage: + +Usage +----- + +Here is a schema definition and sample data. + +Sample schema: + +.. groonga-command +.. include:: ../../example/reference/functions/in_records/usage_setup_schema.log +.. table_create Tags TABLE_PAT_KEY ShortText +.. +.. table_create Conditions TABLE_PAT_KEY ShortText +.. column_create Conditions user_pattern COLUMN_SCALAR ShortText +.. column_create Conditions tag COLUMN_SCALAR Tags +.. column_create Conditions max_length COLUMN_SCALAR UInt32 +.. +.. table_create Memos TABLE_HASH_KEY ShortText +.. column_create Memos user COLUMN_SCALAR ShortText +.. column_create Memos tag COLUMN_SCALAR Tags + +Sample data: + +.. groonga-command +.. include:: ../../example/reference/functions/in_records/usage_setup_data.log +.. load --table Memos +.. [ +.. {"_key": "Groonga is fast", "user": "alice", "tag": "groonga"}, +.. {"_key": "Mroonga is fast", "user": "alice", "tag": "mroonga"}, +.. {"_key": "Groonga is very good!", "user": "alice", "tag": "groonga"}, +.. {"_key": "Droonga is fast", "user": "david", "tag": "droonga"}, +.. {"_key": "Groonga is a HTTP server", "user": "david", "tag": "groonga"} +.. ] + +Sample conditions: + +.. groonga-command +.. include:: ../../example/reference/functions/in_records/usage_setup_conditions.log +.. load --table Conditions +.. [ +.. {"_key": "lic + groonga", "user_pattern": "lic", "tag": "groonga", max_length: 20}, +.. {"_key": "dav + droonga", "user_pattern": "dav", "tag": "droonga", max_length: 50} +.. ] + +Here is a simple usage of ``in_records`` that searches by records in ``Conditions`` table. Each record is used as a condition: + +.. groonga-command +.. include:: ../../example/reference/functions/in_records/usage_search.log +.. plugin_register functions/string +.. select \ +.. --table Memos \ +.. --filter 'in_records(Conditions, \ +.. user, "@", "user_pattern", \ +.. tag, "==", "tag", \ +.. string_length(_key), "<=", "max_length")' \ +.. --sort_by _id \ +.. --output_columns _key,user,tag + +The ``filter`` tries the following three conditions for each record: + + * ``Memos.user`` matches (``@``) ``Conditions.user_pattern``. + + * ``Memos.tag`` equals (``==``) ``Conditions.tag``. + + * The number of characters in ``Memos._key`` is less than or equals to ``Conditions.max_length``. + +If at least one record in ``Conditions`` table returns true for the all three conditions, the record in ``Memos`` is matched. + +The first record in ``Conditions`` table use the following conditions: + + * ``Memos.user`` has ``"lic"`` substring. + + * ``Memos.tag`` is ``"groonga"``. + + * The number of characters in ``Memos._key`` is less than or equals to ``20``. + +This condition matches the following records: + + * ``{"_key": "Groonga is fast", "user": "alice", "tag": "groonga"}`` + +The second record in ``Conditions`` table use the following conditions: + + * ``Memos.user`` has ``"dav"`` substring. + + * ``Memos.tag`` is ``"droonga"``. + + * The number of characters in ``Memos._key`` is less than or equals to ``50``. + +This condition matches the following records: + + * ``{"_key": "Droonga is fast", "user": "david", "tag": "droonga"}`` + +The result has the all above records. + +.. _in-records-parameters: + +Parameters +---------- + +``in_records`` requires four or more parameters. + +.. _in-records-required-parameters: + +Required parameters +^^^^^^^^^^^^^^^^^^^ + +``condition_table`` and tuples of ``value``, ``mode_name`` and ``condition_column_name`` are required. You can specify multiple tuples of ``value``, ``mode_name`` and ``condition_column_name`` + +.. _in-records-condition-table: + +``condition_table`` +""""""""""""""""""" + +Specifies a table that has conditions as its records. + +.. _in-records-value: + +``value`` +^^^^^^^^^ + +Specifies a value to be compared. + +.. _in-records-mode-name: + +``mode_name`` +^^^^^^^^^^^^^ + +Specifies a mode name that specifies how to compare :ref:`in-records-value` with a value of :ref:`in-records-condition-column-name`. + +See :ref:`query-default-mode` for available mode names. All mode names except ``NEAR``, ``SIMILAR`` and ``SUFFIX`` are supported. + +.. _in-records-condition-column-name: + +``condition_column_name`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Specifies a column name of :ref:`in-records-condition-table` to be used as condition. + +.. _in-records-optional-parameters: + +Optional parameter +^^^^^^^^^^^^^^^^^^ + +There are no optional parameter. + +Return value +------------ + +``in_records`` returns whether the record is matched one of records of the specified condition table or not. + +If the record is matched, it returns ``true``. Otherwise, it returns ``false``. Modified: doc/source/reference/functions/query.rst (+2 -0) =================================================================== --- doc/source/reference/functions/query.rst 2017-04-19 18:15:02 +0900 (0381099) +++ doc/source/reference/functions/query.rst 2017-04-19 18:16:19 +0900 (8e8f255) @@ -160,6 +160,8 @@ by following format such as ``${TABLE}.${COLUMN}`` for query expansion. See :ref:`select-query-expander` about details. +.. _query-default-mode: + ``default_mode`` """""""""""""""" -------------- next part -------------- HTML����������������������������...Download