Defining a Parameter

Parameters in Sightfull enable dynamic and reusable values for metrics, dashboards, and analytics features. By defining parameters effectively, you can create flexible, powerful configurations that adapt to various scenarios. This guide covers the parameter structure, types, and provides practical examples to help you define parameters correctly.

Basic Syntax and Structure

Each parameter in Sightfull is defined with the following attributes:

• id (required): A unique identifier for the parameter.
• label (optional): A human-readable name for the parameter.
• description (optional): A brief description of the parameter's purpose.
• type (required): The data type of the parameter. Supported types include:
  • number: For numeric values.
  • string: For text values.
  • boolean: For true/false values.
  • date: For date values.
  • timestamptz: For timestamp with timezone values.
• values_type (required): Defines the type of values the parameter can accept. Options include:
  • any: Accepts any value of the specified type.
  • list: Accepts a predefined list of values.
  • range: Accepts values within a specified range (primarily for number types).
• values (optional): Provides the allowed values if values_type is set to list or range.
• default (required): The default value assigned to the parameter.

Choosing the Right Parameter Type

Selecting the appropriate parameter type is crucial for creating dynamic and effective analytics. Here's a breakdown of the types and when to use them:

1. Number Parameters

Purpose: Use number parameters for numeric values that can be freely entered, selected from a list, or constrained within a range.

• any: Accepts any numeric value.
• list: Allows selection from predefined numeric options.
• range: Limits values within a specified numeric range.

Example: Defining a Dynamic Group Size

Allows users to input any group size to customize data segmentation.

- id: group_size
  label: Group Size
  description: Customizable group size for data segmentation.
  type: number
  values_type: any
  default: 50

Example: Selecting from Predefined Size Options

Constrain the selection to a predefined list of sizes, such as product packaging options.

- id: packaging_size
  label: Packaging Size
  description: Select a product packaging size.
  type: number
  values_type: list
  values:
    - value: 100
      label: Small
    - value: 200
      label: Medium
    - value: 500
      label: Large
  default: 100

2. String Parameters

Purpose: Use string parameters for categorical data, such as selecting a category or type.

• any: Accepts any text input.
• list: Limits input to predefined text values.

Example: Selecting a Customer Segment

Allows users to choose from predefined customer segments, useful for targeted analytics.

- id: customer_segment
  label: Customer Segment
  description: Choose the customer segment for analysis.
  type: string
  values_type: list
  values:
    - value: "retail"
      label: Retail
    - value: "wholesale"
      label: Wholesale
  default: "retail"

3. Boolean Parameters

Purpose: Boolean parameters are ideal for binary choices, such as toggling a feature on or off.

• any: Represents a true or false value.

Example:

Example: Including or Excluding Tax

Allows the user to decide whether to include tax in the total calculation.

- id: include_tax
  label: Include Tax
  description: Whether to include tax in the total calculation.
  type: boolean
  values_type: any
  default: true

4. Date and DateTime Parameters

Purpose: These parameters manage date and time values, useful for time-based filtering and analysis.

• any: Accepts any valid date or datetime input.

Example: Setting a Report Date

Enables users to define the start date of a report period.

- id: report_date
  label: Report Date
  description: Start date for the report period.
  type: date
  values_type: any
  default: "2024-01-01"

Best Practices for Defining Parameters

• Clarity: Use clear and descriptive labels and descriptions.
• Consistency: Choose the appropriate type and values_type based on the intended use.
• Validation: Ensure all default values and allowed values are valid and meaningful.
• Reusability: Define parameters that can be reused across multiple metrics and dashboards.

Conclusion

Defining parameters effectively in Sightfull enhances flexibility and control in your analytics solutions. By understanding the different types and their proper usage, you can create dynamic and reusable elements that cater to a wide range of business needs.