| On this page | |
| Since | 17.5 |
Tip
The $HH/help/files/pdg_examples/top_partitioners example shows how you can use common partitioner features like targeted partitioning, controls for merging attributes, and splitting by attribute.
Parameters ¶
Range ¶
Range Type
Determines how the work item range is specified.
Custom Range
Custom range based on a ratio of upstream items to partition count and an offset in the left/right directions.
Fixed Partition Count
Creates a fixed number of partitions no matter how many upstream work items there are. Upstream items are distributed as evenly as possible among the partitions. If the items don’t divide evenly, the first few partitions will have an extra work item.
Fixed Partition Size
Creates partitions of a fixed size when possible. If the upstream items don’t divide evenly, only the last partition will have the wrong size. It will contain whatever items are left after dividing the upstream items into groups of the desired fixed size.
First/Last Value
Creates exactly two partitions. The first one contains the first work item from each of the input nodes, and the second partition contains the last work item from each of the input nodes. Other upstream items are not partitioned.
First/Middle/Last Value
Create exactly three partitions. Behaves the same as the First/Last range type, except the middle work items from each input node are also put into a partition.
Order By
Determines how the work items should be ordered when the node partitions them.
Work Item Index
Work items are sorted by their index.
Work Item Frame
Work items are sorted by their frame value.
Custom Attribute
Work items are sorted by the value of the Attribute Name custom attribute.
Input Order
Work items are not explicitly sorted and are partitioned based on the order of the work items in the input nodes.
Attribute Name
Specifies the name of the attribute to use when ordering input work items.
This parameter is only available when Order By is set to Custom Attribute.
Custom Range ¶
These parameters configure the behavior of the partitioner when the Custom Range type is selected. The range is determined by two main properties: the ratio of upstream work items to partitions, and an offset in the left and right direction.
For example, with Upstream Range set to 2 and Partition Range set to 1, one partition will be created for every two upstream work items.
Upstream Range
Along with the Partition Range parameter, determines the ratio between upstream work items and partitions
Partition Range
Determines the number of partitions to create, along with the Upstream Range parameter.
Left Offset
The number of additional items proceeding the selected items that should also be included in the partitions.
Right Offset
The number of additional items that follow the selected items that should also be included in the partitions.
Consolidate Work Items by Key
When on, work items with the same sorting key will always be grouped into the same partition, like they are the same work item. The partitioning operation is performed on the list of unique sort keys rather than on the list of input work items.
Fixed Partition Count ¶
Range Count
The number of partitions that will be created.
Fixed Partition Size ¶
Range Size
The number of upstream items that will be added to each partition.
First/Last & First/Middle/Last ¶
Reset Work Item Indices
When on, the work items in the partitions are given indices of 0/1 (for First/Last Value) or 0/1/2 (for First/Middle/Last Value). When off, the work items retain their original indices.
For example, if Range Type is set to First/Last Value and Reset Work Item Indices is off, and your work items come from a range of 1000 items, then the index of your first work item would be 0 and the last item would be 999. However if Reset Work Item Indices is on, then the index of your first work item would be 0 and the last item would be 1.
Merge Attributes ¶
These parameters control how attributes from input work items are merged onto the partitions produced by the node.
Merge Output Files
Determines how output files from work items in partitions are merged onto the partitions themselves. By default, all output files from the work item are copied into the partition output file list.
None
Output files are not merged onto partitions
First File
The output file(s) from the first work item in the partition are copied onto the partition.
Last File
The output file(s) from the last work item in the partition are copied onto the partition.
Unique Files
The unique file paths from all of the work items are copied onto the partition. The order of the files may change as this operation requires sorting the file list.
All Files
The output file(s) from all work items in the partition are copied onto the partition. The order of the files dependends on the order of the work items in the partition.
Merge Operations
Defines the number of attribute merge operations to perform on the partitioner node. The operations are used to merge attributes from work items in the partition onto the partition itself. Operations are performed in descending order. Attributes are merged using the first operation with a pattern that matches the attribute.
Apply Operation
Specifies the operation to perform to merge incoming attributes onto the partition. Each operation only applies only to the subset of attributes matched using the corresponding To Attributes parameter.
The following operations are available:
Ignore
Matching attributes are ignored and will not appear on the partition.
First Value
The value of each matching attribute on the first work item in the partition is kept, and values on subsequent work items are ignored
Last Value
The value of each matching attribute on the last work item in the partition is kept.
Unique Values
The unique values for each matching attribute are merged into an array. Duplicate values are discarded.
Append to Array
The values for each matching attribute are appended to an array for that attribute. All attribute values from all work items are kept.
Minimum
The minimum value for each matching attribute is kept.
Maximum
The maximum value for each matching attribute is kept.
Sum
The sum of the values in each matching attribute is stored on the partition.
Average
The average value of each matching attribute is stored on the partition.
Mode
The most common value in each matching attribute is kept.
Median
The middle value in each matching attribute is kept.
Sorted
The values for each matching attribute are merged into a sorted array.
SortedUnique
Attribute values across all work items are merged into a sorted array, and unique values are kept.
To Attributes
Specifies which attributes the corresponding Apply Operation parameter should apply to. This field can use the Attribute Pattern Syntax to specify multiple attributes.
Preserve Arrays
When on, the merge operation preserves the original array size of the incoming attributes. The merged array size is determined by the first value found across the input work items. When off, the partitioner flattens the incoming array attributes into a single sequence of values (a single scalar value) and performs the merge operation across all values.
Advanced ¶
These are advanced parameters that provide finer control over the behavior of the partitioner.
Partition When
Determines when the partitioning step is performed on the input work items.
Input Items are Generated
Upstream work items are partitioned once all of them have been generated
Input Items are Cooked
Upstream work items are partitioned once all of them are cooked. This may be required when the partitioning scheme is based on the results of the work items' execution.
This makes this partitioner behave like a 
Wait for All node except that it may create multiple partitions.A
Partition Target(s)
Determines which node or nodes(s) should target. Work items in the target nodes are partitioned as soon as they're generated even if the target nodes are not a direct input to this node. The descendants of the target work items are added to the partitions when they become available.
Direct Input Nodes
The partitioner uses work items from its direct input nodes. This is the default behavior
Upstream Static Nodes
The partitioner will skip over dynamic input nodes and partition work items from the nearest upstream static nodes.
Custom Target Node
The partitioner will use the node specified using the Custom Target Node parameter.
Custom Target Node
Specifies the target TOP node for the partition when Partition Targets is set to Custom Target Node. The partition scheme is applied to the work items in the target TOP node instead of this node’s input work items. The target TOP node must be in the same graph and above this node.
Ignore Failed Work Items
When this toggle is enabled, the partitioner node will skip input work items that are failed and create partitions from the subset of upstream work items that succeeded. This option is only meaningful if Partition When is set to Input Items are Cooked, or when the partitioner node is wired into a dynamic node that has upstream failures.
Split by Attribute
When on, the node splits input work items by the specified attribute(s) before partitioning them. The partitioning logic is evaluated on the list of work items for each distinct attribute value. Work items with different attribute values are always put into different partitions. Multiple attribute names can be specified as a space-separated list.
Missing Attribute
Determines how the node handles work items that are missing the split attribute.
This parameter is only available when Split by Attribute is on.
Ignore Work Item
Work items that are missing the split attribute are not put into any of the partitions.
Add Work Item to All Partitions
Work items that are missing the split attribute are put into all of the partitions.
Use Default Value
Work items that are missing the split attribute will use the value set by the Default Value parameter.
Default Value
Specifies the value to use for the split attribute for work items that are missing the attribute.
This parameter is only available when Missing Attribute is set to Use Default Value.
Allow Partial Matches
When Split by Attribute is set to a list of attribute names, this parameter determines how work items with only some of the attributes should be processed. If partial matches are enabled then work items will be added to split groups based on the attributes that do exist. Otherwise, work items with only a subset of the attributes will be excluded from the partitioning step.
Set Partition Frame To
Determines how the partitioner should set the frame value on partitions created by this node. If the partitioner already sets a custom frame value, for example like with a 
Python Partitioner SOP or 
Partition by Frame SOP, then this parameter has no effect.
None
No frame value is set on partitions.
First Work Item’s Frame
The frame value from the first work item based on the current Sort Contents By sort order is copied onto the partition.
Last Work Item’s Frame
The frame value from the last work item based on the current Sort Contents By sort order is copied onto the partition.
Largest Frame
The largest frame value from all work items in the partition is used for the partition’s frame.
Smallest Frame
The smallest frame value from all work items in the partition is used for the partition’s frame.
Sort Contents By
Determines the order that work items are sorted in when accessing the partitions on this node. This also affects the sort order of output files on the partition.
None
No sorting is applied. The work items in the partition are handled in no particular order.
Work Item Index
Work items in the partition are sorted based on their index.
Input Node Order
Work items in the partition are sorted based on the order of input nodes wired into this node. If two work items are from the same input, they are then sorted by index.
Attribute
Work items in the partition are sorted based on the attribute specified in the Sort Attribute field parameter.
Sort Direction
Determines whether the work items in this node’s partitions are sorted in ascending or descending order.
Sort Attribute
Specifies the name of the attribute to sort by.
This parameter is only available when Sort Contents By is set to Attribute.
Store Items to Attrib
When on, the list of IDs corresponding to the work items in the partition are written to the specified attribute. The work item IDs are stored as an integer array. This makes it easier to recover the list of partitioned work items downstream of the partitioner node.
Examples ¶
PartitionByRange Example for Partition by Range TOP node
This example demonstrates how to use the Partition by Range TOP node to group work items input work items based on range limits.
| See also |
Partition by Combination
Partition by Node
