close

Filter

loading table of contents...

Headless Server Developer Manual / Version 2404

Table Of Contents

6.1 Generic Search

Search related features are handled by the adapters searchAdapter, facetedSearchAdapter and suggestionsAdapter. The following functionality is supported:

  • Full text search
  • Paging
  • Limit
  • Filter by content type, optionally including their sub types
  • Predefined sort fields with order
  • Limitation to a site
  • Valid from and valid to conditions are applied to search filters automatically

  • Faceted search results
  • Search suggestions

The following GraphQL query is a simple example for fetching a search result.

{
  content {
    search(query:"Perfect") {
      numFound
      result {
        name
      }
    }
  }
}

Several parameters can be passed to the SearchAdapter to customize the search:

  • query: The search query.
  • offset: The offset.
  • limit: The limit of search result.
  • docTypes: Content types to restrict the search result.

    Misspelled content types and invalid content types will cause a graphql error in the response. When passing an abstract content type, the subtypes are retrieved, if the parameter includeSubTypes = true. Passing an abstract content type with includeSubTypes = false will also cause a graphql error. The search result does not contain abstract content types, only the concrete sub types.

  • sortFields: List of sort field with order, separated by '_', in upper case, for example, ID_ASC.

    The set of available sort fields in the schema is limited to the enum SortFieldWithOrder defined in the content schema: ID, DOCUMENTTYPE, TITLE, TEASER_TITLE, MODIFICATION_DATE, CREATION_DATE, EXTERNALLY_DISPLAYED_DATE. This enum can be extended in the schema by adding an available field with a sort order.

    The available fields are defined in SearchConstants#FIELDS: ID, DOCUMENTTYPE, NAVIGATION_PATHS, NOT_SEARCHABLE, SUBJECT_TAXONOMY, LOCATION_TAXONOMY, TITLE, TEASER_TITLE, TEASER_TEXT, KEYWORDS, MODIFICATION_DATE, CREATION_DATE, TEXTBODY, SEGMENT, COMMERCE_ITEMS, CONTEXTS, AUTHORS, HTML_DESCRIPTION, VALID_FROM, VALID_TO, EXTERNALLY_DISPLAYED_DATE

    To configure custom fields, a specific bean can be configured, see section below.

    Possible order field values: ASC, DESC

  • siteId: The siteId can be passed as parameter to restrict search per site.
  • includeSubTypes: A Boolean flag, indicating to include the sub types of the given doc types in the search. Defaults to 'false'.

The query parameter supports the following syntax:

  • The + and - characters are treated as "mandatory" and "prohibited" modifiers for terms.
  • Quoted expressions, like "Foo Bar" are treated as a phrase
  • An odd number of quote characters is evaluated as if there were no quote characters at all.
  • The wildcard character '*' supports the search for partial terms like 'frag*', which would find, for example, the terms 'fragment' and 'fragile' as well. When used exclusively as a search query, the search is executed with all other search parameters but without an explicit search expression.

By default, the SearchAdapter employs DefaultSearchServiceProvider, which in turn uses the caeSolrQueryBuilder Spring bean. caeSolrQueryBuilder invokes searches on Solr on the cmdismax endpoint. For details, see Section 3.8.1, “Details of Language Processing Steps” in Search Manual.

The used SearchServiceProvider is at the same time an ExtensionPoint, which can be implemented and provided by a plugin. See Section 4.16, “Plugin Support” for details.

The following GraphQL query is a more complex example for fetching a search result.

{
  content {
    search(query: "Perfect", offset: 3, limit: 5, docTypes: ["CMArticle", "CMPicture"], sortFields: [CREATION_DATE_ASC, MODIFICATION_DATE_ASC], siteId: "abffe57734feeee", includeSubTypes: true) {
      numFound
      result {
        name
        type
      }
    }
  }
}

If docTypes or limit is not passed as parameter, the following search configuration is taken into account, which is read from CMS content using settings. See general search configuration for details in Section 5.4.21, “Website Search” in Blueprint Developer Manual .

  • searchDoctypeSelect, search.doctypeselect: content types to restrict the search result
  • searchResultHitsPerPage, search.result.hitsPerPage: limit of the search result

Valid from and valid to conditions are applied to search filters automatically.

Faceted Search Results

The Headless Server Search is able to do a faceted search on configured facets on the Solr search index. Headless Server comes with preconfigured facets,for example, on the content type. See Section 5.4.21, “Website Search” in Blueprint Developer Manual on how to configure facets on the search index.

In contrast to the regular search without facets, the facetedSearch query requires the parameter siteId mandatorily. To issue a faceted search request, the search query has to define the desired facets using the parameter facetFilters:

{
  content {
    facetedSearch(
      query: "*"
      siteId: "abffe57734feeee"
      facetLimit: 10
      facetFilters: [
        { facetName: "type", args: ["CMArticle"], excludeInFacet: false }
        { facetName: "subject", args: ["1234", "5678"] }
      ]
    ) {
      numFound
      facets {
        alias
        field
        values {
          query
          value
          hitCount
        }
      }
      result {
        id
        type
        ... on CMArticle {
          detailText {
            text
          }
        }
      }
    }
  }
}

The facets can be found in the facets property of the search result. They provide information about the requested facets, the corresponding facet values and their count of content items where the facet occurred.

