Submit Feedback

Creating and Managing Search Blueprints

You can create Search Blueprints from the Global menu’s Applications section → Search Experiences. If you already have a Blueprint and want to apply it’s functionality in a Liferay Search Page, see Using a Search Blueprint on a Search Page.

To create Search Blueprints,

Open the Blueprints application by clicking Blueprints from Global Menu → Applications (Search Experiences).
Add a Blueprint by clicking Add ().
In the New Search Blueprint window, give the Blueprint a name (required) and a description (optional).

As of Liferay DXP 2023.Q4+, the title and description fields are localizable. To provide translations, use one of these approaches:
1. After the blueprint is created, re-open the title and description modal, select the language and begin translating.
2. Use the Language Override application to provide a language key (e.g., search-for-new-content) and its translated values (e.g., Search for New Content in the English translation).
Depending on your Blueprint plan, next you’ll use these menus to continue building the Blueprint:
- 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).
- Configuration: Configure advanced settings (e.g., Sorts or Aggregations) in the search.
Test the Blueprint as you build and configure it. Click Preview and enter a search keyword.

See Testing a Blueprint for more details.
Once you’re finished with the initial Blueprint creation, Click Save.

The Blueprint creation process can be fast and simple, but sometimes involves iterating and testing. Make sure you save the Blueprint often to ensure your work is preserved.

Edit or delete a Blueprint from its Actions menu ().

You can also import and export Search Blueprints.

Using the Query Builder

Use the Query Builder to

Add Elements to the Blueprint.
Choose which Liferay assets to search.

Adding Elements to the Blueprint

Add Elements to begin adding query clauses to the Blueprint:

Open the Add Query Elements sidebar by clicking Add () on the Query Elements screen.
Expand the Element category you want to explore.
Hover over the Element, then click Add.
The Element is added to the Query Builder, ready to configure:
Add as many Elements as needed to configure the search query as desired.

See Search Blueprints Elements Reference for a description of each out of the box Element.
If any custom Elements are required, add the Custom JSON Element to the Query Builder and write the query clause you need.

See Creating Elements to learn about building Custom JSON Elements.

Important

Some Elements require more action than adding them to the Blueprint in the Query Builder. For example, to use the Boost Longer Contents element or the Boost Contents with More Versions element, you must reindex the following entries in Control Panel → Search → Index Actions:

com.liferay.blogs.model.BlogsEntry
com.liferay.document.library.kernel.model.DLFileEntry
com.liferay.journal.model.JournalArticle
com.liferay.knowledge.base.model.KBArticle
com.liferay.wiki.model.WikiPage

Other Elements require additional setup, like the Elements that provide geolocation features (e.g., Boost Proximity). For details, see the Elements Reference.

After adding Elements, make sure you save the Blueprint.

Choosing which Liferay Assets to Search

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

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.

Note

De-selecting all assets in the Searchble Types modal is identical to selecting all types: all asset and object types are searched. See Configuring Query Clause Contributors to learn about disabling most of Liferay’s search clauses.

Always save the Blueprint after editing its Searchable Types configuration.

Disabling an asset type in the Searchable Types configuration means that the query clauses usually contributed by its indexing code are excluded. The type isn’t searchable, and end users will not see results of the excluded type when the Blueprint is applied to a search.

More information appears below, as the Searchable Types configuration has important implications for the other clause contributors configuration options.

Advanced: Configuring Query Clause Contributors

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

These clauses contributed by the backend 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 backend contributors work:

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.
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.
Use the Search Framework Query Contributors section to disable all or 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.

Important

Liferay’s Indexer framework was refactored in Liferay 7.2, and most assets now use Query Contributors to add search query clauses to Liferay’s search. Wiki pages and knowledge base articles still use the indexer pattern; the clauses for these assets are always added to the search query when the setting Search Framework Indexer Clauses is enabled. You can disable all the indexers or tweak the search behavior of these assets by layering more clauses on top (boosting certain clause matches, for example).
Disabling all indexers and contributors isn’t a comprehensive override of Liferay’s contributed search clauses. Certain indexers and contributors contribute their clauses regardless of these settings.

When you edit the clause contributors or indexer behavior, make sure to save the Blueprint.

Adding Configurations

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

Aggregations
Highlights
Sorts
Parameters
Advanced Configurations

To add these, click the Configuration tab, then find the text entry box for the desired configuration. Enter your JSON, then save the Blueprint.

Here’s an example Sort that sorts the search results by the name field, in descending (reverse alphabetical–Z-A) order:

{
	"sorts": [
		{
			"title_sortable": "desc"
		}
	]
}

For more details see Search Blueprints Configuration Reference.

Importing and Exporting Blueprints

A Blueprint is a JSON object. Export the JSON of a Blueprint from one environment and import it into another. This can be useful when bringing the Blueprint from a staging and testing environment to production.

To export the Blueprint JSON,

Open the Blueprints application from the Global Menu → Applications → Blueprints (in the Search Experiences section).
From the list of Blueprints, open a Blueprint’s Actions () menu and click Export.

To import a Blueprint’s JSON definition,

Open the Blueprints application from the Global Menu → Applications → Blueprints (in the Search Experiences section).
Open the main Blueprints Actions () menu and click Import.
Choose a valid Blueprint JSON file. Valid Element JSON files can also be imported from this screen.
Click Import.

There’s a preview sidebar that’s handy for examining the results of a search backed by the Blueprint in progress. Access the preview by clicking the Preview button from the Edit Blueprint screen.

Here you can access these features:

For 7.4 U52+, click View Raw Request to see the entire search request string. From the Raw Request modal, you can copy the request to the clipboard or download it as a JSON file. This is the same request seen in the Search Insights widget on the search page.
Click View Raw Response to see the entire search response string. Here you can copy the response to the clipboard or download it as a JSON file. This is the same string you see in the Search Insights widget on the search page.
The score of each result appears to the left of the result title. Click the score to see the Score Explanation.
To expand a result and see all the fields of its returned document, click the right facing angle bracket to the right of the result title.

Some elements read search context attributes that you can provide or override manually. To test Blueprints with these elements, click the gear icon () to add search context attributes to the Blueprint preview search. Enter the key/value pair for the attribute, then click Done. Note that this attribute is only set for the Blueprint preview and isn’t saved with the Blueprint itself. You can configure these attributes on a Search Page. See Using a Search Blueprint on a Search Page for more information.

For example,

Add a new Vocabulary with a Category called administrative.
Add two new Web Content Articles; make sure both have test in the title field. Associate one of them to the category you created.
Create a new Blueprint and add the Conditional Element Hide Contents in a Category for Guest Users.
Select administrative in the Asset Category Names (ID) field, or enter the ID manually if you know it.
Open the Preview sidebar’s Attributes and enter

Key: user.is_signed_in

Value: false
Click Done, then enter a search for test.

Now only the uncategorized Web Content Article is returned. The other one has been hidden because of the search context attribute that causes the search to behave as if the search User is a Guest.

This example uses an Element that reads the context variable user.is_signed_in. By setting a value manually, you override the existing value so the Blueprint can demonstrate a certain behavior. Because a value already exists in the search context, setting it manually is optional. Other Elements have required custom parameters that do not exist within a normal search request’s context. These must be passed manually into the search context for the Element/Blueprint to function properly, whether testing the Blueprint from the preview sidebar or setting the Blueprint for use on a search page.

Setting the External Reference Code (ERC)

Liferay DXP 2023.Q4+/Portal GA102+

You can refer to the blueprint by its editable ERC, and this is recommended whenever possible. For convenience you can set the ERC to something memorable and human readable. From the blueprint editor, click Edit next to the ERC: