Add --key option to insert/upsert/bulk for importing JSON lists nested under a top-level key

Fixes #489. JSON shaped like {"List": [...]} previously required piping through jq .List first; --key lets insert/upsert/bulk select the array directly.

docs/cli-reference.rst

@@ -293,6 +293,9 @@ See :ref:`cli_inserting_data`, :ref:`cli_insert_csv_tsv`, :ref:`cli_insert_unstr
       --flatten                 Flatten nested JSON objects, so {"a": {"b": 1}}
                                 becomes {"a_b": 1}
       --nl                      Expect newline-delimited JSON
+      --key TEXT                If input is a JSON object, import the array of
+                                records under this key, e.g. --key results for
+                                {"results": [...]}
       -c, --csv                 Expect CSV input
       --tsv                     Expect TSV input
       --empty-null              Treat empty strings as NULL
@@ -357,6 +360,9 @@ See :ref:`cli_upsert`.
       --flatten                 Flatten nested JSON objects, so {"a": {"b": 1}}
                                 becomes {"a_b": 1}
       --nl                      Expect newline-delimited JSON
+      --key TEXT                If input is a JSON object, import the array of
+                                records under this key, e.g. --key results for
+                                {"results": [...]}
       -c, --csv                 Expect CSV input
       --tsv                     Expect TSV input
       --empty-null              Treat empty strings as NULL
@@ -412,6 +418,9 @@ See :ref:`cli_bulk`.
       --flatten              Flatten nested JSON objects, so {"a": {"b": 1}} becomes
                              {"a_b": 1}
       --nl                   Expect newline-delimited JSON
+      --key TEXT             If input is a JSON object, import the array of records
+                             under this key, e.g. --key results for {"results":
+                             [...]}
       -c, --csv              Expect CSV input
       --tsv                  Expect TSV input
       --empty-null           Treat empty strings as NULL

docs/cli.rst

@@ -1200,6 +1200,24 @@ You can add the ``--analyze`` option to run ``ANALYZE`` against the table after
 .. note::
     In Python: :ref:`table.insert_all() <python_api_bulk_inserts>`  CLI reference: :ref:`sqlite-utils insert <cli_ref_insert>`
 
+If your JSON is a single object with the list of records nested under a key, use ``--key`` to select it.
+For example, if ``dogs.json`` looks like this:
+
+.. code-block:: json
+
+    {
+        "List": [
+            {"id": 1, "name": "Cleo"},
+            {"id": 2, "name": "Pancakes"}
+        ]
+    }
+
+You can import the records under the ``List`` key like so:
+
+.. code-block:: bash
+
+    sqlite-utils insert dogs.db dogs dogs.json --key List
+
 .. _cli_inserting_data_binary:
 
 Inserting binary data