Use these parameters to issue a faceted search

  • query: The search query.
  • offset: The offset.
  • limit: The limit of search result.
  • facetLimit: Limits the size of facet values per facet. Defaults to studio config if set or 5 if not.
  • sortFields: List of sort field with order, separated by '_', in upper case, for example, ID_ASC.

    The set of available sort fields in the schema is limited to the enum SortFieldWithOrder defined in the content schema: ID, DOCUMENTTYPE, TITLE, TEASER_TITLE, MODIFICATION_DATE, CREATION_DATE, EXTERNALLY_DISPLAYED_DATE. This enum can be extended in the schema by adding an available field with a sort order.

    The available fields are defined in SearchConstants#FIELDS: ID, DOCUMENTTYPE, NAVIGATION_PATHS, NOT_SEARCHABLE, SUBJECT_TAXONOMY, LOCATION_TAXONOMY, TITLE, TEASER_TITLE, TEASER_TEXT, KEYWORDS, MODIFICATION_DATE, CREATION_DATE, TEXTBODY, SEGMENT, COMMERCE_ITEMS, CONTEXTS, AUTHORS, HTML_DESCRIPTION, VALID_FROM, VALID_TO, EXTERNALLY_DISPLAYED_DATE

    To configure custom fields, a specific bean can be configured, see section below.

    Possible order field values: ASC, DESC

  • siteId: The siteId. The siteId is mandatory in order to retrieve the configured facets per site.
  • facetFilters: List of FacetFilter input objects with one ore more configured facets. Optionally with facet values to be excluded from the faceted search result. If no FacetFilter is given, all configured facets are calculated automatically.

    The input type FacetFilter consists of these parameters:

    • facetAlias: Mandatory name of a facet as configured.
    • filterValues: Optional list of filter values for the given facet. The filter values are effectively a filter query on the configured field of the facet, e.g type on the standard field documenttype.
    • excludeInFacet: Defaults to true. If set false, the query clause with filter values is not excluded from facet calculation, resulting in a facet result with the given filter values only.
  • customFilterQueries: Like the generic search, the facet search can also be extended by custom filter queries. See Section 6.3, “Custom Filter Queries” for details.
    Note

    Note

    A faceted search query is a non trivial and complex query. Be aware, that additional queries using the custom filter queries, might affect the search result and the facet calculation in unexpected manners.

By default, the FacetedSearchAdapter employs DefaultFacetedSearchServiceProvider, which in turn uses the caeSolrQueryBuilder Spring bean. caeSolrQueryBuilder invokes searches on Solr on the cmdismax endpoint. For details, seeSection 3.8.1, “Details of Language Processing Steps” in Search Manual.

The used FacetedSearchServiceProvider is at the same time an ExtensionPoint, which can be implemented and provided by a plugin. See Section 4.16, “Plugin Support” for details.

Search Suggestions

Suggestions are a very popular feature for any search on a website. Suggestions are calculated simultaneously and then provided as an optional list to choose from, thus relieving the user from typing the full search expression.

The Headless Server is able to provide suggestions for search query expressions.

{
  content {
    suggest(
      query: "sal"
    ) {
      value
      count
    }
  }
}

Use these parameters to issue a search suggestion query.

  • query: The search query.
  • docTypes: Content types to restrict the search result.

    Misspelled content types and invalid content types will cause a graphql error in the response. When passing an abstract content type, the subtypes are retrieved, if the parameter includeSubTypes = true. Passing an abstract content type with includeSubTypes = false will also cause a graphql error. The search result does not contain abstract content types, only the concrete sub types.

  • siteId: The siteId can be passed as parameter to restrict search per site.
  • includeSubTypes: A Boolean flag, indicating to include the sub types of the given doc types in the search. Defaults to 'false'.
  • customFilterQueries: Like the generic search, the search suggestions can also be extended by custom filter queries. See Section 6.3, “Custom Filter Queries” for details.

By default, the SuggestionAdapter employs DefaultSuggestionSearchServiceProvider, which in turn uses the suggestionsSolrQueryBuilder Spring bean. suggestionsSolrQueryBuilder invokes searches on Solr on the suggest endpoint. For details, seeSection 3.8.1, “Details of Language Processing Steps” in Search Manual.

The used SuggestionSearchServiceProvider is at the same time an ExtensionPoint, which can be implemented and provided by a plugin. See Section 4.16, “Plugin Support” for details.

Configuration of custom SOLR fields

To configure a custom field of the SOLR index, a bean with qualifier customSolrFields can be added to the Spring context.

This bean of type Map<String, String> contains the custom field's name as a constant accessor and the field name in the SOLR index, e.g. TITLE, title.

This custom field can then be used, e.g. to apply a sort order.

The customSolrFields are applied to the SolrQueryBuilder.

The default SOLR fields are defined in the class SearchConstants, these are the default fields of the SOLR CAE index.

Generic configuration

The connection to Solr is defined with solr.url

The search index is specified with property caas.search.solr.collection

Caching is only performed in live mode and can be configured with caas.search.cache.seconds

Configuration of a custom index

If search should be performed on a custom SOLR index, the SolrQueryBuilder must be extended and configured. The following constructor arguments can be passed:

  • searchHandler: the search handler, e.g. /cmdismax
  • filterQueryDefinitionMap: a map containing filter query definitions to be used by custom filter queries
  • customFields: custom fields of the SOLR index as map containing the field name and the SOLR field name, e.g. TITLE, title

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.