You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8b529de
Browse filesBrowse the repository at this point in the historyBrowse files
* Row JSON now returns {"row": {...}}
/database/table/pk.json previously returned the row as the only item in
a "rows" list. It now returns it as an object in a "row" key.
Two other keys change to match: "truncated" is no longer included, since
a single row lookup cannot be truncated, and the render_cell extra is a
single object keyed by column name instead of a list of one.
Any ?_shape= option returns the same shapes as table JSON, so
?_shape=objects gives the previous format. Output renderer plugins are
still passed a rows list containing the one row.
The row edit dialog reads the new shape.
Closes#2612, closes#2137
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/changelog.rst
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,6 +16,7 @@ Unreleased
16
16
- The ``allow_csv_stream`` and ``max_csv_mb`` settings have been renamed to :ref:`setting_default_allow_stream` and :ref:`setting_max_stream_mb`, since they now apply to every format that can stream. The previous names continue to work.
17
17
- The ``allow_facet`` and ``allow_download`` settings have been renamed to :ref:`setting_default_allow_facet` and :ref:`setting_default_allow_download`, matching :ref:`setting_default_allow_sql`. The previous names continue to work. (:issue:`1410`)
18
18
- **Breaking change**: the ``datasette_allow_facet`` template variable has been removed from the table page. Custom ``table.html`` templates that use it should use ``{{ settings.default_allow_facet|tojson }}`` instead.
19
+
- **Breaking change**: the JSON for an individual row, such as ``/database/table/1.json``, now returns that row as an object in a ``"row"`` key instead of as the only item in a ``"rows"`` list. The ``"truncated"`` key has been removed from that response and the ``render_cell`` extra is now a single object. Adding any ``?_shape=`` option, such as ``?_shape=objects``, returns the same shapes as table JSON. See :ref:`json_api_row` and the :ref:`upgrade guide <upgrade_guide_v1_row_json>`. (:issue:`2612`, :issue:`2137`)
19
20
- **Breaking change**: the ``view_name`` passed to plugin hooks for SQL query pages, both arbitrary SQL and stored queries, is now ``"query"``. Template hooks such as :ref:`plugin_hook_extra_template_vars` were previously passed ``"database"`` for those pages. Output renderers were passed ``"table"`` by ``render`` and ``"database"`` by ``can_render``. See :ref:`the upgrade guide <upgrade_guide_v1_view_name_query>`.
20
21
- **Breaking change**: output renderer ``render`` functions must now return a :ref:`Response <internals_response>` object, or ``None``. Returning a dictionary with ``body``, ``content_type``, ``status_code`` and ``headers`` keys, deprecated since Datasette 0.49, is now an error. The ``"callback"`` key, the pre-0.49 name for ``"render"``, has also been removed. See :ref:`the upgrade guide <upgrade_guide_v1_renderer_response>`. (:issue:`954`)
21
22
- Output renderers whose ``render`` function accepts the undocumented ``data`` or ``args`` arguments now trigger a ``DeprecationWarning`` when Datasette starts. Those arguments will be removed before Datasette 1.0. Use the ``page`` argument in place of ``data``, and ``request.args`` in place of ``args``. (:issue:`2770`)
Copy file name to clipboardExpand all lines: docs/json_api.rst
+37-13Lines changed: 37 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -154,6 +154,34 @@ Values for named SQL parameters can be provided as additional query string param
154
154
155
155
The response uses the same default representation described above.
156
156
157
+
.. _json_api_row:
158
+
159
+
Rows
160
+
----
161
+
162
+
Every row in a table has its own JSON URL, see :ref:`RowView`. The row is returned as an object in the ``"row"`` key:
163
+
164
+
::
165
+
166
+
GET /fixtures/simple_primary_key/1.json
167
+
168
+
.. code-block:: json
169
+
170
+
{
171
+
"ok": true,
172
+
"database": "fixtures",
173
+
"table": "simple_primary_key",
174
+
"primary_keys": ["id"],
175
+
"primary_key_values": ["1"],
176
+
"query_ms": 1.2,
177
+
"row": {
178
+
"id": 1,
179
+
"content": "hello"
180
+
}
181
+
}
182
+
183
+
Pass any :ref:`?_shape= option <json_api_shapes>` to return the row using the same shapes as table JSON instead. ``?_shape=objects`` returns the table default representation, with the row as the only item in the ``"rows"`` list.
184
+
157
185
.. _json_api_shapes:
158
186
159
187
Different shapes
@@ -163,7 +191,7 @@ The ``_shape`` parameter can be used to access alternative formats for the
163
191
``rows`` key which may be more convenient for your application. There are three
164
192
options:
165
193
166
-
* ``?_shape=objects`` - ``"rows"`` is a list of JSON key/value objects - the default
194
+
* ``?_shape=objects`` - ``"rows"`` is a list of JSON key/value objects - the default for tables and queries
167
195
* ``?_shape=arrays`` - ``"rows"`` is a list of lists, where the order of values in each list matches the order of the columns
168
196
* ``?_shape=array`` - a JSON array of objects - effectively just the ``"rows"`` key from the default representation
169
197
* ``?_shape=array&_nl=on`` - a newline-separated list of JSON objects
@@ -954,22 +982,18 @@ The following extras are available for row JSON responses.
954
982
``render_cell``
955
983
Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
956
984
957
-
The ``render_cell`` array has one item for the requested row. The object is keyed by column name. Only columns whose rendered value differs from the default are included.
985
+
The ``render_cell`` object is keyed by column name. Only columns whose rendered value differs from the default are included. If a ``?_shape=`` is specified ``render_cell`` is instead a list with one item, matching the ``rows`` list.
Copy file name to clipboardExpand all lines: docs/upgrade_guide.md
+21Lines changed: 21 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,6 +43,27 @@ if view_name in ("database", "query"):
43
43
...
44
44
```
45
45
46
+
(upgrade_guide_v1_row_json)=
47
+
### Row JSON returns a single `"row"` object
48
+
49
+
The JSON for an individual row, such as `/databasename/tablename/1.json`, previously returned that row as the only item in a `"rows"` list. It now returns it as an object in a `"row"` key:
50
+
51
+
```json
52
+
{
53
+
"ok": true,
54
+
"row": {
55
+
"id": 1,
56
+
"content": "hello"
57
+
}
58
+
}
59
+
```
60
+
61
+
Two other keys changed to match. The response no longer includes `"truncated"`, which was always `false`. If you request `?_extra=render_cell`, the `"render_cell"` key is now a single object keyed by column name instead of a list containing one object.
62
+
63
+
Add `?_shape=objects` to the URL to get the previous format, with a `"rows"` list containing that row, a `"truncated"` key and `"render_cell"` as a list. Any other `?_shape=` option returns the same shape as table JSON. See {ref}`json_api_row`.
64
+
65
+
Output renderer plugins are not affected: on row pages they are still passed a `rows` list containing the one row.
0 commit comments