Headless Server Developer Manual / Version 2406.1
Table Of ContentsGeneric search and dynamic query lists can be extended with custom filter queries, that are applied to the
fq
parameter of the Solr query.
Custom filter queries must be predefined in as an implementation of
CustomFilterQuery
and provided as a Spring bean, before they can be used. As CustomFilterQuery
is an extension point also,
custom filter queries may be provided as part of a plugin or directly, e.g. by CaasConfig
.
Definition of custom filter queries
The definition of a custom filter query consists of a query identifier and a function, that maps the field values to a Solr query.
- Query Identifier: a String value to identify the query. The graphql input type
FilterQueryArg
needs to be extended with the query identifier. - Mapping Function: a function which takes a List<String> as argument and returns a String, that contains the Solr query in Solr syntax.
For example, a filter query definition could be defined with a query identifier EXCLUDE_IDS and a (here simplified) mapping function:
// Extension of input type FilterQueryArg in a graphql schema: extend input FilterQueryArg { EXCLUDE_IDS: [String!] } // Bean factory in a configuration class @Bean public CustomFilterQuery excludeIdsQuery() { return new CustomFilterQuery() { /** * The query identifier. */ @Override public String getName() { return "EXCLUDE_IDS"; } /** * The mapping function. */ @Override public String apply(List<String> values) { return SearchQueryHelper .negatedQuery( SearchQueryHelper .orQuery(SearchConstants.FIELDS.ID.toString(), values) ); } }; }
Example 6.1. Example implementation of a custom filter query.
In order to demonstrate the usage and possibilities, Headless Server comes with some out-of-the-box custom filter queries, namely:
- TITLE_OR: Query for one or more exact search expressions on the title field of the index.
- EXCLUDE_IDS: Exclude one or more content ids from the search result.
- FRESHNESS: Query for contents newer than the given date on the modification date field of the index.
- LOC_TAXONOMY_OR: Query for location taxonomy values.
- SUBJ_TAXONOMY_OR: Query for subject taxonomy values.
There are some help utilities in SearchQueryHelper
to generate the Solr query in Solr syntax.
Alternatively, the Solr query can also be given in direct Solr syntax.
Apply custom filter queries
A custom filter query can be applied statically for all queries or dynamically for each graphql query.
Static custom filter queries
Static filter queries, that shall be applied to all Solr queries, can be passed to the corresponding
*AdapterFactories
, e.g. SearchServiceAdapterFactory
or QueryListAdapterFactory
.
They are then added to all Solr queries automatically.
Dynamic custom filter queries
Dynamic filter queries, that are applied to a specific GraphQL query, can be added as query argument for
generic search, faceted search, suggestions or dynamic query lists.
The input format is defined via the built-in type FilterQueryArg
All custom filter queries are applied as fq
(filter query) fragments to the Solr query.
This GraphQL query is an example for fetching a search result using the predefined custom filter queries EXCLUDE_IDS and TITLE_OR.
{ { content { search(query: "*", docTypes: ["CMArticle"], customFilterQueries: [{EXCLUDE_IDS: ["1234", "5678"]}, {TITLE_OR: ["Make your dream come true", "Eveningwear Trends"]}]) { numFound result { id ... on CMArticle { title } } } } } }
This GraphQL query is an example for fetching query list items using the predefined custom filter queries EXCLUDE_IDS.
{ { content { queryList(id: "10") { ... on CMQueryList { id filteredItems(customFilterQueries: {EXCLUDE_IDS: ["1234", "5678"]}) { ... on CMLinkable { id } } } } } } }