add bulk insert defaults

docs/references/api/tables_views.rst

@@ -875,6 +875,56 @@ To bulk insert JSON post an array of objects having all-matching keys
       ]
     EOF
 
+.. _bulk_insert_default:
+
+Bulk Insert with Default Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Any missing columns in the payload will be inserted as ``null`` values. To use the ``DEFAULT`` column value instead, use the ``Prefer: missing=default`` header.
+
+Having:
+
+.. code-block:: postgres
+
+  create table foo (
+    id bigint generated by default as identity primary key
+  , bar text
+  , baz int default 100
+  );
+
+A request:
+
+.. code-block:: http
+
+   POST /foo?columns=id,bar,baz HTTP/1.1
+   Content-Type: application/json
+   Prefer: return=representation
+
+.. code-block:: json
+
+  [
+    { "bar": "val1"
+    }
+  , { "bar": "val2"
+    , "baz": 15
+    }
+  ]
+
+Will result in:
+
+.. code-block:: json
+
+  [
+    { "id":  1
+    , "bar": "val1"
+    , "baz": 100
+    }
+  , { "id":  2
+    , "bar": "val2"
+    , "baz": 15
+    }
+  ]
+
 .. _specify_columns:
 
 Specifying Columns