Add comparison (change indicator) to QueryValueWidgetRequest

.generator/schemas/v1/openapi.yaml

@@ -1345,6 +1345,50 @@ components:
       type: string
       x-enum-varnames:
         - COHORT
+    ComparisonCustomTimeframe:
+      description: Fixed time range for a `custom_timeframe` comparison.
+      properties:
+        from:
+          description: Start time in milliseconds since epoch.
+          example: 1779290190000
+          format: int64
+          type: integer
+        to:
+          description: End time in milliseconds since epoch.
+          example: 1779894990000
+          format: int64
+          type: integer
+      required:
+        - from
+        - to
+      type: object
+    ComparisonDuration:
+      description: The comparison period. Use a preset `type` value or set `type` to `custom_timeframe` and provide `custom_timeframe` with explicit Unix timestamp bounds.
+      properties:
+        custom_timeframe:
+          $ref: "#/components/schemas/ComparisonCustomTimeframe"
+          description: Required when `type` is `custom_timeframe`. Fixed time range to compare against.
+        type:
+          $ref: "#/components/schemas/ComparisonDurationType"
+      required:
+        - type
+      type: object
+    ComparisonDurationType:
+      description: "Comparison window: `previous_timeframe` (same-length window immediately before current), `previous_day`, `previous_week`, `previous_month`, or `custom_timeframe` (set this to enable the `custom_timeframe` field)."
+      enum:
+        - previous_timeframe
+        - custom_timeframe
+        - previous_day
+        - previous_week
+        - previous_month
+      example: previous_timeframe
+      type: string
+      x-enum-varnames:
+        - PREVIOUS_TIMEFRAME
+        - CUSTOM_TIMEFRAME
+        - PREVIOUS_DAY
+        - PREVIOUS_WEEK
+        - PREVIOUS_MONTH
     ContentEncoding:
       description: HTTP header used to compress the media-type.
       enum:
@@ -12028,6 +12072,45 @@ components:
       x-enum-varnames:
         - ASC
         - DESC
+    QueryValueWidgetComparison:
+      description: A change indicator that compares the current value to a historical period.
+      properties:
+        directionality:
+          $ref: "#/components/schemas/QueryValueWidgetComparisonDirectionality"
+          description: Which direction of change is considered an improvement, determining the indicator color.
+        duration:
+          $ref: "#/components/schemas/ComparisonDuration"
+          description: The historical period to compare the current value against.
+        type:
+          $ref: "#/components/schemas/QueryValueWidgetComparisonType"
+          description: "How the delta is shown: as an absolute difference, a percentage, or both."
+      required:
+        - duration
+      type: object
+    QueryValueWidgetComparisonDirectionality:
+      default: neutral
+      description: "Color-coding direction: `increase_better` (green on rise), `decrease_better` (green on drop), or `neutral` (no color)."
+      enum:
+        - increase_better
+        - decrease_better
+        - neutral
+      type: string
+      x-enum-varnames:
+        - INCREASE_BETTER
+        - DECREASE_BETTER
+        - NEUTRAL
+    QueryValueWidgetComparisonType:
+      default: absolute
+      description: "How the delta is expressed: `absolute` (raw difference), `relative` (percentage), or `both`."
+      enum:
+        - absolute
+        - relative
+        - both
+      type: string
+      x-enum-varnames:
+        - ABSOLUTE
+        - RELATIVE
+        - BOTH
     QueryValueWidgetDefinition:
       description: Query values display the current value of a given metric, APM, or log query.
       properties:
@@ -12099,6 +12182,9 @@ components:
           $ref: "#/components/schemas/LogQueryDefinition"
           deprecated: true
           description: Deprecated - Use `queries` and `formulas` instead.
+        comparison:
+          $ref: "#/components/schemas/QueryValueWidgetComparison"
+          description: Displays a change indicator showing a delta against a historical baseline.
         conditional_formats:
           description: List of conditional formats.
           items:

