Understanding Search Blueprints
Use search blueprints to tailor the search page experience to your users’ needs, without deploying custom code. With blueprints you can
- Create context-aware search pages. For example, boost Web Content articles by proximity to the search user.
- Explicitly declare which fields are searched. For example, you can choose not to declare the
userNamefield. - Boost assets with a certain category for a specific period of time. For example, create a seasonal campaign to promote Liferay Commerce products by category.
- Any use case served by the Custom Filter widget can be satisfied with blueprints. For example, boost certain fields that match the searched keyword.
If you need control over what should be searched or how the search should work, Search Blueprints is the feature you need.
How the default Liferay search experience is configured has evolved over time. In the latest Liferay DXP release, out-of-the-box you can tune the search results (synonym sets and result rankings), add custom facets, and use custom filters to perform complex search customizations. These configurations have limits, though, and many search-heavy sites require customizations of the search infrastructure’s backend code. This requires deploying Java-based modules to Liferay’s OSGi runtime.
Instead of building on this code-heavy feature set, blueprints takes a different approach, for the user who needs near-complete control over the search page’s query without deploying custom code. Blueprints offers a UI-based configuration experience that can satisfy almost every use case (if not in the earliest iteration of the feature, in subsequent versions where the feature set is even more robust).
What is a Blueprint?
You build search blueprints using elements and core configurations that define how Liferay handles search requests.
Blueprints: 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.
Elements: These are the building blocks you combine to build a blueprint. Each element is backed by a JSON fragment that defines a specific search behavior. You can use out-of-the-box elements or use the element editor to create your own. Because these elements function by adding logic to the search request, you must consider how they interact with the blueprint’s core settings.
How Blueprints Combine Query Clauses
Blueprints function as additive layers that inject custom clauses into the final search request. The resulting query is a combination of your custom elements and the blueprint’s core configuration, which is driven by three factors:
-
Scope: Use this to filter results based on specific sites, asset libraries, or spaces.
-
Searchable Types: Use this to manage the logic contributed by selected asset types (e.g., basic web content, blogs, or documents).
-
Framework Contributors: Use these advanced settings to toggle specific generic or asset-specific query contributors.
Query elements can conflict with default system query clauses, such as permission or publication filters. Always use the Preview tool to test your configuration to ensure the final search request aligns with your expectations.
To create a blueprint, start with the use case you have in mind. Determine how you want to modify the default search experience, then look at the provided elements and see if they can be used to start building your customization. Once you’ve planned the blueprint, it’s time to create it.
For more details see Creating and Managing Blueprints.
What Can I Do in the Blueprints UI?
To produce a search solution using blueprints, compose elements into a blueprint and apply it to the page. The features available for doing so include:
| Feature | Available in Blueprints? |
|---|---|
| Use the Query Builder to build Blueprints visually | ✔ |
| Compose Blueprints with JSON in the Liferay UI | ✔ |
| Leverage out-of-the-box Elements to simplify Blueprint creation | ✔ |
| Use Elasticsearch queries as custom Elements | ✔ |
| Create custom Elements from Elasticsearch queries | ✔ |
| Create custom JSON Elements for my Blueprints | ✔ |
| Create advanced Blueprints settings by editing the JSON directly | ✔ |
| Choose which Liferay Entities are searchable when the Blueprint is applied | ✔ |
| Choose whether to include clauses from Liferay’s Indexer Framework and individual query clause contributors | ✔ |
| Using JSON, configure advanced settings: Aggregations, Sorts, Highlights, etc. | ✔ |
| Limit the blueprint scope to specific sites, asset libraries, or spaces | ✔ |
In addition to the functionality of the search blueprints UI, the search widgets were enhanced to support applying blueprints to the search page.
Understanding the Search Request
Blueprints are how you control the contents of Liferay’s search request to Elasticsearch. Therefore it’s helpful (though not necessary to get started) to pair your understanding of how the user’s search experience works with a high level understanding of the default Liferay search query’s main components.
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.
The main Liferay query is a bool parent query that wraps a multitude of child queries. It consists of two main occur clauses: must and filter. Blueprints can affect both clauses. Filter type elements are added to the filter clause, and query type elements are added a clauses under the must boolean clause.
All Liferay searches are eventually translated to JSON Elasticsearch queries. Here’s just a small snippet of the query generated by entering the word “test” into the Search Bar widget:
{
"from": 0,
"size": 20,
"query": {
"bool": {
"must": [
{
"bool": {
"must": [
{
"bool": {
"should": [
{
"bool": {
"must": [
{
"match": {
"comments": {
"query": "test"
}
}
}
],
"should": [
{
"match_phrase": {
"comments": {
"query": "test",
"slop": 50
}
}
},
{
"match_phrase": {
"comments": {
"query": "test",
"boost": 2
}
Drilling down a little bit, the following boolean query dictates that a match query must be met for the search term “test” in the content field if the clause is to contribute to the score of a matching result. In addition, if a match phrase query on the content field is matched, the result’s score is boosted by a value of 2.
{
"bool": {
"must": [
{
"match": {
"content": {
"query": "test"
}
}
}
],
"should": [
{
"match_phrase": {
"content": {
"query": "test",
"slop": 50
}
}
},
{
"match_phrase": {
"content": {
"query": "test",
"boost": 2
}
}
}
]
}
}
These are the types of clauses you’re adding with Elements.
The search request parts can be mapped to the Blueprints UI and its configuration options:
