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:

examples/v1/dashboards/CreateDashboard_3685886950.java

@@ -0,0 +1,72 @@
+// Create a new dashboard with a timeseries widget using formulas and functions metrics query with
+// native semantic_mode
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v1.api.DashboardsApi;
+import com.datadog.api.client.v1.model.Dashboard;
+import com.datadog.api.client.v1.model.DashboardLayoutType;
+import com.datadog.api.client.v1.model.FormulaAndFunctionMetricDataSource;
+import com.datadog.api.client.v1.model.FormulaAndFunctionMetricQueryDefinition;
+import com.datadog.api.client.v1.model.FormulaAndFunctionMetricSemanticMode;
+import com.datadog.api.client.v1.model.FormulaAndFunctionQueryDefinition;
+import com.datadog.api.client.v1.model.FormulaAndFunctionResponseFormat;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinition;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinitionType;
+import com.datadog.api.client.v1.model.TimeseriesWidgetRequest;
+import com.datadog.api.client.v1.model.Widget;
+import com.datadog.api.client.v1.model.WidgetDefinition;
+import com.datadog.api.client.v1.model.WidgetDisplayType;
+import com.datadog.api.client.v1.model.WidgetFormula;
+import java.util.Collections;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    DashboardsApi apiInstance = new DashboardsApi(defaultClient);
+
+    Dashboard body =
+        new Dashboard()
+            .layoutType(DashboardLayoutType.ORDERED)
+            .title("Example-Dashboard with native semantic_mode")
+            .widgets(
+                Collections.singletonList(
+                    new Widget()
+                        .definition(
+                            new WidgetDefinition(
+                                new TimeseriesWidgetDefinition()
+                                    .type(TimeseriesWidgetDefinitionType.TIMESERIES)
+                                    .requests(
+                                        Collections.singletonList(
+                                            new TimeseriesWidgetRequest()
+                                                .queries(
+                                                    Collections.singletonList(
+                                                        new FormulaAndFunctionQueryDefinition(
+                                                            new FormulaAndFunctionMetricQueryDefinition()
+                                                                .dataSource(
+                                                                    FormulaAndFunctionMetricDataSource
+                                                                        .METRICS)
+                                                                .name("query1")
+                                                                .query("avg:system.cpu.user{*}")
+                                                                .semanticMode(
+                                                                    FormulaAndFunctionMetricSemanticMode
+                                                                        .NATIVE))))
+                                                .responseFormat(
+                                                    FormulaAndFunctionResponseFormat.TIMESERIES)
+                                                .formulas(
+                                                    Collections.singletonList(
+                                                        new WidgetFormula().formula("query1")))
+                                                .displayType(WidgetDisplayType.LINE)))))));
+
+    try {
+      Dashboard result = apiInstance.createDashboard(body);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DashboardsApi#createDashboard");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

examples/v1/dashboards/CreateDashboard_865807520.java

@@ -0,0 +1,72 @@
+// Create a new dashboard with a timeseries widget using formulas and functions metrics query with
+// combined semantic_mode
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v1.api.DashboardsApi;
+import com.datadog.api.client.v1.model.Dashboard;
+import com.datadog.api.client.v1.model.DashboardLayoutType;
+import com.datadog.api.client.v1.model.FormulaAndFunctionMetricDataSource;
+import com.datadog.api.client.v1.model.FormulaAndFunctionMetricQueryDefinition;
+import com.datadog.api.client.v1.model.FormulaAndFunctionMetricSemanticMode;
+import com.datadog.api.client.v1.model.FormulaAndFunctionQueryDefinition;
+import com.datadog.api.client.v1.model.FormulaAndFunctionResponseFormat;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinition;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinitionType;
+import com.datadog.api.client.v1.model.TimeseriesWidgetRequest;
+import com.datadog.api.client.v1.model.Widget;
+import com.datadog.api.client.v1.model.WidgetDefinition;
+import com.datadog.api.client.v1.model.WidgetDisplayType;
+import com.datadog.api.client.v1.model.WidgetFormula;
+import java.util.Collections;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    DashboardsApi apiInstance = new DashboardsApi(defaultClient);
+
+    Dashboard body =
+        new Dashboard()
+            .layoutType(DashboardLayoutType.ORDERED)
+            .title("Example-Dashboard with combined semantic_mode")
+            .widgets(
+                Collections.singletonList(
+                    new Widget()
+                        .definition(
+                            new WidgetDefinition(
+                                new TimeseriesWidgetDefinition()
+                                    .type(TimeseriesWidgetDefinitionType.TIMESERIES)
+                                    .requests(
+                                        Collections.singletonList(
+                                            new TimeseriesWidgetRequest()
+                                                .queries(
+                                                    Collections.singletonList(
+                                                        new FormulaAndFunctionQueryDefinition(
+                                                            new FormulaAndFunctionMetricQueryDefinition()
+                                                                .dataSource(
+                                                                    FormulaAndFunctionMetricDataSource
+                                                                        .METRICS)
+                                                                .name("query1")
+                                                                .query("avg:system.cpu.user{*}")
+                                                                .semanticMode(
+                                                                    FormulaAndFunctionMetricSemanticMode
+                                                                        .COMBINED))))
+                                                .responseFormat(
+                                                    FormulaAndFunctionResponseFormat.TIMESERIES)
+                                                .formulas(
+                                                    Collections.singletonList(
+                                                        new WidgetFormula().formula("query1")))
+                                                .displayType(WidgetDisplayType.LINE)))))));
+
+    try {
+      Dashboard result = apiInstance.createDashboard(body);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DashboardsApi#createDashboard");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

src/main/java/com/datadog/api/client/v1/model/FormulaAndFunctionMetricQueryDefinition.java

@@ -25,7 +25,8 @@
   FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_CROSS_ORG_UUIDS,
   FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_DATA_SOURCE,
   FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_NAME,
-  FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_QUERY
+  FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_QUERY,
+  FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_SEMANTIC_MODE
 })
 @jakarta.annotation.Generated(
     value = "https://github.com/DataDog/datadog-api-client-java/blob/master/.generator")
