feat(semantic-layer): add get_dimension_values tool by b-per · Pull Request #782 · dbt-labs/dbt-mcp

b-per · 2026-05-19T14:51:22Z

Summary

Adds a get_dimension_values tool to the Semantic Layer toolset
Returns distinct values for a named dimension, optionally scoped to specific metrics
Results are capped at a configurable limit (default 100); a truncated flag signals when more values exist beyond the limit
Intended to be called before query_metrics to discover valid filter values for where clauses

Implementation notes

Uses SyncSemanticLayerClient.dimension_values (ADBC / Arrow Flight SQL), which is lightweight — no metric aggregation
Return type is DimensionValuesResponse(values: list[str], truncated: bool); all column values are stringified for consistent handling regardless of the underlying dimension type (dates, integers, etc.)
limit is validated as ge=1 to prevent empty-but-non-truncated responses
Error handling follows the same pattern as other fetcher methods (_format_semantic_layer_error)

Test plan

Unit tests: uv run pytest tests/unit/semantic_layer/test_client.py -k "dimension_values" -v
Full unit suite: uv run pytest tests/unit/ -x -q
Linting and type checks: task check
Smoke test against a real dbt platform environment with the Semantic Layer enabled

Copilot

Pull request overview

Adds a Semantic Layer get_dimension_values tool for discovering dimension filter values before calling query_metrics.

Changes:

Registers the new Semantic Layer tool and adds parameter descriptions/prompt documentation.
Adds DimensionValuesResponse and fetcher logic using the Semantic Layer SDK.
Adds unit coverage for response creation and basic fetch/truncation behavior, plus README/changelog updates.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`src/dbt_mcp/semantic_layer/client.py`	Adds fetcher support for retrieving and truncating dimension values.
`src/dbt_mcp/semantic_layer/tools.py`	Exposes `get_dimension_values` as an MCP tool.
`src/dbt_mcp/semantic_layer/types.py`	Adds the structured response dataclass.
`src/dbt_mcp/semantic_layer/param_descriptions.py`	Adds descriptions for the new tool parameters.
`src/dbt_mcp/prompts/semantic_layer/get_dimension_values.md`	Adds tool usage guidance and examples.
`src/dbt_mcp/tools/tool_names.py`	Adds the new tool enum value.
`src/dbt_mcp/tools/toolsets.py`	Includes the new tool in the Semantic Layer toolset.
`src/dbt_mcp/tools/readme_mappings.py`	Adds the README description mapping.
`tests/unit/semantic_layer/test_client.py`	Adds unit tests for dimension values behavior.
`README.md`	Documents the new Semantic Layer tool.
`docs/diagram.mmd`	Adds a Mermaid architecture diagram including the new tool.
`.changes/unreleased/Enhancement or New Feature-20260519-141400.yaml`	Adds an enhancement changelog entry.
`.changes/unreleased/Bug Fix-20260519-142146.yaml`	Adds a bug-fix changelog entry.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Add DimensionValuesResponse dataclass to semantic_layer/types.py with values list and truncated flag. Include tests to verify the type can be instantiated and used correctly.

The SDK's dimension_values returns a pa.Table, not a list[str]. Extract the first column via .column(0).to_pylist() before slicing. Update protocol stub return type and tests to use real pa.Table mock return values.

…validation - DimensionValuesResponse.values widened from list[str] to list[Any] to handle non-string dimension types (integers, dates, etc.) - get_dimension_values now wraps body in try/except, re-raising as RuntimeError via _format_semantic_layer_error for clean error propagation - limit param gains ge=1 validation to prevent empty/negative-slice bugs - Add boundary test: N items with limit=N yields truncated=False - Add get_dimension_values to docs/diagram.mmd Semantic Layer subgraph

…tr] type

… to empty string Null values are not valid filter values and would produce invalid where clauses if returned. Also adds a test covering null omission and corrects the changelog entry describing the list[str] fix.

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

…sion_values to multi-project mode - Fix dimension column lookup to be case-insensitive; the SDK returns column names in uppercase which caused a KeyError when the caller passed the dimension name in lowercase - Add get_dimension_values tool to tools_multiproject.py so it is available in multi-project mode alongside the other Semantic Layer tools

…ts, remove diagram - Wrap the five get_dimension_values tests in TestGetDimensionValues with shared mock_sl_client, sl_config, and dim_fetcher fixtures to eliminate repeated setup boilerplate - Remove docs/diagram.mmd; diagram automation will be handled in a separate PR rather than as a manually maintained file

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

