Skip to content

Improve error message for OR operator with column filters #6078

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 16, 2025

Conversation

fubhy
Copy link
Member

@fubhy fubhy commented Jul 15, 2025

Summary

This PR improves the error message when users attempt to mix column filters with the 'or' operator at the same level in GraphQL queries. Instead of the generic "Filter must by an object" error, users now receive a specific, actionable error message with examples.

Problem

Previously, when users wrote queries like:

query {
  users(where: { 
    age_gt: 21, 
    or: [{ status: "active" }, { stage: "review" }] 
  }) {
    id
    name
  }
}

They would receive the unhelpful error: "Filter must by an object" which provided no guidance on what was wrong or how to fix it.

Solution

The new error message provides:

  1. Clear problem identification: "Cannot mix column filters with 'or' operator at the same level"
  2. Specific field listing: Shows exactly which filters are conflicting
  3. Concrete examples: Both the problematic structure and the correct fix
  4. Actionable guidance: Shows how to restructure the query properly

Example New Error Message

Cannot mix column filters with 'or' operator at the same level. Found column filter(s) 'age_gt' alongside 'or' operator.

Instead of:
where: { 'age_gt', or: [...] }

Use:
where: { or: [{ 'age_gt', ... }, { 'age_gt', ... }] }

Changes Made

1. New Error Type (graph/src/data/query/error.rs)

  • Added InvalidOrFilterStructure(Vec<String>, String) variant to QueryExecutionError
  • Implemented comprehensive error display with field listing and examples
  • Added to attestable error list for proper error handling

2. Enhanced Filter Validation (graphql/src/store/query.rs)

  • Added validation in build_filter_from_object to detect mixed filters early
  • Prevents progression to generic error by catching the issue at validation time
  • Handles all types of column filters (simple fields, operators like _gt, _lt, etc.)

3. Comprehensive Test Coverage

Added 5 new test cases covering:

  • ✅ Single column filter with OR operator
  • ✅ Multiple column filters with OR operator
  • ✅ Column filters with operators (like name_gt) with OR operator
  • ✅ Valid OR filter structure (regression test)
  • ✅ Error message formatting verification

Test Results

All existing tests continue to pass, ensuring no regressions:

running 23 tests
.......................
test result: ok. 23 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Benefits

  1. Reduced debugging time: Users immediately understand the problem
  2. Better developer experience: Clear, actionable error messages
  3. Improved API usability: Less confusion about GraphQL filter limitations
  4. Maintained compatibility: All existing functionality preserved

Addresses

For Ford 🚗

A humble plea in verse, for any bugs that might be terse:

Oh Ford, keeper of the Graph's domain,
If bugs slip through like summer rain,
This code was crafted with great care,
But humans err, it's only fair.

Should filters fail or tests go wrong,
Please know the intent was always strong:
To help developers debug with ease,
And make their GraphQL queries please.

So if you find a flaw or two,
Remember: Claude tried something new!
With tests and docs and love so true,
But still might need a fix from you. 🙏

Testing

To test the new error message:

  1. Deploy a subgraph with the updated graph-node
  2. Run a query mixing column filters with 'or' operator
  3. Observe the improved error message with concrete examples

The error now provides everything developers need to fix their queries without additional research or support requests.

fubhy and others added 2 commits July 15, 2025 17:45
Replace the generic "Filter must by an object" error with a specific,
helpful error message when users try to mix column filters with the 'or'
operator at the same level.

The new error message:
- Clearly explains the problem
- Shows which specific column filters are conflicting
- Provides concrete examples of the problematic structure
- Shows how to fix it by restructuring the query

This addresses GitHub issues #6040 and #6041 by making the error
message more descriptive and actionable for developers.

Changes:
- Add InvalidOrFilterStructure error variant to QueryExecutionError
- Add validation in build_filter_from_object to detect mixed filters
- Include comprehensive test coverage for various scenarios

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Use more idiomatic Rust pattern 'if let Some(_) = object.get("or")'
instead of 'let has_or = object.get("or").is_some(); if has_or'.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Copy link
Member

@incrypto32 incrypto32 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nit pick added otherwise LGTM

As suggested by @incrypto32, store column_filters.join(", ") in a
variable instead of calling it three times. This improves performance
and makes the code cleaner.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@fubhy fubhy merged commit 4fbdf0b into master Jul 16, 2025
6 checks passed
@fubhy fubhy deleted the improve-or-filter-error-message branch July 16, 2025 11:01
@fubhy fubhy mentioned this pull request Jul 16, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Clearer error when the OR operator is used with column filters
3 participants