feat: better error messages + property value index

[chitalian]

• Surface user-friendly error messages for ClickHouse errors (timeout, memory, row limits) instead of generic "Internal Server Error"
• Add bloom filter index on mapValues(properties) for faster property filtering

Ticket

Link to the ticket(s) this pull request addresses.

Component/Service

What part of Helicone does this affect?

• Web (Frontend)
• Jawn (Backend)
• Worker (Proxy)
• Bifrost (Marketing)
• AI Gateway
• Packages
• Infrastructure/Docker
• Documentation

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Performance improvement
• Refactoring

Deployment Notes

• No special deployment steps required
• Database migrations need to run
• Environment variable changes required
• Coordination with other teams needed

Screenshots / Demos

Before	After

Extra Notes

Any additional context, considerations, or notes for reviewers.

Context

Why are you making this change?

Screenshots / Demos

[vercel]

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

Project	Deployment	Review	Updated (UTC)
helicone	Ready	Preview, Comment	Jan 21, 2026 4:31am
helicone-bifrost	Ready	Preview, Comment	Jan 21, 2026 4:31am
helicone-eu	Ready	Preview, Comment	Jan 21, 2026 4:31am

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[supabase]

This pull request has been ignored for the connected project bolqqmqbrciybnypvklh because there are no changes detected in supbase/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[supabase]

This pull request has been ignored for the connected project lmahfbbnchpworytrrqk because there are no changes detected in .supabase/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[claude]

Claude finished @chitalian's task —— View job

---

Code Review Complete ✅

Review Tasks:

• Analyze ClickHouse migration file
• Review error handling changes in index.ts
• Check security and performance implications
• Provide specific feedback and recommendations
• Assign confidence score

Summary

Score: 8/10 - Good to merge, minor suggestions for improvement

This PR successfully addresses two important improvements: user-friendly error messaging and query performance optimization. The implementation is solid with no critical security issues identified.

Detailed Analysis

✅ ClickHouse Migration (schema_79_property_value_index.sql)

Strengths:

• Clean, focused migration following ClickHouse best practices
• Bloom filter with 0.01 false positive rate is appropriately conservative
• MATERIALIZE INDEX ensures existing data benefits immediately
• Index on mapValues(properties) will significantly improve property filtering performance

Minor suggestion:

• Consider adding a comment about expected performance impact (e.g., "Expected to improve property filter queries by X%")

✅ Error Handling (index.ts:213-249)

Strengths:

• Smart detection of specific ClickHouse error patterns via getSafeErrorMessage()
• User-friendly error messages with actionable guidance:
  • Timeout → "Try a shorter time range or simpler filters"
  • Memory → "Try a shorter time range"
  • Row limits → "Add more filters"
• Maintains security by not exposing internal details in production
• Preserves error context in development environments

Code Quality:

• Function is pure and testable
• Clear separation of concerns between detection and handling
• Consistent with existing error handling patterns

🔍 Security & Performance Review

Security: ✅ No issues found

• Error messages don't leak sensitive information
• Index doesn't expose additional attack surface
• Follows principle of least privilege for error disclosure

Performance: ✅ Positive impact expected

• Bloom filter index should significantly improve property-based queries
• Error detection adds minimal overhead (just string pattern matching)
• No new performance bottlenecks introduced

Suggestions for Enhancement

1. Error Message Completeness (Low Priority)

Current coverage includes timeout, memory, and row limits. Consider adding:

// In getSafeErrorMessage function
if (msg.includes("too_many_simultaneous_queries")) {
  return "Too many concurrent queries. Please wait and try again.";
}
if (msg.includes("quota")) {
  return "Query quota exceeded. Contact support if this persists.";
}

2. Monitoring Integration (Nice to Have)

Consider adding metrics for error types to track frequency:

// After detecting safe error message
if (safeMessage) {
  // Log for monitoring without exposing details
  console.warn(`ClickHouse user error: ${err.message.split('.')[0]}...`);
}

3. Index Documentation

Add comment in migration about query patterns this optimizes:

-- Optimizes queries like: WHERE properties['key'] = 'value'
-- Expected improvement: 3-5x faster property filtering on large datasets

Code References

• Error detection logic: /home/runner/work/helicone/helicone/valhalla/jawn/src/index.ts:214-226
• Error handling integration: /home/runner/work/helicone/helicone/valhalla/jawn/src/index.ts:242-244
• Migration file: /home/runner/work/helicone/helicone/clickhouse/migrations/schema_79_property_value_index.sql:2-3

Deployment Notes

• ✅ Migration is safe to run in production (additive only)
• ✅ No breaking changes
• ✅ Error handling is backwards compatible
• 📋 Monitor error logs post-deployment to validate user-friendly messages are working

Recommendation: Approve and merge

---