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.

        ToolName.LIST_SAVED_QUERIES,
        ToolName.GET_DIMENSIONS,
        ToolName.GET_ENTITIES,
+        ToolName.GET_DIMENSION_VALUES,


jairus-m · 2026-05-20T04:04:50Z

Nearly all docs today are automated via existing scripts in scripts/ and the use of task docs:generate. This mermaid diagram is not included in that and will drift.

Should we (1) include this mermaid generation in docs automation in this PR or (2) exclude the file from here and open another PR for this addition in particular?

jairus-m · 2026-05-20T04:15:03Z

+            # SDK doesn't support server-side limiting; truncation is applied client-side.
+            raw: list[str] = [
+                str(v) for v in raw_table.column(dimension).to_pylist() if v is not None
+            ]


I tested this locally and a bug came up - the SDK looks to return column names in uppercase and if the dimension is passed as lowercase, there is a mismatch and we get Error: Error executing tool get_dimension_values: 'Field "<field_name>" does not exist in schema'

I was able to fix it by adding a change locally to implement a case-insensitive lookup

jairus-m · 2026-05-20T04:17:16Z

Non-blocker!

mock_sl_client setup and SemanticLayerConfig construction are copy-pasted across all the tests here - may be worth to extract them into class level fixtures for sake of being DRY

jairus-m · 2026-05-20T04:19:15Z

@@ -28,6 +30,7 @@
 )
 from dbt_mcp.semantic_layer.types import (
    DimensionToolResponse,
+    DimensionValuesResponse,
    EntityToolResponse,
    GetMetricsCompiledSqlSuccess,
    ListMetricsResponse,


Do we also need to add these and register the new tool in src/dbt_mcp/semantic_layer/tools_multiproject.py as well? SL tools are registered in both the single and multiproject modules.

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

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

ToolName.LIST_SAVED_QUERIES,

ToolName.GET_DIMENSIONS,

ToolName.GET_ENTITIES,

ToolName.GET_DIMENSION_VALUES,

jairus-m reviewed May 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat(semantic-layer): add get_dimension_values tool#782
b-per wants to merge 11 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!

jairus-m May 20, 2026 •

edited

Loading

Uh oh!

jairus-m May 20, 2026

Uh oh!

jairus-m May 20, 2026

Uh oh!

jairus-m May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

jairus-m May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jairus-m May 20, 2026

Choose a reason for hiding this comment

Uh oh!

jairus-m May 20, 2026

Choose a reason for hiding this comment

Uh oh!

jairus-m May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jairus-m May 20, 2026 •

edited

Loading