Skip to content

Commit a82556b

Browse files
ronishemeshronishemesh
committed
add aggregation properties path filter
1 parent de9552c commit a82556b

File tree

1 file changed

+265
-0
lines changed
  • docs/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/properties

1 file changed

+265
-0
lines changed

‎docs/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/properties/aggregation-property.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -902,6 +902,271 @@ Coming soon...
902902

903903
</Tabs>
904904

905+
### Path Filter
906+
907+
The `pathFilter` option lets you control which entities are included in your aggregation calculation based on their relationship path from the source entity. This is useful for complex relationship chains, where you may want to aggregate data only from entities connected through specific paths.
908+
909+
When a `pathFilter` is defined, Port will include only entities that can be reached through the exact relationship path you specify.
910+
911+
<h4> Structure </h4>
912+
913+
| Field | Description |
914+
|---------------------------|----------------------------------------------------------------------------------------------------------------------|
915+
| `pathFilter.path` | An array containing the full path of relation identifiers to traverse. |
916+
| `pathFilter.fromBlueprint` | *(Optional)* The blueprint to start the path traversal from. If omitted, traversal starts from the source blueprint. |
917+
918+
919+
<h4> For upstream paths </h4>
920+
921+
```json showLineNumbers
922+
{
923+
"pathFilter": [
924+
{
925+
"path": ["relation1", "relation2", "relation3"]
926+
}
927+
]
928+
}
929+
```
930+
931+
<h4> For downstream paths </h4>
932+
933+
```json showLineNumbers
934+
{
935+
"pathFilter": [
936+
{
937+
"path": ["relation1", "relation2", "relation3"],
938+
"fromBlueprint": "{{targetBlueprint}}"
939+
}
940+
]
941+
}
942+
```
943+
944+
945+
<h4> Examples </h4>
946+
947+
<Tabs groupId="path-filter-examples" defaultValue="api" values={[
948+
{label: "API", value: "api"},
949+
{label: "Terraform", value: "tf"}
950+
]}>
951+
952+
<TabItem value="api">
953+
954+
<h4>Example 1: Direct Relationship Path</h4>
955+
956+
Count Jira issues directly related to a Microservice:
957+
958+
```json
959+
{
960+
"identifier": "microservice",
961+
"title": "Microservice",
962+
"aggregationProperties": {
963+
"directJiraIssuesCount": {
964+
"title": "Direct Jira Issues Count",
965+
"target": "jiraIssue",
966+
"pathFilter": [
967+
{
968+
"path": ["jira_issue_rel"]
969+
}
970+
],
971+
"calculationSpec": {
972+
"calculationBy": "entities",
973+
"func": "count"
974+
}
975+
}
976+
}
977+
}
978+
```
979+
980+
The `"path": ["jira_issue_rel"]` ensures that only Jira issues directly related to the microservice through the `jira_issue_rel` relation are counted.
981+
982+
<h4> Example 2: Multi-hop Relationship Path</h4>
983+
984+
Count deployments through Service → Microservice → Deployment
985+
986+
```json
987+
{
988+
"identifier": "service",
989+
"title": "Service",
990+
"aggregationProperties": {
991+
"deploymentCount": {
992+
"title": "Deployment Count",
993+
"target": "deployment",
994+
"pathFilter": [
995+
{
996+
"path": ["microservice_rel", "deployment_rel"]
997+
}
998+
],
999+
"calculationSpec": {
1000+
"calculationBy": "entities",
1001+
"func": "count"
1002+
}
1003+
}
1004+
}
1005+
}
1006+
```
1007+
1008+
The `pathFilter` with `"path": ["microservice_rel", "deployment_rel"]` counts deployments that are connected through the `microservice_rel` relation first, then to the `deployment_rel` relation.
1009+
1010+
<h4>Example 3: Starting Path from Specific Blueprint</h4>
1011+
1012+
Count deployments by starting path traversal from the target blueprint:
1013+
1014+
```json
1015+
{
1016+
"identifier": "service",
1017+
"title": "Service",
1018+
"aggregationProperties": {
1019+
"deploymentCountFromService": {
1020+
"title": "Deployment Count from Service",
1021+
"target": "deployment",
1022+
"pathFilter": [
1023+
{
1024+
"path": ["microservice_rel", "deployment_rel"],
1025+
"fromBlueprint": "deployment"
1026+
}
1027+
],
1028+
"calculationSpec": {
1029+
"calculationBy": "entities",
1030+
"func": "count"
1031+
}
1032+
}
1033+
}
1034+
}
1035+
```
1036+
1037+
The `fromBlueprint: "deployment"` specifies that the path traversal should start from the deployment blueprint (the target), then follow the path backwards through `microservice_rel` to service.
1038+
1039+
</TabItem>
1040+
1041+
<TabItem value="tf">
1042+
1043+
<h4> Example 1: Direct Relationship Path</h4>
1044+
1045+
Count Jira issues directly related to a Microservice:
1046+
1047+
```hcl
1048+
resource "port_blueprint" "microservice_blueprint" {
1049+
identifier = "microservice"
1050+
title = "Microservice"
1051+
}
1052+
1053+
resource "port_aggregation_properties" "microservice_aggregation_properties" {
1054+
blueprint_identifier = port_blueprint.microservice_blueprint.identifier
1055+
properties = {
1056+
direct_jira_issues_count = {
1057+
target_blueprint_identifier = port_blueprint.jira_issue_blueprint.identifier
1058+
title = "Direct Jira Issues Count"
1059+
icon = "Terraform"
1060+
description = "Direct Jira Issues Count"
1061+
path_filter = [
1062+
{
1063+
path = ["jira_issue_rel"]
1064+
}
1065+
]
1066+
method = {
1067+
count_entities = true
1068+
}
1069+
}
1070+
}
1071+
}
1072+
```
1073+
1074+
The `path = ["jira_issue_rel"]` ensures that only Jira issues directly related to the microservice through the `jira_issue_rel` relation are counted.
1075+
1076+
<h4>Example 2: Multi-hop Relationship Path</h4>
1077+
1078+
Count deployments through Service → Microservice → Deployment:
1079+
1080+
```hcl
1081+
resource "port_blueprint" "service_blueprint" {
1082+
identifier = "service"
1083+
title = "Service"
1084+
}
1085+
1086+
resource "port_blueprint" "microservice_blueprint" {
1087+
identifier = "microservice"
1088+
title = "Microservice"
1089+
}
1090+
1091+
resource "port_blueprint" "deployment_blueprint" {
1092+
identifier = "deployment"
1093+
title = "Deployment"
1094+
}
1095+
1096+
resource "port_aggregation_properties" "service_aggregation_properties" {
1097+
blueprint_identifier = port_blueprint.service_blueprint.identifier
1098+
properties = {
1099+
deployment_count = {
1100+
target_blueprint_identifier = port_blueprint.deployment_blueprint.identifier
1101+
title = "Deployment Count"
1102+
icon = "Terraform"
1103+
description = "Deployment Count"
1104+
path_filter = [
1105+
{
1106+
path = ["microservice_rel", "deployment_rel"]
1107+
}
1108+
]
1109+
method = {
1110+
count_entities = true
1111+
}
1112+
}
1113+
}
1114+
}
1115+
```
1116+
1117+
The `path = ["microservice_rel", "deployment_rel"]` counts deployments that are connected through the `microservice_rel` relation first, then to the `deployment_rel` relation.
1118+
1119+
<h4>Example 3: Starting Path from Specific Blueprint</h4>
1120+
1121+
Count deployments by starting path traversal from the target blueprint:
1122+
1123+
```hcl
1124+
resource "port_blueprint" "service_blueprint" {
1125+
identifier = "service"
1126+
title = "Service"
1127+
}
1128+
1129+
resource "port_blueprint" "microservice_blueprint" {
1130+
identifier = "microservice"
1131+
title = "Microservice"
1132+
}
1133+
1134+
resource "port_blueprint" "deployment_blueprint" {
1135+
identifier = "deployment"
1136+
title = "Deployment"
1137+
}
1138+
1139+
resource "port_aggregation_properties" "service_aggregation_properties" {
1140+
blueprint_identifier = port_blueprint.service_blueprint.identifier
1141+
properties = {
1142+
deployment_count_from_service = {
1143+
target_blueprint_identifier = port_blueprint.deployment_blueprint.identifier
1144+
title = "Deployment Count from Service"
1145+
icon = "Terraform"
1146+
description = "Deployment Count from Service"
1147+
path_filter = [
1148+
{
1149+
path = ["microservice_rel", "deployment_rel"]
1150+
from_blueprint = "deployment"
1151+
}
1152+
]
1153+
method = {
1154+
count_entities = true
1155+
}
1156+
}
1157+
}
1158+
}
1159+
```
1160+
1161+
The `from_blueprint = "deployment"` specifies that the path traversal should start from the deployment blueprint (the target), then follow the path backwards through `microservice_rel` to service.
1162+
1163+
</TabItem>
1164+
1165+
</Tabs>
1166+
1167+
:::tip Path Filter Performance
1168+
Path filters can affect the performance of aggregation calculations. In general, shorter and more direct paths perform better than long or complex multi-hop paths.
1169+
:::
9051170

9061171
## Limitations
9071172

0 commit comments

Comments
 (0)