Periods
This document provides an overview of what periods are in Sightfull and introduces essential syntax to create metrics that accurately reflect your intended measurements.
What is the period object?
In Sightfull, the period object is a type of data object crucial for grouping entities over time. It allows for the organization and analysis of data based on specific time frames, which is fundamental in time-based metric calculations and reporting.
There are both calendar as well as fiscal periods. Fiscal periods can be configured to reflect the business reporting methods with a fiscal year offset.
Metrics can be calculated for the following period types (defaults to month):
| Period Unit | Type |
|---|---|
| day | Calendar |
| week | Calendar |
| fweek | Fiscal |
| month | Calendar |
| cquarter | Calendar |
| fquarter | Fiscal |
| fyear | Fiscal |
Period operations
The period object represents a certain timeframe. You can use the $period variable in your metric schema to determine how the metric is calculated and presented along the X-axis.
To effectively utilize Sightfull for metric creation and to configure the metric's x_axis as per your requirements, it is essential to understand how to operate on the period object. This section details the available operations on the period object.
To quickly understand the outcome of each period operation in Sightfull, the below table provides a clear reference. For the period of "March 2023", here is the result and result type of each operation:
| Operation | Is Equal to | Type |
|---|---|---|
period.start | '2023-03-01T00:00:00.000Z' | Datetime |
period.end | '2023-03-31T23:59:59.000Z' | Datetime |
This syntax can help you better configure the metric schema in order to precisely capture the dataset you need in your metric calculation and configure your metric x_axis to your specifications.
period.start
The start of a period is vital for metrics that should include all events from the beginning of a specific timeframe, or create a snapshot at the start of the period. For instance, businesses can use this to analyze the amount of open pipeline at the start of each quarter. The example below groups and sums all products
- name: starting_pipeline
entity: opportunity
operation: sum
x_axis:
period:
- sql: $created_date <= $period.start
- sql: $close_date > $period.start
measure: $amount_in_usd
period.end
The end of a period is crucial for assessments of financial quarters or getting snapshots in time. This helps in evaluating performance metrics at the close of a fiscal period or producing snapshots of results over time. For example, the following metric captures a snapshot of the annualized recurring revenue (ARR) of opportunities that were open at the end of the period:
- name: rolling_arr
entity: opportunity
operation: sum
x_axis:
period:
- sql: $period.end BETWEEN $contract_start AND $contract_end
measure: $arr_amount_in_usd
The following operations provide a relative period. You can use them in combination with the $period.start and $period.end operations to select the appropriate datetime value for metrics you create.
Wrapping up
This guide provides a comprehensive overview of period objects and operations in Sightfull, crucial for accurate time-based metric calculations and data analysis. The examples demonstrate practical applications, from performance evaluation to trend analysis, highlighting the versatility of period operations in metric configuration. To learn more about configuring the time-series behavior of metrics, see the X-axis documentation.