@@ -0,0 +1,65 @@
1+# Project:M36 CSV Import/Export
2+
3+Project:M36's `tutd` console supports the import and export of CSV files as a lowest-common denominator format for moving data. Because the CSV file format does not support all the features of Project:M36- most notably, nested relations- not all relation variables can be marshalled to-and-from CSV files.
4+
5+## CSV Export
6+
7+If a relation variable cannot be exported due to data types which are not supported by the CSV format- such as with a nested relation- then Project:M36 throws an error rather than export a partial file.
8+
9+### Example Export
10+
11+```
12+TutorialD (master/main): :importexample date
13+TutorialD (master/main): :exportcsv s "/tmp/csv"
14+```
15+```
16+$ cat /tmp/csv
17+s#,sname,status,city
18+S2,Jones,10,Paris
19+S1,Smith,20,London
20+S4,Clark,20,London
21+S5,Adams,30,Athens
22+S3,Blake,30,Paris
23+```
24+
25+## CSV Import
26+
27+An import is equivalent to an insert and does not replace the target relation variable.
28+
29+Because relations do not have a natural ordering for their attributes, the CSV file to import must contain a header row which matches the names of attributes.
30+
31+If a value in the CSV file cannot be converted to the expected type (determined by the existing relation attributes), then the entire import is aborted rather than perform a partial import.
32+
33+### Example Import
34+```
35+$ cat /tmp/csv
36+s#,sname,status,city
37+S6,Samson,100,New York
38+```
39+```
40+TutorialD (master/main): :importexample date
41+TutorialD (master/main): :showexpr s
42+┌──────────┬────────┬───────────┬───────────────┐
43+│city::Text│s#::Text│sname::Text│status::Integer│
44+├──────────┼────────┼───────────┼───────────────┤
45+│"Paris" │"S2" │"Jones" │10 │
46+│"Paris" │"S3" │"Blake" │30 │
47+│"London" │"S4" │"Clark" │20 │
48+│"London" │"S1" │"Smith" │20 │
49+│"Athens" │"S5" │"Adams" │30 │
50+└──────────┴────────┴───────────┴───────────────┘
51+TutorialD (master/main): :importcsv "/tmp/csv" s
52+TutorialD (master/main): :showexpr s
53+┌──────────┬────────┬───────────┬───────────────┐
54+│city::Text│s#::Text│sname::Text│status::Integer│
55+├──────────┼────────┼───────────┼───────────────┤
56+│"Paris" │"S3" │"Blake" │30 │
57+│"London" │"S4" │"Clark" │20 │
58+│"New York"│"S6" │"Samson" │100 │
59+│"Athens" │"S5" │"Adams" │30 │
60+│"London" │"S1" │"Smith" │20 │
61+│"Paris" │"S2" │"Jones" │10 │
62+└──────────┴────────┴───────────┴───────────────┘
63+```
64+
65+Note that relations do not have ordering, thus, no ordering from the CSV file is preserved.