io.sphere.sdk.meta.ProductSearchDocumentation Maven / Gradle / Ivy
package io.sphere.sdk.meta;
import io.sphere.sdk.models.Base;
import io.sphere.sdk.products.search.ProductProjectionSearchModel;
/** Products can be retrieved using full-text search, filtering, faceting and sorting functionality combined.
Even though the {@link io.sphere.sdk.meta.QueryDocumentation Query API} lets you query for resources with certain attribute values, its performance is seriously affected by some attributes, specially by custom attributes, when manipulating data (i.e. filtering, sorting). Moreover, some typical operations over a list of resources, such as full-text search, are simply not supported.
The Search API is specially designed to support those uses cases where the Query API is not powerful enough, by providing not only full-text search, filtering, and sorting, but also statistical analysis of the data with facets.
The search endpoints are supposed to be faster than the query endpoints, but for the price of eventual consistency. In other words, whenever the name of a product was changed, it will still take some seconds to propagate this change to the search index.
Currently only products have a search endpoint for {@link io.sphere.sdk.products.ProductProjection} only. Therefore, be aware that the class to create a search request for products is called {@link io.sphere.sdk.products.search.ProductProjectionSearch}.
The following examples in this document are based on the search for products. The product data defined in the SPHERE.IO platform used for the following code examples are:
Product
Product1 "shoe"
Product2 "shirt"
Product3 "dress"
Variant
1
2
1
2
1
2
Color
blue
red
blue
Size
38
46
36
44
40
42
Full Text Search
With {@link io.sphere.sdk.products.search.ProductProjectionSearch} you can perform a full-text search for a specific language. On the Full-Text Search documentation page you can explore which fields are included for the search and other additional information.
The following example searches for all products containing the word "shoe" in English:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#searchByTextInACertainLanguage()}
Pagination
Use {@link io.sphere.sdk.search.SearchDsl#withOffset(long)} and {@link io.sphere.sdk.search.SearchDsl#withLimit(long)} for pagination. An extended explanation about how pagination works in SPHERE.IO can be found in {@link io.sphere.sdk.meta.QueryDocumentation}.
The following request skips the first 50 products and limits the result set to only 25 products:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#paginationExample()}
Sorting
Any attribute you can sort by, allows both sort directions, ascending and descending. On the Sorting documentation page you can explore for which fields you can sort for. Use {@link ProductProjectionSearchModel} class to build sort expressions easily.
The code sample below shows a request for all products which will be sorted by size in an ascending direction:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#sortByAttributeAscending()}
When sorting on product custom attributes, you can also choose which variant should be used for sorting. By default, the values are sorted through variants internally, selecting the best-matching variant according to the sorting direction. This behaviour can easily be inverted, as explained in the Sorting by Attributes documentation page.
In the following example the products are sorted by size in an ascending direction, but sorted by size with the highest value within each product variants instead:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#sortWithAdditionalParameterByAttributeAscending()}
Alternatively, you can provide the sort request directly, even though this method is unsafe and therefore not recommended.
Here is the alternative code equivalent to the previous sorting by size:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#sortWithSimpleExpression()}
Filtering
Types
When searching for products, there are three stages of the process where filters can be applied, as shown in the following drawing:
Filter types
- Filter Query: {@link io.sphere.sdk.search.SearchDsl#withQueryFilters(java.util.List)}.
- This parameter allows to filter products BEFORE facets have been calculated, therefore this scope affects both results and facets.
- Filter Results (in the HTTP API it is called just "filter"): {@link io.sphere.sdk.search.SearchDsl#withResultFilters(java.util.List)}
- This parameter allows to filter products AFTER facets have been calculated, therefore this scope affects the results only. Using this filter only makes sense when used together with facets, otherwise Filter Query should be preferred.
- Filter Facets: {@link io.sphere.sdk.search.SearchDsl#withFacetFilters(java.util.List)}
- This parameter allows to filter those products used for facets calculation only, without affecting the results whatsoever. All facet calculations are affected except for those facets operating on the same field as the filter, enabling multi-select faceting when combined with Filter Results.
Does it filter results?
Does it filter facets?
Filter Query
Yes
Yes
Filter Results
Yes
No
Filter Facets
No
Yes
No filter
No
No
For further explanation, some diagrams regarding the filter mechanism can be found in the Filters and Facets presentation.
Expressions
You can easily build filter expressions with the {@link ProductProjectionSearchModel} class. For more details, check the HTTP API documentation for Filters.
In the following example only the products with red color are returned:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#filtersByTerm()}
Besides filtering by terms, you can also filter by a range of values, as shown in the following code.
Here we are requesting only those products with at least one variant having the size attribute greater than or equals to 44:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#filtersByRange()}
There is also the possibility to provide the filter expression directly, although it is unsafe and thus not recommended.
In the following example the same filter by size is requested as previously, but now in this way:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#simpleFilterByRange()}
Faceting
Expressions
Facets calculate statistical counts based on the values associated with a product attribute. Building facet expressions is very easy thanks to the {@link ProductProjectionSearchModel} class. You can consult the Facets HTTP API documentation for more information.
There are three types of faceted search: {@link io.sphere.sdk.search.TermFacetResult}, {@link io.sphere.sdk.search.RangeFacetResult} and {@link io.sphere.sdk.search.FilteredFacetResult}. Next are presented example codes of each type to better illustrate how these facet types work.
The Term Facet result obtained with the following code contains all different size values found in the products, along with the statistical count of the amount of product variants with that value associated:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#termFacetsAreParsed()}
In contrast, the Filtered Facet result contains the statistical count for a single value specified in the request, in this case the amount of variants with blue color:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#filteredFacetsAreParsed()}
You can also request statistics (i.e. count, minimum and maximum values, as well as the sum and arithmetic mean) about a range of values, like it is done with size in the following example within the range [0, +∞):
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#rangeFacetsAreParsed()}
There is also the possibility to provide the facet expression directly, although it is unsafe and thus not recommended.
In the following code the same request as in the Term Facet example is reproduced, but providing a facet expression now instead:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#simpleFacetsAreParsed()}
Alias
Additionally, facets allow to specify an alias which will then replace the attribute path in the result. This functionality allows to calculate different types of facets on the same attribute. There is an extended explanation with examples in the API documentation for Facets.
In order to use it, there is a method that allows to define the desired alias:
{@include.example io.sphere.sdk.products.ProductProjectionSearchIntegrationTest#filteredFacetsSupportsAlias()}
Product Projection Search Model
The Search Model for products is currently in an experimental status, so please be aware it will probably suffer breaking changes in the future.
The {@link ProductProjectionSearchModel} class offers a domain-specific language (DSL) to build expressions accepted by the search endpoint, which can be otherwise a bit complex to write. In particular, this DSL allows you to build expressions for sorting, filtering and faceting, as it is demonstrated in the corresponding sections.
In order to build an expression, first you will be required to select the field you want to search for (e.g. price or a custom attribute). In the case of custom attributes, you also need to provide the attribute name and select the primary type of the attribute. Notice that {@link io.sphere.sdk.products.search.ProductAttributeSearchModel#ofBoolean(java.lang.String)} method enables search on both boolean and boolean set attributes.
The next step is selecting the type of expression you want to obtain: sort, filter or facet. Finally, you need to indicate the criteria used for the desired operation.
*/
public final class ProductSearchDocumentation extends Base {
private ProductSearchDocumentation() {
}
}