Controls

Control configuration and compilation.

Control Settings

ControlSettings pydantic-model

Settings for controls in a dashboard, defining their behavior and appearance.

Attributes:

Name	Type	Description
label_position	Literal['inline', 'above'] | None	The position of the control label, either 'inline' or 'above'. Defaults to 'inline' if not set.
apply_global_filters	bool | None	Whether to apply global filters to the control. Defaults to true if not set.
apply_global_timerange	bool | None	Whether to apply the global time range to the control. Defaults to true if not set.
ignore_zero_results	bool | None	Whether to ignore controls that return zero results. Defaults to true if not set.
chain_controls	bool | None	Whether to chain controls together, allowing one control's selection to filter the next. Defaults to true if not set.
click_to_apply	bool | None	Whether to require users to click the apply button before applying changes. Defaults to false if not set.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Settings for controls in a dashboard, defining their behavior and appearance.",
  "properties": {
    "label_position": {
      "anyOf": [
        {
          "enum": [
            "inline",
            "above"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The position of the control label, either 'inline' or 'above'. Defaults to 'inline' if not set.",
      "title": "Label Position"
    },
    "apply_global_filters": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to apply global filters to the control. Defaults to true if not set.",
      "title": "Apply Global Filters"
    },
    "apply_global_timerange": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to apply the global time range to the control. Defaults to true if not set.",
      "title": "Apply Global Timerange"
    },
    "ignore_zero_results": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to ignore controls that return zero results. Defaults to true if not set.",
      "title": "Ignore Zero Results"
    },
    "chain_controls": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to chain controls together, allowing one control's selection to filter the next. Defaults to true if not set.",
      "title": "Chain Controls"
    },
    "click_to_apply": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to require users to click the apply button before applying changes. Defaults to false if not set.",
      "title": "Click To Apply"
    }
  },
  "title": "ControlSettings",
  "type": "object"
}

Source code in kb_dashboard_core/controls/config.py

class ControlSettings(BaseCfgModel):
    """Settings for controls in a dashboard, defining their behavior and appearance."""

    label_position: Literal['inline', 'above'] | None = Field(default=None)
    """The position of the control label, either 'inline' or 'above'. Defaults to 'inline' if not set."""

    apply_global_filters: bool | None = Field(default=None)
    """Whether to apply global filters to the control. Defaults to true if not set."""

    apply_global_timerange: bool | None = Field(default=None)
    """Whether to apply the global time range to the control. Defaults to true if not set."""

    ignore_zero_results: bool | None = Field(default=None)
    """Whether to ignore controls that return zero results. Defaults to true if not set."""

    chain_controls: bool | None = Field(default=None)
    """Whether to chain controls together, allowing one control's selection to filter the next. Defaults to true if not set."""

    click_to_apply: bool | None = Field(default=None)
    """Whether to require users to click the apply button before applying changes. Defaults to false if not set."""

Base Control

BaseControl pydantic-model

Base class for defining controls within the YAML schema.

These controls are used to filter data or adjust visualization settings on a dashboard.

Attributes:

Name	Type	Description
width	Literal['small', 'medium', 'large'] | None	The width of the control in the dashboard layout. If not set, defaults to 'medium'.
label	str | None	The display label for the control. If not provided, a label may be inferred.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Base class for defining controls within the YAML schema.\n\nThese controls are used to filter data or adjust visualization settings\non a dashboard.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    }
  },
  "title": "BaseControl",
  "type": "object"
}

Source code in kb_dashboard_core/controls/config.py

class BaseControl(BaseIdentifiableModel):
    """Base class for defining controls within the YAML schema.

    These controls are used to filter data or adjust visualization settings
    on a dashboard.
    """

    width: Literal['small', 'medium', 'large'] | None = Field(default=None)
    """The width of the control in the dashboard layout. If not set, defaults to 'medium'."""

    label: str | None = Field(default=None)
    """The display label for the control. If not provided, a label may be inferred."""

Options List Control

OptionsListControl pydantic-model

Represents an Options List control.

This control allows users to select one or more values from a list to filter data.

Attributes:

Name	Type	Description
type	Literal['options']
field	str	The name of the field within the data view that the control is associated with.
fill_width	bool	If true, the control will automatically adjust its width to fill available space.
match_technique	MatchTechnique | None	The search technique used for filtering options (e.g., 'prefix', 'contains', 'exact').
wait_for_results	bool | None	If set to true, delay the display of the list of values until the results are fully loaded.
preselected	list[str]	A list of options that are preselected when the control is initialized.
multiple	bool | None	If true, allow multiple selection.
data_view	str	The ID or title of the data view (index pattern) the control operates on.

Show JSON schema:

{
  "$defs": {
    "MatchTechnique": {
      "description": "Enumeration for match techniques used in options list controls.",
      "enum": [
        "prefix",
        "contains",
        "exact"
      ],
      "title": "MatchTechnique",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Represents an Options List control.\n\nThis control allows users to select one or more values from a list\nto filter data.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "options",
      "default": "options",
      "title": "Type",
      "type": "string"
    },
    "field": {
      "description": "The name of the field within the data view that the control is associated with.",
      "title": "Field",
      "type": "string"
    },
    "fill_width": {
      "default": false,
      "description": "If true, the control will automatically adjust its width to fill available space.",
      "title": "Fill Width",
      "type": "boolean"
    },
    "match_technique": {
      "anyOf": [
        {
          "$ref": "#/$defs/MatchTechnique"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The search technique used for filtering options (e.g., 'prefix', 'contains', 'exact')."
    },
    "wait_for_results": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "If set to true, delay the display of the list of values until the results are fully loaded.",
      "title": "Wait For Results"
    },
    "preselected": {
      "description": "A list of options that are preselected when the control is initialized.",
      "items": {
        "type": "string"
      },
      "title": "Preselected",
      "type": "array"
    },
    "multiple": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "If true, allow multiple selection.",
      "title": "Multiple"
    },
    "data_view": {
      "description": "The ID or title of the data view (index pattern) the control operates on.",
      "title": "Data View",
      "type": "string"
    }
  },
  "required": [
    "field",
    "data_view"
  ],
  "title": "OptionsListControl",
  "type": "object"
}

