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 +287,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,24 +313,37 @@ 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", // 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.) + } + ], + "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 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:** diff --git a/docs/search-and-query/advanced.md b/docs/search-and-query/advanced.md index b9458d58db..f1c4449cf2 100644 --- a/docs/search-and-query/advanced.md +++ b/docs/search-and-query/advanced.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +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 6427368866..651476c126 100644 --- a/docs/search-and-query/examples.md +++ b/docs/search-and-query/examples.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +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 8c5c829b21..fb2e38f1a8 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: 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 new file mode 100644 index 0000000000..f5f0491622 --- /dev/null +++ b/docs/search-and-query/relation-operators.md @@ -0,0 +1,474 @@ +--- +sidebar_position: 2 +--- + +# Relation operators + +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: + +### 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: + + + +- 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: + +
+
+
+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:
+
+Order-Service-Production upstream related entities (click to expand)
+ +```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" + } + ] +} +``` + +
+
+
+## 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
+
+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:
+
+
+
+Production downstream related entities (click to expand)
+ +```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" + } + ] +} +``` + +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 + +Self-relations allow a blueprint to reference itself, so entities of the same type can be connected. + +
++ +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. + +### Examples + +**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). \ 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 3473538366..6e2b28cece 100644 --- a/docs/search-and-query/search-and-query.md +++ b/docs/search-and-query/search-and-query.md @@ -29,10 +29,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: @@ -150,365 +150,7 @@ ___ ### Relation operators -
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: - - - -- 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: - -
-
-
-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:
-
-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" - } - ] -} -``` - -
-
-
-