@@ -46,6 +47,9 @@ public class FormulaAndFunctionMetricQueryDefinition {
   public static final String JSON_PROPERTY_QUERY = "query";
   private String query;
 
+  public static final String JSON_PROPERTY_SEMANTIC_MODE = "semantic_mode";
+  private FormulaAndFunctionMetricSemanticMode semanticMode;
+
   public FormulaAndFunctionMetricQueryDefinition() {}
 
   @JsonCreator
@@ -180,6 +184,33 @@ public void setQuery(String query) {
     this.query = query;
   }
 
+  public FormulaAndFunctionMetricQueryDefinition semanticMode(
+      FormulaAndFunctionMetricSemanticMode semanticMode) {
+    this.semanticMode = semanticMode;
+    this.unparsed |= !semanticMode.isValid();
+    return this;
+  }
+
+  /**
+   * Semantic mode for metrics queries. This determines how metrics from different sources are
+   * combined or displayed.
+   *
+   * @return semanticMode
+   */
+  @jakarta.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_SEMANTIC_MODE)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public FormulaAndFunctionMetricSemanticMode getSemanticMode() {
+    return semanticMode;
+  }
+
+  public void setSemanticMode(FormulaAndFunctionMetricSemanticMode semanticMode) {
+    if (!semanticMode.isValid()) {
+      this.unparsed = true;
+    }
+    this.semanticMode = semanticMode;
+  }
+
   /**
    * A container for additional, undeclared properties. This is a holder for any undeclared
    * properties as specified with the 'additionalProperties' keyword in the OAS document.
@@ -242,14 +273,16 @@ public boolean equals(Object o) {
         && Objects.equals(this.dataSource, formulaAndFunctionMetricQueryDefinition.dataSource)
         && Objects.equals(this.name, formulaAndFunctionMetricQueryDefinition.name)
         && Objects.equals(this.query, formulaAndFunctionMetricQueryDefinition.query)
+        && Objects.equals(this.semanticMode, formulaAndFunctionMetricQueryDefinition.semanticMode)
         && Objects.equals(
             this.additionalProperties,
             formulaAndFunctionMetricQueryDefinition.additionalProperties);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(aggregator, crossOrgUuids, dataSource, name, query, additionalProperties);
+    return Objects.hash(
+        aggregator, crossOrgUuids, dataSource, name, query, semanticMode, additionalProperties);
   }
 
   @Override
@@ -261,6 +294,7 @@ public String toString() {
     sb.append("    dataSource: ").append(toIndentedString(dataSource)).append("\n");
     sb.append("    name: ").append(toIndentedString(name)).append("\n");
     sb.append("    query: ").append(toIndentedString(query)).append("\n");
+    sb.append("    semanticMode: ").append(toIndentedString(semanticMode)).append("\n");
     sb.append("    additionalProperties: ")
         .append(toIndentedString(additionalProperties))
         .append("\n");

src/main/java/com/datadog/api/client/v1/model/FormulaAndFunctionMetricSemanticMode.java

@@ -0,0 +1,65 @@
+/*
+ * 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.
+ */
+
+package com.datadog.api.client.v1.model;
+
+import com.datadog.api.client.ModelEnum;
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.ser.std.StdSerializer;
+import java.io.IOException;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * Semantic mode for metrics queries. This determines how metrics from different sources are
+ * combined or displayed.
+ */
+@JsonSerialize(
+    using =
+        FormulaAndFunctionMetricSemanticMode.FormulaAndFunctionMetricSemanticModeSerializer.class)
+public class FormulaAndFunctionMetricSemanticMode extends ModelEnum<String> {
+
+  private static final Set<String> allowedValues =
+      new HashSet<String>(Arrays.asList("combined", "native"));
+
+  public static final FormulaAndFunctionMetricSemanticMode COMBINED =
+      new FormulaAndFunctionMetricSemanticMode("combined");
+  public static final FormulaAndFunctionMetricSemanticMode NATIVE =
+      new FormulaAndFunctionMetricSemanticMode("native");
+
+  FormulaAndFunctionMetricSemanticMode(String value) {
+    super(value, allowedValues);
+  }
+
+  public static class FormulaAndFunctionMetricSemanticModeSerializer
+      extends StdSerializer<FormulaAndFunctionMetricSemanticMode> {
+    public FormulaAndFunctionMetricSemanticModeSerializer(
+        Class<FormulaAndFunctionMetricSemanticMode> t) {
+      super(t);
+    }
+
+    public FormulaAndFunctionMetricSemanticModeSerializer() {
+      this(null);
+    }
+
+    @Override
+    public void serialize(
+        FormulaAndFunctionMetricSemanticMode value, JsonGenerator jgen, SerializerProvider provider)
+        throws IOException, JsonProcessingException {
+      jgen.writeObject(value.value);
+    }
+  }
+
+  @JsonCreator
+  public static FormulaAndFunctionMetricSemanticMode fromValue(String value) {
+    return new FormulaAndFunctionMetricSemanticMode(value);
+  }
+}

