feat: Add list saved queries tool for Semantic Layer (#426)

kiwamizamurai · DevonFulcher · web-flow · commit 70803e596e4d · 2025-11-03T15:21:46.000-06:00
### Summary This PR adds support for listing saved queries in the dbt Semantic Layer. Saved queries are pre-defined MetricFlow configurations that group related metrics, dimensions, and filters, making them discoverable and reusable through the MCP server. ### Why Because saved_queries is not implemented yet ## Related Issues Closes #264 ## Reference https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#list-saved-queries --------- Co-authored-by: Devon Fulcher <24593113+DevonFulcher@users.noreply.github.com>
diff --git a/.changes/unreleased/Enhancement or New Feature-20251101-072230.yaml b/.changes/unreleased/Enhancement or New Feature-20251101-072230.yaml
@@ -0,0 +1,3 @@
+kind: Enhancement or New Feature
+body: Add list_saved_queries tool to the Semantic Layer, enabling discovery of predefined MetricFlow queries via GraphQL API. This allows AI agents to list and search saved queries with their associated metrics, dimensions, and filters.
+time: 2025-11-01T07:22:30.000000+09:00
diff --git a/src/dbt_mcp/prompts/semantic_layer/list_saved_queries.md b/src/dbt_mcp/prompts/semantic_layer/list_saved_queries.md
@@ -0,0 +1,19 @@
+List all saved queries from the dbt Semantic Layer.
+
+Saved queries are pre-defined queries that have been saved in the Semantic Layer. 
+They contain specific metrics, group-by dimensions, and filters that are commonly used.
+This tool helps discover what predefined queries are available for quick execution.
+
+Use this tool when:
+- The user wants to see what pre-built queries are available
+- The user mentions "saved queries" or "predefined queries"
+- You need to find commonly used analytical queries
+
+Examples:
+- "What saved queries are available?"
+- "Show me the predefined reports"
+- "List all saved queries for revenue analysis"
+
+<parameters>
+search: Optional string used to filter saved queries by name, label, or description using partial matches
+</parameters>
diff --git a/src/dbt_mcp/semantic_layer/client.py b/src/dbt_mcp/semantic_layer/client.py
@@ -28,6 +28,7 @@
     QueryMetricsError,
     QueryMetricsResult,
     QueryMetricsSuccess,
+    SavedQueryToolResponse,
 )
 
 
@@ -103,6 +104,39 @@ async def list_metrics(self, search: str | None = None) -> list[MetricToolRespon
             for m in metrics_result["data"]["metricsPaginated"]["items"]
         ]
 
+    async def list_saved_queries(
+        self, search: str | None = None
+    ) -> list[SavedQueryToolResponse]:
+        """Fetch all saved queries from the Semantic Layer API."""
+        saved_queries_result = submit_request(
+            await self.config_provider.get_config(),
+            {
+                "query": GRAPHQL_QUERIES["saved_queries"],
+                "variables": {"search": search},
+            },
+        )
+        return [
+            SavedQueryToolResponse(
+                name=sq.get("name"),
+                label=sq.get("label"),
+                description=sq.get("description"),
+                metrics=[
+                    m.get("name") for m in sq.get("queryParams", {}).get("metrics", [])
+                ]
+                if sq.get("queryParams", {}).get("metrics")
+                else None,
+                group_by=[
+                    g.get("name") for g in sq.get("queryParams", {}).get("groupBy", [])
+                ]
+                if sq.get("queryParams", {}).get("groupBy")
+                else None,
+                where=sq.get("queryParams", {}).get("where", {}).get("whereSqlTemplate")
+                if sq.get("queryParams", {}).get("where")
+                else None,
+            )
+            for sq in saved_queries_result["data"]["savedQueriesPaginated"]["items"]
+        ]
+
     async def get_dimensions(
         self, metrics: list[str], search: str | None = None
     ) -> list[DimensionToolResponse]:
diff --git a/src/dbt_mcp/semantic_layer/gql/gql.py b/src/dbt_mcp/semantic_layer/gql/gql.py
@@ -38,6 +38,30 @@
       type
     }
   }
