Creating and Managing Search Blueprints

Create search blueprints to tailor the search experience to your users. You can find the search blueprints application in Global Menu () → Applications → Blueprints.

If you already have a blueprint and want to apply its functionality in a Liferay search page, see Using a Search Blueprint on a Search Page.

To create search blueprints,

Click Global Menu () → Applications → Blueprints.
Click New to create a new blueprint.

In the creation modal, you can toggle Collection Provider to use the blueprint’s search logic with Collection Display fragments. See Collections with Search Blueprints for more information.

For versions before Liferay DXP 2026.Q1, you must activate the LPS-129412 release feature flag to enable blueprints as collection providers.
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:
- After the blueprint is created, re-open the title and description modal, select the language, and begin translating.
- 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).
Use the Query Builder to define both the search logic and scope for your blueprint within a single interface. By combining these configurations, you can manage how content is found and where the search is performed without switching contexts.
- Define Search Scope: Restrict the search to specific sites, asset libraries, and spaces.
- Add Query Elements: Select from out-of-the-box elements or create custom JSON elements to define how the blueprint filters and ranks results.
- Manage Query Settings: Configure additional settings for the query (like which asset and object types to search).
If you do not define a specific scope, the blueprint searches all available content by default. Use these tools to ensure your search solution targets the precise data set required for your implementation.
Use Configuration to manage advanced search parameters, such as sorts and aggregations. From this interface, you can also enable or disable the collection provider for the blueprint.

Note

For Liferay DXP 2025.Q3 and Q4, you must enable the release feature flag to access collection provider settings.
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.

Creating blueprints often requires iterative testing. Save your progress frequently to preserve your configurations.

You can edit, delete, or export an existing blueprint from its Actions menu (). You can import a blueprint from the application’s Actions menu.

Using the Query Builder

Use the query builder to

Define the search scope.
Add elements to the blueprint.
Choose which Liferay assets to search.

You can use the scope configuration within the Query Builder to restrict search results to specific sites, asset libraries, or spaces. Using this dedicated setting is the recommended method for defining search boundaries, as it is more performant than manual filtering via query elements.

Go to the Query Builder tab.
Under the Scope section, click Select Scope.
Select the specific sites, asset libraries, or Spaces you want to search.
Click Save to save the blueprint.

If you do not select a specific scope, the blueprint searches across all available content by default.

When you define a scope within a blueprint, it acts as a strict boundary. Any scope requested at search time must be a subset of the blueprint’s defined scope; if a requested scope falls outside this boundary, the search returns no results.

Note

Use this native Scope setting instead of manual filtering via out-of-the-box or custom query elements. This method ensures a more intuitive configuration and provides a more performant way to define your search boundary.

Adding Elements to the Blueprint

Add elements to begin adding query clauses to the blueprint:

Go to the Query Builder tab, and click Add () on the Query Elements section.
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 be configured.
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.

Note

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.
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 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

By default, blueprints search across all asset types. You can restrict the query to specific content by configuring the Searchable Types settings.

Go to Query Builder → Source → Searchable Types and Subtypes.
Click Selected Types → Select Asset Types.
Use the selection modal to choose the specific assets or object definitions you want to include in the search.

From the searchable types section, you can target specific content, such as entries of a specific object definition, or further refine the scope by selecting subtypes (e.g., web content structures, document types, and dynamic data lists). In versions before Liferay DXP 2026.Q1, you must enable the LPS-129412 release feature flag to use subtype filtering.

Note

De-selecting all assets in the Searchable Types modal is identical to selecting all types; the blueprint searches all asset and object types. See Configuring Query Clause Contributors to learn about disabling specific search clauses.

Always save the blueprint after editing its searchable types configuration. If the blueprint’s collection provider is enabled, changing the searchable types may break existing fragment mappings. If you remove a type that is currently in use by a Collection Display fragment, you must manually update those mappings.

Disabling an asset type in the searchable types configuration excludes the query clauses typically contributed by its indexing code. As a result, the asset type is no longer searchable, and end users do not see results of that type when the blueprint is applied.

Searchable types control which assets participate in a search, but they also determine which backend query clauses are applied. The next section explains how searchable types, indexer clauses, and query contributors interact to shape search behavior.

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 selecting searchable types, you must understand the interaction between these three layers:

Searchable Types: Use this to disable individual indexers from the search. Disabling a type’s indexer prevents any clauses for that type from being added, even if its query contributors remain active. Results for these types do not appear for users.
Search Framework Indexer Clauses: Use this to disable all Liferay indexers from contributing clauses to the search. This is for building a search query entirely from scratch, disabling all query contributors and searchable assets as well.
Search Framework Query Contributors: Use this to disable specific or all contributors from participating in the search. Disable individual contributors to override them with your own custom blueprints configuration, or disable all clauses to override the default search behavior fully, including Liferay’s indexers and searchable types.

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

Beyond query elements, you can apply global search settings to a blueprint using JSON configurations. With these settings you gain precise control over the search response structure:

Enable as a Collection Provider: Registers the blueprint as a collection provider, enabling its results to be used in collection display fragments.

Aggregations: Define buckets of data to group search results, provide counts, or produce statistical summaries.

Highlights: Emphasize search terms within the results.

Sorts: Define custom ordering for search results.

Parameters: Pass variables into the search request.

Advanced Configurations: Access low-level search engine settings.

To add a JSON configuration,

Navigate to the Configuration tab.
Locate the desired setting’s text entry box.
Enter your JSON configuration. For example, add the following JSON to the Sort configuration to order results by the name field, in descending (reverse alphabetical–Z-A) order:
```
{
   "sorts": [
      {
         "title_sortable": "desc"
      }
   ]
}
```
Click Save.

For more details see Search Blueprints Configuration Reference.

Importing and Exporting Blueprints

A blueprint is a JSON object. Use the import and export functions to migrate blueprints between environments, such as moving a tested configuration to production.

To export the blueprint JSON,

Open the blueprints application by clicking Global Menu () → Applications → Blueprints.
From the list of blueprints, click Actions () for a blueprint and click Export.

To import a blueprint’s JSON definition,

Open the blueprints application by clicking Global Menu () → Applications → Blueprints.
Click the main blueprints Actions () menu on the top right 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:

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.

The search now returns only the uncategorized web content article. The categorized article is hidden because the manually set attribute 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:

This human readable ERC comes in handy when setting the blueprint on a search page or in a headless search request.

Managing Search Blueprints while Upgrading Elasticsearch

Following a major version upgrade of Elasticsearch, test your custom query elements and advanced configurations. Custom query elements, Elasticsearch Query elements, or advanced blueprints configurations (e.g., aggregation, highlight, sort) can break after a major Elasticsearch upgrade, since the APIs backing these features can change. Refer to the Elasticsearch Release Notes and Breaking Changes documentation. Liferay does not upgrade these API usages automatically.