๐ 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โ
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.
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
- Or
{
"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 operators (
=
>
, etc.); - Relation operators (
relatedTo
, etc.).
Comparison and 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โ
- =
- !=
- >
- >=
- <
- <=
- isEmpty
- isNotEmpty
- Property schema
- Between
- Contains
- ContainsAny
- In
The =
operator checks exact matches of the specified value:
{
"operator": "=",
"property": "myProperty",
"value": "myExactValue"
}
The !=
operator checks exact matches of the specified value and returns all results that fail to satisfy the check:
{
"operator": "!=",
"property": "myProperty",
"value": "myExactValue"
}
The >
operator checks values larger than the specified value:
{
"operator": ">",
"property": "myNumericProperty",
"value": 7
}
The >=
operator checks values larger than or equal to the specified value:
{
"operator": ">=",
"property": "myNumericProperty",
"value": 7
}
The <
operator checks values less than the specified value:
{
"operator": "<",
"property": "myNumericProperty",
"value": 7
}
The <=
operator checks values less than or equal to the specified value:
{
"operator": "<=",
"property": "myNumericProperty",
"value": 7
}
The isEmpty
operator checks if the value of the specified property is null
:
{
"operator": "isEmpty",
"property": "myProperty"
}
The isNotEmpty
operator checks if the value of the specified property is not null
:
{
"operator": "isNotEmpty",
"property": "myProperty"
}
The propertySchema
filter can be used with any standard operator. It allows you to filter entities based on a properties matching a specific type (for example, find all string properties with a given value):
- String
- URL
{
"propertySchema": {
"type": "string"
},
"operator": "=",
"value": "My value"
}
{
"propertySchema": {
"type": "string",
"format": "url"
},
"operator": "=",
"value": "https://example.com"
}
- The
propertySchema
can be used with any Port property; - The
propertySchema
replaces theproperty
filter when performing property schema search.
The between
operator checks datetime values and returns entities whose relevant datetime property matches the given range:
{
"operator": "between",
"property": "$createdAt",
"value": {
"preset": "lastWeek"
}
}
Available Presets:
- tomorrow
- today
- yesterday
- lastWeek
- lastMonth
The between
operator also supports standard date ranges:
{
"combinator": "and",
"rules": [
{
"operator": "between",
"property": "$createdAt",
"value": {
"from": "2022-07-26T16:38:06.839Z",
"to": "2022-07-29T17:00:28.006Z"
}
}
]
}
The contains
operator checks if the specified substring exists in the specified property:
{
"operator": "contains",
"property": "myStringProperty",
"value": "mySubString"
}
The containsAny
operator checks if any of the specified strings exist in the target array:
{
"operator": "containsAny",
"property": "myArrayProperty",
"value": ["Value1", "Value2", ...]
}
The in
operator checks if a sub group of values exist in a specified property of type array:
- Standard
- Dynamic Filter
{
"property": "myArrayProperty",
"operator": "in",
"value": ["Value1", "Value2"]
}
{
"property": "$team",
"operator": "in",
"value": ["myTeamsDynamicFilter"]
}
- In order to filter entities that belong to your teams you can use the special
myTeamsDynamicFilter
filter.
UI:
- Choose field of type
string
formatteam
or the metadataTeam
field; - Choose
has any of
operator:
Relation structure and 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
- Required
- Direction
The relatedTo
operator will return all entities that have a relationship with the specified entity:
{
"operator": "relatedTo",
"blueprint": "myBlueprint",
"value": "myEntity"
}
The relatedTo
operator also supports the required
property - which allows you to search for:
- Related entities from all relations (relations with either required
true
orfalse
); - 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"
}
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"
}
]
}
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.