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
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
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
Supported Full Text Queries
CommonTermsQuery MatchPhraseQuery MatchPhrasePrefixQuery MatchQuery MultiMatchQuery SimpleStringQuery StringQuery
Here are some common full text queries:
- Match Query: A full text query, scored by relevance.
- Multi Match Query: Execute a
MatchQueryover several fields.
- String Query: Use Lucene query syntax.
Term queries look for exact matching on keyword fields and indexed terms.
ExistsQuery FuzzyQuery IdsQuery PrefixQuery RangeQuery RegexpQuery TermQuery TermsQuery TermRangeQuery TermsSetQuery WildcardQuery
Here are some common term queries:
- Wildcard Query: Wildcard (
?) matching on keyword fields and indexed terms
- Fuzzy Query: Scrambles characters in input before matching
Compound queries are often used to wrap other queries. They’re commonly used to switch from query to filter context.
BooleanQuery BoostingQuery ConstantScoreQuery DisMaxQuery FunctionScoreQuery
Here are some common compound queries:
- Boolean Query: Allows a combo of several query types. Individual queries are
as clauses with
- Constant Score Query: Wraps another query, switches it to filter mode, and gives all returned documents a constant relevance score.
The concept of a join doesn’t work well in a distributed index. Joining
allow similar behavior in the search index, such as using the
to index an array of objects that can be queried independently, using the
Nested Query: Query nested objects as if they each had a separate document in the index.
In Elasticsearch, you can index latitude/longitude pairs and geographic shapes. Geo queries let you query for these points and shapes.
GeoBoundingBoxQuery GeoDistanceQuery GeoDistanceRangeQuery GeoPolygonQuery GeoShapeQuery
A common Geo Query is the
GeoDistanceQuery, used to find documents within a
certain distance of a geographic point (latitude/longitude).
These queries don’t fit into another group:
MoreLikeThisQuery PercolateQuery ScriptQuery
- 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.
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
Legacy queries and filters, which are still supported but moving towards
deprecation, are found in the
Here’s the generalized approach for querying and filtering search documents in your own search code:
- Instantiate and construct the query object.
- 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).
- Execute the search request.
- 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
TermsQuery using the
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
module’s source code.
Search Engine Connector Support
- Elasticsearch 6: Yes
- Solr 7: No* (Only the “legacy” query types from
com.liferay.portal.kernel.search.*are supported as of Liferay DXP Beta 2.)
|Package||Provided by Artifact||Notes|
|com.liferay.portal.search.api||Most of the provided query types are new as of 7.2|
|com.liferay.portal.search.api||Some of the provided filter types are new as of 7.2|