Add annotation to disable query derivation for custom repository methods

[neo-julio-falbo]

Problem Statement

Spring Data MongoDB currently lacks an elegant way to disable automatic query derivation for custom repository methods that contain query keywords (like By, And, Or, etc.) in their names. This leads to PropertyReferenceException errors when developers want to implement custom logic for methods whose names happen to contain these keywords.

Current Behavior

When implementing custom repository methods using the fragment pattern, Spring Data MongoDB attempts to derive queries from method names even when a custom implementation is provided. This causes runtime exceptions when the method name contains query keywords but refers to non-existent properties.

Example Code That Fails

// Custom repository fragment
public interface CustomSnsRepository {
    boolean checkIfExistsByArn(String arn);  // Contains "By" keyword
}

// Custom implementation
public class CustomSnsRepositoryImpl implements CustomSnsRepository {
    private final MongoTemplate mongoTemplate;
    
    public CustomSnsRepositoryImpl(MongoTemplate mongoTemplate) {
        this.mongoTemplate = mongoTemplate;
    }
    
    @Override
    public boolean checkIfExistsByArn(String arn) {
        Query query = new Query(Criteria.where("arn").is(arn));
        return mongoTemplate.exists(query, SnsTopicEntity.class);
    }
}

// Main repository
@Repository
public interface SnsTopicRepository extends MongoRepository<SnsTopicEntity, String>, CustomSnsRepository {
}

Error produced:

Caused by: org.springframework.data.mapping.PropertyReferenceException: 
No property 'checkIfExistsByArn' found for type 'SnsTopicEntity'

Benefits

1. Clear Intent: Explicitly indicates custom implementation is provided
2. Natural Naming: Allows descriptive method names with query keywords
3. Self-Documenting: Makes code intent obvious to other developers
4. Backward Compatible: Doesn't affect existing functionality
5. Consistent: Follows Spring's annotation-driven approach
6. Maintainable: No complex configuration required

Environment

• Spring Boot: 3.4.5
• Spring Data MongoDB: Latest
• Java: 17+

This feature would significantly improve the developer experience when working with custom repository implementations in Spring Data MongoDB by providing a clean, annotation-based solution that aligns with Spring Framework's design principles.

[christophstrobl]

Thank you for getting in touch, please take the time to provide a complete minimal sample (something that we can unzip or git clone, build, and deploy) that reproduces the problem.

[neo-julio-falbo]

Hi @christophstrobl , thank you for your attention.

Here is a github repo simulating the error: https://github.com/neo-julio-falbo/spring-data-mongo-query-derivation-bug

During the creation of the repo, I noticed one thing:

The issue is "resolved" if the implementation class (CustomSnsRepositoryImpl) is moved into the same package as the repository interfaces (CustomSnsRepository and SnsTopicRepository).

This suggests the problem lies in the component scanning and prioritization logic. While this workaround allows the application to function, it imposes rigid package structure requirements and doesn't address the underlying design flaw.

[christophstrobl]

Thank you for the reproducer.

Things work as designed. The behaviour is explained in our reference documentation. To register fragments outside the package hierarchy, please follow the Registering Fragments with spring.factories section.

[neo-julio-falbo]

Thank you for the explanation.

I fixed the example based on the documentations you sent me and it is working as expected.

For those interested, I'll keep the example up.