- v1.0.0-latest-prod
Sometimes, it is necessary to perform a reindex of all documents in a Solr index. This can be performed from the "Reindex" section at the tenant level of the Broadleaf Admin.
From the browse view, we can see a complete history of all reindex processes, as well as their current statuses.
A reindex may be started using the "Create Job" button, which will open the following view.
From here, input a name for the reindex job (optional) and select the domain (such as product) to be reindexed. If product is selected, for example, all products for all catalogs of this tenant will be reindexed.
Once the reindex job is started, we can view real time stats of that particular job. These include how many documents were processed/expected to be processed, run time, errors that have occurred during the reindex process (if any), as well as basic performance statistics.
Some of these statistics, such as Processed Per Second, Queue Load Time, and Queue Processing Time can help track the performance of the full reindex process over time.
|
Note
|
In general, with the exception of search redirects, tweaking boosts on fields, or adding new search terms, there are few cases where it is necessary to modify search configuration directly via the admin, since changes to search configuration are generally accompanied by a code change. |
Search admin functionality is broken up into three separate sections: Fields, Redirects, and Type Ahead.
Fields: Defines fields that should be indexed and searchable.
Redirects: Defines terms that should perform a redirect.
Type Ahead: Defines which fields should be used, and what fields should be returned for type-ahead queries.
For in depth information on the above sections, refer to the search documentation.
The fields section of the admin has an overview of all indexable fields currently defined. By default some fields are already defined for product, customer, and order domains.
Below, we can see one of the default field definitions.
There is a lot of information here, so we’ll cover them each individually.
Label: A label. This is for display purposes in the admin only.
Indexable Type: The domain type for this field (e.g. Product).
List of Values: This should be set to "Yes" if this is a multi-valued field. In this example, these are product keywords, which is an array of strings. An example of a single valued field is the product name.
Abbreviation: If this field is to be returned in a search response, this is name used in that search response.
Combination of Multiple Property Paths: This setting allows combining multiple fields into a single field to be indexed. For example, concatenating multiple strings into a single field to be indexed.
Property Path: This is a JSON path mapping to the desired property (minus the preceding $.). This may also be a nested path.
For example, primaryCategory.name. JSONPath also allows for more advanced functionality if necessary. See the JSON path documentation here.
Variants: This indicates the field variants applicable to this field. These variants indicate how the field is indexed, as well as how the field is searched. Some additional notes around variants:
There should only be a single variant marked as Include in Results. This indicates that the field will be returned when a search request is performed.
It is not always necessary that a field is returned from a search request. You may want to search on a field, but the field is not necessary on your UI, for instance.
It is important to know the Java type of the field being indexed/searched. For example, Strings should be used for Collection<String>, but String would be used for a single String.
All multi valued variants are designated with (Multi). These should not be used on single valued properties.
These fields may directly impact search results.
|
Important
|
When using phonetic matching, it is crucial to make sure that the language(s) your applications use are supported by the configured Search Engine (e.g. Solr) and its analyzer, to avoid adverse search behaviors (e.g. irrelevant data being matched). Out of the box, Broadleaf uses Apache Solr and Beider-Morse Phonetic Matching (BMPM) analyzer for phonetic matching. For all the other analyzers and supported languages in Apache Solr, please see Solr’s Phonetic Matching Reference Guide for more details |
Faceting: See the section on faceting for information on facets.
Since 2.1.0-GA, Facets are managed independently from Fields. Before, they are embedded.
Sorting: Indicates this field may be sorted on. For example, product price or customer name would be useful fields to sort on.
Since 2.1.0-GA, Sort Options are managed independently from Fields. Before, they are embedded.
Is this field searchable: This indicates that a field may or may not be searched on. An example of a searchable field would be a product name, for instance. Searching on a product price, however, wouldn’t make much sense.
Queries: When a field is defined as searchable, the fields that are searched on must be defined in the Queries section from the list of defined Variants. For example, in the screenshot above, we see variants for Strings, Texts, Text Partials, and Spell Checks. However, in the Queries section, Spell Checks is not defined. This means that this field will not be used when performing a search. In general, if the field is searchable, then all of its Variants should be used in the Queries section. In this case, we have spellchecking enabled for this field, but we are not using that capability.
Query Type: There are three query types.
Word: Should be used when it is generally (but not always) known that this field will be a single string, or when single word matching is desired on a term with spaces.
Phrase: Should be used when searching on a phrase, and slop matching is desired. (See the Solr documentation on phrase slop for more information).
Phrase Exact: Should be used when wanting to match a phrase exactly with no phrase slop.
Boost: Indicates that matches on this field should be boosted in search results.
Internationalization: Set this to 'Yes' if this is a translatable field. Examples might include a product name or description.
|
Important
|
Since 2.1.0-GA, facets are managed outside of Field Definitions.
They are also Catalog Trackable using SEARCH_GROUP type Catalogs.
Their management view in the Admin is otherwise as it was before.
|
Faceting allows results in filterable values being returned when a search request is performed. This allows filters to be applied to specific fields. Examples of good candidates for faceting would be attributes like color, dimensions, brand, etc.
To configure a facet, select a variant type, label, and display order.
Variant Type: May be any field defined in the variants section. This must be a field that is designated as stored in the Solr schema.
Label: This value will be returned for display purposes, and is translatable.
Display Order: This will determine the order of this facet when displayed.
Since 2.1.0-GA, Facets should be assigned to Facet Groups and those to Search Settings. Search Settings group Facets and Sort Options to allow differentiation between the facets and sorts available in different Applications and between Admin and Storefront. This also allows defining default settings at the Tenant level and overriding them at the Application.
Setting up a relevancy rule allows for boosting specific documents that meet the specified criteria based on the rule type. This can allow for various strategies to boost a set of documents, for example
All documents containing a specific value should be boosted
All documents that match the query in the specified field should be boosted
All documents should be boosted based on the ordered value of a specified field
An example of a situation where you would wish to setup a relevancy rule may be:
The catalog contains Apple products such as iPad, iPhone, MacBook, etc.
If the customer is looks for something specific, like "Apple laptop", they would want to see relevant items like MacBooks.
This can be achieved by setting up a relevancy rule that matches the value "Apple" in the query and boosting on that keyword in the product document field for MacBooks.
To configure a relevancy rule, select the field, variant type, rule type, and other criteria.
Name: For display purposes in the Admin Management views.
Variant Type: May be any field defined in the variants section of the Field. This must be a field that is designated as stored in the Solr schema.
Active Start/End Dates: The timeframe that this rule should apply. The end date can be left empty and the rule will not expire.
Rule Type: This determines the type of rule being applied & how it should consider relevancy. The rest of the fields in this group are rendered based on the rule type selected.
Boost Value: This field applies for all rule types, and signifies the amount to boost a field in Solr. These boost are applied as a multiplicative function with all other boosts.
Search Term Match: Narrows the context that this rule should apply, by requiring that the search term matches the specified value. This can be a simple string contains, or can use RegEx to match.
In addition to setting up Relevancy Rules, you will also need to setup & assign Relevancy Rule Groups. Search Settings groups Relevancy Rules to allow differentiation between the relevancy rules available in different Applications and between Admin and Storefront. This also allows defining default settings at the Tenant level and overriding them at the Application.
Type ahead (or search suggestions) can be managed in the admin.
Type ahead configuration is separated into three sections: General, highlight fields, and suggestion fields.
This includes several basic configuration fields:
Name: This field is used when making a type ahead request, to determine which configuration to use. This involves adding a ?config=name parameter to the suggestion request.
Indexable Type: The indexable type that this configuration is used for.
Suggestion Limit: The maximum number of suggested queries to return.
Phrase Slop: The phrase slop (See the Solr documentation on phrase slop for more information).
Highlight prepend: Optional. Value that may be prepended to highlight suggestion results.
Hightlight append: Optional. Value that may be appended to highlight suggestion results.
Highlight prepend and append is simply a cosmetic feature to automatically apply styling to the suggestion result text, as shown in the following screenshot:
In this example, highlight append and prepend are <strong> and </strong>, respectively.
Highlight fields are the fields actually searched on during a type ahead search.
In most cases, product name with a field variant of Text Type Ahead is sufficient for product search. Adding additional highlight fields simply requires adding them to this screen.
Suggestion fields are extra content that can be returned in addition to search suggestions. They can also be faceted to have additional details on number of matches, like so:
{
"categories": [{
"categoryNames": "Hot Sauces", // (1)
"numResults": 10 // (2)
}]
}Extra fields returned based on the suggestion field configuration
Additional details on number of matches
By default, there are two suggestion fields configured for the Product Entity: Products and categories fields. This results in additional information that can be displayed on the front end like so:
Looking in the admin, if we open the out-of-box suggestion field configuration named products, we can see the defined fields:
These are the fields that will be returned in the type ahead suggestion for this suggestion field.
If we open the out-of-box suggestion field configuration named categories, we can see the defined fields:
These are the fields that will be returned in the type ahead suggestion for this suggestion field.
The easiest way to see the result of these default configurations is to look at type ahead response.
{
"suggestions": {
"categories": [ // (1)
{
"categoryNames": "Hot Sauces",
"numResults": 2
},
{
"categoryNames": "Merchandise",
"numResults": 2
},
{
"categoryNames": "Top Sellers",
"numResults": 1
},
{
"categoryIds": "category1",
"numResults": 2
},
{
"categoryIds": "category3",
"numResults": 2
},
{
"categoryIds": "category7",
"numResults": 1
}
],
"products": [ // (2)
{
"id": "product5",
"priceInfo": {
"price": {
"amount": 5.99,
"currency": "USD"
},
"priceType": "basePrice",
"priceTypeDetails": {
"basePrice": {
"type": "basePrice",
"bestPrice": {
"amount": 5.99,
"currency": "USD"
},
"priceDetails": {}
}
}
},
"currency": "USD",
"price": {
"amount": 5.99,
"currency": "USD"
},
"options": [],
"variants": [],
"includedProducts": [],
"promotionalProducts": {},
"productType": "STANDARD",
"assets": [],
"name": "Cool Cayenne Pepper Hot Sauce",
"description": "This sauce gets its great flavor from aged peppers and cane vinegar. It will enhance the flavor of most any meal.",
"uri": "/hot-sauces/cool_cayenne_pepper_hot_sauce",
"primaryAssetContentUrl": "https://localhost:8447/content/Cool-Cayenne-Pepper-Hot-Sauce-Bottle.jpg?contextRequest=%7B%22forceCatalogForFetch%22:false,%22tenantId%22:%225DF1363059675161A85F576D%22%7D",
"primaryAssetAltText": "Bottle of Cool Cayenne Pepper Hot Sauce"
},
{
"id": "01F9Y6RZM1Y4J00ZWJJKM316CK",
"priceInfo": {
"price": {
"amount": 2.99,
"currency": "USD"
},
"priceType": "basePrice",
"priceTypeDetails": {
"basePrice": {
"type": "basePrice",
"bestPrice": {
"amount": 2.99,
"currency": "USD"
},
"priceDetails": {}
}
}
},
"currency": "USD",
"price": {
"amount": 2.99,
"currency": "USD"
},
"options": [],
"variants": [],
"includedProducts": [],
"promotionalProducts": {},
"productType": "STANDARD",
"assets": [],
"name": "Bull Snort Cowboy Cayenne Pepper Hot Sauce",
"description": "<p>Been there, roped that. Hotter than a buckin' mare in heat! Sprinkle on meat entrees, seafood and vegetables. Use as additive in barbecue sauce or any food that needs a spicy flavor. Start with a few drops and work up to the desired flavor.</p>",
"uri": "/hot-sauces/bull-snort-cowboy-cayenne-pepper-hot-sauce",
"primaryAssetContentUrl": "https://localhost:8447/content/Bull-Snort-Cowboy-Cayenne-Pepper-Hot-Sauce-Bottle.jpg?contextRequest=%7B%22forceCatalogForFetch%22:false,%22tenantId%22:%225DF1363059675161A85F576D%22%7D",
"primaryAssetAltText": "Bottle of Cowboy Cayenne Pepper Hot Sauce"
}
]
},
"keyWords": [ // (3)
{
"highlightedSuggestion": "<strong>Cayenne</strong> Pepper Hot Sauce",
"suggestion": "Cayenne Pepper Hot Sauce"
}
]
}Type ahead suggestions for the categories suggestion field
Type ahead suggestions for the products suggestion field
Combination of highlight fields and search text suggestion response
As we can see, in the suggestions section of the response above, there are sections for both categories and products.
In the categories section, we can see all the information defined in the default configuration shown previously: category names and ids.
Same thing with the products section shown previously: id, currency, price, name, description, etc.
If additional information is desired in the default type ahead response, there are two options:
Add a field to one of the existing suggestion configurations
Create a new suggestion configuration
|
Note
|
It’s worth noting that implementations will not call the suggestions API directly by default, but the Catalog Browse service suggestion endpoint. This endpoint adds additional information, such as pricing, to the response. |
With rule-based categories, the indexing process is different from the process for explicit-assignment categories. In fact, it provides major benefit on the computational process. Since we don’t have to pre-determine and index each product’s category relationships, which can be a very consuming process. We can directly send the category’s rule to the SearchServices to gather category’s products instead.
Due to the decoupled nature of rule-based categories, the type ahead configurations should be updated accordingly. So that it can identify cross-sections of products based on product-owned properties, such as merchandisingType and brand. Based on facets targeting these properties, we should then identify categories that they can be linked to.
|
Note
|
If unfamiliar with the product’s merchandising type and brand fields, you can learn more by referencing Product’s Data Model and Data Driven Enum’s Data Model. |
|
Note
|
Identifying a category is not a requirement for gathering the correct set of products, rather it’s a beneficial extra step for surfacing specific content (banner images, text, etc.) that is relevant to that subset of products. |
Our recommended type ahead configurations for rule-based categories is to utilize product’s merchandisingType and brand, you can apply the type ahead configuration with the following SQL script:
-- Product type ahead configuration with merchandising type categories and brands suggestions
UPDATE BLC_TYPE_AHEAD_CONFIG
SET TYPE_AHEAD_SUGGEST_CONFIGS = '
[
{
"name": "products", // (1)
"resultLimit": 10,
"suggestionFields": [
{
"fieldDefinitionContextId": "productField1",
"variantType": "TEXT"
},
{
"fieldDefinitionContextId": "productField2",
"variantType": "TEXT"
},
{
"fieldDefinitionContextId": "productField3",
"variantType": "STRING"
},
{
"fieldDefinitionContextId": "productField4",
"variantType": "STRING"
},
{
"fieldDefinitionContextId": "productField5",
"variantType": "MONEY"
},
{
"fieldDefinitionContextId": "productField5_1",
"variantType": "CURRENCY"
},
{
"fieldDefinitionContextId": "productField7",
"variantType": "STRING"
},
{
"fieldDefinitionContextId": "productField8",
"variantType": "STRING"
}
]
},
{
"name": "merchandisingTypeCategories",
"resultLimit": 10,
"faceted": true,
"suggestionFields": [
{
"fieldDefinitionContextId": "productField22", // (2)
"variantType": "STRING"
}
]
},
{
"name": "brands",
"resultLimit": 10,
"faceted": true,
"suggestionFields": [
{
"fieldDefinitionContextId": "productField24", // (3)
"variantType": "STRING"
}
]
}
]'
WHERE ID = '01E214HSQRGABBRDMJGBN2VWF8'; -- (4)The out-of-box products type ahead suggestion configuration
The id of the search field definition for product’s merchandisingType.id
The id of the search field definition for product’s brand.id
The id of the type ahead configuration
|
Important
|
This type ahead configuration is intended to be paired with the usage of rule-based categories. If you’re using explicit-assignment categories, the default configuration stated previously is the better option for you. With that being said, this type ahead configuration can still be used with explicit-assignment categories. |
Once the changsets are applied, there will be three suggestion fields configured: Products, merchandisingTypeCategories, and brands. With the corresponding front end changes, the new type ahead suggestions can be displayed like so:
The products suggestion field configuration is no different from the default. However, the categories field is replaced by a new one named merchandisingTypeCategories, and another named brands is added.
This suggestion field replaced the default named categories, and is no longer driven by the Category Entity. Instead, it is driven by product’s merchandisingType property, which is a Data Driven Enum type to represent things such as Shirts, Jeans, Shoes, etc. This field is also faceted, so that it can be linked to a search result page with proper filters or a category page.
This is a new suggestion field driven by product’s brand property, which is also a Data Driven Enum and is faceted.
With the new merchandisingTypeCategories and brands suggestion field configurations, the type ahead response is different like so:
{
"suggestions": {
"brands": [ // (1)
{
"brandId": "brand-bull-snort", // (2)
"numResults": 1
},
{
"brandId": "brand-daves",
"numResults": 1
}
],
"merchandisingTypeCategories": [ // (3)
{
"numResults": 2,
"merchandisingTypeId": "merchandisingType-hot-sauces" // (4)
}
],
"products": [...] // (5)
},
"keyWords": [...] // (6)
}Type ahead suggestions for the brands suggestion field
The id for product’s brand, which is used to hydrate the Data Driven Enum details, as well as to identify an associated category (if exist) to link to
Type ahead suggestions for the merchandisingTypeCategories suggestion field
The id for product’s merchandising type, same usage as <2>
Same as default products suggestions
Same as default keyword suggestions
|
Note
|
For details about hydrating Data Driven Enum details in commerce, you can learn more by referencing DataDrivenEnumDetailsEndpoint and/or its OpenAPI specification
|