Improve topology map widget documentation

.generator/schemas/v1/openapi.yaml

@@ -21724,6 +21724,46 @@ components:
       type: object
     TopologyMapWidgetDefinition:
       description: This widget displays a topology of nodes and edges for different data sources. It replaces the service map widget.
+      oneOf:
+        - $ref: "#/components/schemas/TopologyMapWidgetDefinitionDataStreams"
+        - $ref: "#/components/schemas/TopologyMapWidgetDefinitionServiceMap"
+    TopologyMapWidgetDefinitionDataStreams:
+      additionalProperties: false
+      description: Topology map widget backed by the data streams data source.
+      properties:
+        custom_links:
+          description: List of custom links.
+          items:
+            $ref: "#/components/schemas/WidgetCustomLink"
+          type: array
+        description:
+          description: The description of the widget.
+          type: string
+        requests:
+          description: One Topology request.
+          items:
+            $ref: "#/components/schemas/TopologyRequestDataStreams"
+          minItems: 1
+          type: array
+        time:
+          $ref: "#/components/schemas/WidgetTime"
+        title:
+          description: Title of your widget.
+          type: string
+        title_align:
+          $ref: "#/components/schemas/WidgetTextAlign"
+        title_size:
+          description: Size of the title.
+          type: string
+        type:
+          $ref: "#/components/schemas/TopologyMapWidgetDefinitionType"
+      required:
+        - type
+        - requests
+      type: object
+    TopologyMapWidgetDefinitionServiceMap:
+      additionalProperties: false
+      description: Topology map widget backed by the service map data source.
       properties:
         custom_links:
           description: List of custom links.
@@ -21734,11 +21774,13 @@ components:
           description: The description of the widget.
           type: string
         requests:
-          description: One or more Topology requests.
+          description: One Topology request.
           items:
-            $ref: "#/components/schemas/TopologyRequest"
+            $ref: "#/components/schemas/TopologyRequestServiceMap"
           minItems: 1
           type: array
+        time:
+          $ref: "#/components/schemas/WidgetTime"
         title:
           description: Title of your widget.
           type: string
@@ -21762,38 +21804,89 @@ components:
       type: string
       x-enum-varnames:
         - TOPOLOGY_MAP
-    TopologyQuery:
-      description: Query to service-based topology data sources like the service map or data streams.
+    TopologyQueryDataStreams:
+      additionalProperties: false
+      description: Query to the data streams topology data source.
       properties:
         data_source:
-          $ref: "#/components/schemas/TopologyQueryDataSource"
+          $ref: "#/components/schemas/TopologyQueryDataStreamsDataSource"
         filters:
           description: Your environment and primary tag (or * if enabled for your account).
           example: ["env:prod", "az:us-east"]
           items:
-            description: Environment or primary tag, generally in a key:value format
+            description: Environment or primary tag, generally in a key:value format.
             type: string
           minItems: 1
           type: array
+        query_string:
+          description: A search string for filtering services. When set, this replaces the `service` field.
+          example: "service:myservice"
+          type: string
         service:
-          description: Name of the service
-          example: myService
+          description: (deprecated) Name of the service. Leave this empty and use query_string instead.
+          example: myservice
           type: string
+      required:
+        - data_source
+        - filters
+        - service
       type: object
-    TopologyQueryDataSource:
-      description: Name of the data source
+    TopologyQueryDataStreamsDataSource:
+      description: Name of the data source.
       enum:
         - data_streams
-        - service_map
+      example: data_streams
       type: string
       x-enum-varnames:
         - DATA_STREAMS
