Skip to main content

Check out Port for yourself ➜ 

Examples

This page provides practical examples of using Port's search and query syntax across different features.

Catalog pages​

Initial filters for catalog pages are configured when creating or editing a catalog page in your software catalog. These filters pre-filter which entities appear when the page loads, improving performance and showing only relevant data.

Filters are particularly useful for blueprints with large entity counts (such as Snyk vulnerabilities), where requests may take a long time to ld or even time out without filtering.

This example demonstrates how to filter a Snyk vulnerability catalog page, showing only high and critical severity vulnerabilities:

{
  "combinator": "and",
  "rules": [
    {
      "value": [
        "high",
        "critical"
      ],
      "property": "severity",
      "operator": "in"
    }
  ]
}

Entity pages​

Filters for related entity tabs are configured when creating custom tabs on any entity page.

To add filters, navigate to the Related Entities tab, click the + button to create a new tab or edit an existing one. Then under Additional filters, click the filters button to add your query.

These filters are particularly useful when a tab displays a large number of related entities. Filters improve performance and make the data more manageable.

This example demonstrates how to filter related pull requests for a repository entity, showing only PRs with an open status:

{
  "combinator": "and",
  "rules": [
    {
      "value": "open",
      "property": "status",
      "operator": "="
    }
  ]
}

Dashboard widgets​

Widget-specific filters are configured in the widget creatio or edit form for dashboard widgets. These filters determine which entities are included in calculations and visualizations.

This example demonstrates how to filter overdue pull requests, showing only PRs with an open status that were created in the past 90 days:

{
  "combinator": "and",
  "rules": [
    {
      "value": "open",
      "property": "status",
      "operator": "="
    },
    {
      "property": "createdAt",
      "operator": "between",
      "value": {
        "preset": "last3Months"
      }
    }
  ]
}

Blueprint read permissions​

Blueprint read permissions can be configured with dynamic policy rules using search and query syntax. Configure these in the data model page by clicking on a blueprint and going to the Permissions tab.

The policy key allows you to create dynamic read access rules that grant users access to entities based on their properties, team membership, and contextual user data. This determines which entities users can see in catalog pages.

For detailed examples and information, see the read permissions policy section in the catalog RBAC documentation.

Aggregation properties​

Configure filters when creating or editing an aggregation property in the data model page. The search and query filter is defined under the query section of the aggregation property.

This example demonstrates how to add an aggregation property to a service blueprint that calculates the number of open high-severity vulnerabilities for each service, filtering only vulnerabilities with severity set to high and status set to open:

{
  "aggregationProperties": {
    "numberOfOpenHighVulnerabilities": {
      "title": "Number of open high severity vulnerabilities",
      "target": "vulnerability",
      "calculationSpec": {
        "calculationBy": "entities",
        "func": "count"
      },
      "query": {
        "combinator": "and",
        "rules": [
          {
            "property": "severity",
            "operator": "=",
            "value": "high"
          },
          {
            "property": "status",
            "operator": "=",
            "value": "open"
          }
        ]
      }
    }
  }
}

Scorecards​

Configure filters when creating or editing a scorecard. Filters determine which entities the rule evaluates, filtering out irrelevant entities and performing checks only on entities that pass the filtering.

Scorecards use conditions

Scorecard filters use conditions instead of rules, but follow the same structure with combinator, property, operator, and value.

This example demonstrates how to filter a scorecard to apply only to production services owned by specific teams. This ensures the quality check only runs on critical services:

"filter": {
  "combinator": "and",
  "conditions": [
    {
      "value": [
        "builder_team",
        "developers_team"
      ],
      "operator": "containsAny",
      "property": "$team"
    },
    {
      "value": "production",
      "operator": "=",
      "property": "environment"
    }
  ]
}
Supported operators

For a complete list of the available operators in scorecard filters, see the available operators section under the rule elements documentation.

Self-service actions​

Configure these options when creating or editing an action in the self-service actions page.

Action conditions determine which entities an action appears on, ensuring actions are only available for relevant entities. Configure this in the Basic Details tab of the action form.

DAY-2 and DELETE only

Action conditions are only available for DAY-2 and DELETE operations.

This example demonstrates how to conditionally display an action based on entity properties. It shows the action only on entities where the environment property equals production:

{
  "type": "SEARCH",
  "rules": [
    {
      "operator": "=",
      "property": "environment",
      "value": "production"
    }
  ],
  "combinator": "and"
}

API​

You can use search and query syntax with the following API routes: search entities and search a blueprint's entities.

United States region

The examples below use the EU region API.
If you wish to use the US region API, replace https://api.getport.io with https://api.us.getport.io.

The following examples provide a foundation for using the search route. You can modify the rules array to match your specific search requirements.

# Dependencies to install:
# $ python -m pip install requests

import json
import requests

CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"

API_URL = "https://api.getport.io/v1"

credentials = {"clientId": CLIENT_ID, "clientSecret": CLIENT_SECRET}

token_response = requests.post(f"{API_URL}/auth/access_token", json=credentials)

access_token = f"Bearer {token_response.json()['accessToken']}"

# You can now use the value in access_token when making further requests

headers = {
    'Authorization': access_token
}

query = {
    "combinator": "or",
    "rules": [
        {
            "property": "$title",
            "operator": "=",
            "value": "admin-prod"
        },
        {
            "property": "$title",
            "operator": "=",
            "value": "admin-test"
        }
    ]
}

search_req = requests.post(f"{API_URL}/entities/search", headers=headers, json=query)

search_entities = search_req.json()['entities']

for entity in search_entities:
    print(json.dumps(entity))