logo

Get in touch

Awesome Image Awesome Image

Liferay May 29, 2023

Liferay Search Blueprint: Improving the Search Experience

Written by Mahipalsinh Rana

23,669

A Search Blueprint is a design plan for Liferay’s search behavior. The search experience starts at a Search Bar for most users. When a search term is entered, a complex query is constructed by Liferay’s search infrastructure, then sent to the search engine. You can see Liferay’s complete query using the Search Insights widget. This query can be thought of as Liferay’s default blueprint for the search page, controlling what is searched and how. 

This document/blog will provide a comprehensive guide to Liferay Search Blueprint. We will cover the following topics:

  • How does search work in Liferay?
  • How to create a Liferay Search Blueprint.
  • What Can I Do in the Blueprints UI?
  • Advanced: Configuring Query Clause Contributors
  • Search Blueprints Configuration Reference.
  • How to apply search blueprint into search page.
  • Search Blueprint use case. 

How does search work in Liferay?

Search Request: Liferay sends a search request to Elasticsearch, which can include the query body and additional parameters that help direct the response returned by Elasticsearch.

Query: The query body instructs the search in how to determine if matching content is found in the index. For example, what kind of query should be used when searching indexed content containing a title field? And if it matches the title field, should the score be boosted? 

Clause: A clause is a self-contained portion of the main bool query. Most often one of the more nested queries is what’s referred to when the word clause is invoked. 

What Can I Do in the Blueprints UI?

Create an element-based Blueprint, then apply it to the page to create a search solution. The features available for doing so include:

Available in Blueprints

Blueprints are made up of Elements with some additional settings on top.

Elements: 

Elements are visual building blocks that combine to build an entire Blueprint. Each Element is backed by a JSON fragment that defines a concrete search behavior. Elements are provided out of the box with Search Experiences, and an Element editor lets you create your own or duplicate the existing elements to use as starting points for your own needs. We can also include our own unique element clicking (+) button. 

Blueprints

Advanced: Configuring Query Clause Contributors

Liferay’s back-end code (and potentially any custom applications deployed in your Liferay instance) contributes query clauses to the ongoing search.

These clauses contributed by the back-end can be configured via Search Blueprints. However, most users should never touch two settings:

  • Search Framework Indexer Clauses
  • Search Framework Query Contributors 

Liferay’s back-end code (and potentially any custom applications deployed in your Liferay instance) contributes query clauses to the ongoing search.

These clauses contributed by the back-end can be configured via Search Blueprints. However, most users should never touch two settings:

  • Search Framework Indexer Clauses
  • Search Framework Query Contributors

The default settings are usually enough. If you’re sure you must tweak this behavior beyond using the Searchable Types, you must understand the way these back-end contributors work:

  1. Use Searchable Types to disable individual indexers from participating in the search. If you disable a type’s indexer, no clauses for the type are added to the search query, even if its Query Contributors are selected. Results for these types do not appear for users.
  2. Use Search Framework Indexer Clauses to disable all Liferay’s indexers from contributing clauses to the search. The only reason to disable all indexers is to build a search query from scratch, disabling all Query Contributors and Searchable Assets as well.
  3. Use the Search Framework Query Contributors section to remove certain contributors from participating in the search. Disable certain clause contributors if you want to override them using your own Blueprints configuration, or disable all clauses to completely override Liferay’s search behavior, disabling Liferay’s Indexers and Searchable Types as well. 

Search framework Indexer Clauses

As an example, if the administrator does not want Liferay to create articleId clauses in request queries, we can disable the journal article query contributor setting. See the image below.

Quick Builder

 

After that setting liferay not including below clauses into search query. You can also verify that by adding a search insight widget to the search page and see the search request query string. 

 

{"bool": {
               "should": [
                   {"match_phrase": {"articleId": {
                       "query": "kotlin",
                       "slop": 50
                   }}},
                   {"match_phrase": {"articleId": {
                       "query": "kotlin",
                       "boost": 2
                   }}}
               ],
               "must": [{"match": {"articleId": {"query": "kotlin"}}}]
           }},

