Skip to content

View predicates

Predicates define what an element view shows. Two types of predicates pick what is visible: element and relationship predicates. where narrows their results, and groups draw boundaries around them.

For how elements look in a view, see Styles. For the layout, see Layout.

Element predicates explicitly define which elements are visible. Each included element brings in its relationships with already visible elements.

view {
// Only backend is visible
include backend
// Add frontend to the view
// and its relationships with backend
include frontend
// Add authService to the view
// and its relationships with visible (backend and frontend)
include authService
// Add children of messageBroker,
// and their relationships among themselves and visible (backend, frontend and authService)
include messageBroker.*
// Add all descendants of messageBroker,
// and their relationships among themselves and visible (backend, frontend and authService)
include messageBroker.**
// Exclude emailsQueue and its relationships
exclude messageBroker.emailsQueue
}

Predicates can be combined. The following is the same as example above:

view {
include
backend,
frontend,
authService,
messageBroker.**
exclude messageBroker.emailsQueue
}

Wildcard predicates can be used to reference “everything” (but it differs for scoped/unscoped views).
Consider the following model:

model {
actor customer {
-> webApp 'uses in browser via HTTPS'
}
system cloud {
container backend {
component api
}
container ui {
component webApp {
-> api 'requests data'
}
}
}
}
views {
// Unscoped view - wildcard refers to top-level elements
view {
include *
// Visible top-level elements: customer, cloud
// and derived relationship customer -> cloud
}
// Scoped view - wildcard refers to element and its children
view of cloud.ui {
include *
// Visible:
// - cloud.ui
// - cloud.ui.webApp
// - customer
// - relationship customer -> cloud.ui.webApp
// - cloud.backend
// - cloud.ui.webApp -> cloud.backend, derived from cloud.ui.webApp -> cloud.backend.api
}
}

You can modify element properties specifically for the view:

// Include the element and override its properties
include cloud.backend with {
title 'Backend components'
description '...'
technology 'Java, Spring'
icon tech:java
color amber
shape browser
multiple true
}
// Include all nested elements, change color and textSize
include cloud.* with {
color amber
textSize small
}

with may be used only within include.

You can define custom navigation and links between views:

example.c4
view view2 {
include *
include cloud.backend with {
// navigate to 'view3' on click
navigateTo view3
}
}
view view3 {
include *
include cloud.backend with {
// navigate back to 'view2'
navigateTo view2
}
}

The children selector includes element’s children and their relationships with visible elements.

include cloud.*
// Same as
include cloud.backend
include cloud.ui

The descendants selector includes element’s descendants IF they have a relationship with visible elements.

include cloud.**
// Same as
include cloud.backend
include cloud.ui
include cloud.ui.webApp

The expand selector includes element’s children IF they have a relationship with visible elements. All other children are omitted.

include cloud._
// Same as
include cloud
include -> cloud.* ->

Relationship predicates include elements only if they have relationships that meet the specified predicate conditions.

Include elements if they have directed relationships (or their nested elements):

// Include customer and cloud:
include customer -> cloud
// Include customer and nested elements of cloud (that have relationships):
include customer -> cloud.*

Include elements if they have any relationships:

include customer <-> cloud

Include elements if they have incoming relationships from already visible elements.
Here’s an example based on the model from the wildcard example:

incoming predicate.c4
view {
// visible element
include customer
// include nothing, customer has no relation to backend
include -> cloud.backend
// add ui,
// because customer has a relationship with nested ui.webApp
include -> cloud.ui
// add backend, because visible ui has a relationship to backend
// derived from ui.webApp -> backend.api
include -> cloud.backend
}
// This view includes customer and ui
view {
include
customer,
-> cloud.*
}

Include elements only if they have outgoing relationships to already visible elements:

include customer ->
include cloud.* ->

Include nested elements of cloud, that have any relationships with visible elements:

include -> cloud.* ->

Relationships can be customized inside view:

include
// Make lines red and solid
cloud.* <-> amazon.* with {
color red
line solid
},
// or only directed
customer -> cloud.* with {
// Override label
title 'Customer uses cloud'
navigateTo dynamicview1
},

