Search & query

Port's API provides tools to easily query, search and filter software catalog data. Port's search and queries can be used across 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

A search request contains filters and rules to find matching entities in your software catalog.
To search for entities using the API, see the search route.

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.

For example:

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

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

Combinator

There are two available combinators:

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

And

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

Or

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

1. Comparison (e.g. =, >).
2. Relation (e.g. 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

Several relation-based operators are available, see them here.

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.

Several relation-based operators are available, see them here.

Usage examples

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

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

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

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

Contextual query rules

To implement specific and/or complex queries, you can add the context of the triggering user to a query rule, allowing you to access that user's properties and/or owning teams.
You can mix contextual query rules freely with other rules as part of your queries. This can be used in either the property or value key in a query rule:

Property

{
   ...other rule keys
   "property": {
      "context": "user" | "userTeams",
      "property": "prop"
  }
}

Value

{
  ...other rule keys
   "value": {
      "context": "user" | "userTeams",
      "property": "prop"
  }
}

Available contexts

Context	Description
user	The entity of the user triggering the query
userTeams	The entities of the owning teams of the user triggering the query

Usage examples

The following rule will result in the entities owned by any one of the user's teams:

[ 
  ...other rules
  { 
    "property": "$team",
    "operator": "containsAny",
    "value": {
      "context": "userTeams",
      "property": "$identifier"
    }
  }
]

The following rule will result in entities with the same department as the user's:

[ 
  ...other rules
  { 
    "property": "department",
    "operator": "=",
    "value": {
      "context": "user",
      "property": "department"
    }
  }
]

The following rule asserts that only users with manager role will get the resulting entities:

[ 
  ...other rules
  { 
    "property": {
      "context": "user",
      "property": "port_role"
    },
    "operator": "=",
    "value": "manager"
  }
]

The following rule asserts that only users in the user's team/s will get the resulting entities:

[
  ...other rules
  { 
    "property": {
      "context": "userTeams",
      "property": "$identifier"
    },
    "operator": "containsAny",
    "value": ["Spider Team", "Builder Team"]
  }
]

Filter by relations/scorecards

When using the search a blueprint's entities API route, you can also filter results by relations or scorecards.

See the following examples for each filter type:

Relation

{
  "relation": "relationId",
  "operator": "=",
  "value": "value"
}

Scorecard

{
  "scorecard": "scorecardId",
  "operator": "=",
  "value": "Bronze"
}

Scorecard rule

{
  "scorecard": "scorecardId",
  "scorecardRule": "scorecardRuleId",
  "operator": "=",
  "value": "Bronze"
}

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.