fix: Fix filter key fetching on multi-shard distributed tables

[pulpdrew]

Summary

This PR fixes an query error when fetching map keys for filters from a distributed table where the distributed table requests keys across servers with different versions. More details here

Screenshots or video

Before filter key query fails:

After query suceeds:

How to test on Vercel preview

The fix can be validated against LogHouse, the change can be regression tested by using the filters in the preview environment.

References

• Linear Issue: Closes HDX-4771
• Related PRs:

[changeset-bot]

🦋 Changeset detected

Latest commit: 41529b5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hyperdx/common-utils	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Jul 14, 2026 6:48pm
hyperdx-storybook	Ready	Preview, Comment	Jul 14, 2026 6:48pm

[greptile-apps]

Greptile Summary

This PR fixes Map-key discovery across version-mismatched ClickHouse shards. The main changes are:

• Uses getSubcolumn(column, 'keys') in both Map-key query strategies.
• Adds unit tests for LowCardinality and plain String Map keys.
• Adds a patch changeset for @hyperdx/common-utils.

Confidence Score: 5/5

This looks safe to merge.

• Both query strategies apply the same explicit subcolumn access.
• Tests cover the generated SQL for both Map-key types.
• No blocking issue remains in the updated code.

Important Files Changed

Filename	Overview
packages/common-utils/src/core/metadata.ts	Updates both Map-key sampling queries to use the explicit getSubcolumn function.
packages/common-utils/src/tests/metadata.test.ts	Adds SQL-shape tests for both supported Map-key query strategies.
.changeset/ninety-grapes-turn.md	Adds a patch release note for the distributed-table compatibility fix.

_{Reviews (4): Last reviewed commit: "Merge branch 'main' into drew/fix-filter..." | Re-trigger Greptile}

[github-actions]

E2E Test Results

✅ All tests passed • 237 passed • 3 skipped • 1510s

Status	Count
✅ Passed	237
❌ Failed	0
⚠️ Flaky	1
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats

• Production files changed: 1
• Production lines changed: 14 (+ 73 in test files, excluded from tier calculation)
• Branch: drew/fix-filter-keys-dist-table
• Author: pulpdrew

To override this classification, remove the review/tier-2 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

Deep Review

✅ No critical issues found.

This is a tight, well-scoped fix: both col.keys Map-subcolumn dot forms in getMapKeys were replaced with the explicit getSubcolumn(col, 'keys') function form, and both query strategies (groupUniqArrayArray and lowCardinalityKeys) are exercised by the two new tests. Reviewers confirmed the two forms are semantically equivalent and that getSubcolumn with a constant 'keys' argument reads only the keys substream — no values are materialized, so there is no IO/memory regression. The sibling getMapValues uses col[key] subscript rather than the dot form, so no unfixed occurrence of this bug class remains.

🔵 P3 nitpicks (3)

• packages/common-utils/src/__tests__/metadata.test.ts:1116 — the regex assertions depend on the exact chSql placeholder rendering ({<hash>:Identifier}) and the literal comma-space before 'keys', so a no-behavior-change reformat of query serialization would break these tests.
  • Fix: assert against the decoded identifier plus the getSubcolumn( / absence-of-.keys structure with tolerance for whitespace, rather than the exact placeholder string.
  • _{testing, kieran-typescript}
• packages/common-utils/src/core/metadata.ts:604 — the distributed-hop rationale comment is duplicated near-verbatim in the source and in the test, which can drift if the reasoning changes.
  • Fix: keep the full explanation in the source comment and have the test reference it briefly instead of restating it.
• .changeset/ninety-grapes-turn.md:5 — the changeset summary describes the target as version-mismatched distributed tables while the code comment and commit describe it as multi-shard distributed tables, so the published CHANGELOG wording diverges from the in-code description.
  • Fix: align the changeset wording with the code comment so the user-facing changelog and source describe the same condition.

---

Reviewers (6): correctness, testing, maintainability, kieran-typescript, performance, project-standards.

Testing gaps: The new tests assert only the rendered SQL string; the actual failure mode (THERE_IS_NO_COLUMN / NOT_FOUND_COLUMN_IN_BLOCK on a real multi-shard Distributed read) and the behavioral equivalence of the returned key set are not exercised by any integration test — inherent to the bug class, not a defect in this diff.

[knudtty]

LGTM