Dashboards - Add semantic_mode support to FormulaAndFunctionMetricQueryDefinition

.generator/schemas/v1/openapi.yaml

@@ -2952,11 +2952,24 @@ components:
           description: Metrics query definition.
           example: avg:system.cpu.user{*}
           type: string
+        semantic_mode:
+          $ref: '#/components/schemas/FormulaAndFunctionMetricSemanticMode'
       required:
       - data_source
       - query
       - name
       type: object
+    FormulaAndFunctionMetricSemanticMode:
+      description: Semantic mode for metrics queries. This determines how metrics
+        from different sources are combined or displayed.
+      enum:
+      - combined
+      - native
+      example: combined
+      type: string
+      x-enum-varnames:
+      - COMBINED
+      - NATIVE
     FormulaAndFunctionProcessQueryDataSource:
       description: Data sources that rely on the process backend.
       enum:

docs/datadog_api_client.v1.model.rst

@@ -893,6 +893,13 @@ datadog\_api\_client.v1.model.formula\_and\_function\_metric\_query\_definition
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v1.model.formula\_and\_function\_metric\_semantic\_mode module
+-----------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v1.model.formula_and_function_metric_semantic_mode
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v1.model.formula\_and\_function\_process\_query\_data\_source module
 -----------------------------------------------------------------------------------------
 

examples/v1/dashboards/CreateDashboard_3685886950.py

@@ -0,0 +1,58 @@
+"""
+Create a new dashboard with a timeseries widget using formulas and functions metrics query with native semantic_mode
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v1.api.dashboards_api import DashboardsApi
+from datadog_api_client.v1.model.dashboard import Dashboard
+from datadog_api_client.v1.model.dashboard_layout_type import DashboardLayoutType
+from datadog_api_client.v1.model.formula_and_function_metric_data_source import FormulaAndFunctionMetricDataSource
+from datadog_api_client.v1.model.formula_and_function_metric_query_definition import (
+    FormulaAndFunctionMetricQueryDefinition,
+)
+from datadog_api_client.v1.model.formula_and_function_metric_semantic_mode import FormulaAndFunctionMetricSemanticMode
+from datadog_api_client.v1.model.formula_and_function_response_format import FormulaAndFunctionResponseFormat
+from datadog_api_client.v1.model.timeseries_widget_definition import TimeseriesWidgetDefinition
+from datadog_api_client.v1.model.timeseries_widget_definition_type import TimeseriesWidgetDefinitionType
+from datadog_api_client.v1.model.timeseries_widget_request import TimeseriesWidgetRequest
+from datadog_api_client.v1.model.widget import Widget
+from datadog_api_client.v1.model.widget_display_type import WidgetDisplayType
+from datadog_api_client.v1.model.widget_formula import WidgetFormula
+
+body = Dashboard(
+    layout_type=DashboardLayoutType.ORDERED,
+    title="Example-Dashboard with native semantic_mode",
+    widgets=[
+        Widget(
+            definition=TimeseriesWidgetDefinition(
+                type=TimeseriesWidgetDefinitionType.TIMESERIES,
+                requests=[
+                    TimeseriesWidgetRequest(
+                        queries=[
+                            FormulaAndFunctionMetricQueryDefinition(
+                                data_source=FormulaAndFunctionMetricDataSource.METRICS,
+                                name="query1",
+                                query="avg:system.cpu.user{*}",
+                                semantic_mode=FormulaAndFunctionMetricSemanticMode.NATIVE,
+                            ),
+                        ],
+                        response_format=FormulaAndFunctionResponseFormat.TIMESERIES,
+                        formulas=[
+                            WidgetFormula(
+                                formula="query1",
+                            ),
+                        ],
+                        display_type=WidgetDisplayType.LINE,
+                    ),
+                ],
+            ),
+        ),
+    ],
+)
+
+configuration = Configuration()
+with ApiClient(configuration) as api_client:
+    api_instance = DashboardsApi(api_client)
+    response = api_instance.create_dashboard(body=body)
+
+    print(response)

examples/v1/dashboards/CreateDashboard_865807520.py

@@ -0,0 +1,58 @@
+"""
+Create a new dashboard with a timeseries widget using formulas and functions metrics query with combined semantic_mode
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v1.api.dashboards_api import DashboardsApi
+from datadog_api_client.v1.model.dashboard import Dashboard
+from datadog_api_client.v1.model.dashboard_layout_type import DashboardLayoutType
+from datadog_api_client.v1.model.formula_and_function_metric_data_source import FormulaAndFunctionMetricDataSource
+from datadog_api_client.v1.model.formula_and_function_metric_query_definition import (
+    FormulaAndFunctionMetricQueryDefinition,
+)
+from datadog_api_client.v1.model.formula_and_function_metric_semantic_mode import FormulaAndFunctionMetricSemanticMode
+from datadog_api_client.v1.model.formula_and_function_response_format import FormulaAndFunctionResponseFormat
+from datadog_api_client.v1.model.timeseries_widget_definition import TimeseriesWidgetDefinition
+from datadog_api_client.v1.model.timeseries_widget_definition_type import TimeseriesWidgetDefinitionType
+from datadog_api_client.v1.model.timeseries_widget_request import TimeseriesWidgetRequest
+from datadog_api_client.v1.model.widget import Widget
+from datadog_api_client.v1.model.widget_display_type import WidgetDisplayType
+from datadog_api_client.v1.model.widget_formula import WidgetFormula
+
+body = Dashboard(
+    layout_type=DashboardLayoutType.ORDERED,
+    title="Example-Dashboard with combined semantic_mode",
+    widgets=[
+        Widget(
+            definition=TimeseriesWidgetDefinition(
+                type=TimeseriesWidgetDefinitionType.TIMESERIES,
+                requests=[
+                    TimeseriesWidgetRequest(
+                        queries=[
+                            FormulaAndFunctionMetricQueryDefinition(
+                                data_source=FormulaAndFunctionMetricDataSource.METRICS,
+                                name="query1",
+                                query="avg:system.cpu.user{*}",
+                                semantic_mode=FormulaAndFunctionMetricSemanticMode.COMBINED,
+                            ),
+                        ],
+                        response_format=FormulaAndFunctionResponseFormat.TIMESERIES,
+                        formulas=[
+                            WidgetFormula(
+                                formula="query1",
+                            ),
+                        ],
+                        display_type=WidgetDisplayType.LINE,
+                    ),
+                ],
+            ),
+        ),
+    ],
+)
+
+configuration = Configuration()
+with ApiClient(configuration) as api_client:
+    api_instance = DashboardsApi(api_client)
+    response = api_instance.create_dashboard(body=body)
+
+    print(response)

