oo

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,

  1. Open the Blueprints application by clicking Blueprints from Global Menu → Applications (Search Experiences).

  2. Add a Blueprint by clicking Add (Add).

    Start creating a Blueprint from the Add Blueprint modal window.

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

      You can translate the blueprint title and description.

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

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

  5. Test the Blueprint as you build and configure it. Click Preview and enter a search keyword.

    Preview a Blueprint before putting it in action.

    See Testing a Blueprint for more details.

  6. 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 (Actions).

You can also import and export Search Blueprints.

Edit, delete, or export a Blueprint from its Actions menu.

Using the Query Builder

Use the Query Builder to

  1. Add Elements to the Blueprint.

  2. Choose which Liferay assets to search.

Adding Elements to the Blueprint

Add Elements to begin adding query clauses to the Blueprint:

  1. Open the Add Query Elements sidebar by clicking Add (Add) on the Query Elements screen.

    Add Elements to the Blueprint.

  2. Expand the Element category you want to explore.

  3. Hover over the Element, then click Add.

  4. The Element is added to the Query Builder, ready to configure:

    This Element gives a boost of 10 to content found on sites the searching user is a member of.

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

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

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

Expand the Searchable Types drop-down to begin removing assets from the Search Blueprint.

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

The Select Types modal is used for bulk management of the assets to be searched.

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:

  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.

important
  • Even when you disable all Indexers and Query Contributors, certain mandatory clauses are always added by Liferay’s search framework. Therefore, you’re never truly building a query from scratch with Blueprints.

  • Liferay’s Indexer framework was refactored in Liferay 7.2. Some of Liferay’s core assets, like Web Content Articles and Folders, have not been updated to the new pattern. This has an impact on Search Blueprints because there are no Query Contributors for these assets. Therefore, the standard clauses for the assets are always added to the search query when Liferay Indexer Clauses is enabled. Therefore, a complete override of the Web Content Article’s clauses is not possible. You can, however, tweak the search behavior of these assets by layering more clauses on top (boosting certain clause matches, for example).

  • Due to internal limitations, you must choose to enable or disable all of Liferay’s Indexers. The other clause contributors can be managed more flexibly: choose to include all, none, or any subset of contributors you wish.

Disable certain clause contributors or all indexers from contributing clauses to the search query.

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

Additional settings can be configured using JSON.

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,

  1. Open the Blueprints application from the Global Menu → Applications → Blueprints (in the Search Experiences section).

  2. From the list of Blueprints, open a Blueprint’s Actions (Actions) menu and click Export.

To import a Blueprint’s JSON definition,

  1. Open the Blueprints application from the Global Menu → Applications → Blueprints (in the Search Experiences section).

  2. Open the main Blueprints Actions (Actions) menu and click Import.

  3. Choose a valid Blueprint JSON file. Valid Element JSON files can also be imported from this screen.

    Import Blueprints and Elements.

  4. Click Import.

Testing a Blueprint with the Preview Sidebar

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.

Preview a Blueprint before putting it in action.

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.

    View the raw response string returned from Elasticsearch.

  • The score of each result appears to the left of the result title. Click the score to see the Score Explanation.

    View the score explanation for a result.

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

    Inspect the document's fields.

Some elements read search context attributes that you can provide or override manually. To test Blueprints with these elements, click the gear icon (Gear) 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,

  1. Add a new Vocabulary with a Category called administrative.

  2. Add two new Web Content Articles; make sure both have test in the title field. Associate one of them to the category you created.

  3. Create a new Blueprint and add the Conditional Element Hide Contents in a Category for Guest Users.

  4. Select administrative in the Asset Category Names (ID) field, or enter the ID manually if you know it.

  5. Open the Preview sidebar’s Attributes and enter

    Key: user.is_signed_in

    Value: false

  6. 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 2023.Q4+/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 Edit next to the ERC:

Edit the ERC to be memorable and readable.

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

What’s Next

Capability: