API for bulk inserts, closes #1866

docs/cli-reference.rst

@@ -213,6 +213,8 @@ These can be passed to ``datasette serve`` using ``datasette serve --setting nam
                                    (default=100)
       max_returned_rows            Maximum rows that can be returned from a table or
                                    custom query (default=1000)
+      max_insert_rows              Maximum rows that can be inserted at a time using
+                                   the bulk insert API (default=1000)
       num_sql_threads              Number of threads in the thread pool for
                                    executing SQLite queries (default=3)
       sql_time_limit_ms            Time limit for a SQL query in milliseconds

docs/json_api.rst

@@ -465,11 +465,13 @@ Datasette provides a write API for JSON data. This is a POST-only API that requi
 
 .. _TableInsertView:
 
-Inserting a single row
-~~~~~~~~~~~~~~~~~~~~~~
+Inserting rows
+~~~~~~~~~~~~~~
 
 This requires the :ref:`permissions_insert_row` permission.
 
+A single row can be inserted using the ``"row"`` key:
+
 ::
 
     POST /<database>/<table>/-/insert
@@ -495,3 +497,45 @@ If successful, this will return a ``201`` status code and the newly inserted row
             }
         ]
     }
+
+To insert multiple rows at a time, use the same API method but send a list of dictionaries as the ``"rows"`` key:
+
+::
+
+    POST /<database>/<table>/-/insert
+    Content-Type: application/json
+    Authorization: Bearer dstok_<rest-of-token>
+    {
+        "rows": [
+            {
+                "column1": "value1",
+                "column2": "value2"
+            },
+            {
+                "column1": "value3",
+                "column2": "value4"
+            }
+        ]
+    }
+
+If successful, this will return a ``201`` status code and an empty ``{}`` response body.
+
+To return the newly inserted rows, add the ``"return_rows": true`` key to the request body:
+
+.. code-block:: json
+
+    {
+        "rows": [
+            {
+                "column1": "value1",
+                "column2": "value2"
+            },
+            {
+                "column1": "value3",
+                "column2": "value4"
+            }
+        ],
+        "return_rows": true
+    }
+
+This will return the same ``"inserted"`` key as the single row example above. There is a small performance penalty for using this option.

docs/settings.rst

@@ -96,6 +96,17 @@ You can increase or decrease this limit like so::
 
     datasette mydatabase.db --setting max_returned_rows 2000
 
+.. _setting_max_insert_rows:
+
+max_insert_rows
+~~~~~~~~~~~~~~~
+
+Maximum rows that can be inserted at a time using the bulk insert API, see :ref:`TableInsertView`. Defaults to 100.
+
+You can increase or decrease this limit like so::
+
+    datasette mydatabase.db --setting max_insert_rows 1000
+
 .. _setting_num_sql_threads:
 
 num_sql_threads