> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tarvah.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Time Series & Date Ranges

> Configure time-based analysis with granularity control, TradingView-style range selection, and date filtering

Time series data — positions over months, daily valuations, quarterly performance — is at the heart of financial analytics. Tarvah lets you configure time series behavior at the VDM level and gives experiment users a TradingView-style dropdown to switch granularity and date ranges on the fly.

## How it works

<Steps>
  <Step title="Configure on the VDM">
    Define which date columns support time series, what granularities are allowed, and the default time window.
  </Step>

  <Step title="Build an experiment">
    Drag a date field onto the X axis of any chart. The time range dropdown appears automatically in the chart header.
  </Step>

  <Step title="Explore interactively">
    Use the dropdown to switch between Day / Month / Quarter / Year granularity and select date ranges like 3M, 6M, YTD, or Since Inception.
  </Step>
</Steps>

***

## VDM Configuration

Time series is configured via the `timeSeriesConfiguration` array on a Virtual Data Mart. Each entry represents one date column with its allowed granularities.

### Configuration fields

| Field                      | Type      | Description                                                      |
| -------------------------- | --------- | ---------------------------------------------------------------- |
| `fieldName`                | string    | Display name (e.g. "Position Date")                              |
| `sourceColumn`             | string    | Database column reference (e.g. `FCT_POSITION.POSITION_DT`)      |
| `availableGranularities`   | string\[] | Which time buckets to allow                                      |
| `defaultGranularity`       | string    | Initial granularity when chart first loads                       |
| `defaultTimeframeCategory` | string    | Maps to query grouping: `DAY`, `WEEK`, `MONTH`, `QUATER`, `YEAR` |
| `defaultDateRange`         | object    | Initial date filter applied to new charts                        |

### Available granularities

<CardGroup cols={5}>
  <Card title="date" icon="calendar-day">Day-level</Card>
  <Card title="week" icon="calendar-week">Week-level</Card>
  <Card title="month" icon="calendar">Month-level</Card>
  <Card title="quarter" icon="chart-bar">Quarter-level</Card>
  <Card title="year" icon="chart-line">Year-level</Card>
</CardGroup>

<Info>
  Only the granularities you list in `availableGranularities` will appear in the experiment's time range dropdown. If you only want users to see Day and Month, set `["date", "month"]`.
</Info>

### Setting up via the VDM editor

<Steps>
  <Step title="Open your VDM">
    Go to **DataBridge** → **Virtual Data Marts** and open the VDM.
  </Step>

  <Step title="Navigate to Time Series">
    In the VDM editor, go to the **Time Series** configuration section.
  </Step>

  <Step title="Add a time series entry">
    Select your date column, choose the allowed granularities, and set the default granularity and date range.
  </Step>

  <Step title="Save">
    Save the VDM. The configuration is now available to all experiments using this VDM.
  </Step>
</Steps>

### BI Import (automatic)

When importing from a BI semantic model, time series configuration is created automatically from LookML `dimension_group` blocks. Each group's `timeframes` array (e.g. `[date, month, quarter, year]`) maps directly to `availableGranularities`. A default 19-month lookback window is applied.

***

## Overriding Defaults

After initial setup (whether from BI import or manual creation), you can override the time series defaults from the VDM column configuration panel.

### Change the default granularity

In the VDM editor, open the time series column's detail panel. Use the **Default Granularity** dropdown to select which granularity the chart should start with (e.g. switch from `date` to `month` so charts default to monthly aggregation).

<Info>
  The default granularity determines the initial `dateRangeFilter.category` when a new chart is created using this date column. Users can still switch granularity at the experiment level via the dropdown.
</Info>

### Enable or disable granularities

In the column detail panel, find **Available Granularities**. Each granularity appears as a clickable chip:

* **Blue border + filled background** = enabled (visible in the experiment dropdown)
* **Grey border + dimmed** = disabled (hidden from the experiment dropdown)

Click a chip to toggle it. For example, if your data only makes sense at monthly and yearly levels, disable `date`, `week`, and `quarter` — the experiment dropdown will only show **Month** and **Year**.

<Warning>
  Disabling a granularity only hides it from the experiment-level dropdown. It does not delete the underlying data or prevent queries at that level via the API.
</Warning>

### Change the default date window

Use the **Default Date Window** field to set how many months of data the chart should load by default. The imported default is 19 months.

* Set to `6` for a 6-month rolling view
* Set to `12` for a trailing year
* Set to `0` or leave blank for all available data

This controls the `defaultDateRange.lookbackMonths` value in the time series configuration.

### Override summary

| What to change                       | Where               | Field                                               |
| ------------------------------------ | ------------------- | --------------------------------------------------- |
| Initial granularity (day/month/year) | Column detail panel | **Default Granularity** dropdown                    |
| Which granularities users can pick   | Column detail panel | **Available Granularities** chips (click to toggle) |
| Default data window                  | Column detail panel | **Default Date Window** (months)                    |
| Display name                         | Time Series Editor  | **Field Name**                                      |
| Source date column                   | Time Series Editor  | **Date Column**                                     |

