Search & query

Port's API provides tools to easily query, search and filter software catalog data. Port's search and queries can be used accross the Port product: in the catalog such as in initial filters to create advanced dynamic filtering, or in the self service actions form, to dynamically select a dropdown list.

Common queries usage

High quality search is essential to effectively track assets in your software catalog, using Port's search you can:

Find all running services that are not healthy.
List all libraries that have known vulnerabilities.
Filter all services running in a specific cluster (in a query or self service form).
Catalog initial filters based on the logged in user's properties.

Search request

The base search route is https://api.getport.io/v1/entities/search, it receives HTTP POST requests.

United States region

The route above uses the EU region API.
If you wish to use the US region API, the route is: https://api.us.getport.io/v1/entities/search.

A search request defines the logical relation between different search rules, and contains filters and rules to find matching entities. Each search request is represented by a JSON object, as shown in the following example:

{
  "combinator": "and",
  "rules": [
    {
      "property": "$blueprint",
      "operator": "=",
      "value": "myBlueprint"
    },
    {
      "property": "$identifier",
      "operator": "contains",
      "value": "myIdentifierPart"
    }
  ]
}

The above query searches for all entities based on the myBlueprint blueprint whose identifier contains the string myIdentifierPart.

Search request elements

Field	Description
`combinator`	Defines the logical operation to apply to the query rules
`rules`	An array of search rules to filter results with

Combinator

There are two available combinators: and/or:

and - will apply a logical AND operation between all rules, requiring all of them to satisfy for a given asset in order to return it;
or - will apply a logical OR operation between all rules, requiring at least one of them to satisfy for a given asset in order to return it.

single rule queries

If you only have a single rule in your query, the combinator has no effect. But keep in mind that it still needs to be included to adhere to the query structure.

Single rule query example

In the following example, only a single rule appears in the rules array, so the combinator field has no effect:

{
  "combinator": "and",
  "rules": [
    {
      "property": "$blueprint",
      "operator": "=",
      "value": "myBlueprint"
    }
  ]
}

{
  "combinator": "and",
  "rules": [
    {
      "property": "$blueprint",
      "operator": "=",
      "value": "myBlueprint"
    },
    {
      "property": "$identifier",
      "operator": "contains",
      "value": "myIdentifierPart"
    }
  ]
}

{
  "combinator": "or",
  "rules": [
    {
      "property": "$blueprint",
      "operator": "=",
      "value": "myBlueprint"
    },
    {
      "property": "$identifier",
      "operator": "contains",
      "value": "myIdentifierPart"
    }
  ]
}

Rules

A search rule is a small filtering unit, used to control the search output.

Here is an example search rule:

{
  "property": "$blueprint",
  "operator": "=",
  "value": "microservice"
}

Port has 2 types of search rule operators:

Comparison (= >, etc.);
Relation (relatedTo).

Comparison operators

Structure

Field	Description
`operator`	Search operator to use when evaluating this rule, see a list of available operators below
`property`	Property to filter by according to its value. It can be a meta-property such as `$identifier`, or one of the standard properties
`value`	The value to filter by

Operators

A wide variety of operators are available, see them here.

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

Operators

Related To

The relatedTo operator will return all entities that have a relationship with the specified entity:

{
  "operator": "relatedTo",
  "blueprint": "myBlueprint",
  "value": "myEntity"
}

The operator also supports multiple related entities as the searched value:

{
  "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:

{
  "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):

"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:

Deployment Configs:
- Order-Service-Production
- Cart-Service-Production

Microservices:
- Order Service
- Cart Service

Environments:
- Production

And the following relations:

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:

{
  "operator": "relatedTo",
  "blueprint": "deploymentConfig",
  "value": "Order-Service-Production",
  "direction": "upstream"
}

And the result shall be:

Order-Service-Production upstream related entities

{
  "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:

{
  "operator": "relatedTo",
  "blueprint": "environment",
  "value": "Production",
  "direction": "downstream"
}

And the result shall be:

Production downstream related entities

{
  "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"
    }
  ]
}

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.

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 and catalog pages.

Usage examples

[
  {
    "property": "$team",
    "operator": "containsAny",
    "value": ["{{getUserTeams()}}"]
  }
]

[
  {
    "property": "emails",
    "operator": "contains",
    "value": "{{getUserEmail()}}"
  }
]

[
  {
    "property": "name",
    "operator": "=",
    "value": "{{getUserFullName()}}"
  }
]

[
  {
    "property": "$blueprint",
    "operator": "=",
    "value": "{{blueprint}}"
  }
]

Examples

Refer to the examples page for practical code snippets for search.

Advanced

Refer to the advanced page for advanced search use cases and outputs.

Common queries usage​

Search request​

Search request elements​

Combinator​

Rules​

Comparison operators​

Structure​

Operators​

Relation operators​

Structure​

Operators​

Required

Direction

Dynamic properties​

Usage examples​

Examples​

Advanced​

Common queries usage

Search request

Search request elements

Combinator

Rules

Comparison operators

Structure

Operators

Relation operators

Structure

Operators

Dynamic properties

Usage examples

Examples

Advanced