Skip to content

Commit 4a5c7fa

Browse files
api-clients-generation-pipeline[bot]ci.datadog-api-spec
api-clients-generation-pipeline[bot]
and
ci.datadog-api-spec
authored
Dashboards - Add semantic_mode support to FormulaAndFunctionMetricQueryDefinition (#3294)
Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>
1 parent d2690ff commit 4a5c7fa

10 files changed

+400
-2
lines changed

‎.generator/schemas/v1/openapi.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2952,11 +2952,24 @@ components:
29522952
description: Metrics query definition.
29532953
example: avg:system.cpu.user{*}
29542954
type: string
2955+
semantic_mode:
2956+
$ref: '#/components/schemas/FormulaAndFunctionMetricSemanticMode'
29552957
required:
29562958
- data_source
29572959
- query
29582960
- name
29592961
type: object
2962+
FormulaAndFunctionMetricSemanticMode:
2963+
description: Semantic mode for metrics queries. This determines how metrics
2964+
from different sources are combined or displayed.
2965+
enum:
2966+
- combined
2967+
- native
2968+
example: combined
2969+
type: string
2970+
x-enum-varnames:
2971+
- COMBINED
2972+
- NATIVE
29602973
FormulaAndFunctionProcessQueryDataSource:
29612974
description: Data sources that rely on the process backend.
29622975
enum:

‎examples/v1/dashboards/CreateDashboard_3685886950.java‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// Create a new dashboard with a timeseries widget using formulas and functions metrics query with
2+
// native semantic_mode
3+
4+
import com.datadog.api.client.ApiClient;
5+
import com.datadog.api.client.ApiException;
6+
import com.datadog.api.client.v1.api.DashboardsApi;
7+
import com.datadog.api.client.v1.model.Dashboard;
8+
import com.datadog.api.client.v1.model.DashboardLayoutType;
9+
import com.datadog.api.client.v1.model.FormulaAndFunctionMetricDataSource;
10+
import com.datadog.api.client.v1.model.FormulaAndFunctionMetricQueryDefinition;
11+
import com.datadog.api.client.v1.model.FormulaAndFunctionMetricSemanticMode;
12+
import com.datadog.api.client.v1.model.FormulaAndFunctionQueryDefinition;
13+
import com.datadog.api.client.v1.model.FormulaAndFunctionResponseFormat;
14+
import com.datadog.api.client.v1.model.TimeseriesWidgetDefinition;
15+
import com.datadog.api.client.v1.model.TimeseriesWidgetDefinitionType;
16+
import com.datadog.api.client.v1.model.TimeseriesWidgetRequest;
17+
import com.datadog.api.client.v1.model.Widget;
18+
import com.datadog.api.client.v1.model.WidgetDefinition;
19+
import com.datadog.api.client.v1.model.WidgetDisplayType;
20+
import com.datadog.api.client.v1.model.WidgetFormula;
21+
import java.util.Collections;
22+
23+
public class Example {
24+
public static void main(String[] args) {
25+
ApiClient defaultClient = ApiClient.getDefaultApiClient();
26+
DashboardsApi apiInstance = new DashboardsApi(defaultClient);
27+
28+
Dashboard body =
29+
new Dashboard()
30+
.layoutType(DashboardLayoutType.ORDERED)
31+
.title("Example-Dashboard with native semantic_mode")
32+
.widgets(
33+
Collections.singletonList(
34+
new Widget()
35+
.definition(
36+
new WidgetDefinition(
37+
new TimeseriesWidgetDefinition()
38+
.type(TimeseriesWidgetDefinitionType.TIMESERIES)
39+
.requests(
40+
Collections.singletonList(
41+
new TimeseriesWidgetRequest()
42+
.queries(
43+
Collections.singletonList(
44+
new FormulaAndFunctionQueryDefinition(
45+
new FormulaAndFunctionMetricQueryDefinition()
46+
.dataSource(
47+
FormulaAndFunctionMetricDataSource
48+
.METRICS)
49+
.name("query1")
50+
.query("avg:system.cpu.user{*}")
51+
.semanticMode(
52+
FormulaAndFunctionMetricSemanticMode
53+
.NATIVE))))
54+
.responseFormat(
55+
FormulaAndFunctionResponseFormat.TIMESERIES)
56+
.formulas(
57+
Collections.singletonList(
58+
new WidgetFormula().formula("query1")))
59+
.displayType(WidgetDisplayType.LINE)))))));
60+
61+
try {
62+
Dashboard result = apiInstance.createDashboard(body);
63+
System.out.println(result);
64+
} catch (ApiException e) {
65+
System.err.println("Exception when calling DashboardsApi#createDashboard");
66+
System.err.println("Status code: " + e.getCode());
67+
System.err.println("Reason: " + e.getResponseBody());
68+
System.err.println("Response headers: " + e.getResponseHeaders());
69+
e.printStackTrace();
70+
}
71+
}
72+
}

‎examples/v1/dashboards/CreateDashboard_865807520.java‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// Create a new dashboard with a timeseries widget using formulas and functions metrics query with
2+
// combined semantic_mode
3+
4+
import com.datadog.api.client.ApiClient;
5+
import com.datadog.api.client.ApiException;
6+
import com.datadog.api.client.v1.api.DashboardsApi;
7+
import com.datadog.api.client.v1.model.Dashboard;
8+
import com.datadog.api.client.v1.model.DashboardLayoutType;
9+
import com.datadog.api.client.v1.model.FormulaAndFunctionMetricDataSource;
10+
import com.datadog.api.client.v1.model.FormulaAndFunctionMetricQueryDefinition;
11+
import com.datadog.api.client.v1.model.FormulaAndFunctionMetricSemanticMode;
12+
import com.datadog.api.client.v1.model.FormulaAndFunctionQueryDefinition;
13+
import com.datadog.api.client.v1.model.FormulaAndFunctionResponseFormat;
14+
import com.datadog.api.client.v1.model.TimeseriesWidgetDefinition;
15+
import com.datadog.api.client.v1.model.TimeseriesWidgetDefinitionType;
16+
import com.datadog.api.client.v1.model.TimeseriesWidgetRequest;
17+
import com.datadog.api.client.v1.model.Widget;
18+
import com.datadog.api.client.v1.model.WidgetDefinition;
19+
import com.datadog.api.client.v1.model.WidgetDisplayType;
20+
import com.datadog.api.client.v1.model.WidgetFormula;
21+
import java.util.Collections;
22+
23+
public class Example {
24+
public static void main(String[] args) {
25+
ApiClient defaultClient = ApiClient.getDefaultApiClient();
26+
DashboardsApi apiInstance = new DashboardsApi(defaultClient);
27+
28+
Dashboard body =
29+
new Dashboard()
30+
.layoutType(DashboardLayoutType.ORDERED)
31+
.title("Example-Dashboard with combined semantic_mode")
32+
.widgets(
33+
Collections.singletonList(
34+
new Widget()
35+
.definition(
36+
new WidgetDefinition(
37+
new TimeseriesWidgetDefinition()
38+
.type(TimeseriesWidgetDefinitionType.TIMESERIES)
39+
.requests(
40+
Collections.singletonList(
41+
new TimeseriesWidgetRequest()
42+
.queries(
43+
Collections.singletonList(
44+
new FormulaAndFunctionQueryDefinition(
45+
new FormulaAndFunctionMetricQueryDefinition()
46+
.dataSource(
47+
FormulaAndFunctionMetricDataSource
48+
.METRICS)
49+
.name("query1")
50+
.query("avg:system.cpu.user{*}")
51+
.semanticMode(
52+
FormulaAndFunctionMetricSemanticMode
53+
.COMBINED))))
54+
.responseFormat(
55+
FormulaAndFunctionResponseFormat.TIMESERIES)
56+
.formulas(
57+
Collections.singletonList(
58+
new WidgetFormula().formula("query1")))
59+
.displayType(WidgetDisplayType.LINE)))))));
60+
61+
try {
62+
Dashboard result = apiInstance.createDashboard(body);
63+
System.out.println(result);
64+
} catch (ApiException e) {
65+
System.err.println("Exception when calling DashboardsApi#createDashboard");
66+
System.err.println("Status code: " + e.getCode());
67+
System.err.println("Reason: " + e.getResponseBody());
68+
System.err.println("Response headers: " + e.getResponseHeaders());
69+
e.printStackTrace();
70+
}
71+
}
72+
}

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

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@
2525
FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_CROSS_ORG_UUIDS,
2626
FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_DATA_SOURCE,
2727
FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_NAME,
28-
FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_QUERY
28+
FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_QUERY,
29+
FormulaAndFunctionMetricQueryDefinition.JSON_PROPERTY_SEMANTIC_MODE
2930
})
3031
@jakarta.annotation.Generated(
3132
value = "https://github.com/DataDog/datadog-api-client-java/blob/master/.generator")
@@ -46,6 +47,9 @@ public class FormulaAndFunctionMetricQueryDefinition {
4647
public static final String JSON_PROPERTY_QUERY = "query";
4748
private String query;
4849

50+
public static final String JSON_PROPERTY_SEMANTIC_MODE = "semantic_mode";
51+
private FormulaAndFunctionMetricSemanticMode semanticMode;
52+
4953
public FormulaAndFunctionMetricQueryDefinition() {}
5054

5155
@JsonCreator
@@ -180,6 +184,33 @@ public void setQuery(String query) {
180184
this.query = query;
181185
}
182186

187+
public FormulaAndFunctionMetricQueryDefinition semanticMode(
188+
FormulaAndFunctionMetricSemanticMode semanticMode) {
189+
this.semanticMode = semanticMode;
190+
this.unparsed |= !semanticMode.isValid();
191+
return this;
192+
}
193+
194+
/**
195+
* Semantic mode for metrics queries. This determines how metrics from different sources are
196+
* combined or displayed.
197+
*
198+
* @return semanticMode
199+
*/
200+
@jakarta.annotation.Nullable
201+
@JsonProperty(JSON_PROPERTY_SEMANTIC_MODE)
202+
@JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
203+
public FormulaAndFunctionMetricSemanticMode getSemanticMode() {
204+
return semanticMode;
205+
}
206+
207+
public void setSemanticMode(FormulaAndFunctionMetricSemanticMode semanticMode) {
208+
if (!semanticMode.isValid()) {
209+
this.unparsed = true;
210+
}
211+
this.semanticMode = semanticMode;
212+
}
213+
183214
/**
184215
* A container for additional, undeclared properties. This is a holder for any undeclared
185216
* properties as specified with the 'additionalProperties' keyword in the OAS document.
@@ -242,14 +273,16 @@ public boolean equals(Object o) {
242273
&& Objects.equals(this.dataSource, formulaAndFunctionMetricQueryDefinition.dataSource)
243274
&& Objects.equals(this.name, formulaAndFunctionMetricQueryDefinition.name)
244275
&& Objects.equals(this.query, formulaAndFunctionMetricQueryDefinition.query)
276+
&& Objects.equals(this.semanticMode, formulaAndFunctionMetricQueryDefinition.semanticMode)
245277
&& Objects.equals(
246278
this.additionalProperties,
247279
formulaAndFunctionMetricQueryDefinition.additionalProperties);
248280
}
249281

250282
@Override
251283
public int hashCode() {
252-
return Objects.hash(aggregator, crossOrgUuids, dataSource, name, query, additionalProperties);
284+
return Objects.hash(
285+
aggregator, crossOrgUuids, dataSource, name, query, semanticMode, additionalProperties);
253286
}
254287

255288
@Override
@@ -261,6 +294,7 @@ public String toString() {
261294
sb.append(" dataSource: ").append(toIndentedString(dataSource)).append("\n");
262295
sb.append(" name: ").append(toIndentedString(name)).append("\n");
263296
sb.append(" query: ").append(toIndentedString(query)).append("\n");
297+
sb.append(" semanticMode: ").append(toIndentedString(semanticMode)).append("\n");
264298
sb.append(" additionalProperties: ")
265299
.append(toIndentedString(additionalProperties))
266300
.append("\n");

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

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
/*
2+
* Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
3+
* This product includes software developed at Datadog (https://www.datadoghq.com/).
4+
* Copyright 2019-Present Datadog, Inc.
5+
*/
6+
7+
package com.datadog.api.client.v1.model;
8+
9+
import com.datadog.api.client.ModelEnum;
10+
import com.fasterxml.jackson.annotation.JsonCreator;
11+
import com.fasterxml.jackson.core.JsonGenerator;
12+
import com.fasterxml.jackson.core.JsonProcessingException;
13+
import com.fasterxml.jackson.databind.SerializerProvider;
14+
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
15+
import com.fasterxml.jackson.databind.ser.std.StdSerializer;
16+
import java.io.IOException;
17+
import java.util.Arrays;
18+
import java.util.HashSet;
19+
import java.util.Set;
20+
21+
/**
22+
* Semantic mode for metrics queries. This determines how metrics from different sources are
23+
* combined or displayed.
24+
*/
25+
@JsonSerialize(
26+
using =
27+
FormulaAndFunctionMetricSemanticMode.FormulaAndFunctionMetricSemanticModeSerializer.class)
28+
public class FormulaAndFunctionMetricSemanticMode extends ModelEnum<String> {
29+
30+
private static final Set<String> allowedValues =
31+
new HashSet<String>(Arrays.asList("combined", "native"));
32+
33+
public static final FormulaAndFunctionMetricSemanticMode COMBINED =
34+
new FormulaAndFunctionMetricSemanticMode("combined");
35+
public static final FormulaAndFunctionMetricSemanticMode NATIVE =
36+
new FormulaAndFunctionMetricSemanticMode("native");
37+
38+
FormulaAndFunctionMetricSemanticMode(String value) {
39+
super(value, allowedValues);
40+
}
41+
42+
public static class FormulaAndFunctionMetricSemanticModeSerializer
43+
extends StdSerializer<FormulaAndFunctionMetricSemanticMode> {
44+
public FormulaAndFunctionMetricSemanticModeSerializer(
45+
Class<FormulaAndFunctionMetricSemanticMode> t) {
46+
super(t);
47+
}
48+
49+
public FormulaAndFunctionMetricSemanticModeSerializer() {
50+
this(null);
51+
}
52+
53+
@Override
54+
public void serialize(
55+
FormulaAndFunctionMetricSemanticMode value, JsonGenerator jgen, SerializerProvider provider)
56+
throws IOException, JsonProcessingException {
57+
jgen.writeObject(value.value);
58+
}
59+
}
60+
61+
@JsonCreator
62+
public static FormulaAndFunctionMetricSemanticMode fromValue(String value) {
63+
return new FormulaAndFunctionMetricSemanticMode(value);
64+
}
65+
}

‎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‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
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‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
[
2+
{
3+
"httpRequest": {
4+
"body": {
5+
"type": "JSON",
6+
"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\"}}]}"
7+
},
8+
"headers": {},
9+
"method": "POST",
10+
"path": "/api/v1/dashboard",
11+
"keepAlive": false,
12+
"secure": true
13+
},
14+
"httpResponse": {
15+
"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\":[]}",
16+
"headers": {
17+
"Content-Type": [
18+
"application/json"
19+
]
20+
},
21+
"statusCode": 200,
22+
"reasonPhrase": "OK"
23+
},
24+
"times": {
25+
"remainingTimes": 1
26+
},
27+
"timeToLive": {
28+
"unlimited": true
29+
},
30+
"id": "12799a14-8e00-3af0-63c6-68a7afe8dc6f"
31+
},
32+
{
33+
"httpRequest": {
34+
"headers": {},
35+
"method": "DELETE",
36+
"path": "/api/v1/dashboard/bpt-wdw-b9x",
37+
"keepAlive": false,
38+
"secure": true
39+
},
40+
"httpResponse": {
41+
"body": "{\"deleted_dashboard_id\":\"bpt-wdw-b9x\"}",
42+
"headers": {
43+
"Content-Type": [
44+
"application/json"
45+
]
46+
},
47+
"statusCode": 200,
48+
"reasonPhrase": "OK"
49+
},
50+
"times": {
51+
"remainingTimes": 1
52+
},
53+
"timeToLive": {
54+
"unlimited": true
55+
},
56+
"id": "9b44312f-fbef-89fa-47c2-93c7e4a76bde"
57+
}
58+
]

‎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‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
2025-12-08T18:32:38.191Z

0 commit comments

Comments
 (0)