Kouhei Sutou
null+****@clear*****
Tue Aug 28 17:15:27 JST 2018
Kouhei Sutou 2018-08-28 17:15:27 +0900 (Tue, 28 Aug 2018) Revision: d8ec41e149137d971293d4d6e2ec0a521cfd167c https://github.com/groonga/groonga/commit/d8ec41e149137d971293d4d6e2ec0a521cfd167c Message: doc load: update Added files: doc/source/example/reference/commands/load/usage_lock_table.log doc/source/example/reference/commands/load/usage_parameter.log doc/source/example/reference/commands/load/usage_setup.log doc/source/example/reference/commands/load/usage_standard_input.log Modified files: doc/files.am doc/source/reference/commands/load.rst doc/update_execution_example.py Modified: doc/files.am (+8 -0) =================================================================== --- doc/files.am 2018-08-28 10:10:27 +0900 (0955c1901) +++ doc/files.am 2018-08-28 17:15:27 +0900 (b5a6e2d23) @@ -102,6 +102,10 @@ 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/load/usage_lock_table.log \ + $(top_srcdir)/doc/source/example/reference/commands/load/usage_parameter.log \ + $(top_srcdir)/doc/source/example/reference/commands/load/usage_setup.log \ + $(top_srcdir)/doc/source/example/reference/commands/load/usage_standard_input.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 \ @@ -1080,6 +1084,10 @@ 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/load/usage_lock_table.log \ + source/example/reference/commands/load/usage_parameter.log \ + source/example/reference/commands/load/usage_setup.log \ + source/example/reference/commands/load/usage_standard_input.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 \ Added: doc/source/example/reference/commands/load/usage_lock_table.log (+7 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/commands/load/usage_lock_table.log 2018-08-28 17:15:27 +0900 (a23a03edc) @@ -0,0 +1,7 @@ +Execution example:: + + load --table Entries --lock_table yes + [ + {"_key": "Groonga", "content": "It's very fast!!"} + ] + # [[0, 1337566253.89858, 0.000355720520019531], 1] Added: doc/source/example/reference/commands/load/usage_parameter.log (+6 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/commands/load/usage_parameter.log 2018-08-28 17:15:27 +0900 (2c4d3f36b) @@ -0,0 +1,6 @@ +Execution example:: + + load \ + --table Entries \ + --values "[{\"_key\":\"Groonga\",\"content\":\"It's very fast!!\"}]" + # [[0, 1337566253.89858, 0.000355720520019531], 1] Added: doc/source/example/reference/commands/load/usage_setup.log (+6 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/commands/load/usage_setup.log 2018-08-28 17:15:27 +0900 (abb8a520d) @@ -0,0 +1,6 @@ +Execution example:: + + table_create Entries TABLE_HASH_KEY ShortText + # [[0, 1337566253.89858, 0.000355720520019531], true] + column_create Entries content COLUMN_SCALAR Text + # [[0, 1337566253.89858, 0.000355720520019531], true] Added: doc/source/example/reference/commands/load/usage_standard_input.log (+7 -0) 100644 =================================================================== --- /dev/null +++ doc/source/example/reference/commands/load/usage_standard_input.log 2018-08-28 17:15:27 +0900 (9b32ec60b) @@ -0,0 +1,7 @@ +Execution example:: + + load --table Entries + [ + {"_key": "Groonga", "content": "It's very fast!!"} + ] + # [[0, 1337566253.89858, 0.000355720520019531], 1] Modified: doc/source/reference/commands/load.rst (+208 -41) =================================================================== --- doc/source/reference/commands/load.rst 2018-08-28 10:10:27 +0900 (a751f221c) +++ doc/source/reference/commands/load.rst 2018-08-28 17:15:27 +0900 (39196b7f8) @@ -16,85 +16,252 @@ Summary Syntax ------ -:: - load values table [columns [ifexists [input_type]]] +The required parameters are only ``values`` and ``table``. Other +parameters are optional:: + + load values + table + [columns=null] + [ifexists=null] + [input_type=json] + [each=null] + [output_ids=no] + [output_errors=no] + [lock_table=no] + +This command is a special command. Other commands need to pass all +parameters to one line but this command can accept ``values`` as +followed data. + +If you use command line style, you can pass ``values`` like the +following:: + + load --table Bookmarks + [ + {"_key": "http://groonga.org/", "title": "Groonga"}, + {"_key": "http://mroonga.org/", "title": "Mroonga"} + ] + +``[...]`` is value of ``values``. + +If you use HTTP style, you can pass ``values`` as body:: + + % curl \ + --request POST \ + --header "Content-Type: application/json" \ + --data-raw '[{"_key": "http://groonga.org/"}]' \ + http://localhost:10041/d/load?table=Bookmarks" + + +Usage +----- + +Here are schema definitions to show usage: + +.. groonga-command +.. include:: ../../example/reference/commands/load/usage_setup.log +.. table_create Entries TABLE_HASH_KEY ShortText +.. column_create Entries content COLUMN_SCALAR Text + +Here is an example to add records to ``Entries`` table by parameter: + +.. groonga-command +.. include:: ../../example/reference/commands/load/usage_parameter.log +.. load \ +.. --table Entries \ +.. --values "[{\"_key\":\"Groonga\",\"content\":\"It's very fast!!\"}]" + +Here is an example to add records to ``Entries`` table from standard input: + +.. groonga-command +.. include:: ../../example/reference/commands/load/usage_standard_input.log +.. load --table Entries +.. [ +.. {"_key": "Groonga", "content": "It's very fast!!"} +.. ] + +Here is an example to lock table while updating columns: + +.. groonga-command +.. include:: ../../example/reference/commands/load/usage_lock_table.log +.. load --table Entries --lock_table yes +.. [ +.. {"_key": "Groonga", "content": "It's very fast!!"} +.. ] Parameters ---------- -This section describes all parameters. +This section describes all parameters. Parameters are categorized. + +Required parameters +^^^^^^^^^^^^^^^^^^^ + +There are some required parameters. + +.. _load-values: ``values`` +"""""""""" + +Specifies values to be loaded. + +Values should satisfy ``input_type`` format. If you specify ``json`` +as ``input_type``, you can choose a format from below: + +Bracket style:: - Specifies values loaded to records. - Values should satisfy ``input_type`` format. - If you specify "json" as ``input_type``, you can choose a format from below: + [ + [COLUMN_NAME1, COLUMN_NAME2, ...], + [VALUE1, VALUE2, ...], + [VALUE1, VALUE2, ...], + ... + ] - ``Format 1:`` - [[COLUMN_NAME1, COLUMN_NAME2,..], [VALUE1, VALUE2,..], [VALUE1, VALUE2,..],..] +Brace style:: - ``Format 2:`` - [{COLUMN_NAME1: VALUE1, COLUMN_NAME2: VALUE2}, {COLUMN_NAME1: VALUE1, COLUMN_NAME2: VALUE2},..] + [ + {"COLUMN_NAME1": VALUE1, "COLUMN_NAME2": VALUE2, ...}, + {"COLUMN_NAME1": VALUE1, "COLUMN_NAME2": VALUE2, ...}, + ... + ] - ``[COLUMN_NAME1, COLUMN_NAME2,..]`` format in ``Format 1`` is effective only when ``columns`` parameter isn't specified. +``[COLUMN_NAME1, COLUMN_NAME2, ...]`` in bracket style is effective +only when ref:`load-columns` parameter isn't specified. - When a target table contains primary key, you must specify ``_key`` column (pseudo column associated primary key) as the one of ``COLUMN_NAME``. +When a target table contains primary key, you must specify ``_key`` +column (pseudo column associated primary key) as the one of +``COLUMN_NAME``. - If ``values`` isn't specified any values, they are read from the standard input until all opened parenthes match their closed ones. - You don't have to enclose them with single-quotes or double-quotes, but if you specified values with ``values`` parameter, you should do. +If ``values`` isn't specified any values, they are read from the +standard input in command line style or body in HTTP style. - In following values, you also don't have to enclose any spaces (' ') with single-quotes or double-quotes. +.. _load-table: ``table`` +""""""""" + +Specifies a table name you want to add records. + +Optional parameters +^^^^^^^^^^^^^^^^^^^ + +There are some optional parameters. - Specifies a table name you want to add records. +.. _load-columns: ``columns`` +""""""""""" - Specifies column names in added records with comma separations. +Specifies column names in added records with comma separations. + +.. _load-ifexists: ``ifexists`` +"""""""""""" + +Specifies executed expression in +:doc:`/reference/grn_expr/script_syntax` when the same primary key as +added records already exists in your table. + +If ``ifexists`` specifies expression and its value is ``true``, values +in other (all columns excluding ``_key`` column) columns is updated. - Specifies executed ``grn_expr`` string when the same primary key - as added records already exists in your table. - If ``ifexists`` specifies ``grn_expr`` string (default: true) and - its value is true, values in other (all columns excluding ``_key`` - column) columns is updated. +.. _load-input-type: ``input_type`` +"""""""""""""" - Specifies an input format for ``values``. It supports JSON only. +Specifies an input format for ``values``. It supports only ``json`` +for now. It means format of ``values`` is JSON. -Usage ------ +The default value is ``json``. -Here is an example to add records to "Entry" table. :: +.. _load-each: - load --table Entry --input_type json --values [{\"_key\":\"Groonga\",\"body\":\"It's very fast!!\"}] +``each`` +"""""""" - [1] +TODO -This example shows how to add values from standard input. :: +.. _load-output-ids: - load --table Entry --input_type json - [ - {"_key": "Groonga", "body": "It's very fast!!"} - ] +``output_ids`` +"""""""""""""" - [1] +TODO -Return value ------------- +.. _load-output-errors: + +``output_errors`` +""""""""""""""""" + +TODO + +.. _load-lock-table: + +``lock_table`` +"""""""""""""" + +Specifies whether locking table while updating columns. -JSON format -^^^^^^^^^^^ +The default is ``no``. - ``load`` returns the number of added records such as :: +If you may run destructive commands such as ``load``, ``delete`` and +so on concurrently, it may break database. For example, if you're +updating a record by ``load`` and deleting the updating record by +``delete``, the ``load`` may refer the delete record. + +You can guard the update conflict by locking the target table but it +reduces load performance. + +If you specify ``yes`` to this parameter, you can lock the target +table while updating columns. Here is the update sequence of each +record: + + 1. Lock the target table + 2. Add or refer a record to the target table + 3. Unlock the target table + 4. Lock the target table when ``lock_table`` is ``yes`` + 5. Update columns of the target record + 6. Unlock the target table when ``lock_table`` is ``yes`` + +Return value +------------ - [NUMBER] +The command returns a response with the following format:: + + [THE_NUMBER_OF_LOADED_RECORDS] + +The command returns a response with the following format with +:doc:`/reference/command/command_version` 3 or later:: + + { + "n_loaded_records": THE_NUMBER_OF_LOADED_RECORDS, + "loaded_ids": [ + LOADED_RECORD'S_ID1, + LOADED_RECORD'S_ID2, + ... + ], + "errors": [ + { + "return_code": RETURN_CODE_FOR_1ST_RECORD, + "message": MESSAGE_FOR_1ST_RECORD + }, + { + "return_code": RETURN_CODE_FOR_2ND_RECORD, + "message": MESSAGE_FOR_2ND_RECORD + }, + ... + ] + } + +``loaded_ids`` is only included when :ref:`load-output-ids` is ``yes``. + +``errors`` is only included when :ref:`load-output-errors` is ``yes``. See also -------- -:doc:`/reference/grn_expr` + * :doc:`/reference/grn_expr/script_syntax` Modified: doc/update_execution_example.py (+2 -1) =================================================================== --- doc/update_execution_example.py 2018-08-28 10:10:27 +0900 (e78eb2154) +++ doc/update_execution_example.py 2018-08-28 17:15:27 +0900 (1f3440178) @@ -111,7 +111,8 @@ def execmd(command, fout): fout.write(formatted_command_line) is_load_data_end = re.match("^\]", command) if is_load_command: - return + if not re.search(" --values ", command): + return if not is_command and not is_load_data_end: return output_buffer = "" -------------- next part -------------- HTML����������������������������... URL: https://lists.osdn.me/mailman/archives/groonga-commit/attachments/20180828/f10641fa/attachment-0001.htm