+    TopologyQueryServiceMap:
+      additionalProperties: false
+      description: Query to the service map topology data source.
+      properties:
+        data_source:
+          $ref: "#/components/schemas/TopologyQueryServiceMapDataSource"
+        filters:
+          description: Your environment and primary tag (or * if enabled for your account).
+          example: ["env:prod", "az:us-east"]
+          items:
+            description: Environment or primary tag, generally in a key:value format
+            type: string
+          minItems: 1
+          type: array
+        query_string:
+          description: A search string for filtering services. When set, this replaces the `service` field.
+          example: "service:myservice"
+          type: string
+        service:
+          description: (deprecated) Name of the service. Leave this empty and use query_string instead.
+          example: myservice
+          type: string
+      required:
+        - data_source
+        - filters
+        - service
+      type: object
+    TopologyQueryServiceMapDataSource:
+      description: Name of the data source.
+      enum:
+        - service_map
+      example: service_map
+      type: string
+      x-enum-varnames:
         - SERVICE_MAP
-    TopologyRequest:
-      description: Request that will return nodes and edges to be used by topology map.
+    TopologyRequestDataStreams:
+      description: Request that returns nodes and edges from the data streams data source.
+      properties:
+        query:
+          $ref: "#/components/schemas/TopologyQueryDataStreams"
+        request_type:
+          $ref: "#/components/schemas/TopologyRequestType"
+      type: object
+    TopologyRequestServiceMap:
+      description: Request that returns nodes and edges from the service map data source.
       properties:
         query:
-          $ref: "#/components/schemas/TopologyQuery"
+          $ref: "#/components/schemas/TopologyQueryServiceMap"
         request_type:
           $ref: "#/components/schemas/TopologyRequestType"
       type: object

cassettes/features/v1/dashboards/Create-a-new-dashboard-with-topology-map-data-streams-widget.frozen

@@ -0,0 +1 @@
+2026-03-20T18:16:51.929Z

examples/v1/dashboards/CreateDashboard_2652180930.rb

@@ -14,16 +14,16 @@
         width: 47,
         height: 15,
       }),
