Search Queries and Filters

To get sensible results from the search engine, you must provide a sensible query.

Queries and Filters in Liferay’s Search API

Elasticsearch and Solr do not make API level distinctions between queries and filters. In the past, Liferay’s API explicitly provided two sets of APIs, one for queries and one for filters. Both APIs lived in portal-kernel (the 7.1 source code for filters is here).

In Liferay DXP 7.2, there’s a new way of querying and filtering via Liferay’s Search API, and the APIs for it live in the portal-search-api module. Instead of calling specific filter APIs, you’ll now construct a query and add it to the search request, specifying it as a filter using the SearchRequestBuilder.postFilterQuery(Query) method. See the 7.2 Query APIs.

Despite the more unified filtering and querying code, you should understand the functional difference between filtering and querying:

Filters ask a yes or no question for every document. A filter might ask is the status field equal to staging or live?

Queries ask the same yes or no question AND how well a document matches the specified criteria. This is the concept of relevance scoring. A query might ask Does the document’s content field field contain the words “Liferay”, “Content”, or “Management”, and how relevant is the content of the document to the searched keywords?

Supported Query Types

Liferay’s Search API supports the following types of queries:

Full Text Queries

Full text queries are high-level queries usually used for querying full text fields like the content field of a Blogs Entry. How terms are matched depends on the query type.

Supported Full Text Queries


Here are some common full text queries:

  • Match Query: A full text query, scored by relevance.
  • Multi Match Query: Execute a MatchQuery over several fields.
  • String Query: Use Lucene query syntax.

Term Queries

Term queries look for exact matching on keyword fields and indexed terms.


Here are some common term queries:

  • Wildcard Query: Wildcard (* and ?) matching on keyword fields and indexed terms
  • Fuzzy Query: Scrambles characters in input before matching

Compound Queries

Compound queries are often used to wrap other queries. They’re commonly used to switch from query to filter context.


Here are some common compound queries:

  • Boolean Query: Allows a combo of several query types. Individual queries are as clauses with SHOULD | MUST | MUST_NOT | FILTER
  • Constant Score Query: Wraps another query, switches it to filter mode, and gives all returned documents a constant relevance score.

Joining Queries

The concept of a join doesn’t work well in a distributed index. Joining queries allow similar behavior in the search index, such as using the nested datatype to index an array of objects that can be queried independently, using the NestedQuery.


Nested Query: Query nested objects as if they each had a separate document in the index.

Geo Queries

In Elasticsearch, you can index latitude/longitude pairs and geographic shapes. Geo queries let you query for these points and shapes.


A common Geo Query is the GeoDistanceQuery, used to find documents within a certain distance of a geographic point (latitude/longitude).

Specialized Queries

These queries don’t fit into another group:

  • More Like This: Use a document to query for similar documents.
  • Percolate: Match individual documents against indexed queries (for alerting to new documents of interest, or automatically categorizing documents).
  • Script: Filter based on a script.

Other Queries

MatchAllQuery Matches all documents in the index.

The proper search query is entirely context- and search engine-specific, so you should read the Query documentation straight from Elasticsearch or Solr to determine which queries are available and what they do.

All the recommended and supported queries and filters are found in the portal-search-api module’s and packages.

Legacy queries and filters, which are still supported but moving towards deprecation, are found in the* packages provided by portal-kernel.

Using Queries

Here’s the generalized approach for querying and filtering search documents in your own search code:

  1. Instantiate and construct the query object.
  2. Add the query to the search request—the method you use determines whether the context is filtering or querying (or both in the same request).
  3. Execute the search request.
  4. Process the search response.

These steps are covered in more detail (with examples) in the next article.

Search Queries in Liferay’s Code

The APIs for creating queries are best exemplified in Liferay’s own test cases. For example, BaseTermsQueryTestCase constructs a search request containing a TermsQuery using the Queries API:

TermsQuery termsQuery = queries.terms(Field.USER_NAME);

This code executes the search request with the terms query constructed above in a query context.

Other query test cases are also available to reference in the portal-search module’s source code.

External References

Search Engine Connector Support

  • Elasticsearch 6: Yes
  • Solr 7: No* (Only the “legacy” query types from* are supported as of Liferay DXP Beta 2.)

New/Related APIs

PackageProvided by ArtifactNotes* of the provided query types are new as of 7.2* of the provided filter types are new as of 7.2
« Search Service RegistrationBuilding Search Queries and Filters »
¿Fue útil este artículo?
Usuarios a los que les pareció útil: 1 de 2