Source code in kb_dashboard_core/controls/config.py

class OptionsListControl(BaseControl):
    """Represents an Options List control.

    This control allows users to select one or more values from a list
    to filter data.
    """

    type: Literal['options'] = 'options'

    field: str = Field(...)
    """The name of the field within the data view that the control is associated with."""

    fill_width: bool = Field(default=False)
    """If true, the control will automatically adjust its width to fill available space."""

    match_technique: MatchTechnique | None = Field(default=None, strict=False)  # strict=False for enum coercion
    """The search technique used for filtering options (e.g., 'prefix', 'contains', 'exact')."""

    wait_for_results: bool | None = Field(default=None)
    """If set to true, delay the display of the list of values until the results are fully loaded."""

    preselected: list[str] = Field(default_factory=list)
    """A list of options that are preselected when the control is initialized."""

    multiple: bool | None = Field(default=None)
    """If true, allow multiple selection."""

    data_view: str = Field(...)
    """The ID or title of the data view (index pattern) the control operates on."""

Range Slider Control

RangeSliderControl pydantic-model

Represents a Range Slider control.

This control allows users to select a range of numeric or date values to filter data.

Attributes:

Name	Type	Description
type	Literal['range']
fill_width	bool	If true, the control will automatically adjust its width to fill available space.
field	str	The name of the field within the data view that the control is associated with.
step	int | float | None	The step value for the range, defining the granularity of selections.
data_view	str	The ID or title of the data view (index pattern) the control operates on.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Represents a Range Slider control.\n\nThis control allows users to select a range of numeric or date values\nto filter data.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "range",
      "default": "range",
      "title": "Type",
      "type": "string"
    },
    "fill_width": {
      "default": false,
      "description": "If true, the control will automatically adjust its width to fill available space.",
      "title": "Fill Width",
      "type": "boolean"
    },
    "field": {
      "description": "The name of the field within the data view that the control is associated with.",
      "title": "Field",
      "type": "string"
    },
    "step": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The step value for the range, defining the granularity of selections.",
      "title": "Step"
    },
    "data_view": {
      "description": "The ID or title of the data view (index pattern) the control operates on.",
      "title": "Data View",
      "type": "string"
    }
  },
  "required": [
    "field",
    "data_view"
  ],
  "title": "RangeSliderControl",
  "type": "object"
}

Source code in kb_dashboard_core/controls/config.py

class RangeSliderControl(BaseControl):
    """Represents a Range Slider control.

    This control allows users to select a range of numeric or date values
    to filter data.
    """

    type: Literal['range'] = 'range'

    fill_width: bool = Field(default=False)
    """If true, the control will automatically adjust its width to fill available space."""

    field: str = Field(...)
    """The name of the field within the data view that the control is associated with."""

    step: int | float | None = Field(default=None)
    """The step value for the range, defining the granularity of selections."""

    data_view: str = Field(...)
    """The ID or title of the data view (index pattern) the control operates on."""

Time Slider Control

TimeSliderControl pydantic-model

Represents a Time Slider control.

This control allows users to select a time range to filter data by adjusting start and end offsets within the global time range.

Attributes:

Name	Type	Description
type	Literal['time']
start_offset	float | None	The start offset for the time range as a %, defining the beginning of the selection.
end_offset	float | None	The end offset for the time range as a %, defining the end of the selection.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Represents a Time Slider control.\n\nThis control allows users to select a time range to filter data\nby adjusting start and end offsets within the global time range.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "time",
      "default": "time",
      "title": "Type",
      "type": "string"
    },
    "start_offset": {
      "anyOf": [
        {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The start offset for the time range as a %, defining the beginning of the selection.",
      "title": "Start Offset"
    },
    "end_offset": {
      "anyOf": [
        {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The end offset for the time range as a %, defining the end of the selection.",
      "title": "End Offset"
    }
  },
  "title": "TimeSliderControl",
  "type": "object"
}

Validators:

• validate_offsets

Source code in kb_dashboard_core/controls/config.py

class TimeSliderControl(BaseControl):
    """Represents a Time Slider control.

    This control allows users to select a time range to filter data
    by adjusting start and end offsets within the global time range.
    """

    type: Literal['time'] = 'time'

    start_offset: float | None = Field(default=None, ge=0, le=1)
    """The start offset for the time range as a %, defining the beginning of the selection."""

    end_offset: float | None = Field(default=None, ge=0, le=1)
    """The end offset for the time range as a %, defining the end of the selection."""

    @model_validator(mode='after')
    def validate_offsets(self) -> Self:
        """Ensure that start_offset is less than end_offset."""
        if self.start_offset is not None and self.end_offset is not None and self.start_offset > self.end_offset:
            msg = 'start_offset must be less than end_offset'
            raise ValueError(msg)

        return self