Support allChildrenOf on /api/v2/entities

[EliotRagueneau]

New feature description.
Would be great to support same options as /api/search inside /api/v2/entities, specially allChildrenOf.
Being able to filter the fields to retreve could be nice as well as most of the response are useless to me, could save a fair share of bandwidth

Use cases
This would allow to use auto-suggestions on a predefined subset of an ontology which is quite often useful in curation. Indeed /api/search works already, but it only returns a match if there is an exact token match, and doesn't support partial label match like /api/v2/entities does. An alternative would be to optionally allow partial matches in /api/search.

e.g. compare results of
live(r) on search
https://www.ebi.ac.uk/ols4/api/search?q=live&ontology=uberon&local=true&rows=10&queryFields=label
https://www.ebi.ac.uk/ols4/api/search?q=liver&ontology=uberon&local=true&rows=10&queryFields=label

live(r) on entities (much better results, but unable to filter for a specific branch)
https://www.ebi.ac.uk/ols4/api/v2/entities?search=live&ontologyId=uberon&isDefiningOntology=true&size=10
https://www.ebi.ac.uk/ols4/api/v2/entities?search=liver&ontologyId=uberon&isDefiningOntology=true&size=10

User communities
Would like to use it for biostudies users in our submission tool, so that they can easily add ontology terms from partial matches (auto-suggestions) while staying relevant on a specific topic

Describe the solution you'd like
If you are using Solr, then maybe if you exposed the fq parameters, we could filter to only get results having a specific node in their hierarchicalAncestors. Having a more explicit option could work too

Describe alternatives you've considered
I tried a bit using searchproperties but couldn't find what synthax is expected there, anf if accapeted filters

[EliotRagueneau]

I realised that you actually support allChildrenOf by adding hierarchicalAncestor as a parameter, but the API for these endpoints is really not clear on what can be added inside the searchProperties, specially when it actually supports being flattened.
e.g. https://www.ebi.ac.uk/ols4/api/v2/entities?search=gene&ontologyId=mi&hierarchicalAncestor=http://purl.obolibrary.org/obo/MI_0313 fetches correctly the right branch compared to https://www.ebi.ac.uk/ols4/api/v2/entities?search=gene&ontologyId=mi.

So the functionality requested here already exists, but is not very well docuemented

[haideriqbal]

I've added clarification in our documentation:

All solr indexed fields can be passed as query filters to this endpoint. the /api/v2/entities endpoint passes any unknown query parameter directly through as a Solr field filter.

[EliotRagueneau]

May I suggest to use slightly stronger typing, if not for your internal usage, at least for the controllers:

import io.swagger.v3.oas.annotations.media.Schema;
import com.fasterxml.jackson.annotation.JsonAlias;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;

import java.util.Collection;
import java.util.List;
import java.util.Map;

@Schema(description = "Search filters for OLS entities")
public class SearchProperties {

    private static final ObjectMapper mapper = new ObjectMapper();

    @Schema(description = "The list of ontologies in which the current entity is used")
    private List<String> appearsIn;

    @JsonAlias("baseUris")
    @Schema(description = "The beginning of URIs that OLS assumes to belong to an ontology")
    private List<String> baseUri;

    @Schema(description = "A list of ontologies which defines this term")
    private List<String> definedBy;

    @JsonAlias("description")
    @Schema(description = "The definition of this entity")
    private String definition;

    @Schema(description = "A list of all direct parents by subclass and hierarchical relations")
    private List<String> directAncestor;

    @Schema(description = "A list of the direct parents of this entity")
    private List<String> directParent;

    @Schema(description = "Lists the prefixes of ontologies that import this ontology")
    private List<String> exportsTo;

    @JsonAlias("has_children")
    @Schema(description = "Whether this class has direct children")
    private Boolean hasDirectChildren;

    @Schema(description = "Indicates whether this class has direct parents")
    private Boolean hasDirectParents;

    @Schema(description = "Whether this class has hierarchical children")
    private Boolean hasHierarchicalChildren;

    @Schema(description = "Whether this class has hierarchical parents")
    private Boolean hasHierarchicalParents;

    @Schema(description = "Whether individuals exist")
    private Boolean hasIndividuals;

    @Schema(description = "True if term is defined within this ontology")
    private Boolean hasLocalDefinition;