docs/datadog_api_client.v1.model.rst

@@ -501,6 +501,27 @@ datadog\_api\_client.v1.model.cohort\_widget\_definition\_type module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v1.model.comparison\_custom\_timeframe module
+------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v1.model.comparison_custom_timeframe
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v1.model.comparison\_duration module
+---------------------------------------------------------
+
+.. automodule:: datadog_api_client.v1.model.comparison_duration
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v1.model.comparison\_duration\_type module
+---------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v1.model.comparison_duration_type
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v1.model.content\_encoding module
 ------------------------------------------------------
 
@@ -3721,6 +3742,27 @@ datadog\_api\_client.v1.model.query\_sort\_order module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v1.model.query\_value\_widget\_comparison module
+---------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v1.model.query_value_widget_comparison
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v1.model.query\_value\_widget\_comparison\_directionality module
+-------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v1.model.query_value_widget_comparison_directionality
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v1.model.query\_value\_widget\_comparison\_type module
+---------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v1.model.query_value_widget_comparison_type
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v1.model.query\_value\_widget\_definition module
 ---------------------------------------------------------------------
 

src/datadog_api_client/v1/model/comparison_custom_timeframe.py

@@ -0,0 +1,39 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+)
+
+
+class ComparisonCustomTimeframe(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        return {
+            "_from": (int,),
+            "to": (int,),
+        }
+
+    attribute_map = {
+        "_from": "from",
+        "to": "to",
+    }
+
+    def __init__(self_, _from: int, to: int, **kwargs):
+        """
+        Fixed time range for a ``custom_timeframe`` comparison.
+
+        :param _from: Start time in milliseconds since epoch.
+        :type _from: int
+
+        :param to: End time in milliseconds since epoch.
+        :type to: int
+        """
+        super().__init__(kwargs)
+
+        self_._from = _from
+        self_.to = to

src/datadog_api_client/v1/model/comparison_duration.py

@@ -0,0 +1,56 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import Union, TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+    unset,
+    UnsetType,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v1.model.comparison_custom_timeframe import ComparisonCustomTimeframe
+    from datadog_api_client.v1.model.comparison_duration_type import ComparisonDurationType
+
+
+class ComparisonDuration(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v1.model.comparison_custom_timeframe import ComparisonCustomTimeframe
+        from datadog_api_client.v1.model.comparison_duration_type import ComparisonDurationType
+
+        return {
+            "custom_timeframe": (ComparisonCustomTimeframe,),
+            "type": (ComparisonDurationType,),
+        }
+
+    attribute_map = {
+        "custom_timeframe": "custom_timeframe",
+        "type": "type",
+    }
+
+    def __init__(
+        self_,
+        type: ComparisonDurationType,
+        custom_timeframe: Union[ComparisonCustomTimeframe, UnsetType] = unset,
+        **kwargs,
+    ):
+        """
+        The comparison period. Use a preset ``type`` value or set ``type`` to ``custom_timeframe`` and provide ``custom_timeframe`` with explicit Unix timestamp bounds.
+
+        :param custom_timeframe: Fixed time range for a ``custom_timeframe`` comparison.
+        :type custom_timeframe: ComparisonCustomTimeframe, optional
+
+        :param type: Comparison window: ``previous_timeframe`` (same-length window immediately before current), ``previous_day`` , ``previous_week`` , ``previous_month`` , or ``custom_timeframe`` (set this to enable the ``custom_timeframe`` field).
+        :type type: ComparisonDurationType
+        """
+        if custom_timeframe is not unset:
+            kwargs["custom_timeframe"] = custom_timeframe
+        super().__init__(kwargs)
+
+        self_.type = type

src/datadog_api_client/v1/model/comparison_duration_type.py

@@ -0,0 +1,47 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelSimple,
+    cached_property,
+)
+
+from typing import ClassVar
+
+
+class ComparisonDurationType(ModelSimple):
+    """
+    Comparison window: `previous_timeframe` (same-length window immediately before current), `previous_day`, `previous_week`, `previous_month`, or `custom_timeframe` (set this to enable the `custom_timeframe` field).
+
+    :param value: Must be one of ["previous_timeframe", "custom_timeframe", "previous_day", "previous_week", "previous_month"].
+    :type value: str
+    """
+
+    allowed_values = {
+        "previous_timeframe",
+        "custom_timeframe",
+        "previous_day",
+        "previous_week",
+        "previous_month",
+    }
+    PREVIOUS_TIMEFRAME: ClassVar["ComparisonDurationType"]
+    CUSTOM_TIMEFRAME: ClassVar["ComparisonDurationType"]
+    PREVIOUS_DAY: ClassVar["ComparisonDurationType"]
+    PREVIOUS_WEEK: ClassVar["ComparisonDurationType"]
+    PREVIOUS_MONTH: ClassVar["ComparisonDurationType"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (str,),
+        }
+
+
+ComparisonDurationType.PREVIOUS_TIMEFRAME = ComparisonDurationType("previous_timeframe")
+ComparisonDurationType.CUSTOM_TIMEFRAME = ComparisonDurationType("custom_timeframe")
+ComparisonDurationType.PREVIOUS_DAY = ComparisonDurationType("previous_day")
+ComparisonDurationType.PREVIOUS_WEEK = ComparisonDurationType("previous_week")
+ComparisonDurationType.PREVIOUS_MONTH = ComparisonDurationType("previous_month")

src/datadog_api_client/v1/model/query_value_widget_comparison.py

@@ -0,0 +1,70 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import Union, TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+    unset,
+    UnsetType,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v1.model.query_value_widget_comparison_directionality import (
+        QueryValueWidgetComparisonDirectionality,
+    )
+    from datadog_api_client.v1.model.comparison_duration import ComparisonDuration
+    from datadog_api_client.v1.model.query_value_widget_comparison_type import QueryValueWidgetComparisonType
+
+
+class QueryValueWidgetComparison(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v1.model.query_value_widget_comparison_directionality import (
+            QueryValueWidgetComparisonDirectionality,
+        )
+        from datadog_api_client.v1.model.comparison_duration import ComparisonDuration
+        from datadog_api_client.v1.model.query_value_widget_comparison_type import QueryValueWidgetComparisonType
+
+        return {
+            "directionality": (QueryValueWidgetComparisonDirectionality,),
+            "duration": (ComparisonDuration,),
+            "type": (QueryValueWidgetComparisonType,),
+        }
+
+    attribute_map = {
+        "directionality": "directionality",
+        "duration": "duration",
+        "type": "type",
+    }
+
+    def __init__(
+        self_,
+        duration: ComparisonDuration,
+        directionality: Union[QueryValueWidgetComparisonDirectionality, UnsetType] = unset,
+        type: Union[QueryValueWidgetComparisonType, UnsetType] = unset,
+        **kwargs,
+    ):
+        """
+        A change indicator that compares the current value to a historical period.
+
+        :param directionality: Color-coding direction: ``increase_better`` (green on rise), ``decrease_better`` (green on drop), or ``neutral`` (no color).
+        :type directionality: QueryValueWidgetComparisonDirectionality, optional
+
+        :param duration: The comparison period. Use a preset ``type`` value or set ``type`` to ``custom_timeframe`` and provide ``custom_timeframe`` with explicit Unix timestamp bounds.
+        :type duration: ComparisonDuration
+
+        :param type: How the delta is expressed: ``absolute`` (raw difference), ``relative`` (percentage), or ``both``.
+        :type type: QueryValueWidgetComparisonType, optional
+        """
+        if directionality is not unset:
+            kwargs["directionality"] = directionality
+        if type is not unset:
+            kwargs["type"] = type
+        super().__init__(kwargs)
+
+        self_.duration = duration