join features
Feature Description
Join features can associate the attributes of one dataset with another dataset (which can be spatial data or attribute data) based on spatial, temporal, attribute relationships, or the aggregation of these three. This process first filters all input objects that meet the connection conditions based on specified criteria, and then connects the qualified input objects with corresponding objects in the source data. Finally, the returned result is a feature dataset (FeatureRDD), and only features with successful connections are retained.
This tool can transfer and append information from one layer to another, and you can choose to connect features based on spatial relationships, attribute relationships, temporal relationships, or a combination of these three as needed. The details are as follows:
Spatial relationships
To determine the spatial relationships between features, the available relationships depend on the geometry type (point, line, or polygon) of the layers being joined. The provided spatial relationships are as follows: proximity, containment, being contained, crossing, intersection, overlap, adjacency, disjoint, and identity. For detailed explanations, please refer to:
| Spatial relationships | Illustration | Description |
|---|---|---|
| Contain |  |
The source object contains the join object. |
| Within |  |
The source object is contained by the join object. |
| Intersected |  |
The source object intersects with the join object. |
| InnerIntersected |  |
Join objects that have internal overlap (not boundary contact) with the source object, i.e., excluding objects that only touch at the boundary from the intersection result. |
| Overlap |  |
The source object partially overlaps with the join object. |
| Identical |  |
Objects of the same type coincide, such as point with point, line with line, or polygon with polygon. |
| Disjointed |  |
Objects in the two datasets have no intersection. |
| Touch |  |
Objects in the two datasets share common points or edges. |
| Cross |  |
The source object crosses the join object. |
| Near |  |
If the join object is within a specified distance radius from the source object, the condition is met. |
Temporal Relationships
To determine the temporal relationships between objects, the available relationships depend on the time type (instant or interval) of the layers being joined. For detailed explanations, please refer to:
| Temporal Relationships | Illustration | Description |
|---|---|---|
| Near |  |
If the time interval between the source time period and the join time period is less than the time distance, the proximity relationship is satisfied. |
| After |  |
When the source time is after the join time. |
| Before |  |
When the source time is before the join time. |
| Contains |  |
The source time contains the join time when the join time occurs between the start and end points of the source time interval. |
| During |  |
The source time is during the join time when it occurs between the start and end points of the join time interval. |
| Finishes |  |
The source time ends at the same time as the join time, and the source time starts after the join time. |
| Meets |  |
The end time of the source data equals the start time of the join data. |
| MetBy |  |
The start time of the source data equals the end time of the join data. |
| Overlaps |  |
The source data start time is before the join data start time, and the source data time ends before the join data time. |
| OverlappedBy |  |
The source data start time is after the join data start time, and the source data time ends after the join data time. |
| Starts |  |
The source time starts at the same time as the join time, and the source time ends before the end point of the join time interval. |
| StartedBy |  |
The source time starts at the same time as the join time, and the source time ends after the end point of the join time. |
| Equals |  |
If the source data time interval and the join data time interval are exactly the same, these two times are identical. |
Attribute Relationships
To determine the attribute relationships between objects, if the field values in the join data are equal or not equal to the field values in the source data, the objects that meet the conditions will be matched.
Type
Refers to the matching relationship between source object properties and join objects, providing two join methods: one-to-one and one-to-many. Set using the 'Feature Type' parameter.
- One-to-One Join: If there is one join object that meets the conditions, the attribute values of the join object's connection field will be updated to the source object; if there are multiple join objects that meet the conditions, only the count of qualified objects will be recorded.
- One-to-Many Join: This method retains every qualified multiple object in the result dataset. For example, if one object in the source dataset matches five objects in the join dataset, the result dataset will contain these five objects.
Application Scenarios
- Using the join features tool, additional information from various city districts (such as school districts, police districts, communities, etc.) can be appended to each crime incident, further studying and analyzing the impact of crimes on different districts.
Parameter Description
| Parameter Name | Parameter interpretation | Parameter type |
|---|---|---|
| Target dataset | The target dataset for join features, where the attributes of the join data will be appended to the associated target dataset. | FeatureRDD |
| Join data for join features | The join data for join features, a dataset with attributes offered. | FeatureRDD |
| Feature type | Feature type, including the following two: One-to-One Join: If multiple join objects and one target meet the association conditions, the multiple join objects will be aggregated into one object through attribute statistics. The attribute statistics can be set via stats; if not set, the default is to count the number of join objects. One-to-Many Join: If multiple join objects and one target meet the association conditions, the attributes of all multiple join objects will be connected to the target, forming multiple result objects, and no attribute statistics will be performed. |
JavaJoinOperatorType |
| Retain all target features | If checked, the output result includes all features of the target dataset; if unchecked, only features in the target dataset that meet the specified relationships are retained. | Boolean |
| Join features field | Join features field, when the type is one-to-one join, take the mode of the field values. | String |
| Spatial relationship type （Optional） |
Spatial relationship type, the spatial relationships between feature objects in the target dataset and the join dataset, as described above. At least one of the spatial association condition, temporal association condition, and attribute association condition must be valid. | JavaSpatialRelationType |
| Proximity distance （Optional） |
Proximity distance, when the spatial relationship is "Near", used to determine whether the spatial distance between two objects is within the specified proximity distance range. | JavaDistance |
| Temporal relationship judgment type （Optional） |
Temporal relationship judgment type, as described in the temporal relationships above. At least one of the spatial association condition, temporal association condition, and attribute association condition must be valid. | JavaTimeOperatorType |
| Time distance （Optional） |
When the temporal relationship judgment type is "Near", used to determine whether the minimum time interval between two features is within the specified time distance range. Parameter input format: numerical value + space + unit, e.g., 5 Days, meaning the time interval between two features must be within 5 days to be considered "Near". Supports multiple time units, including: Years, Months, Weeks, Days, Hours, Minutes, Seconds, Milliseconds. |
JavaDuration |
| Attribute connection condition （Optional） |
Attribute connection condition, supporting Equal and NotEqual. Parameter input format: field name to be joined, connection condition, field name for matching join, separated by English commas, e.g., tagField,Equal,joinField. Note: This parameter only takes effect when at least one of the spatial association condition, temporal association condition, and attribute association condition is valid. |
JavaAttributeRelation |
| Specify the field and statistical method of the join data to be counted （Optional） |
Specify the field and statistical method of the join data to be counted, only valid when the type is "One-to-One Join". Parameter input format: field name to be counted, statistical method, result field name, separated by English commas, e.g., YSMJ,sum,YSMJ_SUM. Statistical methods include: sum, min, max, mean, var (sample variance), varpop (population variance), sddev (standard deviation), sdpop (population standard deviation), count (record count), modalvalue (mode). |
JavaFieldStat |
| Fuzzy （Optional） |
The default value for fuzzy is 0.0, meaning that when the dataset's coordinate system is a geographic coordinate system, a fuzzy of 1.0e-8 is used; when the coordinate system is empty or a projected coordinate system, a fuzzy of 1.0e-3 is used. | Double |
| Field in the target feature dataset identifying the start time （Optional） |
Field in the target feature dataset identifying the start time. | String |
| Field in the target feature dataset identifying the end time （Optional） |
Field in the target feature dataset identifying the end time. | String |
| Field in the join feature dataset identifying the start time （Optional） |
Field in the join feature dataset identifying the start time. | String |
| Field in the join feature dataset identifying the end time （Optional） |
Field in the join feature dataset identifying the end time. | String |
Output Result
| Parameter Name | Parameter interpretation | Parameter type |
|---|---|---|
| Result feature dataset | The result dataset needs to be written to a database or local storage by connecting the 【Save Vector Data】 tool. | FeatureRDD |