# Card


# 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

<img src="/reference_examples/card_ex_1.png" width="200pt" />

<br />

```hcl
card {
  sql = <<-EOQ
    select 
      count(*) as "Buckets" 
    from 
  aws_s3_bucket
  EOQ
  
  icon  = "hashtag"
  width = 2
} 

```


## 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](/docs/reference/config-files/connection), [connection string](/docs/powerpipe-hcl/query#connection-strings), or [Pipes workspace](/docs/run/workspaces#implicit-workspaces) to query.  If not specified, the [default database](/docs/run#selecting-a-database ) will be used.
| `icon` |  String	| Optional | An [icon](/docs/powerpipe-hcl/dashboard#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](#jq-templates) 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](/docs/powerpipe-hcl/query#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](/docs/powerpipe-hcl/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](/docs/powerpipe-hcl/dashboard#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](/docs/powerpipe-hcl/dashboard#width) as a number of grid units that this item should consume from its parent.

## Data Structure

A card supports 2 data structures.

1. A simple structure where column 1's name is the card `label` and column 1's value is the card `value`.
2. 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](https://stedolan.github.io/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](/docs/reference/cli/query#powerpipe-query-run), where the keys are the column names and the values are the data for that row. 

For example, this query:
```sql
select
  s.volume_id as value,
  'Source Volume' as label,
  'info' as type,
  v.arn
from
  aws_ebs_snapshot as s,
  aws_ebs_volume as v
where
  s.volume_id = v.volume_id
  and s.snapshot_id = 'snap-0cc613495a9fe5c1c';

```

will present rows to the jq template in this format:
```json
{
  "arn": "arn:aws:ec2:us-east-2:123456789012:volume/vol-0566e02dcc2c08e77",
  "label": "Source Volume",
  "type": "info",
  "value": "vol-0566e02dcc2c08e77"
 }
```

which you can then use in a jq template in the `href` argument:
```hcl
card {
  sql = <<-EOQ
    select
      s.volume_id as value,
      'Source Volume' as label,
      'info' as type,
      v.arn
    from
      aws_ebs_snapshot as s,
      aws_ebs_volume as v
    where
      s.volume_id = v.volume_id
      and s.snapshot_id = 'snap-0cc613495a9fe5c1c';
  EOQ
  
  width = 3
  href  = "/aws_insights.dashboard.aws_ebs_volume_detail?input.volume_arn={{.arn | @uri}}"
}
```

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](/docs/powerpipe-hcl/dashboard#jq-escaping--interpolation) for more advanced examples.


## More Examples


### Alert Card

<img src="/reference_examples/card_ex_alert.png" width="200pt" />

<br />

```hcl
card {
  sql = "select 0 as alert"
  type  = "alert"
  width = 2
} 
```

### OK Card

<img src="/reference_examples/card_ex_ok.png" width="200pt" />

<br />

```hcl
card {
  sql = "select 0 as ok"
  type  = "ok"
  width = 2
} 
```


### Info Card

<img src="/reference_examples/card_ex_info.png" width="200pt" />

<br />

```hcl
card {
  sql = "select 0 as info"
  type  = "info"
  width = 2
} 
```



### Dynamic Styling via formal query data structure

<img src="/reference_examples/card_ex_dynamic.png" width="200pt" />

<br />

```hcl
card {
  sql = <<-EOQ
    select
      'Unencrypted Buckets' as label,
      count(*) as value,
      case
        when count(*) > 0 then 'alert'
        else 'ok'
      end as type
    from
      aws_s3_bucket
    where
      server_side_encryption_configuration is null;
  EOQ
  width = 2
}
```



### Static data and static (external) link

<img src="/reference_examples/card_ex_static_link.png" width="200pt" />

<br />

```hcl
card {
  value = "github"
  label = "site"
  width = 2
  href  = "https://github.com"
}
```


### Dynamic data and static (internal) link
<img src="/reference_examples/card_ex_internal_link.png" width="200pt" />

<br />

```hcl
card {
  sql = <<-EOQ
    select
      count(*) as value,
      'Has Public Bucket Policy' as label,
      case
        count(*)
        when 0 then 'ok'
        else 'alert'
      end as "type"
    from
      aws_s3_bucket
    where
      bucket_policy_is_public;
  EOQ
  
  icon  = "hashtag"
  width = 2
  href  = "${dashboard.aws_s3_bucket_public_access_report.url_path}"
}
```


### Dynamic link with JQ template
<img src="/reference_examples/card_ex_dynamic_link.png" width="300pt" />

<br />

```hcl
card {
  sql = <<-EOQ
    select
      s.volume_id as value,
      'Source Volume' as label,
      'info' as type,
      v.arn
    from
      aws_ebs_snapshot as s,
      aws_ebs_volume as v
    where
      s.volume_id = v.volume_id
      and s.snapshot_id = 'snap-0cc613495a9fe5c1c';
  EOQ
  
  width = 3
  href  = "/aws_insights.dashboard.aws_ebs_volume_detail?input.volume_arn={{.arn | @uri}}"
}
```