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
Section titled “Element predicates”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}Combining
Section titled “Combining”Predicates can be combined. The following is the same as example above:
view { include backend, frontend, authService, messageBroker.**
exclude messageBroker.emailsQueue}Wildcard
Section titled “Wildcard”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 }}With overrides
Section titled “With overrides”You can modify element properties specifically for the view:
// Include the element and override its propertiesinclude 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 textSizeinclude cloud.* with { color amber textSize small}with may be used only within include.
With custom navigation
Section titled “With custom navigation”You can define custom navigation and links between views:
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 }}Element selectors
Section titled “Element selectors”Children .*
Section titled “Children .*”The children selector includes element’s children and their relationships with visible elements.
include cloud.*
// Same asinclude cloud.backendinclude cloud.uiDescendants .**
Section titled “Descendants .**”The descendants selector includes element’s descendants IF they have a relationship with visible elements.
include cloud.**
// Same asinclude cloud.backendinclude cloud.uiinclude cloud.ui.webAppExpand ._
Section titled “Expand ._”The expand selector includes element’s children IF they have a relationship with visible elements. All other children are omitted.
include cloud._
// Same asinclude cloudinclude -> cloud.* ->Relationship predicates
Section titled “Relationship predicates”Relationship predicates include elements only if they have relationships that meet the specified predicate conditions.
Directed relationships
Section titled “Directed relationships”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.*Any relationship
Section titled “Any relationship”Include elements if they have any relationships:
include customer <-> cloudIncoming
Section titled “Incoming”Include elements if they have incoming relationships from already visible elements.
Here’s an example based on the model from the wildcard example:
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 uiview { include customer, -> cloud.*}Outgoing
Section titled “Outgoing”Include elements only if they have outgoing relationships to already visible elements:
include customer ->include cloud.* ->In/Out
Section titled “In/Out”Include nested elements of cloud, that have any relationships with visible elements:
include -> cloud.* ->Relationship customization
Section titled “Relationship customization”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 },Relationship navigation
Section titled “Relationship navigation”To customize navigation from relationship:
include webApp -> backend.api with { navigateTo dashboardRequestFlow }Filter
Section titled “Filter”where operator narrows down results by applying additional conditions:
// include only microservices from nestedinclude cloud.* where kind is microservice
// only microservices and not deprecatedinclude cloud.* where kind == microservice and // possible to use 'is' or '==' tag != #deprecated // possible to use 'is not' or '!='
// Use logical operatorsinclude cloud.* where not (kind is microservice or kind is webapp) and tag is not #legacy and (tag is #v1 or tag is #v2)With relationship predicates
Section titled “With relationship predicates”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 backendIt 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 microserviceTogether with with
Section titled “Together with with”It is possible to use where together with with, but where should be defined first:
include * where kind is microservice with { color amber }Metadata filter
Section titled “Metadata filter”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 keyexclude * where not metadata.version
// combine with other filtersinclude cloud.* where metadata.environment is "production" and kind is not databaseBoolean metadata values can be matched with true or false directly (no quotes needed):
// matches elements where critical is trueinclude * where metadata.critical is trueWhen 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 regionsinclude * 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 elementsexclude * -> * 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.
By element kind or tag (legacy)
Section titled “By element kind or tag (legacy)”Before where, elements were filtered by kind or tag with this syntax:
// elements by kindinclude element.kind != systemexclude element.kind = container
// elements by taginclude element.tag != #V2exclude element.tag = #nextGlobal predicate groups
Section titled “Global predicate groups”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.* }}Groups
Section titled “Groups”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 } }}