Document OAuth scope requirements for public DDSQL endpoints

.generator/schemas/v2/openapi.yaml

@@ -145929,9 +145929,18 @@ paths:
               schema:
                 $ref: "#/components/schemas/JSONAPIErrorResponse"
           description: Internal Server Error
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - timeseries_query
       summary: Execute a tabular DDSQL query
       tags:
         - DDSQL
+      "x-permission":
+        operator: OR
+        permissions:
+          - timeseries_query
   /api/v2/ddsql/query/tabular/fetch:
     post:
       description: |-
@@ -146037,9 +146046,18 @@ paths:
               schema:
                 $ref: "#/components/schemas/JSONAPIErrorResponse"
           description: Internal Server Error
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - timeseries_query
       summary: Fetch the result of a DDSQL query
       tags:
         - DDSQL
+      "x-permission":
+        operator: OR
+        permissions:
+          - timeseries_query
   /api/v2/deletion/data/{product}:
     post:
       description: Creates a data deletion request by providing a query and a timeframe targeting the proper data.

examples/v2/ddsql/ExecuteDdsqlTabularQuery.java

@@ -0,0 +1,45 @@
+// Execute a tabular DDSQL query returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.DdsqlApi;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryRequest;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryRequestAttributes;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryRequestData;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryRequestType;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryResponse;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryTimeWindow;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    DdsqlApi apiInstance = new DdsqlApi(defaultClient);
+
+    DdsqlTabularQueryRequest body =
+        new DdsqlTabularQueryRequest()
+            .data(
+                new DdsqlTabularQueryRequestData()
+                    .attributes(
+                        new DdsqlTabularQueryRequestAttributes()
+                            .query(
+                                "SELECT cloud_provider, count(*) FROM dd.hosts group by"
+                                    + " cloud_provider")
+                            .rowLimit(1000L)
+                            .time(
+                                new DdsqlTabularQueryTimeWindow()
+                                    .fromTimestamp(1736942400000L)
+                                    .toTimestamp(1736946000000L)))
+                    .type(DdsqlTabularQueryRequestType.DDSQL_QUERY_REQUEST));
+
+    try {
+      DdsqlTabularQueryResponse result = apiInstance.executeDdsqlTabularQuery(body);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DdsqlApi#executeDdsqlTabularQuery");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

examples/v2/ddsql/FetchDdsqlTabularQuery.java

@@ -0,0 +1,37 @@
+// Fetch the result of a DDSQL query returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.DdsqlApi;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryFetchRequest;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryFetchRequestAttributes;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryFetchRequestData;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryFetchRequestType;
+import com.datadog.api.client.v2.model.DdsqlTabularQueryResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    DdsqlApi apiInstance = new DdsqlApi(defaultClient);
+
+    DdsqlTabularQueryFetchRequest body =
+        new DdsqlTabularQueryFetchRequest()
+            .data(
+                new DdsqlTabularQueryFetchRequestData()
+                    .attributes(
+                        new DdsqlTabularQueryFetchRequestAttributes()
+                            .queryId("eyJxdWVyeSI6ICJTRUxFQ1QgKiBGUk9NIGxvZ3MifQ=="))
+                    .type(DdsqlTabularQueryFetchRequestType.DDSQL_QUERY_FETCH_REQUEST));
+
+    try {
+      DdsqlTabularQueryResponse result = apiInstance.fetchDdsqlTabularQuery(body);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DdsqlApi#fetchDdsqlTabularQuery");
+      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/v2/api/DdsqlApi.java

@@ -117,7 +117,7 @@ public ApiResponse<DdsqlTabularQueryResponse> executeDdsqlTabularQueryWithHttpIn
             localVarHeaderParams,
             new HashMap<String, String>(),
             new String[] {"application/json"},
-            new String[] {"apiKeyAuth", "appKeyAuth"});
+            new String[] {"apiKeyAuth", "appKeyAuth", "AuthZ"});
     return apiClient.invokeAPI(
         "POST",
         builder,
@@ -164,7 +164,7 @@ public ApiResponse<DdsqlTabularQueryResponse> executeDdsqlTabularQueryWithHttpIn
               localVarHeaderParams,
               new HashMap<String, String>(),
               new String[] {"application/json"},
-              new String[] {"apiKeyAuth", "appKeyAuth"});
+              new String[] {"apiKeyAuth", "appKeyAuth", "AuthZ"});
     } catch (ApiException ex) {
       CompletableFuture<ApiResponse<DdsqlTabularQueryResponse>> result = new CompletableFuture<>();
       result.completeExceptionally(ex);
@@ -255,7 +255,7 @@ public ApiResponse<DdsqlTabularQueryResponse> fetchDdsqlTabularQueryWithHttpInfo
             localVarHeaderParams,
             new HashMap<String, String>(),
             new String[] {"application/json"},
-            new String[] {"apiKeyAuth", "appKeyAuth"});
+            new String[] {"apiKeyAuth", "appKeyAuth", "AuthZ"});
     return apiClient.invokeAPI(
         "POST",
         builder,
@@ -302,7 +302,7 @@ public ApiResponse<DdsqlTabularQueryResponse> fetchDdsqlTabularQueryWithHttpInfo
               localVarHeaderParams,
               new HashMap<String, String>(),
               new String[] {"application/json"},
-              new String[] {"apiKeyAuth", "appKeyAuth"});
+              new String[] {"apiKeyAuth", "appKeyAuth", "AuthZ"});
     } catch (ApiException ex) {
       CompletableFuture<ApiResponse<DdsqlTabularQueryResponse>> result = new CompletableFuture<>();
       result.completeExceptionally(ex);

src/test/resources/com/datadog/api/client/v2/api/ddsql.feature

@@ -0,0 +1,40 @@
+@endpoint(ddsql) @endpoint(ddsql-v2)
+Feature: DDSQL
+  Execute DDSQL queries against the Datadog data catalog and poll for their
+  results. Queries are dispatched asynchronously: the initial request may
+  return a `running` state with a `query_id`, and clients poll the fetch
+  endpoint until the response transitions to `completed` with a column-major
+  result set.
+
+  Background:
+    Given a valid "apiKeyAuth" key in the system
+    And a valid "appKeyAuth" key in the system
+    And an instance of "DDSQL" API
+
+  @generated @skip @team:DataDog/query-apis
+  Scenario: Execute a tabular DDSQL query returns "Bad Request" response
+    Given new "ExecuteDdsqlTabularQuery" request
+    And body with value {"data": {"attributes": {"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider", "row_limit": 1000, "time": {"from_timestamp": 1736942400000, "to_timestamp": 1736946000000}}, "type": "ddsql_query_request"}}
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @generated @skip @team:DataDog/query-apis
+  Scenario: Execute a tabular DDSQL query returns "OK" response
+    Given new "ExecuteDdsqlTabularQuery" request
+    And body with value {"data": {"attributes": {"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider", "row_limit": 1000, "time": {"from_timestamp": 1736942400000, "to_timestamp": 1736946000000}}, "type": "ddsql_query_request"}}
+    When the request is sent
+    Then the response status is 200 OK
+
+  @generated @skip @team:DataDog/query-apis
+  Scenario: Fetch the result of a DDSQL query returns "Bad Request" response
+    Given new "FetchDdsqlTabularQuery" request
+    And body with value {"data": {"attributes": {"query_id": "eyJxdWVyeSI6ICJTRUxFQ1QgKiBGUk9NIGxvZ3MifQ=="}, "type": "ddsql_query_fetch_request"}}
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @generated @skip @team:DataDog/query-apis
+  Scenario: Fetch the result of a DDSQL query returns "OK" response
+    Given new "FetchDdsqlTabularQuery" request
+    And body with value {"data": {"attributes": {"query_id": "eyJxdWVyeSI6ICJTRUxFQ1QgKiBGUk9NIGxvZ3MifQ=="}, "type": "ddsql_query_fetch_request"}}
+    When the request is sent
+    Then the response status is 200 OK

src/test/resources/com/datadog/api/client/v2/api/undo.json

@@ -2284,6 +2284,18 @@
       "type": "idempotent"
     }
   },
+  "ExecuteDdsqlTabularQuery": {
+    "tag": "DDSQL",
+    "undo": {
+      "type": "idempotent"
+    }
+  },
+  "FetchDdsqlTabularQuery": {
+    "tag": "DDSQL",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "CreateDataDeletionRequest": {
     "tag": "Data Deletion",
     "undo": {