src/datadog_api_client/v1/model/distribution_widget_histogram_request_query.py

@@ -30,6 +30,9 @@ def __init__(self, **kwargs):
         :param query: Metrics query definition.
         :type query: str
 
+        :param semantic_mode: Semantic mode for metrics queries. This determines how metrics from different sources are combined or displayed.
+        :type semantic_mode: FormulaAndFunctionMetricSemanticMode, optional
+
         :param compute: Compute options.
         :type compute: FormulaAndFunctionEventQueryDefinitionCompute
 

src/datadog_api_client/v1/model/formula_and_function_metric_query_definition.py

@@ -16,6 +16,9 @@
 if TYPE_CHECKING:
     from datadog_api_client.v1.model.formula_and_function_metric_aggregation import FormulaAndFunctionMetricAggregation
     from datadog_api_client.v1.model.formula_and_function_metric_data_source import FormulaAndFunctionMetricDataSource
+    from datadog_api_client.v1.model.formula_and_function_metric_semantic_mode import (
+        FormulaAndFunctionMetricSemanticMode,
+    )
 
 
 class FormulaAndFunctionMetricQueryDefinition(ModelNormal):
@@ -33,13 +36,17 @@ def openapi_types(_):
         from datadog_api_client.v1.model.formula_and_function_metric_data_source import (
             FormulaAndFunctionMetricDataSource,
         )
