| On this page | |
| Since | 17.5 |
This node will read in JSON files and extract data that is specified by the user. The user can specify the name of the work item attribute in which the data will be placed as well as its type and list index.
Tip
The $HH/help/files/pdg_examples/top_jsonpipeline example shows how you can use this node to create work items from a .json file.
TOP Attributes ¶
|
|
integer |
When performing the Array Retrieve operation, this will be set to the object’s index in the array from which it was retrieved, or to 0 if the retrieved value was not stored in an array. |
|
|
integer |
When performing the Array Retrieve operation, this will be set to the index of the object. This is useful when performing queries that use the wildcard operator, as this attribute acts as an identifier of the object from which the information was retrieved. |
|
|
string |
When performing the Array Retrieve operation, this shows the query that was used to conduct the operation. If the wildcard operator was used in the query, the wildcard will be replaced with the resolved value. |
|
|
string |
When performing the Array Retrieve operation, this attribute is set to the field that was retrieved during the operation. |
Parameters ¶
Work Items ¶
Generate When
Determines when this node will generate work items. You should generally leave this set to “Automatic” unless you know the node requires a specific generation mode, or that the work items need to be generated dynamically.
All Upstream Items are Generated
This node will generate work items once all of the input nodes have generated their work items.
All Upstream Items are Cooked
This node will generate work items once all of the input nodes have cooked their work items.
Each Upstream Item is Cooked
This node will generate work items each time a work item in an input node is cooked.
Automatic
The generation mode is selected based on the generation mode of the input nodes. If any of the input nodes are generating work items when their inputs cook, this node will be set to Each Upstream Item is Cooked. Otherwise, it will be set to All Upstream Items are Generated.
Input ¶
Input Source
The source of the JSON data
Upstream Output File
JSON data is loaded from output file(s) on the upstream work items
Custom File Path
JSON data is loaded from a custom file path
Attribute
JSON data is loaded from an attribute on the upstream work item
File Tag
The data tag used to select the result from the upstream work item, when Input Source is set to Upstream Output File.
File Path
The path to the JSON file, when Input Source is set to Custom File Path.
Attribute Name
The name of the upstream dictionary, string or PyObject attribute that contains the JSON data.
Operation ¶
Operation
This specifies the retrieval operation that you want to perform.
Retrieve
This operation allows single data extractions to be performed on the JSON file. For example, it can be used to query a specific value in an object or a value at a certain index in a list. The Data Extractions multiparm specifies the extractions that should be performed on the JSON.
Array Retrieve
This operation allows a specified field to be extracted from each index of a list within the JSON file.
Deserialize Work Item
This operation will deserialize a work item from the given JSON file, the file should be formatted as a serialized work item file, such as that produced by 
JSON Output.
On Attribute Collision
Determines what should happen if the work item in the .json file has attributes that already exist on upstream work items that are inputs to this node. By default, this node will prefer to keep upstream attribute values, but you can change this parameter to Keep JSON Attribute instead to ensure that upstream attributes are overwritten by the values found in the .json file.
This parameter is only available when Operation is set to Deserialize Work Item.
Keep Upstream Attribute
Work items on this node will keep the upstream attribute data.
Keep JSON Attribute
Work items on this node will keep the JSON attribute data.
Report Warning
Work items on this node will keep the upstream attribute data and a warning is issued.
Store Input JSON File
When Operation is set to Deserialize Work Item, this parameter determines whether or not the node should save the input JSON file to the deserialized work item.
None
The JSON file path is discarded after deserializing the work item.
File Attribute
The JSON file path is stored to a file attribute on the deserialized work item. The name of the attribute is determined by the File Attribute Name parameter.
Output File
The JSON file path is added as an output file on the deserialized work item.
File Attribute Name
When When Operation is set to Deserialize Work Item and Store Input JSON File is set to File Attribute, this parameter determines the name of the attribute that contains the original JSON file path.
Preserve Deserialized Item Index
Determines whether or not work items loaded from a JSON file should use the work item indices specified in the file. If this toggle is disabled the work items will use the parent index instead.
This parameter is only available when Operation is set to Deserialize Work Item.
On Query Failure
This parameter controls what happens when any part of the query fails. An example of a query failure would be using an index in the query that is larger than the size of the array that is being indexed.
Raise Error
The node will automatically fail the entire operation when a query fails.
Add Warning
The node will attach a warning but the node will finish cooking. If an Array Retrieve operation is being
performed, the node will attempt to complete the other queries.
Add Warning
This is useful if the JSON file contains non-uniform data. For example, when an array of objects may or may not contain a specific sub-object.
Data Extractions
The parameters in this multiparm are used to specify the data extractions that should be performed when using the Retrieve operation.
Query
This parameter is used to specify the path to the JSON object or value that you want to extract. It uses a hierarchical syntax separated by / characters to specify the path. If an list is within the hierarchy, a number can be used to specify the array index.
If we have the following JSON file:
{
"plants" :
[
{ "name" : "tree", "inMyGarden" : true, "height" : 5.5 },
{ "name" : "sunflower", "inMyGarden": false, "height" : 3 }
]
}
And we wanted to retrieve the height of the first plant, the query would be:
plants/0/height
If we wanted to retrieve the name of the second plant, the query would be:
plants/1/name
When performing the Array Retrieve operation, the query must point to a list in the JSON, with one exception described below.
The Array Retrieve operation can make use of the wildcard (*)
operator in its queries. The wildcard will cause branching traversal of the
JSON hierarchy, where each object at that level becomes a branch of the JSON
traversal.
If we have the following JSON file:
{
"Houdini" : {
"Contexts" : {
"Sop" : {
"mountain" : {
"name" : "Mountain"
},
"polybevel" : {
"name" : "PolyBevel"
}
},
"Top" : {
"jsoninput" : {
"name" : "Json Input"
},
"jsonoutput" : {
"name" : "Json Output"
}
}
}
}
}
And we wanted to go the names of all the nodes in this JSON file, we could perform the following query:
Houdini/Contexts/*/*
with the field parameter set to name.
This will create 4 separate work items, each containing a node name. Note that json_arrayindex will be set to 0 on each, because these objects are all independent and not part of the same array.
Field
This parameter is only used when the Array Retrieve operation is being performed. It is used to specify the property that should be retrieved from each array index in the list pointed to by the query.
If the array pointed to by the Query is filled with anonymous objects (such as an array of integers), this parameter can be set to the wildcard operator (*) which simply means that it will get everything in the array.
Output Attribute
This specifies the name of the work item attribute to store the extracted value in.
Store As
This specifies what type of PDG attribute will be used to store the queried JSON data. If a specific PDG attribute type choice is selected and the JSON data type does not match, it will result in an error. JSON objects will be stored as PyObjects when the Automatic option is chosen.
Automatic
The type of the PDG attribute to use will be automatically determined from the type of the JSON data.
String
The data will be stored as a string attribute.
Integer
The data will be stored as an integer attribute.
Float
The data will be stored as a float attribute.
PyObject
The data will be stored as a PyObject attribute.
Dictionary
The data will be stored as a Dictionary attribute.
String Array
The list of data will be stored in a string attribute.
Integer Array
The list of data will be stored in an integer attribute.
Float Array
The list of data will be stored in a float attribute.
Dictionary Array
The list of data will be stored in a Dictionary attribute.
Unpacked Attributes
This option will unpack a JSON object into individual attributes.
PDG Value Index
This specifies the index of the work item attribute’s list to store the extracted value in.
Examples ¶
example_top_jsoninput Example for JSON Input TOP node
This example demonstrates how to use json input node to create workitems based on information contained in json files.
| See also |
