Improved usability, telemetry, 9 new plugins →

input

Allow user input in a dashboard using common form components such as text, select and multiselect. Data can either be static or derived from a SQL query.

Dashboard components can depend on the value of an input within the dashboard by referring to self e.g. self.input.<input_name>.value. This allows you to pass the value of an input as an argument to a query (or any other dashboard element) to create dynamic dashboards!

Input blocks can be declared as named resources at the top level of a mod, or be declared as named blocks inside a dashboard or container, or be re-used inside a dashboard or container by using an input with base = <mod>.input.<input_resource_name>.

Example Usage


input "vpc_id" {
title = "VPC"
type = "select"
width = 2
sql = <<-EOQ
select
title as label,
vpc_id as value
from
aws_vpc;
EOQ
}

Argument Reference

ArgumentTypeOptional?Description
argsMapOptionalA map of arguments to pass to the query.
baseStringOptionalA reference to a named input resource that this input should source its definition from. title, sql, type, options and width can be overridden after sourcing via base.
optionBlockOptionaloption block to add static values to the input
placeholderStringOptionalPlaceholder text to display. If a placeholder is set for a select or multiselect, then dependent resources will not run until a selection is made. If no placeholder is set, the first item in the list will be selected by default.
paramBlockOptionalA param block that defines the parameters that can be passed in to the query. param blocks may only be specified for inputs that specify the sql argument.
queryQuery ReferenceOptionalA reference to a query resource that defines the query to run. An input may either specify the query argument or the sql argument, but not both.
sqlStringOptionalAn SQL string to provide data for the input. An input may either specify the query argument or the sql argument, but not both.
titleStringOptionalA plain text title to display for this input.
typeStringOptionalThe type of the input. Can be text, select or multiselect.
widthNumberOptionalThe width as a number of grid units that this item should consume from its parent.

Common Input Properties

option

Add static options to an input. Applies to select and multiselect. The block name is the value. If a label is not specified, the value will be used as the label.

PropertyTypeDefaultDescription
labelStringIf not specified, the value will be used as the labelthe display label for this option

Data Structure

The data structure for an input will depend on the type.

select / multiselect

labelvaluetags
defaultvpc-05657e5bef9676266null
acme @ 10.84.0.0/16vpc-03656e5eef967f366{ "account_id": "123456789012" }

tags is an optional JSONB object of key/value pairs. Any tag values will be displayed in the list of available options, along with the selected option(s). This will allow you to identify resources across multi-account queries for example. When a user types to search in the input, the labels and tags will be searched.

More Examples

Single-select with tags


input "instance_arn" {
title = "Select an instance:"
width = 4
sql = <<-EOQ
select
title as label,
arn as value,
json_build_object(
'region', region,
'instance_id', instance_id
) as tags
from
aws_ec2_instance
order by
title;
EOQ
}

Single-select with fixed options

input "regions" {
title = "Select regions:"
width = 2
option "us-east-1" {}
option "us-east-2" {}
}

Single-select with fixed options, using labels

input "vpc_id" {
title = "Select VPC:"
width = 2
option "vpc-05657e5bef9676266" {
label = "default"
}
option "vpc-03656e5eef967f366" {
label = "acme @ 10.84.0.0/16"
}
}

Multi-select with dynamic options


input "policy_arns" {
title = "Select policies:"
type = "multiselect"
width = 2
sql = <<-EOQ
select
name as label,
arn as value
from
aws_iam_policy;
EOQ
}

Select with dynamic options


input "vpc_id" {
title = "VPC"
type = "select"
width = 2
sql = <<-EOQ
select
title as label,
vpc_id as value
from
aws_vpc;
EOQ
}

Text input


input "search_string" {
title = "Search String:"
width = 2
type = "text"
placeholder = "enter a search string"
}

Example dashboard using an input


query "aws_region_input" {
sql = <<-EOQ
select
distinct region as label,
region as value
from
aws_region
order by
region;
EOQ
}
query "aws_s3_buckets_by_versioning_enabled" {
sql = <<-EOQ
with versioning as (
select
case when versioning_enabled then 'Enabled' else 'Disabled' end as versioning_status,
region
from
aws_s3_bucket
)
select
versioning_status,
count(versioning_status) as "Total"
from
versioning
where
region = $1
group by
versioning_status
EOQ
param "region" {}
}
query "aws_s3_buckets_in_region" {
sql = <<-EOQ
select
name,
versioning_enabled
from
aws_s3_bucket
where
region = $1
EOQ
param "region" {}
}
dashboard "inputs_example_dashboard" {
title = "Inputs Example Dashboard"
input "region" {
sql = query.aws_region_input.sql
width = 3
}
container {
chart {
title = "AWS Bucket Versioning Status"
type = "pie"
width = 2
query = query.aws_s3_buckets_by_versioning_enabled
args = {
"region" = self.input.region.value
}
}
table {
width = 4
query = query.aws_s3_buckets_in_region
args = {
"region" = self.input.region.value
}
}
}
}