To customize navigation from relationship:

include
webApp -> backend.api with {
navigateTo dashboardRequestFlow
}

where operator narrows down results by applying additional conditions:

// include only microservices from nested
include cloud.*
where kind is microservice
// only microservices and not deprecated
include cloud.*
where
kind == microservice and // possible to use 'is' or '=='
tag != #deprecated // possible to use 'is not' or '!='
// Use logical operators
include cloud.*
where
not (kind is microservice or kind is webapp)
and tag is not #legacy
and (tag is #v1 or tag is #v2)

When where is used with element predicates, it is applied to the elements.
When used with relationship predicates - to the relationships.

include
// only relationships with tag #messaging
cloud.* <-> amazon.*
where tag is #messaging,
// only incoming http-requests
-> backend
where kind is http-request,
// relationships of kind http-request from any element to backend
* -[http-request]-> backend,
// the same, shorter
* .http-request backend

It is also possible to filter relations by tag or kind of its endpoints.

include
// only relationships outgoing from elements with tag #next
cloud.* -> amazon.*
where source.tag is #next,
// only incoming relations of elements with kind microservice
-> *
where target.kind is microservice

It is possible to use where together with with, but where should be defined first:

include *
where kind is microservice
with {
color amber
}

where can also filter by element or relationship metadata values:

// include only elements with environment="production"
include cloud.*
where metadata.environment is "production"
// exclude elements without a version metadata key
exclude *
where not metadata.version
// combine with other filters
include cloud.*
where
metadata.environment is "production"
and kind is not database

Boolean metadata values can be matched with true or false directly (no quotes needed):

// matches elements where critical is true
include *
where metadata.critical is true

When a metadata value is an array (e.g. regions ['us-east-1', 'eu-west-1']), is checks if the array contains the value:

// matches if "us-east-1" is one of the regions
include *
where metadata.regions is "us-east-1"

For relationship predicates, filter by the relationship’s own metadata or by its endpoints:

include
// only relationships with protocol="grpc"
cloud.* -> amazon.*
where metadata.protocol is "grpc",
// only relations from elements with env="production"
cloud.* -> *
where source.metadata.environment is "production",
// only relations to staging targets
* -> *
where target.metadata.environment is "staging"

The same metadata filters work with exclude predicates:

// remove relationships with protocol="http"
exclude * -> *
where metadata.protocol is "http"
// remove relationships targeting staging elements
exclude * -> *
where target.metadata.environment is "staging"

In deployment views, source.metadata.* and target.metadata.* follow the deployment metadata rules. Metadata defined on a deployed instance replaces the metadata from its model element.

Before where, elements were filtered by kind or tag with this syntax:

// elements by kind
include element.kind != system
exclude element.kind = container
// elements by tag
include element.tag != #V2
exclude element.tag = #next

If you find yourself repeating the same predicates in multiple views, you can define them as global group:

global {
predicateGroup microservices {
include cloud.*
where kind is microservice
exclude *
where tag is #deprecated
}
}
views {
view of newServices {
include cloud.new.*
global predicate microservices
}
view of newBackendServices {
// Keep in mind that order is significant
global predicate microservices
include cloud.backend.*
}
}

It is possible to group elements in element views and deployment views, and this is rendered as a boundary around them:

view {
group {
include backend
}
// with title
group 'Frontend' {
include frontend.*
}
// with style
group 'Service Bus' {
color amber
opacity 20%
border solid
include messageBroker.*
}
}

Groups can be nested:

view {
group 'Third-parties' {
group 'Integrations' {
group 'Analytics' {}
group 'Marketing' {}
}
group 'Monitoring' {}
}
}

Deployment views have groups too, with their own rules, see deployment groups.

Groups may also reference global predicate groups, to reuse a set of predicates and keep the matched elements inside the group:

global {
predicateGroup microservices {
include cloud.*
where kind is microservice
}
}
views {
view of newServices {
include cloud.new.*
group 'Microservices' {
global predicate microservices
}
}
}