+}
+    """,
+    "saved_queries": """
+query GetSavedQueries($environmentId: BigInt!, $search: String) {
+  savedQueriesPaginated(environmentId: $environmentId, search: $search) {
+    items {
+      name
+      description
+      label
+      queryParams {
+        metrics {
+          name
+        }
+        groupBy {
+          name
+          grain
+          datePart
+        }
+        where {
+          whereSqlTemplate
+        }
+      }
+    }
+  }
 }
     """,
 }
diff --git a/src/dbt_mcp/semantic_layer/tools.py b/src/dbt_mcp/semantic_layer/tools.py
@@ -20,6 +20,7 @@
     MetricToolResponse,
     OrderByParam,
     QueryMetricsSuccess,
+    SavedQueryToolResponse,
 )
 from dbt_mcp.tools.annotations import create_tool_annotations
 from dbt_mcp.tools.definitions import ToolDefinition
@@ -41,6 +42,11 @@ def create_sl_tool_definitions(
     async def list_metrics(search: str | None = None) -> list[MetricToolResponse]:
         return await semantic_layer_fetcher.list_metrics(search=search)
 
+    async def list_saved_queries(
+        search: str | None = None,
+    ) -> list[SavedQueryToolResponse]:
+        return await semantic_layer_fetcher.list_saved_queries(search=search)
+
     async def get_dimensions(
         metrics: list[str], search: str | None = None
     ) -> list[DimensionToolResponse]:
@@ -102,6 +108,16 @@ async def get_metrics_compiled_sql(
                 idempotent_hint=True,
             ),
         ),
+        ToolDefinition(
+            description=get_prompt("semantic_layer/list_saved_queries"),
+            fn=list_saved_queries,
+            annotations=create_tool_annotations(
+                title="List Saved Queries",
+                read_only_hint=True,
+                destructive_hint=False,
+                idempotent_hint=True,
+            ),
+        ),
         ToolDefinition(
             description=get_prompt("semantic_layer/get_dimensions"),
             fn=get_dimensions,
diff --git a/src/dbt_mcp/semantic_layer/types.py b/src/dbt_mcp/semantic_layer/types.py
@@ -36,6 +36,16 @@ class EntityToolResponse:
     description: str | None = None
 
 
+@dataclass
+class SavedQueryToolResponse:
+    name: str
+    label: str | None = None
+    description: str | None = None
+    metrics: list[str] | None = None
+    group_by: list[str] | None = None
+    where: list[str] | None = None
+
+
 @dataclass
 class QueryMetricsSuccess:
     result: str
diff --git a/src/dbt_mcp/tools/policy.py b/src/dbt_mcp/tools/policy.py
@@ -57,6 +57,9 @@ class ToolPolicy:
     ToolName.LIST_METRICS.value: ToolPolicy(
         name=ToolName.LIST_METRICS.value, behavior=ToolBehavior.METADATA
     ),
+    ToolName.LIST_SAVED_QUERIES.value: ToolPolicy(
+        name=ToolName.LIST_SAVED_QUERIES.value, behavior=ToolBehavior.METADATA
+    ),
     ToolName.GET_DIMENSIONS.value: ToolPolicy(
         name=ToolName.GET_DIMENSIONS.value, behavior=ToolBehavior.METADATA
     ),
diff --git a/src/dbt_mcp/tools/tool_names.py b/src/dbt_mcp/tools/tool_names.py
@@ -21,6 +21,7 @@ class ToolName(Enum):
 
     # Semantic Layer tools
     LIST_METRICS = "list_metrics"
+    LIST_SAVED_QUERIES = "list_saved_queries"
     GET_DIMENSIONS = "get_dimensions"
     GET_ENTITIES = "get_entities"
     QUERY_METRICS = "query_metrics"
diff --git a/src/dbt_mcp/tools/toolsets.py b/src/dbt_mcp/tools/toolsets.py
@@ -28,6 +28,7 @@ class Toolset(Enum):
     },
     Toolset.SEMANTIC_LAYER: {
         ToolName.LIST_METRICS,
+        ToolName.LIST_SAVED_QUERIES,
         ToolName.GET_DIMENSIONS,
         ToolName.GET_ENTITIES,
         ToolName.QUERY_METRICS,
diff --git a/tests/unit/semantic_layer/__init__.py b/tests/unit/semantic_layer/__init__.py
diff --git a/tests/unit/semantic_layer/test_saved_queries.py b/tests/unit/semantic_layer/test_saved_queries.py
@@ -0,0 +1,166 @@
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+from dbt_mcp.semantic_layer.client import SemanticLayerFetcher
+from dbt_mcp.semantic_layer.types import SavedQueryToolResponse
+
+
+class TestSavedQueries:
+    @pytest.fixture
+    def mock_config_provider(self):
+        """Create a mock config provider."""
+        config_provider = AsyncMock()
+        config_provider.get_config.return_value = MagicMock(
+            prod_environment_id=123,
+            token="test-token",
+            host="test-host",
+            url="https://test-host/api/graphql",
+        )
+        return config_provider
+
+    @pytest.fixture
+    def mock_client_provider(self):
+        """Create a mock client provider."""
+        client_provider = AsyncMock()
+        return client_provider
+
+    @pytest.fixture
+    def fetcher(self, mock_config_provider, mock_client_provider):
+        """Create a SemanticLayerFetcher instance with mocked dependencies."""
+        return SemanticLayerFetcher(
+            config_provider=mock_config_provider,
+            client_provider=mock_client_provider,
+        )
+
+    @pytest.mark.asyncio
+    @patch("dbt_mcp.semantic_layer.client.submit_request")
+    async def test_list_saved_queries_no_filter(
+        self, mock_submit_request, fetcher, mock_config_provider
+    ):
+        """Test listing saved queries without a search filter."""
+        # Mock GraphQL response
+        mock_submit_request.return_value = {
+            "data": {
+                "savedQueriesPaginated": {
+                    "items": [
+                        {
+                            "name": "daily_revenue",
+                            "label": "Daily Revenue Report",
+                            "description": "Daily revenue metrics by product",
+                            "queryParams": {
+                                "metrics": [{"name": "revenue"}, {"name": "profit"}],
+                                "groupBy": [{"name": "product_name"}, {"name": "date"}],
+                                "where": {"whereSqlTemplate": "date >= '2024-01-01'"},
+                            },
+                        },
+                        {
+                            "name": "monthly_users",
+                            "label": "Monthly Active Users",
+                            "description": "Monthly active user counts",
+                            "queryParams": {
+                                "metrics": [{"name": "user_count"}],
+                                "groupBy": [{"name": "month"}],
+                                "where": None,
+                            },
+                        },
+                    ]
+                }
+            }
+        }
+
+        # Call the method
+        result = await fetcher.list_saved_queries()
+
+        # Assertions
+        assert len(result) == 2
+        assert isinstance(result[0], SavedQueryToolResponse)
+        assert result[0].name == "daily_revenue"
+        assert result[0].label == "Daily Revenue Report"
+        assert result[0].metrics == ["revenue", "profit"]
+        assert result[0].group_by == ["product_name", "date"]
+        assert result[0].where == "date >= '2024-01-01'"
+        assert result[1].name == "monthly_users"
+        assert result[1].metrics == ["user_count"]
+        assert result[1].where is None
+
+    @pytest.mark.asyncio
+    @patch("dbt_mcp.semantic_layer.client.submit_request")
+    async def test_list_saved_queries_with_search(
+        self, mock_submit_request, fetcher, mock_config_provider
+    ):
+        """Test listing saved queries with a search filter."""
+        # Mock GraphQL response - only revenue query matches search
+        mock_submit_request.return_value = {
+            "data": {
+                "savedQueriesPaginated": {
+                    "items": [
+                        {
+                            "name": "daily_revenue",
+                            "label": "Daily Revenue Report",
+                            "description": "Daily revenue metrics",
+                            "queryParams": {},
+                        }
+                    ]
+                }
+            }
+        }
+
+        # Call the method with search filter
+        result = await fetcher.list_saved_queries(search="revenue")
+
+        # Should return the matched query
+        assert len(result) == 1
+        assert result[0].name == "daily_revenue"
+
+        # Verify search parameter was passed
+        mock_submit_request.assert_called_once()
+        call_args = mock_submit_request.call_args[0]
+        assert call_args[1]["variables"]["search"] == "revenue"
+
+    @pytest.mark.asyncio
+    @patch("dbt_mcp.semantic_layer.client.submit_request")
+    async def test_list_saved_queries_empty_result(
+        self, mock_submit_request, fetcher, mock_config_provider
+    ):
+        """Test listing saved queries when no queries exist."""
+        # Mock empty GraphQL response
+        mock_submit_request.return_value = {
+            "data": {"savedQueriesPaginated": {"items": []}}
+        }
+
+        # Call the method
+        result = await fetcher.list_saved_queries()
+
+        # Should return empty list
+        assert result == []
+
+    @pytest.mark.asyncio
+    @patch("dbt_mcp.semantic_layer.client.submit_request")
+    async def test_list_saved_queries_missing_attributes(
+        self, mock_submit_request, fetcher, mock_config_provider
+    ):
+        """Test listing saved queries when some attributes are missing."""
+        # Mock GraphQL response with missing attributes
+        mock_submit_request.return_value = {
+            "data": {
+                "savedQueriesPaginated": {
+                    "items": [
+                        {
+                            "name": "test_query",
+                            # Missing label, description, and queryParams
+                        }
+                    ]
+                }
+            }
+        }
+
+        # Call the method
+        result = await fetcher.list_saved_queries()
+
+        # Should handle missing attributes gracefully
+        assert len(result) == 1
+        assert result[0].name == "test_query"
+        assert result[0].label is None
+        assert result[0].description is None
+        assert result[0].metrics is None
+        assert result[0].group_by is None
+        assert result[0].where is None

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+kind: Enhancement or New Feature`
	`2`	`+body: Add list_saved_queries tool to the Semantic Layer, enabling discovery of predefined MetricFlow queries via GraphQL API. This allows AI agents to list and search saved queries with their associated metrics, dimensions, and filters.`
	`3`	`+time: 2025-11-01T07:22:30.000000+09:00`