…_values The Protocol must keep Any to match the SDK stubs (which incorrectly type dimension_values as list[str] despite returning a pa.Table at runtime), but the local variable in the method body can be typed as pa.Table to preserve mypy coverage for all downstream attribute accesses.

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

+    @pytest.mark.asyncio
+    async def test_truncates_at_limit(self, dim_fetcher, mock_sl_client, sl_config):
+        mock_sl_client.dimension_values.return_value = pa.table(
+            {"status": ["a", "b", "c", "d", "e"]}
+        )
+        result = await dim_fetcher.get_dimension_values(
+            config=sl_config, dimension="status", limit=3
+        )
+        assert result.values == ["a", "b", "c"]
+        assert result.truncated is True
+


Copilot AI review requested due to automatic review settings May 19, 2026 14:51

b-per requested review from a team, jairus-m and jasnonaz as code owners May 19, 2026 14:51

b-per temporarily deployed to integration May 19, 2026 14:51 — with GitHub Actions Inactive

Copilot started reviewing on behalf of b-per May 19, 2026 14:52 View session

Copilot AI reviewed May 19, 2026

View reviewed changes

Comment thread src/dbt_mcp/semantic_layer/client.py Outdated

Comment thread src/dbt_mcp/semantic_layer/client.py Outdated

Comment thread .changes/unreleased/Bug Fix-20260519-142146.yaml Outdated

b-per added 11 commits May 19, 2026 17:19

feat(semantic_layer): add DimensionValuesResponse type

1f41d2b

Add DimensionValuesResponse dataclass to semantic_layer/types.py with values list and truncated flag. Include tests to verify the type can be instantiated and used correctly.

feat(semantic-layer): add get_dimension_values to SemanticLayerFetcher

1ca9011

fix(semantic-layer): extract pa.Table column in get_dimension_values

09220b3

The SDK's dimension_values returns a pa.Table, not a list[str]. Extract the first column via .column(0).to_pylist() before slicing. Update protocol stub return type and tests to use real pa.Table mock return values.

fix(semantic-layer): access dimension_values column by name not index

094634a

feat(semantic-layer): register get_dimension_values tool name and prompt

e8dfe38

feat(semantic-layer): add get_dimension_values MCP tool

19fa51b

chore: changelog and regenerated docs for get_dimension_values

14e35c1

fix(semantic-layer): stringify dimension values for consistent list[s…

81f58a7

…tr] type

docs(semantic-layer): update get_dimension_values prompt example wording

0f489f6

b-per force-pushed the feat/get-dimension-values branch from 4392825 to b685479 Compare May 19, 2026 15:23

b-per temporarily deployed to integration May 19, 2026 15:24 — with GitHub Actions Inactive

b-per requested a review from Copilot May 19, 2026 16:36

Copilot started reviewing on behalf of b-per May 19, 2026 16:37 View session

Copilot AI reviewed May 19, 2026

View reviewed changes

Comment thread src/dbt_mcp/tools/toolsets.py

jairus-m reviewed May 20, 2026

View reviewed changes

Comment thread docs/diagram.mmd Outdated

Comment thread src/dbt_mcp/semantic_layer/client.py

Comment thread tests/unit/semantic_layer/test_client.py

Comment thread src/dbt_mcp/semantic_layer/tools.py

b-per had a problem deploying to integration June 3, 2026 13:09 — with GitHub Actions Failure

Copilot AI review requested due to automatic review settings June 3, 2026 13:18

b-per temporarily deployed to integration June 3, 2026 13:18 — with GitHub Actions Inactive

Copilot started reviewing on behalf of b-per June 3, 2026 13:18 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

Comment thread src/dbt_mcp/semantic_layer/client.py

Comment thread src/dbt_mcp/semantic_layer/client.py Outdated

b-per temporarily deployed to integration June 3, 2026 13:46 — with GitHub Actions Inactive

jairus-m approved these changes Jun 3, 2026

View reviewed changes

Merge branch 'main' into feat/get-dimension-values

c7867bc

Copilot AI review requested due to automatic review settings June 3, 2026 15:00

jairus-m temporarily deployed to integration June 3, 2026 15:00 — with GitHub Actions Inactive

Copilot started reviewing on behalf of jairus-m June 3, 2026 15:00 View session

jairus-m merged commit f667f9a into main Jun 3, 2026
8 checks passed

jairus-m deleted the feat/get-dimension-values branch June 3, 2026 15:03

Copilot AI reviewed Jun 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(semantic-layer): add get_dimension_values tool#782

feat(semantic-layer): add get_dimension_values tool#782
jairus-m merged 15 commits into
mainfrom
feat/get-dimension-values

b-per commented May 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

b-per commented May 19, 2026

Summary

Implementation notes

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants