diff --git a/docs/binary_data.png b/docs/binary_data.png new file mode 100644 index 0000000000..2c5d0bdda8 Binary files /dev/null and b/docs/binary_data.png differ diff --git a/docs/binary_data.rst b/docs/binary_data.rst new file mode 100644 index 0000000000..593cf78d08 --- /dev/null +++ b/docs/binary_data.rst @@ -0,0 +1,68 @@ +.. _binary: + +============= + Binary data +============= + +SQLite tables can contain binary data in ``BLOB`` columns. + +Datasette includes special handling for these binary values. The Datasette interface detects binary values and provides a link to download their content, for example on https://latest.datasette.io/fixtures/binary_data + +.. image:: binary_data.png + :width: 311px + :alt: Screenshot showing download links next to binary data in the table view + +Binary data is represented in ``.json`` exports using Base64 encoding. + +https://latest.datasette.io/fixtures/binary_data.json?_shape=array + +.. code-block:: json + + [ + { + "rowid": 1, + "data": { + "$base64": true, + "encoded": "FRwCx60F/g==" + } + }, + { + "rowid": 2, + "data": { + "$base64": true, + "encoded": "FRwDx60F/g==" + } + }, + { + "rowid": 3, + "data": null + } + ] + +.. _binary_linking: + +Linking to binary downloads +--------------------------- + +The ``.blob`` output format is used to return binary data. It requires a ``_blob_column=`` querystring argument specifying which BLOB column should be downloaded, for example: + +https://latest.datasette.io/fixtures/binary_data/1.blob?_blob_column=data + +This output format can also be used to return binary data from an arbitrary SQL query. Since such queries do not specify an exact row, an additional ``?_blob_hash=`` parameter can be used to specify the SHA-256 hash of the value that is being linked to. + +Consider the query ``select data from binary_data`` - `demonstrated here `__. + +That page links to the binary value downloads. Those links look like this: + +https://latest.datasette.io/fixtures.blob?sql=select+data+from+binary_data&_blob_column=data&_blob_hash=f3088978da8f9aea479ffc7f631370b968d2e855eeb172bea7f6c7a04262bb6d + +These ``.blob`` links are also returned in the ``.csv`` exports Datasette provides for binary tables and queries, since the CSV format does not have a mechanism for representing binary data. + +Binary plugins +-------------- + +Several Datasette plugins are available that change the way Datasette treats binary data. + +- `datasette-render-binary `__ modifies +- https://github.com/simonw/datasette-render-images +- https://github.com/simonw/datasette-media \ No newline at end of file diff --git a/docs/changelog.rst b/docs/changelog.rst index 262400c88b..fc566a3796 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -9,7 +9,7 @@ Changelog 0.51a2 (2020-10-30) ------------------- -- New :ref:`plugin_hook_load_template` plugin hook. (`#1042 `__) +- New ``load_template`` plugin hook. (`#1042 `__) - New :ref:`permissions_debug_menu` permission. (`#1068 `__) .. _v0_51_a1: diff --git a/docs/csv_export.rst b/docs/csv_export.rst index 9b7f81883e..b5cc599ab6 100644 --- a/docs/csv_export.rst +++ b/docs/csv_export.rst @@ -1,6 +1,6 @@ .. _csv_export: -CSV Export +CSV export ========== Any Datasette table, view or custom SQL query can be exported as CSV. diff --git a/docs/index.rst b/docs/index.rst index 9096efd948..6b55da8c82 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,6 +46,7 @@ Contents authentication performance csv_export + binary_data facets full_text_search spatialite