From c707b40e25787e32817f188a23e72916261b735d Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Tue, 2 Sep 2025 09:14:11 +0300 Subject: [PATCH 01/12] WIP --- docs/search-and-query/search-and-query.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/search-and-query/search-and-query.md b/docs/search-and-query/search-and-query.md index a5b0b6652d..c1f1f5728a 100644 --- a/docs/search-and-query/search-and-query.md +++ b/docs/search-and-query/search-and-query.md @@ -28,10 +28,10 @@ To search for entities using the API, see the [search](/api-reference/search-a-b A search request is comprised of the following elements: -| Field | Description | -| ------------ | --------------------------------------------------------- | -| `combinator` | Defines the logical operation to apply to the query rules | -| `rules` | An array of search rules to filter results with | +| Field | Description | +| ------------ | ---------------------------------------------------------- | +| `combinator` | Defines the logical operation to apply to the query rules. | +| `rules` | An array of search rules to filter results with. | For example: @@ -190,8 +190,8 @@ This query will return all of the entities that are related to one or more of th The `relatedTo` operator also supports the `required` property - which allows you to search for: -- Related entities from all relations (relations with either required `true` or `false`); -- Related entities only from required relations (relations with required `true`); +- Related entities from all relations (relations with either required `true` or `false`). +- Related entities only from required relations (relations with required `true`). - Related entities only from non-required relations (relations with required `false`). For example, to search only for related entities that _require_ the `myEntity` entity from the `myBlueprint` blueprint, use the following search rule: @@ -252,7 +252,7 @@ By looking at the resulting graph layout, we can also map the directions: ![Dependency graph upstream downstream diagram](/img/software-catalog/search-in-port/search-direction-diagram.png) -- To search for entities which the source depends on - use `"direction": "upstream"`; +- To search for entities which the source depends on - use `"direction": "upstream"`. - To search for entities which depend on the source - use `"direction": "downstream"`. In the example shown above, if we want to get the `Microservice` and `Environment` that _Order-Service-Production_ depends on, the search rule would be: From 31559a17b414adf1cf624d2ed36d11a4b3557226 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Tue, 2 Sep 2025 14:40:40 +0300 Subject: [PATCH 02/12] edited the existing self-relation documentation --- .../page/entity-page.md | 117 +++++++++++------- 1 file changed, 72 insertions(+), 45 deletions(-) diff --git a/docs/customize-pages-dashboards-and-plugins/page/entity-page.md b/docs/customize-pages-dashboards-and-plugins/page/entity-page.md index 29165ab212..bd6c84a215 100644 --- a/docs/customize-pages-dashboards-and-plugins/page/entity-page.md +++ b/docs/customize-pages-dashboards-and-plugins/page/entity-page.md @@ -67,7 +67,7 @@ When looking at the entity page of a certain `Workflow Run`, the related entitie :::tip Relation path options -The relation path dropdown displays straightforward, acyclic paths. For complex scenarios involving circular relationships, advanced path configurations, multiple self relations, or maxHops, use [JSON mode](#filters-and-edit-json). +The relation path dropdown displays straightforward, acyclic paths. For complex scenarios involving circular relationships, advanced path configurations, multiple self-relations, or maxHops, use [JSON mode](#filters-and-edit-json). Using "All paths" is less performant than selecting a specific path, as it requires the system to evaluate multiple relationship paths. ::: @@ -174,48 +174,60 @@ If **Deployment Workflow** has multiple relations to **Microservice** (e.g., `de Additionally, when you have an existing relation between blueprints, Port automatically creates a mirror property relation that allows you to traverse the relationship in both directions. This mirror relation will appear as an option in the relation dropdown, enabling you to explore connections from either side of the relationship. ::: -#### Self relation +#### Self-relation -A self relation allows a blueprint to establish a relationship with itself. This is useful when you want entities of the same blueprint to be related to other entities within that same blueprint. +A self-relation allows a blueprint to establish a relationship with itself. This is useful when you want entities of the same blueprint to be related to other entities within that same blueprint. -For example, consider an **Organization** blueprint where: -- Organizations contain teams -- Teams can belong to other organizational entities (like groups) -- All entities share the same blueprint but have hierarchical relationships +For example, consider a **Team** blueprint where: +- Organizations contain teams. +- Teams can belong to other organizational entities (like groups). -When defining a self relation, you can specify how many "hops" to traverse in the relationship chain. +All entities share the same blueprint but have hierarchical relationships. + +When defining a self-relation, you can specify how many "hops" to traverse in the relationship chain. Hops represent the number of jumps you want to make upstream or downstream through the self-relation. -

Set up self relations

+:::tip Create a self-relation +Before performing the following steps, make sure the desired blueprint has a relation to itself. + +
+Add self-relation (click to exapnd) +1. Go to your [Builder](https://app.getport.io/settings/data-model) page of your portal. +2. Choose the relevant blueprint. +3. Click the `+ New relation` button. +4. Give the property a `title`, choose the same blueprint in the `Related to` field. +5. Choose the entity limit and whether its required. +6. Click `Save`. +
+::: -Follow these steps to set up a self relation in related entities: +**Set up self-relations tab** -1. Click the `+` button above the Related Entities table. +To add a self-relation tab to the related entities: -2. Choose your blueprint as the `Related blueprint`. +1. Click the `+` button in the **Related Entities** table. -3. Select the self relation path from the available paths. +2. Choose your blueprint as the **Related blueprint**. - :::tip How self relation hops work - If you want more than one **hop** then you would have to toggle `Json mode` on to specify more than one self relation blueprint identifier for the number of **hops** you want to make. - ::: +3. Select the self-relation path from the available paths. -4. You can also toggle to `Json mode` in the "Add tab" dialog to define the relationship path with precise control over hops. - - For example if we want to make 2 hops then we would have to specify 2 self relation blueprint identifiers in the path array. +4. If you want to traverse more than one hop, switch to `Json mode`. + In JSON mode you can: + - Specify multiple self-relation identifiers (for fixed hops). + For example, to traverse exactly 2 hops, list the relation twice in the path array: ```json showLineNumbers - "relationPath": { + "relationPath": { "path": [ "self_relation", "self_relation" - ] - } + ] + } ``` - - In JSON mode, you can use the `maxHops` feature to control the number of relationship traversals. Path elements can be objects instead of strings, and `maxHops` can only be specified once in the path. - - ```json showLineNumbers + + - Use maxHops (for variable hops). + For example, here we use `maxHops` to allow a flexible number of traversals (1–15). In this case, the system will traverse up to 4 hops: + ```json showLineNumbers "relationPath": { { "relation": "", @@ -223,8 +235,8 @@ Follow these steps to set up a self relation in related entities: } } ``` - - You can also have a mix of fixed and variable hops. + - Combine fixed hops with maxHops for mixed control. + In this example, the system traverses 2 fixed hops, then continues with up to 3 additional hops via maxHops: ```json showLineNumbers "relationPath": { @@ -242,23 +254,24 @@ Follow these steps to set up a self relation in related entities: You can only use `maxHops` once in a path and it it accepts a number between 1 and 15. ::: -6. Click on `Save` to save the tab. +5. Click on `Save` to save the tab. -:::info Self relation identifier -Note that `self_relation` in these examples represents the identifier of the self relation you created in your blueprint. Replace it with your actual self relation identifier. +:::info Self-relation identifier +Note that `self_relation` in these examples represents the identifier of the self-relation you created in your blueprint. Replace it with your actual self-relation identifier. ::: -

Examples

+**Examples** + Let's take a look at some examples using the concept of Teams. - +

-**Basic self relation with multiple self relations:** +**Basic self-relation with multiple self-relations:** -If you want exactly 2 hops, specify the relation twice: +If you want **exactly 2 hops**, specify the relation twice: ```json showLineNumbers { @@ -277,8 +290,9 @@ If you want exactly 2 hops, specify the relation twice: } } ``` +In this case, the added tab under the `Unit` entity should show the `Group` entity. -**Self relation with maxHops for variable hops:** +**Self-relation with maxHops for variable hops:** If you want a variable number of hops (between 1 and 15), use maxHops: @@ -302,25 +316,38 @@ If you want a variable number of hops (between 1 and 15), use maxHops: } ``` +In this case, the added tab under the `Unit`entity should show the `Basic Team`, `Group` and `Office` entities. + **Mixed approach example:** You can also mix fixed hops with variable hops. For example, if you specify `self_relation` twice followed by a `maxHops` object, the system will start traversing from the 2 hops already made and continue with the additional hops specified in `maxHops`. ```json showLineNumbers -"relationPath": { - "path": [ - "self_relation", // 1st hop: Unit -> Basic Team - "self_relation", // 2nd hop: Basic Team -> Group - { - "relation": "team_self_relation", - "maxHops": 3 // Continues from Group, adding up to 3 more hops (Group -> Office -> etc.) - } - ] +{ + "title": "Team Hierarchy", + "targetBlueprint": "Team", + "dataset": { + "combinator": "and", + "rules": [] + }, + "relationPath": { + "path": [ + "self_relation", + "self_relation", + { + "relation": "self_relation", + "maxHops": 3 + } + ], + "fromBlueprint": "Team" + } } ``` In this example, the system will traverse 2 fixed hops (Unit → Basic Team → Group) and then continue with up to 3 additional hops using the `team_self_relation`, starting from where the fixed hops left off. This could represent a complete organizational hierarchy from Unit all the way up to higher-level organizational structures. +In this case, the added tab under the `Unit`entity should show the `Group` and `Office` entities. + **Simple relation path example:** You can also use regular relations (not self-relations) in your paths: From b1554873046362d752668b943614a3b447747546 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Tue, 2 Sep 2025 17:40:06 +0300 Subject: [PATCH 03/12] WIP --- docs/search-and-query/search-and-query.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/search-and-query/search-and-query.md b/docs/search-and-query/search-and-query.md index c1f1f5728a..74c6c3a649 100644 --- a/docs/search-and-query/search-and-query.md +++ b/docs/search-and-query/search-and-query.md @@ -501,10 +501,19 @@ This will return all **deployments** that are related to the "production-service --- +**Examples** + +Suppose you have the following data model: + + + +--- + The `matchAny` operator will match entities based on your input: - If you specify a single value, it will find all entities with the same identifier. - If you provide a list of values, it will match any entity whose identifier is in the list. + From c9c786a20fb1c6c8cfb4de16b26d8aacb161b30b Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Tue, 2 Sep 2025 17:59:26 +0300 Subject: [PATCH 04/12] WIP --- docs/search-and-query/search-and-query.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/search-and-query/search-and-query.md b/docs/search-and-query/search-and-query.md index 74c6c3a649..b5b9f47cee 100644 --- a/docs/search-and-query/search-and-query.md +++ b/docs/search-and-query/search-and-query.md @@ -505,7 +505,18 @@ This will return all **deployments** that are related to the "production-service Suppose you have the following data model: - + + +The image above represents different entities of the same blueprint, in this case `Team`. + +**Example 1: Basic self-relation with multiple self-relations** + +If you want **exactly 2 hops**, specify the relation twice: + +```json showLineNumbers + + +``` --- From dab7adaa090e7fa6f4a5180dab832999ff540339 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Tue, 2 Sep 2025 18:07:46 +0300 Subject: [PATCH 05/12] WIP --- docs/search-and-query/search-and-query.md | 65 +++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/docs/search-and-query/search-and-query.md b/docs/search-and-query/search-and-query.md index b5b9f47cee..b498583ed4 100644 --- a/docs/search-and-query/search-and-query.md +++ b/docs/search-and-query/search-and-query.md @@ -514,8 +514,73 @@ The image above represents different entities of the same blueprint, in this cas If you want **exactly 2 hops**, specify the relation twice: ```json showLineNumbers +{ + "combinator": "and", + "rules": [ + { + "property": { + "path": [ + "self_relation", + "sefl_relation" + ] + }, + "operator": "matchAny", + "value": "targetEntity" + } + ] +} +``` + +**Example 2: Self-relation with maxHops for variable hops** + +If you want a variable number of hops (between 1 and 15), use maxHops: + +```json showLineNumbers +{ + "combinator": "and", + "rules": [ + { + "property": { + "path": [ + "self_relation", + { + "relation": "self_relation", + "maxHops": 4 + } + ], + "fromBlueprint": "_team" + }, + "operator": "matchAny", + "value": "targetEntity" + } + ] +} +``` +**Example 3: Mixed approach example:** +You can also mix fixed hops with variable hops. For example, if you specify `self_relation` twice followed by a `maxHops` object, the system will start traversing from the 2 hops already made and continue with the additional hops specified in `maxHops`. + +```json showLineNumbers +{ + "combinator": "and", + "rules": [ + { + "property": { + "path": [ + "self_relation", + "self_relation", + { + "relation": "self_relation", + "maxHops": 3 + } + ], + "fromBlueprint": "Team", + "operator": "matchAny", + "value": "targetEntity" + } + ] +} ``` --- From 398c8c8b76366024f236c51db562c33b6fcf2cc0 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Wed, 3 Sep 2025 13:40:48 +0300 Subject: [PATCH 06/12] Added examples for search-and-query --- .../page/entity-page.md | 19 ++--- docs/search-and-query/search-and-query.md | 74 +++++++++++++------ 2 files changed, 61 insertions(+), 32 deletions(-) diff --git a/docs/customize-pages-dashboards-and-plugins/page/entity-page.md b/docs/customize-pages-dashboards-and-plugins/page/entity-page.md index 0fb9db3263..ee9d175f60 100644 --- a/docs/customize-pages-dashboards-and-plugins/page/entity-page.md +++ b/docs/customize-pages-dashboards-and-plugins/page/entity-page.md @@ -214,8 +214,7 @@ To add a self-relation tab to the related entities: 4. If you want to traverse more than one hop, switch to `Json mode`. In JSON mode you can: - - Specify multiple self-relation identifiers (for fixed hops). - For example, to traverse exactly 2 hops, list the relation twice in the path array: + - Specify multiple self-relation identifiers (for fixed hops). ```json showLineNumbers "relationPath": { "path": [ @@ -225,8 +224,7 @@ To add a self-relation tab to the related entities: } ``` - - Use maxHops (for variable hops). - For example, here we use `maxHops` to allow a flexible number of traversals (1–15). In this case, the system will traverse up to 4 hops: + - Use maxHops (for variable hops). ```json showLineNumbers "relationPath": { { @@ -235,8 +233,7 @@ To add a self-relation tab to the related entities: } } ``` - - Combine fixed hops with maxHops for mixed control. - In this example, the system traverses 2 fixed hops, then continues with up to 3 additional hops via maxHops: + - Combine fixed hops with maxHops for mixed control. ```json showLineNumbers "relationPath": { @@ -250,8 +247,8 @@ To add a self-relation tab to the related entities: } ``` - :::info maxHops limitation - You can only use `maxHops` once in a path and it accepts a number between 1 and 15. + :::info `maxHops` limitation + The `maxHops` parameter can only be applied **once** per path, and it accepts values from **1 to 15**. ::: 5. Click on `Save` to save the tab. @@ -316,7 +313,7 @@ If you want a variable number of hops (between 1 and 15), use maxHops: } ``` -In this case, the added tab under the `Unit`entity should show the `Basic Team`, `Group` and `Office` entities. +In this case, the added tab under the `Unit` entity should show the `Basic Team`, `Group` and `Office` entities. **Mixed approach example:** @@ -335,7 +332,7 @@ You can also mix fixed hops with variable hops. For example, if you specify `sel "self_relation", "self_relation", { - "relation": "self_relation", + "relation": "team_self_relation", "maxHops": 3 } ], @@ -344,7 +341,7 @@ You can also mix fixed hops with variable hops. For example, if you specify `sel } ``` -In this example, the system will traverse 2 fixed hops (Unit → Basic Team → Group) and then continue with up to 3 additional hops using the `team_self_relation`, starting from where the fixed hops left off. This could represent a complete organizational hierarchy from Unit all the way up to higher-level organizational structures. +In this example, the system will traverse 2 fixed hops (`Unit` → `Basic Team` → `Group`) and then continue with up to 3 additional hops using the `team_self_relation`, starting from where the fixed hops left off. This could represent a complete organizational hierarchy from Unit all the way up to higher-level organizational structures. In this case, the added tab under the `Unit`entity should show the `Group` and `Office` entities. diff --git a/docs/search-and-query/search-and-query.md b/docs/search-and-query/search-and-query.md index 8e830197ad..6c241ca3e3 100644 --- a/docs/search-and-query/search-and-query.md +++ b/docs/search-and-query/search-and-query.md @@ -502,17 +502,19 @@ This will return all **deployments** that are related to the "production-service --- -**Examples** +**Examples: self-relation** Suppose you have the following data model: +

-The image above represents different entities of the same blueprint, in this case `Team`. +The image above represents an organization hierarchy, with different entities of the same **blueprint**, in this case `Team`. +Let's assume the blueprint has a self-relation and call it `parent`. -**Example 1: Basic self-relation with multiple self-relations** +**Example 1: basic self-relation with fixed hops count** -If you want **exactly 2 hops**, specify the relation twice: +If you want **exactly 2 hops**, specify the self-relation twice: ```json showLineNumbers { @@ -521,9 +523,10 @@ If you want **exactly 2 hops**, specify the relation twice: { "property": { "path": [ - "self_relation", - "sefl_relation" - ] + "parent", + "parent" + ], + "fromBlueprint" : "Team" }, "operator": "matchAny", "value": "targetEntity" @@ -531,10 +534,19 @@ If you want **exactly 2 hops**, specify the relation twice: ] } ``` + +For example, if the `value` is `Squad`: +- First hop: `Squad` → `Tribe`. +- Second hop: `Tribe` → `Domain`. + +Result: `Domain` (only the final destination after exactly 2 hops). + +___ -**Example 2: Self-relation with maxHops for variable hops** +**Example 2: self-relation with maxHops for variable hops** -If you want a variable number of hops (between 1 and 15), use maxHops: +If you want a variable number of hops (between 1 and 15), use `maxHops`. +`maxHops` specifies the maximum number of hops to traverse through the self-relation. ```json showLineNumbers { @@ -543,13 +555,12 @@ If you want a variable number of hops (between 1 and 15), use maxHops: { "property": { "path": [ - "self_relation", { - "relation": "self_relation", - "maxHops": 4 + "relation": "parent", + "maxHops": 3 } ], - "fromBlueprint": "_team" + "fromBlueprint": "Team" }, "operator": "matchAny", "value": "targetEntity" @@ -558,9 +569,22 @@ If you want a variable number of hops (between 1 and 15), use maxHops: } ``` -**Example 3: Mixed approach example:** +For example, if the `value` is `Squad`: +- First hop: `Squad` → `Tribe`. +- Second hop: `Tribe` → `Domain`. +- Third hop: `Domain` → `Group`. + +Result: `Tribe`, `Domain` and `Group` (all entities found along the path up to 3 hops). -You can also mix fixed hops with variable hops. For example, if you specify `self_relation` twice followed by a `maxHops` object, the system will start traversing from the 2 hops already made and continue with the additional hops specified in `maxHops`. +:::info `maxHops` limitation +The `maxHops` parameter can only be applied **once** per path, and it accepts values from **1 to 15**. +::: + +___ + +**Example 3: mixed approach** + +You can also mix fixed hops with variable hops. For example, if you specify the self-relation twice followed by a `maxHops` object, the system will start traversing from the 2 hops already made and continue with the additional hops specified in `maxHops`. ```json showLineNumbers { @@ -569,21 +593,29 @@ You can also mix fixed hops with variable hops. For example, if you specify `sel { "property": { "path": [ - "self_relation", - "self_relation", + "parent", + "parent", { - "relation": "self_relation", + "relation": "parent", "maxHops": 3 } - ], - "fromBlueprint": "Team", + ], + "fromBlueprint": "Team" + }, "operator": "matchAny", - "value": "targetEntity" + "value": "targetEntity" } ] } ``` +For example, if the `value` is `Squad`: +- First hop: `Squad` → `Tribe`. +- Second hop: `Tribe` → `Domain`. +- Third hop: `Domain` → `Group`. + +Result: `Domain` (from fixed hops) and `Group` (from variable hops, up to 3 additional hops). + --- The `matchAny` operator will match entities based on your input: From a310d10149bdb621eac60c2a8b9947213e5c16cc Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Wed, 3 Sep 2025 13:44:59 +0300 Subject: [PATCH 07/12] added back the comments accidently deleted --- .../page/entity-page.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/customize-pages-dashboards-and-plugins/page/entity-page.md b/docs/customize-pages-dashboards-and-plugins/page/entity-page.md index ee9d175f60..bb2fd2ff1d 100644 --- a/docs/customize-pages-dashboards-and-plugins/page/entity-page.md +++ b/docs/customize-pages-dashboards-and-plugins/page/entity-page.md @@ -329,11 +329,11 @@ You can also mix fixed hops with variable hops. For example, if you specify `sel }, "relationPath": { "path": [ - "self_relation", - "self_relation", + "self_relation", // 1st hop: Unit -> Basic Team + "self_relation", // 2nd hop: Basic Team -> Group { "relation": "team_self_relation", - "maxHops": 3 + "maxHops": 3 // Continues from Group, adding up to 3 more hops (Group -> Office -> etc.) } ], "fromBlueprint": "Team" From d280d8eb68f05d4a9f3d55a4e07c0ea80bfd311f Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Thu, 4 Sep 2025 15:33:15 +0300 Subject: [PATCH 08/12] WIP --- docs/customize-pages-dashboards-and-plugins/page/entity-page.md | 2 +- docs/search-and-query/relation-operators.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 docs/search-and-query/relation-operators.md diff --git a/docs/customize-pages-dashboards-and-plugins/page/entity-page.md b/docs/customize-pages-dashboards-and-plugins/page/entity-page.md index bb2fd2ff1d..b4d772069a 100644 --- a/docs/customize-pages-dashboards-and-plugins/page/entity-page.md +++ b/docs/customize-pages-dashboards-and-plugins/page/entity-page.md @@ -192,7 +192,7 @@ Before performing the following steps, make sure the desired blueprint has a rel
Add self-relation (click to exapnd) -1. Go to your [Builder](https://app.getport.io/settings/data-model) page of your portal. +1. Go to the [Builder](https://app.getport.io/settings/data-model) page of your portal. 2. Choose the relevant blueprint. 3. Click the `+ New relation` button. 4. Give the property a `title`, choose the same blueprint in the `Related to` field. diff --git a/docs/search-and-query/relation-operators.md b/docs/search-and-query/relation-operators.md new file mode 100644 index 0000000000..e69de29bb2 From 21e97534cae89d6b734c7f02fa4fb117bb7de7ba Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Thu, 4 Sep 2025 16:59:06 +0300 Subject: [PATCH 09/12] WIP --- docs/search-and-query/advanced.md | 2 +- docs/search-and-query/examples.md | 2 +- docs/search-and-query/global-search.md | 2 +- docs/search-and-query/relation-operators.md | 472 +++++++++++++++++++ docs/search-and-query/search-and-query.md | 490 +------------------- 5 files changed, 476 insertions(+), 492 deletions(-) diff --git a/docs/search-and-query/advanced.md b/docs/search-and-query/advanced.md index b9458d58db..5ec5bb445d 100644 --- a/docs/search-and-query/advanced.md +++ b/docs/search-and-query/advanced.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- import Tabs from "@theme/Tabs" diff --git a/docs/search-and-query/examples.md b/docs/search-and-query/examples.md index 6427368866..d610a26271 100644 --- a/docs/search-and-query/examples.md +++ b/docs/search-and-query/examples.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 5 --- import Tabs from "@theme/Tabs" diff --git a/docs/search-and-query/global-search.md b/docs/search-and-query/global-search.md index 8c5c829b21..ab644be938 100644 --- a/docs/search-and-query/global-search.md +++ b/docs/search-and-query/global-search.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 3 --- import PortTooltip from "/src/components/tooltip/tooltip.jsx" diff --git a/docs/search-and-query/relation-operators.md b/docs/search-and-query/relation-operators.md index e69de29bb2..0092042e28 100644 --- a/docs/search-and-query/relation-operators.md +++ b/docs/search-and-query/relation-operators.md @@ -0,0 +1,472 @@ +--- +sidebar_position: 2 +--- + +# Relation operators + +## Related to + +The `relatedTo` operator will return all entities that have a relationship with the specified entity: + +### Structure + +| Field | Description | +| ----------- | ------------------------------------------------------------------------------------------ | +| `operator` | Search operator to use when evaluating this rule, see a list of available operators below. | +| `blueprint` | Blueprint of the entity identifier specified in the `value` field. | +| `value` | Value to filter by. | + + +```json showLineNumbers +{ + "operator": "relatedTo", + "blueprint": "myBlueprint", + "value": "myEntity" +} +``` + +The operator also supports multiple related entities as the searched value: + +```json showLineNumbers +{ + "operator": "relatedTo", + "blueprint": "myBlueprint", + "value": ["myFirstEntity", "mySecondEntity"] +} +``` +This query will return all of the entities that are related to one or more of the identifiers in the value array. + +### Required + +The `relatedTo` operator also supports the `required` property - which allows you to search for: + +- Related entities from all relations (relations with either required `true` or `false`). +- Related entities only from required relations (relations with required `true`). +- Related entities only from non-required relations (relations with required `false`). + +For example, to search only for related entities that _require_ the `myEntity` entity from the `myBlueprint` blueprint, use the following search rule: + +```json showLineNumbers +{ + "operator": "relatedTo", + "required": true, + "value": "myEntity", + "blueprint": "myBlueprint" +} +``` + +### Direction + +The `relatedTo` operator also supports the `direction` property - which allows you to search for dependent entities in a specific direction on the dependency graph. To better understand the functionality of this property, let's take a look at the example below: + +Let's assume that we have the blueprints `deploymentConfig` and `microservice` with the following relation definition (declared on the `deploymentConfig` blueprint): + +```json showLineNumbers +"relations": { + "microservice": { + "description": "The service this Deployment Config belongs to", + "many": false, + "required": false, + "target": "microservice", + "title": "Microservice" + } +} +``` + +In addition, we have the following entities: + +```text showLineNumbers +Deployment Configs: +- Order-Service-Production +- Cart-Service-Production + +Microservices: +- Order Service +- Cart Service + +Environments: +- Production +``` + +And the following relations: + +```text showLineNumbers +Order-Service-Production -> Order-Service +Order-Service-Production -> Production + +Cart-Service-Production -> Cart-Service +Cart-Service-Production -> Production +``` + +By looking at the resulting graph layout, we can also map the directions: + +![Dependency graph upstream downstream diagram](/img/software-catalog/search-in-port/search-direction-diagram.png) + +- To search for entities which the source depends on - use `"direction": "upstream"`. +- To search for entities which depend on the source - use `"direction": "downstream"`. + +In the example shown above, if we want to get the `Microservice` and `Environment` that _Order-Service-Production_ depends on, the search rule would be: + +```json showLineNumbers +{ + "operator": "relatedTo", + "blueprint": "deploymentConfig", + "value": "Order-Service-Production", + "direction": "upstream" +} +``` + +And the result shall be: + +
+Order-Service-Production upstream related entities + +```json showLineNumbers +{ + "ok": true, + "matchingBlueprints": ["microservice", "environment"], + "entities": [ + { + "identifier": "Order-Service", + "title": "Order-Service", + "blueprint": "microservice", + "properties": { + "on-call": "mor@getport.io", + "language": "Python", + "slack-notifications": "https://slack.com/Order-Service", + "launch-darkly": "https://launchdarkly.com/Order-Service" + }, + "relations": {}, + "createdAt": "2022-11-17T15:54:20.432Z", + "createdBy": "auth0|62ab380295b34240aa511cdb", + "updatedAt": "2022-11-17T15:54:20.432Z", + "updatedBy": "auth0|62ab380295b34240aa511cdb" + }, + { + "identifier": "Production", + "title": "Production", + "blueprint": "environment", + "properties": { + "awsRegion": "eu-west-1", + "configUrl": "https://github.com/config-labs/kube/config.yml", + "slackChannel": "https://yourslack.slack.com/archives/CHANNEL-ID", + "onCall": "Mor P", + "namespace": "Production" + }, + "relations": {}, + "createdAt": "2022-09-19T08:54:23.025Z", + "createdBy": "Cnc3SiO7T0Ld1y1u0BsBZFJn0SCiPeLS", + "updatedAt": "2022-10-16T09:28:32.960Z", + "updatedBy": "auth0|62ab380295b34240aa511cdb" + } + ] +} +``` + +
+ +If we want to get all of the `deploymentConfigs` that are deployed in the _Production_ `Environment`, the search rule would be: + +```json showLineNumbers +{ + "operator": "relatedTo", + "blueprint": "environment", + "value": "Production", + "direction": "downstream" +} +``` + +And the result shall be: + +
+Production downstream related entities + +```json showLineNumbers +{ + "ok": true, + "matchingBlueprints": ["deploymentConfig"], + "entities": [ + { + "identifier": "Order-Service-Production", + "title": "Order-Service-Production", + "blueprint": "deploymentConfig", + "properties": { + "url": "https://github.com/port-labs/order-service", + "config": { + "encryption": "SHA256" + }, + "monitor-links": [ + "https://grafana.com", + "https://prometheus.com", + "https://datadog.com" + ] + }, + "relations": { + "microservice": "Order-Service", + "environment": "Production" + }, + "createdAt": "2022-11-17T15:55:55.591Z", + "createdBy": "auth0|62ab380295b34240aa511cdb", + "updatedAt": "2022-11-17T15:55:55.591Z", + "updatedBy": "auth0|62ab380295b34240aa511cdb" + }, + { + "identifier": "Cart-Service-Production", + "title": "Cart-Service-Production", + "blueprint": "deploymentConfig", + "properties": { + "url": "https://github.com/port-labs/cart-service", + "config": { + "foo": "bar" + }, + "monitor-links": [ + "https://grafana.com", + "https://prometheus.com", + "https://datadog.com" + ] + }, + "relations": { + "microservice": "Cart-Service", + "environment": "Production" + }, + "createdAt": "2022-11-17T15:55:10.714Z", + "createdBy": "auth0|62ab380295b34240aa511cdb", + "updatedAt": "2022-11-17T15:55:20.253Z", + "updatedBy": "auth0|62ab380295b34240aa511cdb" + } + ] +} +``` + +
+ +## Match any + +### Related to by specific path + +You can search for entities that are related through a specific path of relations. This is useful when you want to find entities that are connected through a specific chain of relationships. + + +### Structure + +| Field | Description | +|---------------------------|----------------------------------------------------------------------------------------------------------------------| +| `property.path` | An array containing the full path of relation identifiers to traverse. | +| `property.fromBlueprint` | *(Optional)* The blueprint to start the path traversal from. If omitted, traversal starts from the target blueprint. | +| `operator` | The search operator to use. For this feature, use `"matchAny"`. | +| `value` | The value or list of values to match against the target entity identifiers at the end of the path. | + + +#### For upstream paths + +```json showLineNumbers +{ + "property": { + "path": ["relation1", "relation2", "relation3"] + }, + "operator": "matchAny", + "value": "targetEntity" +} +``` + +#### For downstream paths + +```json showLineNumbers +{ + "property": { + "path": ["relation1", "relation2", "relation3"], + "fromBlueprint": "sourceBlueprint" + }, + "operator": "matchAny", + "value": "targetEntity" +} +``` + +When using downstream paths, the `fromBlueprint` parameter specifies the source blueprint from which to start the path traversal. + +Instead of thinking about the path as downstream from the target, we treat it as upstream from the specified blueprint to the target blueprint. This means that the path will be traversed starting from entities of the specified `fromBlueprint`. + +### Examples + +Suppose you have the following data model: + +![Dependency graph upstream downstream diagram](/img/software-catalog/search-in-port/specific-path-diagram-example.png) + +

Example 1: Find all services related to a cluster (upstream)

+ +To find all services that are related to a specific cluster (e.g., "production-cluster"): + +```json showLineNumbers +{ + "combinator": "and", + "rules": [ + { + "property": "$blueprint", + "operator": "=", + "value": "service" + }, + { + "property": { + "path": ["deployedOn"] + }, + "operator": "matchAny", + "value": "production-cluster" + } + ] +} +``` + +This will return all **services** that have a deployment in the "production-cluster". + +--- + +

Example 2: Find all deployments related to a specific service (downstream)

+ +To find all deployments related to a specific service (e.g., "production-service"): + +```json showLineNumbers +{ + "combinator": "and", + "rules": [ + { + "property": "$blueprint", + "operator": "=", + "value": "deployment" + }, + { + "property": { + "path": ["deployedOn", "deployments"], + "fromBlueprint": "service" + }, + "operator": "matchAny", + "value": "production-service" + } + ] +} +``` + +This will return all **deployments** that are related to the "production-service". + +--- + +## Self-relation + +**Examples** + +Suppose you have the following data model: + + +

+ +The image above represents an organization hierarchy, with different entities of the same **blueprint**, in this case `Team`. +Let's assume the blueprint has a self-relation and call it `parent`. + +**Example 1: basic self-relation with fixed hops count** + +If you want **exactly 2 hops**, specify the self-relation twice: + +```json showLineNumbers +{ + "combinator": "and", + "rules": [ + { + "property": { + "path": [ + "parent", + "parent" + ], + "fromBlueprint" : "Team" + }, + "operator": "matchAny", + "value": "targetEntity" + } + ] +} +``` + +For example, if the `value` is `Squad`: +- First hop: `Squad` → `Tribe`. +- Second hop: `Tribe` → `Domain`. + +Result: `Domain` (only the final destination after exactly 2 hops). + +___ + +**Example 2: self-relation with maxHops for variable hops** + +If you want a variable number of hops (between 1 and 15), use `maxHops`. +`maxHops` specifies the maximum number of hops to traverse through the self-relation. + +```json showLineNumbers +{ + "combinator": "and", + "rules": [ + { + "property": { + "path": [ + { + "relation": "parent", + "maxHops": 3 + } + ], + "fromBlueprint": "Team" + }, + "operator": "matchAny", + "value": "targetEntity" + } + ] +} +``` + +For example, if the `value` is `Squad`: +- First hop: `Squad` → `Tribe`. +- Second hop: `Tribe` → `Domain`. +- Third hop: `Domain` → `Group`. + +Result: `Tribe`, `Domain` and `Group` (all entities found along the path up to 3 hops). + +:::info `maxHops` limitation +The `maxHops` parameter can only be applied **once** per path, and it accepts values from **1 to 15**. +::: + +___ + +**Example 3: mixed approach** + +You can also mix fixed hops with variable hops. For example, if you specify the self-relation twice followed by a `maxHops` object, the system will start traversing from the 2 hops already made and continue with the additional hops specified in `maxHops`. + +```json showLineNumbers +{ + "combinator": "and", + "rules": [ + { + "property": { + "path": [ + "parent", + "parent", + { + "relation": "parent", + "maxHops": 3 + } + ], + "fromBlueprint": "Team" + }, + "operator": "matchAny", + "value": "targetEntity" + } + ] +} +``` + +For example, if the `value` is `Squad`: +- First hop: `Squad` → `Tribe`. +- Second hop: `Tribe` → `Domain`. +- Third hop: `Domain` → `Group`. + +Result: `Domain` (from fixed hops) and `Group` (from variable hops, up to 3 additional hops). + +--- + +The `matchAny` operator will match entities based on your input: +- If you specify a single value, it will find all entities with the same identifier. +- If you provide a list of values, it will match any entity whose identifier is in the list. \ No newline at end of file diff --git a/docs/search-and-query/search-and-query.md b/docs/search-and-query/search-and-query.md index 6c241ca3e3..823b8f1c9b 100644 --- a/docs/search-and-query/search-and-query.md +++ b/docs/search-and-query/search-and-query.md @@ -150,495 +150,7 @@ ___ ### Relation operators - - - - -The `relatedTo` operator will return all entities that have a relationship with the specified entity: - -

Structure

- -| Field | Description | -| ----------- | ----------------------------------------------------------------------------------------- | -| `operator` | Search operator to use when evaluating this rule, see a list of available operators below | -| `blueprint` | Blueprint of the entity identifier specified in the `value` field | -| `value` | Value to filter by | - - -```json showLineNumbers -{ - "operator": "relatedTo", - "blueprint": "myBlueprint", - "value": "myEntity" -} -``` - -The operator also supports multiple related entities as the searched value: - -```json showLineNumbers -{ - "operator": "relatedTo", - "blueprint": "myBlueprint", - "value": ["myFirstEntity", "mySecondEntity"] -} -``` -This query will return all of the entities that are related to one or more of the identifiers in the value array. - -

Required

- -The `relatedTo` operator also supports the `required` property - which allows you to search for: - -- Related entities from all relations (relations with either required `true` or `false`). -- Related entities only from required relations (relations with required `true`). -- Related entities only from non-required relations (relations with required `false`). - -For example, to search only for related entities that _require_ the `myEntity` entity from the `myBlueprint` blueprint, use the following search rule: - -```json showLineNumbers -{ - "operator": "relatedTo", - "required": true, - "value": "myEntity", - "blueprint": "myBlueprint" -} -``` - -

Direction

- -The `relatedTo` operator also supports the `direction` property - which allows you to search for dependent entities in a specific direction on the dependency graph. To better understand the functionality of this property, let's take a look at the example below: - -Let's assume that we have the blueprints `deploymentConfig` and `microservice` with the following relation definition (declared on the `deploymentConfig` blueprint): - -```json showLineNumbers -"relations": { - "microservice": { - "description": "The service this Deployment Config belongs to", - "many": false, - "required": false, - "target": "microservice", - "title": "Microservice" - } -} -``` - -In addition, we have the following entities: - -```text showLineNumbers -Deployment Configs: -- Order-Service-Production -- Cart-Service-Production - -Microservices: -- Order Service -- Cart Service - -Environments: -- Production -``` - -And the following relations: - -```text showLineNumbers -Order-Service-Production -> Order-Service -Order-Service-Production -> Production - -Cart-Service-Production -> Cart-Service -Cart-Service-Production -> Production -``` - -By looking at the resulting graph layout, we can also map the directions: - -![Dependency graph upstream downstream diagram](/img/software-catalog/search-in-port/search-direction-diagram.png) - -- To search for entities which the source depends on - use `"direction": "upstream"`. -- To search for entities which depend on the source - use `"direction": "downstream"`. - -In the example shown above, if we want to get the `Microservice` and `Environment` that _Order-Service-Production_ depends on, the search rule would be: - -```json showLineNumbers -{ - "operator": "relatedTo", - "blueprint": "deploymentConfig", - "value": "Order-Service-Production", - "direction": "upstream" -} -``` - -And the result shall be: - -
-Order-Service-Production upstream related entities - -```json showLineNumbers -{ - "ok": true, - "matchingBlueprints": ["microservice", "environment"], - "entities": [ - { - "identifier": "Order-Service", - "title": "Order-Service", - "blueprint": "microservice", - "properties": { - "on-call": "mor@getport.io", - "language": "Python", - "slack-notifications": "https://slack.com/Order-Service", - "launch-darkly": "https://launchdarkly.com/Order-Service" - }, - "relations": {}, - "createdAt": "2022-11-17T15:54:20.432Z", - "createdBy": "auth0|62ab380295b34240aa511cdb", - "updatedAt": "2022-11-17T15:54:20.432Z", - "updatedBy": "auth0|62ab380295b34240aa511cdb" - }, - { - "identifier": "Production", - "title": "Production", - "blueprint": "environment", - "properties": { - "awsRegion": "eu-west-1", - "configUrl": "https://github.com/config-labs/kube/config.yml", - "slackChannel": "https://yourslack.slack.com/archives/CHANNEL-ID", - "onCall": "Mor P", - "namespace": "Production" - }, - "relations": {}, - "createdAt": "2022-09-19T08:54:23.025Z", - "createdBy": "Cnc3SiO7T0Ld1y1u0BsBZFJn0SCiPeLS", - "updatedAt": "2022-10-16T09:28:32.960Z", - "updatedBy": "auth0|62ab380295b34240aa511cdb" - } - ] -} -``` - -
- -If we want to get all of the `deploymentConfigs` that are deployed in the _Production_ `Environment`, the search rule would be: - -```json showLineNumbers -{ - "operator": "relatedTo", - "blueprint": "environment", - "value": "Production", - "direction": "downstream" -} -``` - -And the result shall be: - -
-Production downstream related entities - -```json showLineNumbers -{ - "ok": true, - "matchingBlueprints": ["deploymentConfig"], - "entities": [ - { - "identifier": "Order-Service-Production", - "title": "Order-Service-Production", - "blueprint": "deploymentConfig", - "properties": { - "url": "https://github.com/port-labs/order-service", - "config": { - "encryption": "SHA256" - }, - "monitor-links": [ - "https://grafana.com", - "https://prometheus.com", - "https://datadog.com" - ] - }, - "relations": { - "microservice": "Order-Service", - "environment": "Production" - }, - "createdAt": "2022-11-17T15:55:55.591Z", - "createdBy": "auth0|62ab380295b34240aa511cdb", - "updatedAt": "2022-11-17T15:55:55.591Z", - "updatedBy": "auth0|62ab380295b34240aa511cdb" - }, - { - "identifier": "Cart-Service-Production", - "title": "Cart-Service-Production", - "blueprint": "deploymentConfig", - "properties": { - "url": "https://github.com/port-labs/cart-service", - "config": { - "foo": "bar" - }, - "monitor-links": [ - "https://grafana.com", - "https://prometheus.com", - "https://datadog.com" - ] - }, - "relations": { - "microservice": "Cart-Service", - "environment": "Production" - }, - "createdAt": "2022-11-17T15:55:10.714Z", - "createdBy": "auth0|62ab380295b34240aa511cdb", - "updatedAt": "2022-11-17T15:55:20.253Z", - "updatedBy": "auth0|62ab380295b34240aa511cdb" - } - ] -} -``` - -
- - - - - -

Related to by specific path

- -You can search for entities that are related through a specific path of relations. This is useful when you want to find entities that are connected through a specific chain of relationships. - - -

Structure

- -| Field | Description | -|---------------------------|----------------------------------------------------------------------------------------------------------------------| -| `property.path` | An array containing the full path of relation identifiers to traverse. | -| `property.fromBlueprint` | *(Optional)* The blueprint to start the path traversal from. If omitted, traversal starts from the target blueprint. | -| `operator` | The search operator to use. For this feature, use `"matchAny"`. | -| `value` | The value or list of values to match against the target entity identifiers at the end of the path. | - - -

For upstream paths:

- -```json showLineNumbers -{ - "property": { - "path": ["relation1", "relation2", "relation3"] - }, - "operator": "matchAny", - "value": "targetEntity" -} -``` - -

For downstream paths:

- -```json showLineNumbers -{ - "property": { - "path": ["relation1", "relation2", "relation3"], - "fromBlueprint": "sourceBlueprint" - }, - "operator": "matchAny", - "value": "targetEntity" -} -``` - -When using downstream paths, the `fromBlueprint` parameter specifies the source blueprint from which to start the path traversal. - -Instead of thinking about the path as downstream from the target, we treat it as upstream from the specified blueprint to the target blueprint. This means that the path will be traversed starting from entities of the specified `fromBlueprint`. - -

Examples

- -Suppose you have the following data model: - -![Dependency graph upstream downstream diagram](/img/software-catalog/search-in-port/specific-path-diagram-example.png) - -

Example 1: Find all services related to a cluster (upstream)

- -To find all services that are related to a specific cluster (e.g., "production-cluster"): - -```json showLineNumbers -{ - "combinator": "and", - "rules": [ - { - "property": "$blueprint", - "operator": "=", - "value": "service" - }, - { - "property": { - "path": ["deployedOn"] - }, - "operator": "matchAny", - "value": "production-cluster" - } - ] -} -``` - -This will return all **services** that have a deployment in the "production-cluster". - ---- - -

Example 2: Find all deployments related to a specific service (downstream)

- -To find all deployments related to a specific service (e.g., "production-service"): - -```json showLineNumbers -{ - "combinator": "and", - "rules": [ - { - "property": "$blueprint", - "operator": "=", - "value": "deployment" - }, - { - "property": { - "path": ["deployedOn", "deployments"], - "fromBlueprint": "service" - }, - "operator": "matchAny", - "value": "production-service" - } - ] -} -``` - -This will return all **deployments** that are related to the "production-service". - ---- - -**Examples: self-relation** - -Suppose you have the following data model: - - -

- -The image above represents an organization hierarchy, with different entities of the same **blueprint**, in this case `Team`. -Let's assume the blueprint has a self-relation and call it `parent`. - -**Example 1: basic self-relation with fixed hops count** - -If you want **exactly 2 hops**, specify the self-relation twice: - -```json showLineNumbers -{ - "combinator": "and", - "rules": [ - { - "property": { - "path": [ - "parent", - "parent" - ], - "fromBlueprint" : "Team" - }, - "operator": "matchAny", - "value": "targetEntity" - } - ] -} -``` - -For example, if the `value` is `Squad`: -- First hop: `Squad` → `Tribe`. -- Second hop: `Tribe` → `Domain`. - -Result: `Domain` (only the final destination after exactly 2 hops). - -___ - -**Example 2: self-relation with maxHops for variable hops** - -If you want a variable number of hops (between 1 and 15), use `maxHops`. -`maxHops` specifies the maximum number of hops to traverse through the self-relation. - -```json showLineNumbers -{ - "combinator": "and", - "rules": [ - { - "property": { - "path": [ - { - "relation": "parent", - "maxHops": 3 - } - ], - "fromBlueprint": "Team" - }, - "operator": "matchAny", - "value": "targetEntity" - } - ] -} -``` - -For example, if the `value` is `Squad`: -- First hop: `Squad` → `Tribe`. -- Second hop: `Tribe` → `Domain`. -- Third hop: `Domain` → `Group`. - -Result: `Tribe`, `Domain` and `Group` (all entities found along the path up to 3 hops). - -:::info `maxHops` limitation -The `maxHops` parameter can only be applied **once** per path, and it accepts values from **1 to 15**. -::: - -___ - -**Example 3: mixed approach** - -You can also mix fixed hops with variable hops. For example, if you specify the self-relation twice followed by a `maxHops` object, the system will start traversing from the 2 hops already made and continue with the additional hops specified in `maxHops`. - -```json showLineNumbers -{ - "combinator": "and", - "rules": [ - { - "property": { - "path": [ - "parent", - "parent", - { - "relation": "parent", - "maxHops": 3 - } - ], - "fromBlueprint": "Team" - }, - "operator": "matchAny", - "value": "targetEntity" - } - ] -} -``` - -For example, if the `value` is `Squad`: -- First hop: `Squad` → `Tribe`. -- Second hop: `Tribe` → `Domain`. -- Third hop: `Domain` → `Group`. - -Result: `Domain` (from fixed hops) and `Group` (from variable hops, up to 3 additional hops). - ---- - -The `matchAny` operator will match entities based on your input: -- If you specify a single value, it will find all entities with the same identifier. -- If you provide a list of values, it will match any entity whose identifier is in the list. - - - - - - -### Dynamic properties - -When using Port's UI, you can use properties of the logged-in user when writing rules by using the following functions: - -- `getUserTeams` - a list of the teams the user belongs to. -- `getUserEmail` - the user's email. -- `getUserFullName` - the user's full name. -- `blueprint` - the blueprint identifier of the current page. - -:::info UI only -Since we don't have context of the logged-in user when using the API, these functions are only available when using the UI. This is useful when creating [chart/table widgets](/customize-pages-dashboards-and-plugins/dashboards/#chart-filters) and [catalog pages](/customize-pages-dashboards-and-plugins/page/catalog-page#page-creation). -::: +TODO: Add a line here referncing the page. #### Usage examples From 834142618b24d9cc31b376f4ce0b8bcdae356b94 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Thu, 4 Sep 2025 18:03:14 +0300 Subject: [PATCH 10/12] WIP --- docs/search-and-query/relation-operators.md | 41 ++++++++++++--------- docs/search-and-query/search-and-query.md | 2 +- 2 files changed, 25 insertions(+), 18 deletions(-) diff --git a/docs/search-and-query/relation-operators.md b/docs/search-and-query/relation-operators.md index 0092042e28..411200a0dc 100644 --- a/docs/search-and-query/relation-operators.md +++ b/docs/search-and-query/relation-operators.md @@ -4,7 +4,9 @@ sidebar_position: 2 # Relation operators -## Related to +This page details the available relation operators when writing [rules](/search-and-query/#rules) as part of the search route. + +## RelatedTo The `relatedTo` operator will return all entities that have a relationship with the specified entity: @@ -119,7 +121,7 @@ In the example shown above, if we want to get the `Microservice` and `Environmen And the result shall be:
-Order-Service-Production upstream related entities +Order-Service-Production upstream related entities (click to expand) ```json showLineNumbers { @@ -179,7 +181,7 @@ If we want to get all of the `deploymentConfigs` that are deployed in the _Produ And the result shall be:
-Production downstream related entities +Production downstream related entities (click to expand) ```json showLineNumbers { @@ -240,7 +242,11 @@ And the result shall be:
-## Match any +## MatchAny + +The `matchAny` operator will match entities based on your input: +- If you specify a single value, it will find all entities with the same identifier. +- If you provide a list of values, it will match any entity whose identifier is in the list. ### Related to by specific path @@ -351,15 +357,22 @@ This will return all **deployments** that are related to the "production-service ## Self-relation -**Examples** +Self-relations allow a blueprint to reference itself, so entities of the same type can be connected. -Suppose you have the following data model: +For example, consider a `Team` blueprint used to represent an organization’s hierarchy: + +- `Squad` is a `Team`. +- A `Squad` can relate to a `Tribe`. +- A `Tribe` can relate to a `Domain`, and so on. + +All of these entities are instances of the `Team` blueprint, connected through a self-relation, let's call it `parent`. - -

+ +

-The image above represents an organization hierarchy, with different entities of the same **blueprint**, in this case `Team`. -Let's assume the blueprint has a self-relation and call it `parent`. +The diagram above illustrates this hierarchy, where different entities are linked by the same self-relation within the `Team` blueprint. + +### Examples **Example 1: basic self-relation with fixed hops count** @@ -463,10 +476,4 @@ For example, if the `value` is `Squad`: - Second hop: `Tribe` → `Domain`. - Third hop: `Domain` → `Group`. -Result: `Domain` (from fixed hops) and `Group` (from variable hops, up to 3 additional hops). - ---- - -The `matchAny` operator will match entities based on your input: -- If you specify a single value, it will find all entities with the same identifier. -- If you provide a list of values, it will match any entity whose identifier is in the list. \ No newline at end of file +Result: `Domain` (from fixed hops) and `Group` (from variable hops, up to 3 additional hops). \ No newline at end of file diff --git a/docs/search-and-query/search-and-query.md b/docs/search-and-query/search-and-query.md index 823b8f1c9b..058f945113 100644 --- a/docs/search-and-query/search-and-query.md +++ b/docs/search-and-query/search-and-query.md @@ -150,7 +150,7 @@ ___ ### Relation operators -TODO: Add a line here referncing the page. +Several relation-based operators are available, see them [here](./relation-operators). #### Usage examples From d08d85d491c6c2c28b685aea5c86a27a8bab0362 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Sun, 7 Sep 2025 09:40:42 +0300 Subject: [PATCH 11/12] Added a sentence about matchany and self-relation + added back dynamic properties I deleted accidently --- docs/search-and-query/relation-operators.md | 6 ++++-- docs/search-and-query/search-and-query.md | 14 ++++++++++++++ 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/search-and-query/relation-operators.md b/docs/search-and-query/relation-operators.md index 411200a0dc..b6ffc09048 100644 --- a/docs/search-and-query/relation-operators.md +++ b/docs/search-and-query/relation-operators.md @@ -370,7 +370,9 @@ All of these entities are instances of the `Team` blueprint, connected through a

-The diagram above illustrates this hierarchy, where different entities are linked by the same self-relation within the `Team` blueprint. +The diagram above illustrates this hierarchy, where different entities are linked by the same self-relation within the `Team` blueprint. + +You can use the `matchAny` operator to search through self-relations, allowing you to find entities at various levels of the hierarchy. ### Examples @@ -438,7 +440,7 @@ For example, if the `value` is `Squad`: Result: `Tribe`, `Domain` and `Group` (all entities found along the path up to 3 hops). -:::info `maxHops` limitation +:::info maxHops limitation The `maxHops` parameter can only be applied **once** per path, and it accepts values from **1 to 15**. ::: diff --git a/docs/search-and-query/search-and-query.md b/docs/search-and-query/search-and-query.md index 058f945113..2de71ac2be 100644 --- a/docs/search-and-query/search-and-query.md +++ b/docs/search-and-query/search-and-query.md @@ -152,6 +152,20 @@ ___ Several relation-based operators are available, see them [here](./relation-operators). +### Dynamic properties + +When using Port's UI, you can use properties of the logged-in user when writing rules by using the following functions: + +- `getUserTeams` - a list of the teams the user belongs to. +- `getUserEmail` - the user's email. +- `getUserFullName` - the user's full name. +- `blueprint` - the blueprint identifier of the current page. + +:::info UI only +Since we don't have context of the logged-in user when using the API, these functions are only available when using the UI. This is useful when creating [chart/table widgets](/customize-pages-dashboards-and-plugins/dashboards/#chart-filters) and [catalog pages](/customize-pages-dashboards-and-plugins/page/catalog-page#page-creation). +::: +Several relation-based operators are available, see them [here](./relation-operators). + #### Usage examples ```json showLineNumbers From ca41543dcddeffbbb9c92186cbf70ce537f689f9 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Sun, 7 Sep 2025 10:07:41 +0300 Subject: [PATCH 12/12] chaned hierarchy and self-relation explanation --- docs/search-and-query/advanced.md | 2 +- docs/search-and-query/examples.md | 2 +- docs/search-and-query/global-search.md | 2 +- docs/search-and-query/relation-operators.md | 11 ++--------- 4 files changed, 5 insertions(+), 12 deletions(-) diff --git a/docs/search-and-query/advanced.md b/docs/search-and-query/advanced.md index 5ec5bb445d..f1c4449cf2 100644 --- a/docs/search-and-query/advanced.md +++ b/docs/search-and-query/advanced.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 --- import Tabs from "@theme/Tabs" diff --git a/docs/search-and-query/examples.md b/docs/search-and-query/examples.md index d610a26271..651476c126 100644 --- a/docs/search-and-query/examples.md +++ b/docs/search-and-query/examples.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 3 --- import Tabs from "@theme/Tabs" diff --git a/docs/search-and-query/global-search.md b/docs/search-and-query/global-search.md index ab644be938..fb2e38f1a8 100644 --- a/docs/search-and-query/global-search.md +++ b/docs/search-and-query/global-search.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- import PortTooltip from "/src/components/tooltip/tooltip.jsx" diff --git a/docs/search-and-query/relation-operators.md b/docs/search-and-query/relation-operators.md index b6ffc09048..f5f0491622 100644 --- a/docs/search-and-query/relation-operators.md +++ b/docs/search-and-query/relation-operators.md @@ -359,18 +359,11 @@ This will return all **deployments** that are related to the "production-service Self-relations allow a blueprint to reference itself, so entities of the same type can be connected. -For example, consider a `Team` blueprint used to represent an organization’s hierarchy: - -- `Squad` is a `Team`. -- A `Squad` can relate to a `Tribe`. -- A `Tribe` can relate to a `Domain`, and so on. - -All of these entities are instances of the `Team` blueprint, connected through a self-relation, let's call it `parent`. -

-The diagram above illustrates this hierarchy, where different entities are linked by the same self-relation within the `Team` blueprint. +In this example, a **group** is comprised of one or more **domains**, which are comprised of one or more **tribes**, and so on. +The diagram illustrates the hierarchy, where different entities are linked by the same self-relation (parent) within the `Team` blueprint. You can use the `matchAny` operator to search through self-relations, allowing you to find entities at various levels of the hierarchy.