Dataset
Read CSV, TSV, JSON or NDJSON from an asset, a host-chosen file or a connection as rows, JSON and text.
- Data
- Since 0.2.0
- dataset
- csv
- tsv
- json
- ndjson
- table
- spreadsheet
- file
- data
Dataset reads tabular or JSON data and sends it into the Patch three ways: as a table of rows, as JSON value and as text.
What it does#
The source is a Toy asset (the data travels with the Toy), a file you pick on this device, a file from a connected service such as Google Drive, or whatever is cabled into source. Dataset parses it and emits rows (a table with typed columns), value (for CSV and TSV, one JSON object per row keyed by column), text (when it fits in a message) and changed. Large files are parsed in a worker; tables are bounded to 100 000 cells and sources to 16 MiB.
Device files and connection files are host-local: the Toy stores which kind of source to use, never the file or your account. Someone else opening the Toy chooses their own file. A Dataset with Source File requires file access; Source Connection requires that connection.
Select a Dataset and open the Data panel to see its rows as a spreadsheet. Editing a cell of an asset dataset writes a new version of the asset (with Undo) and the chain downstream recomputes; a device file is written back after a permission check; a connection file is uploaded as a new revision.
When to use it#
Use it for sequences, lookup tables, lyrics or any data you want to play with: step through rows with List and turn columns into sound with Convert and Data to control.
Ports#
| Port | Direction | Signal | Lanes |
|---|---|---|---|
source | Input | Data (any) | 1 |
rows | Output | Data (table) | 1 |
value | Output | Data (json) | 1 |
text | Output | Data (string) | 1 |
changed | Output | Data (trigger) | 1 |
Parameters#
| Parameter | Label | Range | Default | Unit | Scale | Notes |
|---|---|---|---|---|---|---|
source | Source | 0 to 2 | 0 | linear | An asset travels with the Toy; a file or connection is chosen on each host and never stored. Choices: 0 Asset, 1 File, 2 Connection. | |
format | Format | 0 to 4 | 0 | linear | Parser; Auto follows the media type and extension. Choices: 0 Auto, 1 CSV, 2 TSV, 3 JSON, 4 NDJSON. | |
header | Header row | 0 to 1 | 1 | linear | Treat the first CSV or TSV row as column names. Choices: 0 No, 1 Yes. | |
encoding | Encoding | 0 to 2 | 0 | linear | Text encoding of the source bytes. Choices: 0 UTF-8, 1 UTF-16, 2 Windows-1252. |
asset: asset.connection: requirement.delimiter: text.
Source (source)#
Asset, File or Connection. An asset is named by the node's asset field and stored in the Toy. File and Connection are chosen on each host. A cabled source input replaces whichever is set.
Format (format)#
Auto (by media type and extension), CSV, TSV, JSON or NDJSON.
Header row (header)#
Yes treats the first CSV or TSV row as column names; No numbers the columns and makes value a list of lists.
Encoding (encoding)#
UTF-8, UTF-16 or Windows-1252, for the source bytes.
Delimiter#
The delimiter field overrides the CSV separator, for example ;.
Tips#
- Keep sequence data in an asset so the Toy plays the same anywhere.
- During replay an asset dataset reads its asset again; file and connection datasets play back what they read while recording.
See also#
Convert, List, Data to control, Data cables.
Help patches
Each help patch is an ordinary Toy that teaches one idea. The diagram shows the Patch; the preview shows its Frame. Open it in TuneToys to play and edit it.
1. A table from text
beginner Teaches: source, format, header
CSV text cabled into a Dataset becomes rows, JSON and text; open the Data panel to see the table.
Connections as text
- Value value output connected to Dataset source input
- Dataset value output connected to Console log value input
- A cabled source replaces the asset; Format CSV with Header row Yes names the columns.
- value is the rows as JSON objects keyed by column.
Related nodes
- Convert Convert a value to another datatype, optionally picking a field or formatting a string; failures go to error.
- List List operations on data values: get, push, insert, remove, slice, sort, unique, flatten, join, range, sum, minimum, maximum, mean, shuffle and more.
- Data to control Turn numbers into one control lane for a parameter or control input, mapped from a declared range.