Skip to main content

Search & query

Port's API provides tools to easily query, search and filter software catalog data.

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.
  • Get all services running in a specific cluster.

Search request​

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

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​

FieldDescription
combinatorDefines the logical operation to apply to the query rules
rulesAn 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"
    }
  ]
}

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:

  1. Comparison operators (= >, etc.);
  2. Relation operators (relatedTo, etc.).

Comparison and operators​

Structure​

FieldDescription
operatorSearch operator to use when evaluating this rule, see a list of available operators below
propertyProperty to filter by according to its value. It can be a meta-property such as $identifier, or one of the standard properties
valueThe value to filter by

Operators​

The = operator checks exact matches of the specified value:

{
  "operator": "=",
  "property": "myProperty",
  "value": "myExactValue"
}

Relation structure and operators​

Structure​

FieldDescription
operatorSearch operator to use when evaluating this rule, see a list of available operators below
blueprintBlueprint of the entity identifier specified in the value field
valueValue to filter by

Operators​

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

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

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.