null+****@clear*****
null+****@clear*****
2012年 5月 20日 (日) 20:32:30 JST
Kouhei Sutou 2012-05-20 20:32:30 +0900 (Sun, 20 May 2012) New Revision: 8b7da4f82fa3b700ba64b6e5898cda10e1af5290 Log: doc: add output_columns and sortby Added files: doc/source/example/commands/select/output_columns_asterisk.log doc/source/example/commands/select/output_columns_simple.log doc/source/example/commands/select/sort_by_descending.log doc/source/example/commands/select/sort_by_score_with_query.log doc/source/example/commands/select/sort_by_simple.log Modified files: doc/source/commands/select.txt Modified: doc/source/commands/select.txt (+58 -9) =================================================================== --- doc/source/commands/select.txt 2012-05-20 20:08:57 +0900 (785cc05) +++ doc/source/commands/select.txt 2012-05-20 20:32:30 +0900 (e5a4908) @@ -73,7 +73,7 @@ Here are a schema definition and sample data to show usage. .. "n_likes": 3}, .. {"_key": "Good-bye Tritonn", .. "content": "I also migrated all Tritonn system!", -.. "n_likes": 6} +.. "n_likes": 3} .. ] There is a table, ``Entries``, for blog entries. An entry has title, @@ -538,24 +538,73 @@ Output related parameters ``output_columns`` """""""""""""""""" -TODO: write in English and add example. +It specifies output columns separated by ``,``. + +Here is a simple ``output_columns`` usage example. + +.. groonga-command +.. include:: ../example/commands/select/output_columns_simple.log +.. select Entries --output_columns '_id, _key' --limit 1 + +The ``select`` command just outputs ``_id`` and ``_key`` column +values. -出力するカラム名のリストをカンマ(',')区切りで指定します。 +``*`` is a special value. It means that all columns that are not +:doc:``/pseudo_column``. -アスタリスク('*')を指定すると、全てのカラムが指定されたものとみなされます。または、script形式のgrn_expr文字列を指定します。 (デフォルトは、'_id, _key, \*') +Here is a ``*`` usage example. + +.. groonga-command +.. include:: ../example/commands/select/output_columns_asterisk.log +.. select Entries --output_columns '_key, *' --limit 1 + +The ``select`` command outputs ``_key`` pseudo column, ``content`` +column and ``n_likes`` column values but doesn't output ``_id`` pseudo +column value. + +The default value is ``_id, _key, *``. It means that all column +values except ``_score`` are outputted. ``sortby`` """""""""" -TODO: write in English and add example. +It specifies sort keys separated by ``,``. Each sort key is column +name. -ソートキーとなるカラム名のリストをカンマ(',')区切りで指定します。:: +Here is a simple ``sortby`` usage example. - [-]カラム名1, [-]カラム名2, [-]カラム名3, ... +.. groonga-command +.. include:: ../example/commands/select/sort_by_simple.log +.. select Entries --sortby 'n_likes, _id' + +The ``select`` command sorts by ``n_likes`` column value in ascending +order. For records that has the same ``n_likes`` are sorted by ``_id`` +in ascending order. ``"Good-bye Senna"`` and ``"Good-bye Tritonn"`` +are the case. + +If you want to sort in descending order, add ``-`` before column name. + +Here is a descending order ``sortby`` usage example. + +.. groonga-command +.. include:: ../example/commands/select/sort_by_descending.log +.. select Entries --sortby '-n_likes, _id' + +The ``select`` command sorts by ``n_likes`` column value in descending +order. But ascending order is used for sorting by ``_id``. + +You can use ``_score`` pseudo column in ``sortby`` if you use +``query`` or ``filter`` parameter. + +.. groonga-command +.. include:: ../example/commands/select/sort_by_score_with_query.log +.. select Entries --match_columns content --query fast --sortby -_score --output_columns '_key, _score' -カラム名1の値でソートし、値が同一である場合はカラム名2でソート、と順次比較を行いソートします。カラム名の前に - を付加した場合は降順にソートします。付加しない場合には昇順にソートします。 +The ``select`` command sorts matched records by hit score in +descending order and outputs entry key and hit score. -query引数またはfilter引数を指定した場合はカラム名に'_score'を使えます。'_score'を指定することでスコアでソートすることができます。query引数もfilter引数も指定していない状態で'_score'を指定するとエラーになります。 +If you use ``_score`` without ``query`` nor ``filter`` parameters, +it's just ignored but get a warning in log file. ``offset`` """""""""" Added: doc/source/example/commands/select/output_columns_asterisk.log (+36 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/commands/select/output_columns_asterisk.log 2012-05-20 20:32:30 +0900 (0caca43) @@ -0,0 +1,36 @@ +Execution example:: + + select Entries --output_columns '_key, *' --limit 1 + # [ + # [ + # 0, + # 1337513353.85526, + # 0.000221729278564453 + # ], + # [ + # [ + # [ + # 5 + # ], + # [ + # [ + # "_key", + # "ShortText" + # ], + # [ + # "content", + # "Text" + # ], + # [ + # "n_likes", + # "UInt32" + # ] + # ], + # [ + # "The first post!", + # "Welcome! This is my first post!", + # 5 + # ] + # ] + # ] + # ] Added: doc/source/example/commands/select/output_columns_simple.log (+31 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/commands/select/output_columns_simple.log 2012-05-20 20:32:30 +0900 (5ba8747) @@ -0,0 +1,31 @@ +Execution example:: + + select Entries --output_columns '_id, _key' --limit 1 + # [ + # [ + # 0, + # 1337513353.65307, + # 0.000175237655639648 + # ], + # [ + # [ + # [ + # 5 + # ], + # [ + # [ + # "_id", + # "UInt32" + # ], + # [ + # "_key", + # "ShortText" + # ] + # ], + # [ + # 1, + # "The first post!" + # ] + # ] + # ] + # ] Added: doc/source/example/commands/select/sort_by_descending.log (+65 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/commands/select/sort_by_descending.log 2012-05-20 20:32:30 +0900 (2ded74b) @@ -0,0 +1,65 @@ +Execution example:: + + select Entries --sortby '-n_likes, _id' + # [ + # [ + # 0, + # 1337513354.26027, + # 0.000281333923339844 + # ], + # [ + # [ + # [ + # 5 + # ], + # [ + # [ + # "_id", + # "UInt32" + # ], + # [ + # "_key", + # "ShortText" + # ], + # [ + # "content", + # "Text" + # ], + # [ + # "n_likes", + # "UInt32" + # ] + # ], + # [ + # 3, + # "Mroonga", + # "I also started to use mroonga. It's also very fast! Really fast!", + # 15 + # ], + # [ + # 2, + # "Groonga", + # "I started to use groonga. It's very fast!", + # 10 + # ], + # [ + # 1, + # "The first post!", + # "Welcome! This is my first post!", + # 5 + # ], + # [ + # 4, + # "Good-bye Senna", + # "I migrated all Senna system!", + # 3 + # ], + # [ + # 5, + # "Good-bye Tritonn", + # "I also migrated all Tritonn system!", + # 3 + # ] + # ] + # ] + # ] Added: doc/source/example/commands/select/sort_by_score_with_query.log (+35 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/commands/select/sort_by_score_with_query.log 2012-05-20 20:32:30 +0900 (eac862b) @@ -0,0 +1,35 @@ +Execution example:: + + select Entries --match_columns content --query fast --sortby -_score --output_columns '_key, _score' + # [ + # [ + # 0, + # 1337513354.46427, + # 0.000624895095825195 + # ], + # [ + # [ + # [ + # 2 + # ], + # [ + # [ + # "_key", + # "ShortText" + # ], + # [ + # "_score", + # "Int32" + # ] + # ], + # [ + # "Mroonga", + # 2 + # ], + # [ + # "Groonga", + # 1 + # ] + # ] + # ] + # ] Added: doc/source/example/commands/select/sort_by_simple.log (+65 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/commands/select/sort_by_simple.log 2012-05-20 20:32:30 +0900 (b7fc407) @@ -0,0 +1,65 @@ +Execution example:: + + select Entries --sortby 'n_likes, _id' + # [ + # [ + # 0, + # 1337513354.0577, + # 0.000392436981201172 + # ], + # [ + # [ + # [ + # 5 + # ], + # [ + # [ + # "_id", + # "UInt32" + # ], + # [ + # "_key", + # "ShortText" + # ], + # [ + # "content", + # "Text" + # ], + # [ + # "n_likes", + # "UInt32" + # ] + # ], + # [ + # 4, + # "Good-bye Senna", + # "I migrated all Senna system!", + # 3 + # ], + # [ + # 5, + # "Good-bye Tritonn", + # "I also migrated all Tritonn system!", + # 3 + # ], + # [ + # 1, + # "The first post!", + # "Welcome! This is my first post!", + # 5 + # ], + # [ + # 2, + # "Groonga", + # "I started to use groonga. It's very fast!", + # 10 + # ], + # [ + # 3, + # "Mroonga", + # "I also started to use mroonga. It's also very fast! Really fast!", + # 15 + # ] + # ] + # ] + # ]