src/test/resources/cassettes/features/v1/Create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_combined_semantic_mode.freeze

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

src/test/resources/cassettes/features/v1/Create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_combined_semantic_mode.json

@@ -0,0 +1,58 @@
+[
+  {
+    "httpRequest": {
+      "body": {
+        "type": "JSON",
+        "json": "{\"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": {},
+      "method": "POST",
+      "path": "/api/v1/dashboard",
+      "keepAlive": false,
+      "secure": true
+    },
+    "httpResponse": {
+      "body": "{\"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\":\"frog@datadoghq.com\",\"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"
+        ]
+      },
+      "statusCode": 200,
+      "reasonPhrase": "OK"
+    },
+    "times": {
+      "remainingTimes": 1
+    },
+    "timeToLive": {
+      "unlimited": true
+    },
+    "id": "12799a14-8e00-3af0-63c6-68a7afe8dc6f"
+  },
+  {
+    "httpRequest": {
+      "headers": {},
+      "method": "DELETE",
+      "path": "/api/v1/dashboard/bpt-wdw-b9x",
+      "keepAlive": false,
+      "secure": true
+    },
+    "httpResponse": {
+      "body": "{\"deleted_dashboard_id\":\"bpt-wdw-b9x\"}",
+      "headers": {
+        "Content-Type": [
+          "application/json"
+        ]
+      },
+      "statusCode": 200,
+      "reasonPhrase": "OK"
+    },
+    "times": {
+      "remainingTimes": 1
+    },
+    "timeToLive": {
+      "unlimited": true
+    },
+    "id": "9b44312f-fbef-89fa-47c2-93c7e4a76bde"
+  }
+]

src/test/resources/cassettes/features/v1/Create_a_new_dashboard_with_a_timeseries_widget_using_formulas_and_functions_metrics_query_with_native_semantic_mode.freeze

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