category

Powerpipe is now the recommended way to run dashboards and benchmarks! Mods still work as normal in Steampipe for now, but they are deprecated and will be removed in a future release:

The category block defines a category for a graph node or edge. Categories are used to define display properties for the item, such as the color, icon, and folding options.

Example Usage

category "ec2_instance" {
title = "EC2 Instance"
href = "/aws_insights.dashboard.ec2_instance_detail?input.instance_arn={{.properties.'ARN' | @uri}}"
icon = "memory"
color = "orange"
}

A category may be defined as a top-level, named resource block, or as a block inside a graph, flow, or hierarchy. If defined as a top-level resource, the category will be available to all graph nodes and edges, and you can set it on a node or edge using the category HCL property:

dashboard "categories_ex1" {
graph {
node "iam_policy" {
category = category.iam_policy
sql = <<-EOQ
select
arn as id,
name as title,
jsonb_build_object(
'ARN', arn,
'AWS Managed', is_aws_managed::text,
'Attached', is_attached::text,
'Create Date', create_date,
'Account ID', account_id
) as properties
from
aws_iam_policy
where
arn = 'arn:aws:iam::aws:policy/ReadOnlyAccess';
EOQ
}
}
}
category "iam_policy" {
title = "IAM Policy"
color = "red"
href = "/aws_insights.dashboard.iam_policy_detail?input.policy_arn={{.properties.'ARN' | @uri}}"
icon = "policy"
}

If defined as a block inside a graph, flow, or hierarchy, the category will only be available to that graph, flow, or hierarchy. In this case, you cannot set the category with category HCL property, but can set it dynamically for each row in the SQL result set using the category column:

dashboard "categories_ex2" {
graph {
category "iam_policy" {
title = "IAM Policy"
color = "red"
href = "/aws_insights.dashboard.iam_policy_detail?input.policy_arn={{.properties.'ARN' | @uri}}"
icon = "policy"
}
node "iam_policy" {
sql = <<-EOQ
select
arn as id,
name as title,
'iam_policy' as category,
jsonb_build_object(
'ARN', arn,
'AWS Managed', is_aws_managed::text,
'Attached', is_attached::text,
'Create Date', create_date,
'Account ID', account_id
) as properties
from
aws_iam_policy
where
arn = 'arn:aws:iam::aws:policy/ReadOnlyAccess';
EOQ
}
}
}

The inline category block is useful when you want to define a category dynamically based on the SQL result set. You can even use the base property in the inline category to inherit properties from a named category:

dashboard "categories_ex3" {
graph {
category "iam_policy" {
base = category.iam_policy
}
node "iam_policy" {
sql = <<-EOQ
select
arn as id,
name as title,
'iam_policy' as category,
jsonb_build_object(
'ARN', arn,
'AWS Managed', is_aws_managed::text,
'Attached', is_attached::text,
'Create Date', create_date,
'Account ID', account_id
) as properties
from
aws_iam_policy
where
arn = 'arn:aws:iam::aws:policy/ReadOnlyAccess';
EOQ
}
}
}
category "iam_policy" {
title = "IAM Policy"
color = "red"
href = "/aws_insights.dashboard.iam_policy_detail?input.policy_arn={{.properties.'ARN' | @uri}}"
icon = "policy"
}

Argument Reference

ArgumentTypeOptional?Description
colorStringThe matching color from the default theme for the data series index.A valid color value. This may be a named color, RGB or RGBA string, or a control status color.
hrefStringOptionalA url that the item should link to. The href may use a jq template to dynamically generate the link.
iconStringOptionalAn icon to use for the elements with this category.
titleStringOptionalA plain text title to display for this category.
foldBlockOptionalA fold block for this category.

Folding

The graph resource supports folding, allowing you to collapse multiple nodes that have the same category into a single node. You can click to expand or collapse the folded nodes. To be considered for folding, the nodes must have the same category and the same edges.

By default, folding is enabled with a threshold of 3. This means that if there are 3 or more nodes with the same category and edges, they will be folded into a single node. You can change the fold options in the fold block in the category definition. The fold block has the following properties:

ArgumentTypeOptional?Description
iconStringOptionalAn icon to use when this category is folded. If not specified, the category icon will be used.
titleStringOptionalA plain text title to display for this category. If not specified, the category title will be used.
thresholdNumberOptionalThe number of items that should be displayed before folding. The default is 3.

More Examples

Category with Material Symbol Icon

category "ec2_instance" {
title = "EC2 Instance"
color = "orange"
icon = "memory"
}

Category with Heroicons Icon

category "ec2_instance" {
title = "EC2 Instance"
color = "orange"
icon = "heroicons-outline:cpu-chip"
}

Category with Text Icon

category "ec2_instance" {
title = "EC2 Instance"
color = "orange"
icon = "text:Instance"
}

Category with fold properties

category "aws_vpc_subnet" {
title = "Subnet"
icon = "lan"
color = "#FF9900"
fold {
title = "Subnets..."
icon = "more-horiz"
threshold = 2
}