@data
Declares a dataset under an #id: a table of values written inline, attached as a .csv or read from a URL, or boundaries attached as a .geojson.
On this page
#Attributes
srcWhere the dataset comes from: an attached file, or an
https:// URL. A .csv file's header row names the columns, and a .geojson file holds boundaries; a file's extension decides which, and no other is accepted. A URL says what it returns with format:. Written as the implicit value, #survey:plants.csv or #stouts:https://api.sampleapis.com/beers/stouts(format: json). Omitted, the body holds the table inline.Can be written as shorthand:
:valueformatWhat a URL returns:
csv and json are tables, geojson is boundaries. Required on a URL, since a URL rarely ends in an extension, and refused on a file, whose extension already says.csvjsongeojsonpathWhere the rows are in a
json response, as a dotted path: path: results.items. Every array on the way is stepped into, and the objects the path ends on are the rows, each carrying the plain fields of every object above it. Omitted, the response itself is read: an array of objects is the rows, and a single object is one row.nextThe field of a
json response that leads to the next page, as a dotted path: next: meta.cursor. A URL there is fetched as the next page, and any other value is sent back as a query parameter named after the path's last part, ?cursor=…. Pages are followed until the field is empty, and every page's rows are read in order.keyThe name of an API key the author has saved in Preferences, sent with each request:
key: weather. Lowercase letters, digits and hyphens. A reader never sees the key.#Allowed content
Body { }header and rows, pipe-delimited (inline form only)
#Examples
@data#islands{
island | area | species
Baltra | 25.09 | 58
Bartolomé | 1.24 | 31
Santa Cruz | 903.82 | 444
}@data#survey:galapagos-plants-1973.csv@data#stouts:https://api.sampleapis.com/beers/stouts(format: json; path: rating)
graph{
scatter(x: #stouts.reviews; y: #stouts.average)
}@data#islands{
island | area | species
Baltra | 25.09 | 58
Bartolomé | 1.24 | 31
Santa Cruz | 903.82 | 444
}
code{
lines{
area = np.array([{{#islands.area}}])
}
}(
language: python
)@data#wards:sydney-wards.geojson
@data#turnout:turnout.csv
geo{
choropleth(basemap: #wards; regions: #turnout.ward; value: #turnout.pct)
}(
projection: conic
)#Notes
- The id is required: @data: requires an id — datasets are reached as
#id.column. - Inline, the first row names the columns, cells are separated by
|, and every row has as many cells as the header: @data: row 1 has 3 cells; the header declares 2. A cell cannot contain|. A cell is text, typed where it is used, and a blank cell is the empty text"", which a number position refuses, naming the row. - Column names are read in lower case, with spaces as hyphens: a header
Species Countis the columnspecies-count. A name written twice is refused: duplicate column namea. - A dataset is visible to the whole document wherever it is declared, including inside an
d partial.is the exception: it reads its dataset in document order, so thecomes first. - Only
.csvand.geojsonfiles are attached:x.jsonhas extensionjson, but only csv, geojson are permitted. - A URL must be
https://, and must say what it returns:format:is required on a URL and refused on a file. A URL holding a space or any of{ } ( ) [ ] ; " < > \ | ^or a backtick is refused, naming the character and how to write it percent-encoded:[as%5B. A URL built from a{{…}}value is written assrc:, since the implicit value takes none. - A URL's response is fetched when the internote is published or its data refreshed, never as a reader opens it, so every reader sees the same rows. The columns are checked against that response, as a file's are.
- In a
jsonresponse a field that holds an object or an array is not a column: naming it is refused, as any unknown column is.path:reaches inside one instead. - An inline body and
srctogether are refused: declare either an inline {grid} body orsrc:, not both. - A
.geojsondataset has no columns and no rows. It is bound whole,in: #wards;#wards.nameis refused with that fix, and boundaries are never written inline. - Packs bring datasets as well, through
:#biology.lynx-hare.hare.
#Writing guidance
- Checking a document's claims — Every other number worked out, every output quoted from a run, every dataset read and attached whole, every external fact checked and cited, or cut.