    @Schema(description = "The list of ancestors via subclass and hierarchical relations")
    private List<String> hierarchicalAncestor;

    @Schema(description = "The list of parents via subclass and hierarchical relations")
    private List<String> hierarchicalParent;

    @Schema(description = "Whether this entity is imported")
    private Boolean imported;

    @Schema(description = "Lists the prefixes of ontologies this ontology imports from")
    private List<String> importsFrom;

    @JsonAlias("is_defining_ontology")
    @Schema(description = "Whether this entity is defined in this ontology")
    private Boolean isDefiningOntology;

    @Schema(description = "Set to true if this entity is obsolete")
    private Boolean isObsolete;

    @JsonAlias("is_preferred_root")
    @Schema(description = "Set to true if this entity is a preferred root")
    private Boolean isPreferredRoot;

    @Schema(description = "The name of this entity")
    private String label;

    @Schema(description = "The languages this ontology is available in")
    private List<String> language;

    @Schema(description = "The mailing list for the ontology")
    private String mailingList;

    @Schema(description = "Number of descendants", minimum = "0")
    private Integer numDescendants;

    @Schema(description = "Number of hierarchical descendants", minimum = "0")
    private Integer numHierarchicalDescendants;

    @Schema(description = "The URL of the ontology file")
    private String ontologyPurl;

    @Schema(description = "Entities that serve as roots for this ontology")
    private List<String> preferredRoot;

    @Schema(description = "Classes in which this class is used in definitions")
    private List<String> relatedFrom;

    @Schema(description = "Classes used in defining axioms of this class")
    private List<String> relatedTo;

    @Schema(description = "Entities that this entity links to")
    private List<String> linksTo;

    @Schema(description = "Synonyms of this entity")
    private List<String> synonym;

    // --- Getters & Setters omitted for brevity ---

    /**
     * Converts this SearchProperties object into a MultiValueMap<String, String>
     * to avoid full refactoring and stay flexible.
     */
    public MultiValueMap<String, String> toMultiValueMap() {
        Map<String, Object> map = mapper.convertValue(this, Map.class);
        MultiValueMap<String, String> result = new LinkedMultiValueMap<>();

        map.forEach((key, value) -> {
            if (value == null) return;

            if (value instanceof Collection<?> collection) {
                for (Object v : collection) {
                    result.add(key, String.valueOf(v));
                }
            } else {
                result.add(key, String.valueOf(value));
            }
        });

        return result;
    }
}

    @Operation(description = "Search and filter entities within a specific ontology. ")
    @RequestMapping(path = "/ontologies/{onto}/entities", produces = {MediaType.APPLICATION_JSON_VALUE}, method = RequestMethod.GET)
    public HttpEntity<V2PagedAndFacetedResponse<V2Entity>> getTerms(
            ...
            @ParameterObject SearchProperties searchProperties,
            @RequestParam(value = "lang", required = false, defaultValue = "en") String lang,
            @ParameterObject JsonTransformOptions outputOpts
    ) throws ResourceNotFoundException, IOException {

        Map<String,Collection<String>> properties = new HashMap<>();
        if(!includeObsoleteEntities)
            properties.put(IS_OBSOLETE.getText(), List.of("false"));
        properties.putAll(searchProperties.toMultiValueMap());

        return new ResponseEntity<>(
                new V2PagedAndFacetedResponse<V2Entity>(
                    entityRepository.findByOntologyId(ontologyId, pageable, lang, search, searchFields, boostFields, facetFields, exactMatch, DynamicQueryHelper.filterProperties(properties), outputOpts).map(V2Entity::new)
                ),
                HttpStatus.OK);
    }

You could apply this typing to any searchProperties across controllers and it should be very easy with an improved API. Ultimately you might want to refactor everything to use directly the attribute values instead of a map, but that is a lot more work ^^'

This way at least API users will know exactly what are all the fields supported, and you won't have to maintain this page https://www.ebi.ac.uk/ols4/defined-response-fields as much since it would be directly in the API.

That is just a suggestion, but I think it would be helpful as it's not necessarily so obvious what are the indexed fields (the link to it is rather small at the top of the page, and isn't annotated as search fields or indexed fields but just as "defined response field in OLS" )