id,page,ref,title,content,breadcrumbs,references
json_api:expand-foreign-keys,json_api,expand-foreign-keys,Expanding foreign key references,"Datasette can detect foreign key relationships and resolve those references into
labels. The HTML interface does this by default for every detected foreign key
column - you can turn that off using ?_labels=off .
You can request foreign keys be expanded in JSON using the _labels=on or
_label=COLUMN special query string parameters. Here's what an expanded row
looks like:
[
{
""rowid"": 1,
""TreeID"": 141565,
""qLegalStatus"": {
""value"": 1,
""label"": ""Permitted Site""
},
""qSpecies"": {
""value"": 1,
""label"": ""Myoporum laetum :: Myoporum""
},
""qAddress"": ""501X Baker St"",
""SiteOrder"": 1
}
]
The column in the foreign key table that is used for the label can be specified
in metadata.json - see Specifying the label column for a table .","[""JSON API""]",[]
json_api:id2,json_api,id2,Table arguments,The Datasette table view takes a number of special query string arguments.,"[""JSON API""]",[]
json_api:json-api-discover-alternate,json_api,json-api-discover-alternate,Discovering the JSON for a page,"Most of the HTML pages served by Datasette provide a mechanism for discovering their JSON equivalents using the HTML link mechanism.
You can find this near the top of the source code of those pages, looking like this:
The JSON URL is also made available in a Link HTTP header for the page:
Link: https://latest.datasette.io/fixtures/sortable.json; rel=""alternate""; type=""application/json+datasette""","[""JSON API""]",[]
json_api:json-api-pagination,json_api,json-api-pagination,Pagination,"The default JSON representation includes a ""next_url"" key which can be used to access the next page of results. If that key is null or missing then it means you have reached the final page of results.
Other representations include pagination information in the link HTTP header. That header will look something like this:
link: ; rel=""next""
Here is an example Python function built using requests that returns a list of all of the paginated items from one of these API endpoints:
def paginate(url):
items = []
while url:
response = requests.get(url)
try:
url = response.links.get(""next"").get(""url"")
except AttributeError:
url = None
items.extend(response.json())
return items","[""JSON API""]","[{""href"": ""https://requests.readthedocs.io/"", ""label"": ""requests""}]"
json_api:json-api-shapes,json_api,json-api-shapes,Different shapes,"The default JSON representation of data from a SQLite table or custom query
looks like this:
{
""database"": ""sf-trees"",
""table"": ""qSpecies"",
""columns"": [
""id"",
""value""
],
""rows"": [
[
1,
""Myoporum laetum :: Myoporum""
],
[
2,
""Metrosideros excelsa :: New Zealand Xmas Tree""
],
[
3,
""Pinus radiata :: Monterey Pine""
]
],
""truncated"": false,
""next"": ""100"",
""next_url"": ""http://127.0.0.1:8001/sf-trees-02c8ef1/qSpecies.json?_next=100"",
""query_ms"": 1.9571781158447266
}
The columns key lists the columns that are being returned, and the rows
key then returns a list of lists, each one representing a row. The order of the
values in each row corresponds to the columns.
The _shape parameter can be used to access alternative formats for the
rows key which may be more convenient for your application. There are three
options:
?_shape=arrays - ""rows"" is the default option, shown above
?_shape=objects - ""rows"" is a list of JSON key/value objects
?_shape=array - an JSON array of objects
?_shape=array&_nl=on - a newline-separated list of JSON objects
?_shape=arrayfirst - a flat JSON array containing just the first value from each row
?_shape=object - a JSON object keyed using the primary keys of the rows
_shape=objects looks like this:
{
""database"": ""sf-trees"",
...
""rows"": [
{
""id"": 1,
""value"": ""Myoporum laetum :: Myoporum""
},
{
""id"": 2,
""value"": ""Metrosideros excelsa :: New Zealand Xmas Tree""
},
{
""id"": 3,
""value"": ""Pinus radiata :: Monterey Pine""
}
]
}
_shape=array looks like this:
[
{
""id"": 1,
""value"": ""Myoporum laetum :: Myoporum""
},
{
""id"": 2,
""value"": ""Metrosideros excelsa :: New Zealand Xmas Tree""
},
{
""id"": 3,
""value"": ""Pinus radiata :: Monterey Pine""
}
]
_shape=array&_nl=on looks like this:
{""id"": 1, ""value"": ""Myoporum laetum :: Myoporum""}
{""id"": 2, ""value"": ""Metrosideros excelsa :: New Zealand Xmas Tree""}
{""id"": 3, ""value"": ""Pinus radiata :: Monterey Pine""}
_shape=arrayfirst looks like this:
[1, 2, 3]
_shape=object looks like this:
{
""1"": {
""id"": 1,
""value"": ""Myoporum laetum :: Myoporum""
},
""2"": {
""id"": 2,
""value"": ""Metrosideros excelsa :: New Zealand Xmas Tree""
},
""3"": {
""id"": 3,
""value"": ""Pinus radiata :: Monterey Pine""
}
]
The object shape is only available for queries against tables - custom SQL
queries and views do not have an obvious primary key so cannot be returned using
this format.
The object keys are always strings. If your table has a compound primary
key, the object keys will be a comma-separated string.","[""JSON API""]",[]
json_api:json-api-special,json_api,json-api-special,Special JSON arguments,"Every Datasette endpoint that can return JSON also accepts the following
query string arguments:
?_shape=SHAPE
The shape of the JSON to return, documented above.
?_nl=on
When used with ?_shape=array produces newline-delimited JSON objects.
?_json=COLUMN1&_json=COLUMN2
If any of your SQLite columns contain JSON values, you can use one or more
_json= parameters to request that those columns be returned as regular
JSON. Without this argument those columns will be returned as JSON objects
that have been double-encoded into a JSON string value.
Compare this query without the argument to this query using the argument
?_json_infinity=on
If your data contains infinity or -infinity values, Datasette will replace
them with None when returning them as JSON. If you pass _json_infinity=1
Datasette will instead return them as Infinity or -Infinity which is
invalid JSON but can be processed by some custom JSON parsers.
?_timelimit=MS
Sets a custom time limit for the query in ms. You can use this for optimistic
queries where you would like Datasette to give up if the query takes too
long, for example if you want to implement autocomplete search but only if
it can be executed in less than 10ms.
?_ttl=SECONDS
For how many seconds should this response be cached by HTTP proxies? Use
?_ttl=0 to disable HTTP caching entirely for this request.
?_trace=1
Turns on tracing for this page: SQL queries executed during the request will
be gathered and included in the response, either in a new ""_traces"" key
for JSON responses or at the bottom of the page if the response is in HTML.
The structure of the data returned here should be considered highly unstable
and very likely to change.
Only available if the trace_debug setting is enabled.","[""JSON API""]","[{""href"": ""https://fivethirtyeight.datasettes.com/fivethirtyeight.json?sql=select+%27{%22this+is%22%3A+%22a+json+object%22}%27+as+d&_shape=array"", ""label"": ""this query without the argument""}, {""href"": ""https://fivethirtyeight.datasettes.com/fivethirtyeight.json?sql=select+%27{%22this+is%22%3A+%22a+json+object%22}%27+as+d&_shape=array&_json=d"", ""label"": ""this query using the argument""}]"