<Tip>
  Changes to the VDM take effect for new experiments and new charts. Existing experiment charts retain their saved `dateRangeFilter` settings — the VDM defaults only apply at chart creation time.
</Tip>

### Example configuration

```json theme={null}
{
  "fieldName": "Position",
  "sourceColumn": "FCT_POSITION_SECURITY_LEVEL.POSITION_DT",
  "availableGranularities": ["date", "month", "quarter", "year"],
  "defaultGranularity": "date",
  "defaultTimeframeCategory": "DAY",
  "defaultDateRange": {
    "selectDateOption": "All",
    "lookbackMonths": 19,
    "category": "DAY"
  }
}
```

***

## Experiment: Time Range Dropdown

When a chart has a date column on its X axis, a dropdown button appears in the chart header next to the title. It combines granularity and range selection in a single control.

### Dropdown layout

The dropdown has grouped sections:

| Section         | Options                         | What it controls                              |
| --------------- | ------------------------------- | --------------------------------------------- |
| **Granularity** | Day, Week, Month, Quarter, Year | How data points are aggregated (`DATE_TRUNC`) |
| **Range**       | 5D, 1M, 3M, 6M, 1Y, 5Y          | Rolling time window                           |
| **To Date**     | WTD, MTD, QTD, YTD              | Period-to-date                                |
| **Other**       | All, Since Inception            | Full data set                                 |

<Tip>
  The **Granularity** section only shows options matching the VDM's `availableGranularities`. If the VDM allows `["date", "month", "year"]`, the dropdown shows Day, Month, Year — Week and Quarter are hidden.
</Tip>

### Button label

The button displays the current selection as `{Granularity} · {Range}`:

* `D · All` — Day granularity, all data
* `M · 1Y` — Monthly aggregation, past 1 year
* `Q · YTD` — Quarterly aggregation, year to date

### Chart type support

The dropdown appears on **any chart type** with a date axis — Line Series, Area, Column, Bar, Stacked, Combo, Scatter, Step Line, Table, and more. It is not limited to a specific chart type.

***

## Date Range Types

### Rolling ranges

| Button | Description   | Lookback                      |
| ------ | ------------- | ----------------------------- |
| **5D** | Past 5 Days   | 5 calendar days from max date |
| **1M** | Past 1 Month  | 1 month rolling               |
| **3M** | Past 3 Months | 3 months rolling              |
| **6M** | Past 6 Months | 6 months rolling              |
| **1Y** | Past 1 Year   | 1 year rolling                |
| **5Y** | Past 5 Years  | 5 years rolling               |

### Period-to-date

| Button  | Description     | From                        |
| ------- | --------------- | --------------------------- |
| **WTD** | Week to Date    | Monday of current week      |
| **MTD** | Month to Date   | 1st of current month        |
| **QTD** | Quarter to Date | 1st of current quarter      |
| **YTD** | Year to Date    | January 1st of current year |

### Calendar ranges (in filter panel)

When the grouping category is set, additional calendar-aligned options appear in the filter panel:

* **1CW / 2CW / 3CW** — Last 1 / 2 / 3 calendar weeks (when grouped by Day)
* **1CM / 2CM / 3CM** — Last 1 / 2 / 3 calendar months (when grouped by Month)
* **1CQ / 2CQ / 3CQ** — Last 1 / 2 / 3 calendar quarters (when grouped by Quarter)
* **1CY / 2CY / 3CY** — Last 1 / 2 / 3 calendar years (when grouped by Year)

### Special

| Button     | Description                                         |
| ---------- | --------------------------------------------------- |
| **All**    | No date filter — show all available data            |
| **SI**     | Since Inception — from the earliest record to today |
| **DR**     | Custom Date Range — opens a from/to date picker     |
| **Last N** | Custom lookback — enter a number and press Enter    |

***

## SDK Import

When creating dashboards via the SDK, set the `dateRange` property on time series charts:

```json theme={null}
{
  "title": "Market Value Trend",
  "type": "line-series",
  "dimensions": [
    { "field": "Position Date", "isDate": true },
    "Account Group Code"
  ],
  "measures": [
    { "field": "Total Market Value", "aggregation": "as-is" }
  ],
  "dateRange": {
    "category": "MONTH",
    "selectDateOption": "Past 1 Year"
  }
}
```

Named ranges (`Past 1 Year`, `YTD`, `Past 6 Months`, etc.) are resolved into concrete from/to dates at import time, so the chart loads pre-filtered.

<Warning>
  If you provide explicit `fromDate` and `toDate` in the `dateRange` object, those take priority over the named `selectDateOption`.
</Warning>

### Supported selectDateOption values

`All`, `Past 5 Days`, `Past 1 Month`, `Past 3 Months`, `Past 6 Months`, `Past 1 Year`, `Past 5 Years`, `Week to Date`, `Month to Date`, `Quarter to Date`, `Year to Date`, `Since Inception`