Creating Search Blueprints

To create Search Blueprints,

  1. Open the Blueprints application by clicking Blueprints from Global Menu → Applications (Search Experiences).
  2. Add a Blueprint by clicking Add ().New Search BlueprintCreate a blueprint
  3. In the New Search Blueprint window, give the Blueprint a name (required) and a description (optional).
  4. Depending on your Blueprint plan, next you’ll use these menus to continue building the Blueprint:    a. Query Builder: in the Query Elements section, add new query clauses to the search by choosing or composing Elements for the Blueprint. In the Query Settings section, configure additional settings for the query (like which asset and object types to search).     b. Configuration: Configure advanced settings (e.g., Sorts or Aggregations) in the search.
  5. Once you’re finished with the initial Blueprint creation, Click Save.

Adding Elements to blueprint

  1. Open the Add Query Elements sidebar by clicking the Add (+) button on the Query Elements screen.Query Elements
  2. Expand the Element category you’d like to explore Link.
  3. Hover over the Element, then click the Add button.
  4. The Element is added to the Query Builder, ready to configure: as an example i add boost all keyword match element to blueprint, see the below image. 

Demo Blueprint

In Above image, the configured element, when a search keyword matches in the title field, assigns 4000 boosts. You can see the result by clicking on the Preview button.

  1. After adding Elements, make sure you save the Blueprint.

We can also add our custom Elasticsearch query into the blueprint. 

Query Element

Choosing which Liferay Assets to Search

Decide which Liferay Asset Types to include in the Blueprint’s query. Use Query Settings → Searchable Types: 

Query Setting

  • All asset and object types are selected by default.
  • To remove specific types, click Select Asset Types to open the Select Types, then de-select the corresponding checkboxes. 

Select Type

Adding Configurations

In addition to micromanaging the search query, add Search Blueprint settings add JSON configurations for

  • Aggregations
  • Highlights
  • Sorts
  • Parameters
  • Advanced Configurations 

Aggregation Configuration

Configure Aggregations in the Search Blueprint. Aggregations take the results of a query and group the data into logical sets. Aggregations can be composed to provide complex data summaries.

Aggregations added in Search Blueprints are applied in addition to those already present in the search request (e.g., from facets).

Note

  1. From the Blueprint editor, click the Configuration tab.
  2. Find the Aggregation Configuration text area and enter valid JSON. Use the Elasticsearch DSL to craft the JSON. 

