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

@@ -0,0 +1,32 @@
+"""
+Execute a tabular DDSQL query returns "OK" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.ddsql_api import DDSQLApi
+from datadog_api_client.v2.model.ddsql_tabular_query_request import DdsqlTabularQueryRequest
+from datadog_api_client.v2.model.ddsql_tabular_query_request_attributes import DdsqlTabularQueryRequestAttributes
+from datadog_api_client.v2.model.ddsql_tabular_query_request_data import DdsqlTabularQueryRequestData
+from datadog_api_client.v2.model.ddsql_tabular_query_request_type import DdsqlTabularQueryRequestType
+from datadog_api_client.v2.model.ddsql_tabular_query_time_window import DdsqlTabularQueryTimeWindow
+
+body = DdsqlTabularQueryRequest(
+    data=DdsqlTabularQueryRequestData(
+        attributes=DdsqlTabularQueryRequestAttributes(
+            query="SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
+            row_limit=1000,
+            time=DdsqlTabularQueryTimeWindow(
+                from_timestamp=1736942400000,
+                to_timestamp=1736946000000,
+            ),
+        ),
+        type=DdsqlTabularQueryRequestType.DDSQL_QUERY_REQUEST,
+    ),
+)
+
+configuration = Configuration()
+with ApiClient(configuration) as api_client:
+    api_instance = DDSQLApi(api_client)
+    response = api_instance.execute_ddsql_tabular_query(body=body)
+
+    print(response)

examples/v2/ddsql/FetchDdsqlTabularQuery.py

@@ -0,0 +1,28 @@
+"""
+Fetch the result of a DDSQL query returns "OK" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.ddsql_api import DDSQLApi
+from datadog_api_client.v2.model.ddsql_tabular_query_fetch_request import DdsqlTabularQueryFetchRequest
+from datadog_api_client.v2.model.ddsql_tabular_query_fetch_request_attributes import (
+    DdsqlTabularQueryFetchRequestAttributes,
+)
+from datadog_api_client.v2.model.ddsql_tabular_query_fetch_request_data import DdsqlTabularQueryFetchRequestData
+from datadog_api_client.v2.model.ddsql_tabular_query_fetch_request_type import DdsqlTabularQueryFetchRequestType
+
+body = DdsqlTabularQueryFetchRequest(
+    data=DdsqlTabularQueryFetchRequestData(
+        attributes=DdsqlTabularQueryFetchRequestAttributes(
+            query_id="eyJxdWVyeSI6ICJTRUxFQ1QgKiBGUk9NIGxvZ3MifQ==",
+        ),
+        type=DdsqlTabularQueryFetchRequestType.DDSQL_QUERY_FETCH_REQUEST,
+    ),
+)
+
+configuration = Configuration()
+with ApiClient(configuration) as api_client:
+    api_instance = DDSQLApi(api_client)
+    response = api_instance.fetch_ddsql_tabular_query(body=body)
+
+    print(response)

src/datadog_api_client/v2/api/ddsql_api.py

@@ -28,7 +28,7 @@ def __init__(self, api_client=None):
         self._execute_ddsql_tabular_query_endpoint = _Endpoint(
             settings={
                 "response_type": (DdsqlTabularQueryResponse,),
-                "auth": ["apiKeyAuth", "appKeyAuth"],
+                "auth": ["apiKeyAuth", "appKeyAuth", "AuthZ"],
                 "endpoint_path": "/api/v2/ddsql/query/tabular",
                 "operation_id": "execute_ddsql_tabular_query",
                 "http_method": "POST",
@@ -48,7 +48,7 @@ def __init__(self, api_client=None):
         self._fetch_ddsql_tabular_query_endpoint = _Endpoint(
             settings={
                 "response_type": (DdsqlTabularQueryResponse,),
-                "auth": ["apiKeyAuth", "appKeyAuth"],
+                "auth": ["apiKeyAuth", "appKeyAuth", "AuthZ"],
                 "endpoint_path": "/api/v2/ddsql/query/tabular/fetch",
                 "operation_id": "fetch_ddsql_tabular_query",
                 "http_method": "POST",

tests/v2/features/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

tests/v2/features/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": {