attr := DATASET( file, struct, JSON( xpath [, NOROOT ] ) [,ENCRYPT(key) ]);
| JSON | Specifies the file is a JSON file. |
| xpath | A string constant containing the full XPATH to the tag that delimits the records in the file. |
| NOROOT | Specifies the file is a JSON file with no root level markup, only a collection of objects. |
| ENCRYPT | Optional. Specifies the file was created by OUTPUT with the ENCRYPT option. |
| key | A string constant containing the encryption key used to create the file. |
This form is used to read a JSON file. The xpath parameter defines the path used to locate records within the JSON content using a subset of standard XPATH (www.w3.org/TR/xpath) syntax (see the XPATH Support section under the RECORD structure discussion for a description of the supported subset).
The key to getting individual field values from the JSON lies in the RECORD structure field definitions. If the field name exactly matches a lower case JSON tag containing the data, then nothing special is required. Otherwise, {xpath(xpathtag)} appended to the field name (where the xpathtag is a string constant containing standard XPATH syntax) is required to extract the data. An XPATH consisting of empty quotes ('') indicates the field receives the entire record. An absolute XPATH is used to access properties of child elements. Because JSON is case sensitive, and ECL identifiers are case insensitive, xpaths need to be specified if the tag contains any upper case characters.
NOTE: JSON reading and parsing can consume a large amount of memory, depending on the usage. In particular, if the specified xpath matches a very large amount of data, then a large data structure will be provided to the transform. Therefore, the more you match, the more resources you consume per match. For example, if you have a very large document and you match an element near the root that virtually encompasses the whole thing, then the whole thing will be constructed as a referenceable structure that the ECL can get at.
Example:
/* a JSON file called "mybooks.json" contains this data:
[
{
"id" : "978-0641723445",
"name" : "The Lightning Thief",
"author" : "Rick Riordan"
}
,
{
"id" : "978-1423103349",
"name" : "The Sea of Monsters",
"author" : "Rick Riordan"
}
]
*/
BookRec := RECORD
STRING ID {XPATH('id')}; //data from id tag -- renames field to uppercase
STRING title {XPATH('name')}; //data from name tag, renaming the field
STRING author; //data from author tag -- tag name is lowercase and matches field name
END;
books := DATASET('~LR::mybooks.json',BookRec,JSON('/'));
OUTPUT(books);