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;
  • etc.

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 suitable 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 from the myBlueprint blueprint that their 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.