card
A card is used to show a value to the user, or some change in value. A card can also present itself in different types. You can even dynamically style the card. For example, you may show the count of public S3 buckets and if the value is greater than 0, display an alert type card, otherwise show an ok type card.
Cards can be declared as named resources at the top level of a mod, or they can be declared as anonymous blocks inside a dashboard or container, or be re-used inside a dashboard or container by using a card with base = <mod>.card.<card_resource_name>.
Example Usage
Argument Reference
| Argument | Type | Optional? | Description |
|---|---|---|---|
| args | Map | Optional | A map of arguments to pass to the query. |
| base | Card Reference | Optional | A reference to a named card resource that this card should source its definition from. label, title, value, type and width can be overridden after sourcing via base. |
| database | String | Optional | A database connection reference, connection string, or Pipes workspace to query. If not specified, the default database will be used. |
| icon | String | Optional | An icon to use for the elements with this category. |
| href | String | Optional | A url that the card should link to. The href may use a jq template to dynamically generate the link the card. |
| label | String | Optional | Inferred from the first column name in simple data format. Else can be set explicitly in HCL, or returned by the query in the label column in the formal data format. |
| param | Block | Optional | A param block that defines the parameters that can be passed in to the query. param blocks may only be specified for cards that specify the sql argument. |
| query | Query Reference | Optional | A reference to a query resource that defines the query to run. A card may either specify the query argument or the sql argument, but not both. |
| --search-path | String | Optional | Set a comma-separated list of connections to use as a custom search path for the query |
| --search-path-prefix | String | Optional | Set a comma-separated list of connections to use as a prefix to the current search path for the query. |
| sql | String | Optional | An SQL string to provide data for the card. A card may either specify the query argument or the sql argument, but not both. |
| title | String | Optional | A plain text title to display for this card. |
| type | String | Optional | plain (default), alert, info or ok. You can also use table to review the raw data. |
| value | String | Optional | Inferred from the first column's value in simple data format. |
| width | Number | Optional | The width as a number of grid units that this item should consume from its parent. |
Data Structure
A card supports 2 data structures.
- A simple structure where column 1's name is the card label and column 1's value is the card value.
- A formal data structure where the column names map to the properties of the card.
Simple data structure:
| label |
|---|
| value |
For example:
| Unencrypted Buckets |
|---|
| 25 |
Formal data structure:
| label | value | type |
|---|---|---|
| Unencrypted Buckets | 10 | alert |
JQ Templates
The href argument allows you to specify a jq template to dynamically generate a hyperlink from the data in the row. To use a jq template, enclose the jq in double curly braces ({{ }}).
Powerpipe will pass the first row of data to jq in the same format that is returned by powerpipe query JSON mode output, where the keys are the column names and the values are the data for that row.
For example, this query:
will present rows to the jq template in this format:
which you can then use in a jq template in the href argument:
Note that for a card, we pass label, value, type or icon HCL attributes in the JQ context, but the columns from the SQL query will overwrite any of the statically-defined HCL attributes.
Refer to JQ Escaping & Interpolation for more advanced examples.