+        from datadog_api_client.v1.model.formula_and_function_metric_semantic_mode import (
+            FormulaAndFunctionMetricSemanticMode,
+        )
 
         return {
             "aggregator": (FormulaAndFunctionMetricAggregation,),
             "cross_org_uuids": ([str],),
             "data_source": (FormulaAndFunctionMetricDataSource,),
             "name": (str,),
             "query": (str,),
+            "semantic_mode": (FormulaAndFunctionMetricSemanticMode,),
         }
 
     attribute_map = {
@@ -48,6 +55,7 @@ def openapi_types(_):
         "data_source": "data_source",
         "name": "name",
         "query": "query",
+        "semantic_mode": "semantic_mode",
     }
 
     def __init__(
@@ -57,6 +65,7 @@ def __init__(
         query: str,
         aggregator: Union[FormulaAndFunctionMetricAggregation, UnsetType] = unset,
         cross_org_uuids: Union[List[str], UnsetType] = unset,
+        semantic_mode: Union[FormulaAndFunctionMetricSemanticMode, UnsetType] = unset,
         **kwargs,
     ):
         """
@@ -76,11 +85,16 @@ def __init__(
 
         :param query: Metrics query definition.
         :type query: str
+
+        :param semantic_mode: Semantic mode for metrics queries. This determines how metrics from different sources are combined or displayed.
+        :type semantic_mode: FormulaAndFunctionMetricSemanticMode, optional
         """
         if aggregator is not unset:
             kwargs["aggregator"] = aggregator
         if cross_org_uuids is not unset:
             kwargs["cross_org_uuids"] = cross_org_uuids
+        if semantic_mode is not unset:
+            kwargs["semantic_mode"] = semantic_mode
         super().__init__(kwargs)
 
         self_.data_source = data_source

src/datadog_api_client/v1/model/formula_and_function_metric_semantic_mode.py

@@ -0,0 +1,38 @@
+# 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 FormulaAndFunctionMetricSemanticMode(ModelSimple):
+    """
+    Semantic mode for metrics queries. This determines how metrics from different sources are combined or displayed.
+
+    :param value: Must be one of ["combined", "native"].
+    :type value: str
+    """
+
+    allowed_values = {
+        "combined",
+        "native",
+    }
+    COMBINED: ClassVar["FormulaAndFunctionMetricSemanticMode"]
+    NATIVE: ClassVar["FormulaAndFunctionMetricSemanticMode"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (str,),
+        }
+
+
+FormulaAndFunctionMetricSemanticMode.COMBINED = FormulaAndFunctionMetricSemanticMode("combined")
+FormulaAndFunctionMetricSemanticMode.NATIVE = FormulaAndFunctionMetricSemanticMode("native")

src/datadog_api_client/v1/model/formula_and_function_query_definition.py

@@ -30,6 +30,9 @@ def __init__(self, **kwargs):
         :param query: Metrics query definition.
         :type query: str
 
+        :param semantic_mode: Semantic mode for metrics queries. This determines how metrics from different sources are combined or displayed.
+        :type semantic_mode: FormulaAndFunctionMetricSemanticMode, optional
+
         :param compute: Compute options.
         :type compute: FormulaAndFunctionEventQueryDefinitionCompute
 

src/datadog_api_client/v1/model/slo_data_source_query_definition.py

@@ -29,6 +29,9 @@ def __init__(self, **kwargs):
 
         :param query: Metrics query definition.
         :type query: str
+
+        :param semantic_mode: Semantic mode for metrics queries. This determines how metrics from different sources are combined or displayed.
+        :type semantic_mode: FormulaAndFunctionMetricSemanticMode, optional
         """
         super().__init__(kwargs)
 

src/datadog_api_client/v1/models/__init__.py

@@ -155,6 +155,7 @@
 from datadog_api_client.v1.model.formula_and_function_metric_query_definition import (
     FormulaAndFunctionMetricQueryDefinition,
 )
+from datadog_api_client.v1.model.formula_and_function_metric_semantic_mode import FormulaAndFunctionMetricSemanticMode
 from datadog_api_client.v1.model.formula_and_function_process_query_data_source import (
     FormulaAndFunctionProcessQueryDataSource,
 )
@@ -1248,6 +1249,7 @@
     "FormulaAndFunctionMetricAggregation",
     "FormulaAndFunctionMetricDataSource",
     "FormulaAndFunctionMetricQueryDefinition",
+    "FormulaAndFunctionMetricSemanticMode",
     "FormulaAndFunctionProcessQueryDataSource",
     "FormulaAndFunctionProcessQueryDefinition",
     "FormulaAndFunctionQueryDefinition",

tests/v1/cassettes/test_scenarios/test_create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_combined_semantic_mode.frozen

@@ -0,0 +1 @@
+2025-12-08T18:40:10.047Z

tests/v1/cassettes/test_scenarios/test_create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_combined_semantic_mode.yaml

@@ -0,0 +1,38 @@
+interactions:
+- request:
+    body: '{"layout_type":"ordered","title":"Test-Create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_comb-1765219210
+      with combined semantic_mode","widgets":[{"definition":{"requests":[{"display_type":"line","formulas":[{"formula":"query1"}],"queries":[{"data_source":"metrics","name":"query1","query":"avg:system.cpu.user{*}","semantic_mode":"combined"}],"response_format":"timeseries"}],"type":"timeseries"}}]}'
+    headers:
+      accept:
+      - application/json
+      content-type:
+      - application/json
+    method: POST
+    uri: https://api.datadoghq.com/api/v1/dashboard
+  response:
+    body:
+      string: '{"id":"bpt-wdw-b9x","title":"Test-Create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_comb-1765219210
+        with combined semantic_mode","description":null,"author_handle":"[email protected]","author_name":"frog","layout_type":"ordered","url":"/dashboard/bpt-wdw-b9x/test-createanewdashboardwithatimeserieswidgetusingformulasandfunctionsmetricsque","template_variables":null,"widgets":[{"definition":{"requests":[{"display_type":"line","formulas":[{"formula":"query1"}],"queries":[{"data_source":"metrics","name":"query1","query":"avg:system.cpu.user{*}","semantic_mode":"combined"}],"response_format":"timeseries"}],"type":"timeseries"},"id":7196642548461969}],"notify_list":null,"created_at":"2025-12-08T18:40:10.214467+00:00","modified_at":"2025-12-08T18:40:10.214467+00:00","restricted_roles":[]}'
+    headers:
+      content-type:
+      - application/json
+    status:
+      code: 200
+      message: OK
+- request:
+    body: null
+    headers:
+      accept:
+      - application/json
+    method: DELETE
+    uri: https://api.datadoghq.com/api/v1/dashboard/bpt-wdw-b9x
+  response:
+    body:
+      string: '{"deleted_dashboard_id":"bpt-wdw-b9x"}'
+    headers:
+      content-type:
+      - application/json
+    status:
+      code: 200
+      message: OK
+version: 1

tests/v1/cassettes/test_scenarios/test_create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_native_semantic_mode.frozen

@@ -0,0 +1 @@
+2025-12-08T18:32:38.191Z

tests/v1/cassettes/test_scenarios/test_create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_native_semantic_mode.yaml

@@ -0,0 +1,38 @@
+interactions:
+- request:
+    body: '{"layout_type":"ordered","title":"Test-Create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_nati-1765218758
+      with native semantic_mode","widgets":[{"definition":{"requests":[{"display_type":"line","formulas":[{"formula":"query1"}],"queries":[{"data_source":"metrics","name":"query1","query":"avg:system.cpu.user{*}","semantic_mode":"native"}],"response_format":"timeseries"}],"type":"timeseries"}}]}'
+    headers:
+      accept:
+      - application/json
+      content-type:
+      - application/json
+    method: POST
+    uri: https://api.datadoghq.com/api/v1/dashboard
+  response:
+    body:
+      string: '{"id":"ptr-h98-jx4","title":"Test-Create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_nati-1765218758
+        with native semantic_mode","description":null,"author_handle":"[email protected]","author_name":"frog","layout_type":"ordered","url":"/dashboard/ptr-h98-jx4/test-createanewdashboardwithatimeserieswidgetusingformulasandfunctionsmetricsque","template_variables":null,"widgets":[{"definition":{"requests":[{"display_type":"line","formulas":[{"formula":"query1"}],"queries":[{"data_source":"metrics","name":"query1","query":"avg:system.cpu.user{*}","semantic_mode":"native"}],"response_format":"timeseries"}],"type":"timeseries"},"id":7543625669678795}],"notify_list":null,"created_at":"2025-12-08T18:32:38.359385+00:00","modified_at":"2025-12-08T18:32:38.359385+00:00","restricted_roles":[]}'
+    headers:
+      content-type:
+      - application/json
+    status:
+      code: 200
+      message: OK
+- request:
+    body: null
+    headers:
+      accept:
+      - application/json
+    method: DELETE
+    uri: https://api.datadoghq.com/api/v1/dashboard/ptr-h98-jx4
+  response:
+    body:
+      string: '{"deleted_dashboard_id":"ptr-h98-jx4"}'
+    headers:
+      content-type:
+      - application/json
+    status:
+      code: 200
+      message: OK
+version: 1