-      definition: DatadogAPIClient::V1::TopologyMapWidgetDefinition.new({
+      definition: DatadogAPIClient::V1::TopologyMapWidgetDefinitionServiceMap.new({
         title: "",
         title_size: "16",
         title_align: DatadogAPIClient::V1::WidgetTextAlign::LEFT,
         type: DatadogAPIClient::V1::TopologyMapWidgetDefinitionType::TOPOLOGY_MAP,
         requests: [
-          DatadogAPIClient::V1::TopologyRequest.new({
+          DatadogAPIClient::V1::TopologyRequestServiceMap.new({
             request_type: DatadogAPIClient::V1::TopologyRequestType::TOPOLOGY,
-            query: DatadogAPIClient::V1::TopologyQuery.new({
-              data_source: DatadogAPIClient::V1::TopologyQueryDataSource::SERVICE_MAP,
+            query: DatadogAPIClient::V1::TopologyQueryServiceMap.new({
+              data_source: DatadogAPIClient::V1::TopologyQueryServiceMapDataSource::SERVICE_MAP,
               service: "",
               filters: [
                 "env:none",

examples/v1/dashboards/CreateDashboard_2815497946.rb

@@ -0,0 +1,42 @@
+# Create a new dashboard with topology_map data_streams widget
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V1::DashboardsAPI.new
+
+body = DatadogAPIClient::V1::Dashboard.new({
+  title: "Example-Dashboard",
+  description: "",
+  widgets: [
+    DatadogAPIClient::V1::Widget.new({
+      layout: DatadogAPIClient::V1::WidgetLayout.new({
+        x: 0,
+        y: 0,
+        width: 47,
+        height: 15,
+      }),
+      definition: DatadogAPIClient::V1::TopologyMapWidgetDefinitionDataStreams.new({
+        title: "",
+        title_size: "16",
+        title_align: DatadogAPIClient::V1::WidgetTextAlign::LEFT,
+        type: DatadogAPIClient::V1::TopologyMapWidgetDefinitionType::TOPOLOGY_MAP,
+        requests: [
+          DatadogAPIClient::V1::TopologyRequestDataStreams.new({
+            request_type: DatadogAPIClient::V1::TopologyRequestType::TOPOLOGY,
+            query: DatadogAPIClient::V1::TopologyQueryDataStreams.new({
+              data_source: DatadogAPIClient::V1::TopologyQueryDataStreamsDataSource::DATA_STREAMS,
+              service: "",
+              filters: [
+                "env:prod",
+              ],
+              query_string: "service:myservice",
+            }),
+          }),
+        ],
+      }),
+    }),
+  ],
+  template_variables: [],
+  layout_type: DatadogAPIClient::V1::DashboardLayoutType::FREE,
+  notify_list: [],
+})
+p api_instance.create_dashboard(body)

features/v1/dashboards.feature

@@ -1128,6 +1128,19 @@ Feature: Dashboards
     And the response "widgets[0].definition.requests[0].sort.order_by[0].type" is equal to "formula"
     And the response "widgets[0].definition.requests[0].sort.order_by[0].index" is equal to 0
 
+  @team:DataDog/dashboards-backend
+  Scenario: Create a new dashboard with topology_map data_streams widget
+    Given new "CreateDashboard" request
+    And body from file "dashboards_json_payload/topology_map_widget_data_streams.json"
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "widgets[0].definition.type" is equal to "topology_map"
+    And the response "widgets[0].definition.requests[0].request_type" is equal to "topology"
+    And the response "widgets[0].definition.requests[0].query.data_source" is equal to "data_streams"
+    And the response "widgets[0].definition.requests[0].query.service" is equal to ""
+    And the response "widgets[0].definition.requests[0].query.filters" is equal to ["env:prod"]
+    And the response "widgets[0].definition.requests[0].query.query_string" is equal to "service:myservice"
+
   @team:DataDog/dashboards-backend
   Scenario: Create a new dashboard with topology_map widget
     Given new "CreateDashboard" request

features/v1/dashboards_json_payload/topology_map_widget_data_streams.json

@@ -0,0 +1,34 @@
+{
+  "title": "{{ unique }}",
+  "description": "",
+  "widgets": [
+    {
+      "layout": {
+        "x": 0,
+        "y": 0,
+        "width": 47,
+        "height": 15
+      },
+      "definition": {
+        "title": "",
+        "title_size": "16",
+        "title_align": "left",
+        "type": "topology_map",
+        "requests": [
+          {
+            "request_type": "topology",
+            "query": {
+              "data_source": "data_streams",
+              "service": "",
+              "filters": ["env:prod"],
+              "query_string": "service:myservice"
+            }
+          }
+        ]
+      }
+    }
+  ],
+  "template_variables": [],
+  "layout_type": "free",
+  "notify_list": []
+}

lib/datadog_api_client/inflector.rb

@@ -981,10 +981,15 @@ def overrides
           "v1.toplist_widget_stacked_type" => "ToplistWidgetStackedType",
           "v1.toplist_widget_style" => "ToplistWidgetStyle",
           "v1.topology_map_widget_definition" => "TopologyMapWidgetDefinition",
+          "v1.topology_map_widget_definition_data_streams" => "TopologyMapWidgetDefinitionDataStreams",
+          "v1.topology_map_widget_definition_service_map" => "TopologyMapWidgetDefinitionServiceMap",
           "v1.topology_map_widget_definition_type" => "TopologyMapWidgetDefinitionType",
-          "v1.topology_query" => "TopologyQuery",
-          "v1.topology_query_data_source" => "TopologyQueryDataSource",
-          "v1.topology_request" => "TopologyRequest",
+          "v1.topology_query_data_streams" => "TopologyQueryDataStreams",
+          "v1.topology_query_data_streams_data_source" => "TopologyQueryDataStreamsDataSource",
+          "v1.topology_query_service_map" => "TopologyQueryServiceMap",
+          "v1.topology_query_service_map_data_source" => "TopologyQueryServiceMapDataSource",
+          "v1.topology_request_data_streams" => "TopologyRequestDataStreams",
+          "v1.topology_request_service_map" => "TopologyRequestServiceMap",
           "v1.topology_request_type" => "TopologyRequestType",
           "v1.tree_map_color_by" => "TreeMapColorBy",
           "v1.tree_map_group_by" => "TreeMapGroupBy",