feat(api-gateway): expose query limit settings on /v1/meta

[keydunov]

Add a settings object to the /v1/meta response containing defaultLimit (CUBEJS_DB_QUERY_DEFAULT_LIMIT) and maxLimit (CUBEJS_DB_QUERY_LIMIT) so clients can render correct UI defaults and validate queries client-side without knowing about Cube env vars.

defaultLimit is clamped to maxLimit to mirror the runtime behaviour in query.js#normalizeQuery.

Check List

• Tests have been run in packages where changes have been made if available
• Linter has been run for changed code
• Tests for the changes have been added if not covered yet
• Docs have been added / updated if required

[claude]

Claude finished @keydunov's task in 1m 24s —— View job

---

PR Review: expose query limit settings on /v1/meta

• Read and understand all changed files
• Review code quality and correctness
• Review security considerations
• Review test coverage
• Review API documentation (openspec.yml)
• Post final review

---

Overall this is a clean, well-scoped PR. The implementation mirrors the existing clamping logic in query.js#normalizeQuery correctly, the OpenAPI spec is updated, client types are extended, and both /v1/meta and /v1/meta?extended paths are covered. A few observations:

Issues

1. onlyCompilerId path omits settings — intentional?
gateway.ts:708-714 — When onlyCompilerId is true, the early-return response includes only cubes: [] and compilerId, but no settings. Since this is a lightweight "has the schema changed?" check, omitting settings is probably fine, but it creates an inconsistency: every other meta response includes settings, this one doesn't. Worth a brief comment or making it explicit in the type. The OpenAPI spec marks settings as optional on V1MetaResponse so it's valid, but clients calling with onlyCompilerId and also reading settings would get undefined.

2. MetaResponse.settings is typed as optional but always sent
In request.ts:103, settings is declared as settings?: MetaResponseSettings (optional). But in gateway.ts:734 (normal path) and gateway.ts:789 (extended path), it's always populated. Consider making it non-optional in the type to match reality — the only path that skips it is onlyCompilerId, which builds its own inline type anyway. This would give downstream consumers stronger type guarantees.

3. metaExtended uses ResponseResultFn (generic), not MetaResponseResultFn
gateway.ts:756 — The extended meta path uses the generic ResponseResultFn (Record<string, any>), so the addition of settings there isn't type-checked against MetaResponse. This is a pre-existing issue, not introduced by this PR, but worth noting since it means the settings shape in the extended path has no compile-time contract.

Minor / Nits

4. Comment is verbose for this codebase
gateway.ts:676-684 — The 8-line JSDoc on getMetaSettings() is thorough but heavier than what the surrounding code uses. The codebase tends toward minimal comments. Consider trimming to 1-2 lines or removing entirely — the method name and the Math.min call are self-documenting.

5. Tests could assert specific default values
index.test.ts:689-714 — The tests verify the shape (toHaveProperty, typeof) and the clamping invariant (defaultLimit <= maxLimit), which is good. You could additionally assert the actual default values (e.g., expect(res.body.settings.defaultLimit).toBe(10000) or whatever the env defaults are) to catch accidental env-var default changes. Not strictly required, but would strengthen the regression safety net.

6. Inline type repeated in gateway.ts
gateway.ts:731 — The type { defaultLimit: number, maxLimit: number } is written inline on the response object, duplicating MetaResponseSettings from request.ts. Consider importing and reusing the type for a single source of truth:

import { MetaResponseSettings } from './types/request';

Security

No concerns. The exposed values (defaultLimit and maxLimit) are server configuration, not secrets. They are already implicitly observable by clients (through query behavior), so making them explicit is fine.

Summary

Clean feature addition. The main actionable items are (1) deciding whether the onlyCompilerId path should include settings and (2) making the settings field non-optional in MetaResponse since it's always present in normal responses. Everything else is minor.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.11%. Comparing base (87f4dc1) to head (15021e0).
⚠️ Report is 5 commits behind head on master.

❗ There is a different number of reports uploaded between BASE (87f4dc1) and HEAD (15021e0). Click for more details.

HEAD has 1 upload less than BASE

Flag	BASE (87f4dc1)	HEAD (15021e0)
cubesql	1	0

Additional details and impacted files

@@             Coverage Diff             @@
##           master   #10813       +/-   ##
===========================================
- Coverage   78.79%   58.11%   -20.68%     
===========================================
  Files         470      216      -254     
  Lines       92135    16906    -75229     
  Branches     3424     3428        +4     
===========================================
- Hits        72597     9825    -62772     
+ Misses      19035     6578    -12457     
  Partials      503      503               

Flag	Coverage Δ
cube-backend	58.11% <100.00%> (+0.02%)	⬆️
cubesql	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.