github/datasette
1
0
Fork 0
mirror of https://github.com/simonw/datasette.git synced 2025-12-10 16:51:24 +01:00
Code Issues Projects Releases Packages Wiki Activity

Docs for CSV export, refs #266

Browse source
This commit is contained in:
Simon Willison 2018-06-18 07:12:21 -07:00
commit bb4a9fbf36
No known key found for this signature in database
GPG key ID: 17E2DEA2588B7F52
6 changed files with 78 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

63
docs/csv_export.rst Normal file
View file

@ -0,0 +1,63 @@
.. _csv_export:
CSV Export
==========
Any Datasette table, view or custom SQL query can be exported as CSV.
To obtain the CSV representation of the table you are looking, click the "this
data as CSV" link.
You can also use the advanced export form for more control over the resulting
file, which looks like this and has the following options:
.. image:: advanced_export.png
* **download file** - instead of displaying CSV in your browser, this forces
your browser to download the CSV to your downloads directory.
* **expand labels** - if your table has any foreign key references this option
will cause the CSV to gain additional ``COLUMN_NAME_label`` columns with a
label for each foreign key derived from the linked table. `In this example
<https://latest.datasette.io/fixtures/facetable.csv?_labels=on&_size=max>`_
the ``city_id`` column is accompanied by a ``city_id_label`` column.
* **stream all records** - by default CSV files only contain the first
:ref:`config_max_returned_rows` records. This option will cause Datasette to
loop through every matching record and return them as a single CSV file.
You can try that out on https://latest.datasette.io/fixtures/facetable?_size=4
Streaming all records
---------------------
The *stream all records* option is designed to be as efficient as possible -
under the hood it takes advantage of Python 3 asyncio capabilities and
Datasette's efficient :ref:`pagination <pagination>` to stream back the full
CSV file.
Since databases can get pretty large, by default this option is capped at 100MB -
if a table returns more than 100MB of data the last line of the CSV will be a
truncation error message.
You can increase or remove this limit using the :ref:`config_max_csv_mb` config
setting. You can also disable the CSV export feature entirely using
:ref:`config_allow_csv_stream`.
A note on URLs
--------------
The default URL for the CSV representation of a table is that table with
``.csv`` appended to it:
* https://latest.datasette.io/fixtures/facetable - HTML interface
* https://latest.datasette.io/fixtures/facetable.csv - CSV export
* https://latest.datasette.io/fixtures/facetable.json - JSON API
This pattern doesn't work for tables with names that already end in ``.csv`` or
``.json``. For those tables, you can instead use the ``_format=`` querystring
parameter:
* https://latest.datasette.io/fixtures/table%2Fwith%2Fslashes.csv - HTML interface
* https://latest.datasette.io/fixtures/table%2Fwith%2Fslashes.csv?_format=csv - CSV export
* https://latest.datasette.io/fixtures/table%2Fwith%2Fslashes.csv?_format=json - JSON API