Dashboards - Add semantic_mode support to FormulaAndFunctionMetricQueryDefinition (#2817)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.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:

cassettes/features/v1/dashboards/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

cassettes/features/v1/dashboards/Create-a-new-dashboard-with-a-timeseries-widget-using-formulas-and-functions-metrics-query-with-combined-semantic-mode.yml

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

cassettes/features/v1/dashboards/Create-a-new-dashboard-with-a-timeseries-widget-using-formulas-and-functions-metrics-query-with-native-semantic-mode.frozen

@@ -0,0 +1,36 @@
+# Create a new dashboard with a timeseries widget using formulas and functions metrics query with native semantic_mode
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V1::DashboardsAPI.new
+
+body = DatadogAPIClient::V1::Dashboard.new({
+  layout_type: DatadogAPIClient::V1::DashboardLayoutType::ORDERED,
+  title: "Example-Dashboard with native semantic_mode",
+  widgets: [
+    DatadogAPIClient::V1::Widget.new({
+      definition: DatadogAPIClient::V1::TimeseriesWidgetDefinition.new({
+        type: DatadogAPIClient::V1::TimeseriesWidgetDefinitionType::TIMESERIES,
+        requests: [
+          DatadogAPIClient::V1::TimeseriesWidgetRequest.new({
+            queries: [
+              DatadogAPIClient::V1::FormulaAndFunctionMetricQueryDefinition.new({
+                data_source: DatadogAPIClient::V1::FormulaAndFunctionMetricDataSource::METRICS,
+                name: "query1",
+                query: "avg:system.cpu.user{*}",
+                semantic_mode: DatadogAPIClient::V1::FormulaAndFunctionMetricSemanticMode::NATIVE,
+              }),
+            ],
+            response_format: DatadogAPIClient::V1::FormulaAndFunctionResponseFormat::TIMESERIES,
+            formulas: [
+              DatadogAPIClient::V1::WidgetFormula.new({
+                formula: "query1",
+              }),
+            ],
+            display_type: DatadogAPIClient::V1::WidgetDisplayType::LINE,
+          }),
+        ],
+      }),
+    }),
+  ],
+})
+p api_instance.create_dashboard(body)

cassettes/features/v1/dashboards/Create-a-new-dashboard-with-a-timeseries-widget-using-formulas-and-functions-metrics-query-with-native-semantic-mode.yml

@@ -0,0 +1,36 @@
+# Create a new dashboard with a timeseries widget using formulas and functions metrics query with combined semantic_mode
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V1::DashboardsAPI.new
+
+body = DatadogAPIClient::V1::Dashboard.new({
+  layout_type: DatadogAPIClient::V1::DashboardLayoutType::ORDERED,
+  title: "Example-Dashboard with combined semantic_mode",
+  widgets: [
+    DatadogAPIClient::V1::Widget.new({
+      definition: DatadogAPIClient::V1::TimeseriesWidgetDefinition.new({
+        type: DatadogAPIClient::V1::TimeseriesWidgetDefinitionType::TIMESERIES,
+        requests: [
+          DatadogAPIClient::V1::TimeseriesWidgetRequest.new({
+            queries: [
+              DatadogAPIClient::V1::FormulaAndFunctionMetricQueryDefinition.new({
+                data_source: DatadogAPIClient::V1::FormulaAndFunctionMetricDataSource::METRICS,
+                name: "query1",
+                query: "avg:system.cpu.user{*}",
+                semantic_mode: DatadogAPIClient::V1::FormulaAndFunctionMetricSemanticMode::COMBINED,
+              }),
+            ],
+            response_format: DatadogAPIClient::V1::FormulaAndFunctionResponseFormat::TIMESERIES,
+            formulas: [
+              DatadogAPIClient::V1::WidgetFormula.new({
+                formula: "query1",
+              }),
+            ],
+            display_type: DatadogAPIClient::V1::WidgetDisplayType::LINE,
+          }),
+        ],
+      }),
+    }),
+  ],
+})
+p api_instance.create_dashboard(body)

examples/v1/dashboards/CreateDashboard_3685886950.rb

@@ -195,6 +195,30 @@ Feature: Dashboards
     And the response "widgets[0].definition.requests[0].formulas[0].formula" is equal to "query1"
     And the response "widgets[0].definition.time.live_span" is equal to "week_to_date"
 
+  @team:DataDog/dashboards-backend
+  Scenario: Create a new dashboard with a timeseries widget using formulas and functions metrics query with combined semantic_mode
+    Given new "CreateDashboard" request
+    And body with value {"layout_type": "ordered", "title": "{{ unique }} with combined semantic_mode", "widgets": [{"definition": {"type": "timeseries", "requests": [{"queries": [{"data_source": "metrics", "name": "query1", "query": "avg:system.cpu.user{*}", "semantic_mode": "combined"}], "response_format": "timeseries", "formulas": [{"formula": "query1"}], "display_type": "line"}]}}]}
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "widgets[0].definition.requests[0].response_format" is equal to "timeseries"
+    And the response "widgets[0].definition.requests[0].queries[0].data_source" is equal to "metrics"
+    And the response "widgets[0].definition.requests[0].queries[0].name" is equal to "query1"
+    And the response "widgets[0].definition.requests[0].queries[0].query" is equal to "avg:system.cpu.user{*}"
+    And the response "widgets[0].definition.requests[0].queries[0].semantic_mode" is equal to "combined"
+
+  @team:DataDog/dashboards-backend
+  Scenario: Create a new dashboard with a timeseries widget using formulas and functions metrics query with native semantic_mode
+    Given new "CreateDashboard" request
+    And body with value {"layout_type": "ordered", "title": "{{ unique }} with native semantic_mode", "widgets": [{"definition": {"type": "timeseries", "requests": [{"queries": [{"data_source": "metrics", "name": "query1", "query": "avg:system.cpu.user{*}", "semantic_mode": "native"}], "response_format": "timeseries", "formulas": [{"formula": "query1"}], "display_type": "line"}]}}]}
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "widgets[0].definition.requests[0].response_format" is equal to "timeseries"
+    And the response "widgets[0].definition.requests[0].queries[0].data_source" is equal to "metrics"
+    And the response "widgets[0].definition.requests[0].queries[0].name" is equal to "query1"
+    And the response "widgets[0].definition.requests[0].queries[0].query" is equal to "avg:system.cpu.user{*}"
+    And the response "widgets[0].definition.requests[0].queries[0].semantic_mode" is equal to "native"
+
   @team:DataDog/dashboards-backend
   Scenario: Create a new dashboard with a toplist widget sorted by group
     Given new "CreateDashboard" request

examples/v1/dashboards/CreateDashboard_865807520.rb

@@ -134,6 +134,7 @@ def overrides
           "v1.formula_and_function_metric_aggregation" => "FormulaAndFunctionMetricAggregation",
           "v1.formula_and_function_metric_data_source" => "FormulaAndFunctionMetricDataSource",
           "v1.formula_and_function_metric_query_definition" => "FormulaAndFunctionMetricQueryDefinition",
+          "v1.formula_and_function_metric_semantic_mode" => "FormulaAndFunctionMetricSemanticMode",
           "v1.formula_and_function_process_query_data_source" => "FormulaAndFunctionProcessQueryDataSource",
           "v1.formula_and_function_process_query_definition" => "FormulaAndFunctionProcessQueryDefinition",
           "v1.formula_and_function_query_definition" => "FormulaAndFunctionQueryDefinition",

features/v1/dashboards.feature

@@ -36,6 +36,9 @@ class FormulaAndFunctionMetricQueryDefinition
     # Metrics query definition.
     attr_reader :query
 
+    # Semantic mode for metrics queries. This determines how metrics from different sources are combined or displayed.
+    attr_accessor :semantic_mode
+
     attr_accessor :additional_properties
 
     # Attribute mapping from ruby-style variable name to JSON key.
@@ -46,7 +49,8 @@ def self.attribute_map
         :'cross_org_uuids' => :'cross_org_uuids',
         :'data_source' => :'data_source',
         :'name' => :'name',
-        :'query' => :'query'
+        :'query' => :'query',
+        :'semantic_mode' => :'semantic_mode'
       }
     end
 
@@ -58,7 +62,8 @@ def self.openapi_types
         :'cross_org_uuids' => :'Array<String>',
         :'data_source' => :'FormulaAndFunctionMetricDataSource',
         :'name' => :'String',
-        :'query' => :'String'
+        :'query' => :'String',
+        :'semantic_mode' => :'FormulaAndFunctionMetricSemanticMode'
       }
     end
 
@@ -101,6 +106,10 @@ def initialize(attributes = {})
       if attributes.key?(:'query')
         self.query = attributes[:'query']
       end
+
+      if attributes.key?(:'semantic_mode')
+        self.semantic_mode = attributes[:'semantic_mode']
+      end
     end
 
     # Check to see if the all the properties in the model are valid
@@ -185,14 +194,15 @@ def ==(o)
           data_source == o.data_source &&
           name == o.name &&
           query == o.query &&
+          semantic_mode == o.semantic_mode &&
           additional_properties == o.additional_properties
     end
 
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     # @!visibility private
     def hash
-      [aggregator, cross_org_uuids, data_source, name, query, additional_properties].hash
+      [aggregator, cross_org_uuids, data_source, name, query, semantic_mode, additional_properties].hash
     end
   end
 end