{
  "aggs": {
     "date_histogram-test": {
        "date_histogram": {
           "date_histogram_interval": "minute",
           "field": "modified",
           "min_doc_count": 1,
           "order": {
              "_count": "desc"
           }
        }
     }
  }

In the above json query, you are defining an aggregation named “date_histogram-test” using the “date_histogram” aggregation type. The purpose of this aggregation is to generate a histogram of documents based on the “modified” field, grouping them into intervals of one minute. 

Output: clicking by view raw response button on top right corner in blueprint ui. 

Raw Response

Highlight Configuration

Configure Highlights in Search Blueprints. If you add a highlight configuration in Search Blueprints, it overrides the default search highlight configuration.

To add a Highlight to a Blueprint,

  1. From the Blueprint editor, click the Configuration tab.
  2. Find the Highlight Configuration text area and enter valid JSON. The properties and their possible values are detailed in the Elasticsearch documentation.

{
  "fields": {
     "lastName": {}
  },
  "post_tags": [
     "</liferay-hl>"
  ],
  "pre_tags": [
     "<liferay-hl>"
  ],
  "require_field_match": true

Highlight Configuration

Output: 

Test Test

 

Sort Configuration

Configure Sorts in Search Blueprints. Sorts added via Search Blueprints are applied in addition to those already in the search request (e.g., from the Sort widget). However, Sorts added in a Search Blueprint are not reflected in the Sort widget’s UI or configuration screen. 

Warning

Add into the sort configuration box.
{
  "sorts": [
     {
        "publishDate_sortable": "desc"
     }
  ]

Output: sort document according to publishDate (Desending order). 

Demo Bluepoint

Advanced Configuration 

Warning

The Advanced Configuration adds source includes and excludes as search request parameters. The _source field contains the stored document body that was passed to the index request. This field is not itself indexed. The Advanced Configuration in Blueprints lets you prune the _source field by specifying what fields to include or exclude from the field. As it overlaps in functionality and may conflict with the Low Level Search Option widget’s Fields to Return configuration, you must not use both approaches in tandem. To add an Advanced configuration to a Blueprint,

  1. From the Blueprint editor, click the Configuration tab. 
  2. Find the Advanced Configuration text area and enter the excludes and includes you need. 

{
  "source":{
      "excludes":[
          "<fieldName1>", // [example- “title_en_US”]
          "<fieldName2>"
      ],
      "fetchSource":true,
      "includes":[
          "<fieldName3>",
          "<fieldName4>"
      ]
  }

Search blueprint Use Cases

Blueprints is a powerful tool that can be used to customize the search experience for users and to improve the relevance of search results.

  • Boosting search results for important content. You can use boosting to ensure that important content is always displayed at the top of the search results, For example, you could boost search results for the newest job post display first.
  • Personalizing the search experience: Blueprints can be used to personalize the search experience for users by adjusting the ranking of search results based on factors such as the user’s location, interests.
  • Improving the relevance of search result:. Blueprints can be used to improve the relevance of search results by adding additional filters and criteria to the search query. For example, you could use a Blueprint to only return results that were created within the last 30 days or that were authored by a specific user.
  • Managing search results: Blueprints can be used to manage search results by adding, removing, and rearranging the fields that are displayed in the search results list. You can also use Blueprints to change the order in which the results are displayed.
  • Improved user experience: By personalizing search results, you can improve the user experience and make it easier for users to find the information they are looking for. 

Add Blueprint to search page

By default, a search page does not have a search blueprint associated with it. A blueprint must be applied to a search page to affect the Liferay search experience. If a site has multiple search pages, follow the steps below on each page that should use a blueprint, as each must be configured separately. You can use different blueprints on each page, if desired.

  1. Add blueprints options widget into search pageAdd Bluepoint
  2. After adding a widget , select our blueprint by clicking the configuration button. 
  3. Click the save button to save the configuration.
  4. Search your keyword from the search bar and search result are retrieve according to selected blueprint.Liferay DXP

Example

How to Use Liferay Search Blueprint Boosting Date Wise to Promote New Content.

Suppose you have a blogs website. You want to make sure that new blogs are always visible to users, so you can use boosting to promote new blogs.

You can create a blueprint that boosts search results for blogs that were published within the last 30 days or your requirement. This will ensure that new blogs are always displayed at the top of the search results. Using a range Elasticsearch query we archived that requirements. 

Paste any Elasticsearch query

Conclusion

In conclusion, Liferay Search Blueprint is a powerful tool that enables organizations to customize and improve the search experience within their Liferay portal. By creating a blueprint, administrators can define the search behavior, control what is searched and how, and enhance the relevance and personalization of search results. We can also define aggregation, sort, and highlights in query.

With over 20 years of industry experience, our CTO is a distinguished expert in Liferay Enterprise DXP, AI/ML, and a broad array of cutting-edge technologies including Enterprise Search, ElasticSearch, Java, Spring Boot, .NET, Microservices, Python (Django, FastAPI, Flask), ReactJs, and NodeJs. As a seasoned Technical Architect, he has a proven track record of leading complex, large-scale projects across diverse industries.

Bringing Software Development Expertise to Every
Corner of the World

United States

India

Germany

United Kingdom

Canada

Singapore

Australia

New Zealand

Dubai

Qatar

Kuwait

Finland

Brazil

Netherlands

Ireland

Japan

Kenya

South Africa