# Report

<Callout>
  Reports, Charts, Dashboards are intended to be created and modified through the
  user interface. The file representation is for checking errors during
  validation.
</Callout>

Each Report must be stored as **report_name.report** YAML file:

```yaml
report: report_name
title: ''
access_roles:
- role
- role
parameters:
- filter: f1
  label: ''
  description: ''
  result: string
  suggest_model_dimension: model_name.field_path
  conditions:
  - f\`%a\`

- filter: f2
  store_model: ga
  store_result: string
  fractions:
  - logic: OR
    type: contains
    controls:
    - input: value_input
      value: a

- filter: f3
  store_model: ga
  store_filter: top_config
  fractions:
  - controls:
    - selector: ga_property
      value: 123123123
    - date_picker: start_date
      value: $METRICS_DATE_FROM
    - date_picker: end_date
      value: $METRICS_DATE_TO

rows:
- row_id: A
  type: empty

- row_id: B
  type: header
  name: 'name in UI'

- row_id: C
  type: metric
  metric: metric_id
  show_chart: true
  format_number: '$,.0f'
  currency_prefix: $
  currency_suffix: ''
  parameters: 
  - apply_to: field_path
    listen: f1

- row_id: D
  type: metric
  metric: metric_id
  parameters: 
  - apply_to: field_path
    conditions:
    - f\`> 100\`

- row_id: E
  type: metric
  metric: ga.screen_page_views.by.event_created_at
  parameters: 
  - apply_to: city
    listen: f2
  - apply_to: top_config
    listen: f3

- row_id: F
  type: metric
  metric: ga.screen_page_views.by.event_created_at
  parameters: 
  - apply_to: city
    fractions:
    - logic: OR
      type: contains
      controls:
      - input: value_input
        value: a
  - apply_to: top_config
    fractions:
    - controls:
      - selector: ga_property
        value: 123123123
      - date_picker: start_date
        value: $METRICS_DATE_FROM
      - date_picker: end_date
        value: $METRICS_DATE_TO

- row_id: G
  type: formula
  formula: ($C + $E) / 2
  name: 'name in UI'

options:
  series: 
  - data_row_id: C
    y_axis_index: 0
    type: 'line'
```

## Reference

### Report Constants

`$METRICS_DATE_FROM` and `$METRICS_DATE_TO` are intended for use by [Store Models](/content/docs/reference/model-store).
Their values are provided based on the time filter set by the user for a specific query.

### Report

| Name         | Type                                             | Default | Description                                                               |
| ------------ | ------------------------------------------------ | ------- | ------------------------------------------------------------------------- |
| report\*     | string                                           | -       | Report name                                                               |
| title        | string                                           | -       | Dashboard title in UI                                                     |
| access_roles | string []                                        | -       | If specified, only users with the listed roles will have access to Report |
| parameters   | [Top Filter []](/content/docs/reference/parameters#top-filter) | -       | Begin a section of report parameters                                      |
| rows         | [Row []](#row)                                   | -       | Begin a section of rows                                                   |
| options      | [Tile Options](/content/docs/reference/dashboard#tile-options) | -       | Report options schema is the same as dashboard tile options schema        |

### Row

| Name            | Type                               | Default | Description                                                                                                                                            |
| --------------- | ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| row_id\*        | string                             | -       | Row Id                                                                                                                                                 |
| type\*          | enum                               | -       | <span>Row type:</span><ul><li>**metric**</li><li>**formula**</li><li>**header**</li><li>**empty**</li></ul>                                            |
| metric\*\*      | string                             | -       | metric_id. Required for row type **Metric**.                                                                                                           |
| formula\*\*     | string                             | -       | PostgresSQL SQL formula for calculating row data using `$ROW_ID` references to other rows (simple math operations). Required for row type **Formula**. |
| name\*\*        | string                             | -       | Row name. Required for row type **Formula** or **Header**.                                                                                             |
| show_chart      | boolean                            | false   | Show row data on chart                                                                                                                                 |
| format_number   | string                             | -       | [Format Number](/content/docs/reference/format-number)                                                                                                               |
| currency_prefix | string                             | -       | [Format Number - Symbol](/content/docs/reference/format-number#symbol)                                                                                               |
| currency_suffix | string                             | -       | [Format Number - Symbol](/content/docs/reference/format-number#symbol)                                                                                               |
| parameters      | [Row Parameter []](#row-parameter) | -       | Begin a section of row parameters                                                                                                                      |

### Row Parameter

Row parameter must have **conditions**, **listen** or **fractions**.

| Name       | Type                                         | Default | Description                                                 |
| ---------- | -------------------------------------------- | ------- | ----------------------------------------------------------- |
| apply_to\* | string                                       | -       | Field or Filter name                                        |
| listen     | string                                       | -       | Specify report parameter to listen to                       |
| conditions | string []                                    | -       | `for parameters mapped to Model` <br/> List of filter expressions |
| fractions  | [Fraction []](/content/docs/reference/parameters#fraction) | -       | `for parameters mapped to Store` <br/> List of fractions          |