Broadleaf Microservices
  • v1.0.0-latest-prod

Search Services Data Model

Field Definition

Fields for indexing documents and constructing queries are defined in the following data model:

Field Definition Model

BLC_FIELD

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

LABEL

The label of the field, suitable for display.

INDEXABLE_TYPE

The type to which this field belongs, e.g., PRODUCT.

MULTI_VALUED

Whether this field should contain a list of values.

PROPERTY_PATH

The JSON path of this field excluding the root prefix, "$.". This is the path to the actual value that will be stored in the index, e.g. 'price', 'description', 'customer.name', etc. For more advanced mapping options, see the JSONPath documentation

COMBINED

Whether this field should be a combination of multiple path values. If true, then instead of propertyPath, the multi-valued propertyPaths will be used and joined with the delimiter.

MULTI_VAL_COMBINED_PROP_PATH

For fields which are both MULTI_VALUED and COMBINED, this will be path to the list containing the objects representing each value. For example, to combine property paths for each category in a list of all categories in the object being indexed, this would be categories[*].

PROPERTY_PATHS

If this is a combined field, these are the JSON paths to the fields to be combined into the final value, excluding the root prefix, "$.". For combined fields, all property paths should point to a single-valued object, the String value of which will be used.

For fields which are both MULTI_VALUED and COMBINED, the root for this path will be an individual object in the list defined by the MULTI_VAL_COMBINED_PROP_PATH. For example, if the indexable domain was: { "categories": [ { "id": "exampleId", "name": "exampleName" } ] } and the MULTI_VAL_COMBINED_PROP_PATH was categories[*], then the property paths might be id or name.

DELIMITER

If this is a combined field, this is the delimiter string which should separate the values found from the propertyPaths.

ABBREVIATION

Short field name which will be used for request parameters for example in sorting and filtering, as well as response field names.

TRANSLATABLE

Indicates if this field is translatable. If so, then translations will also be indexed.

VARIANTS

The specific typed variants for this field. See JpaFieldVariant.

FACETED

Deprecated since 2.1.0, see BLC_FACET.

FACET_LABEL

Deprecated since 2.1.0, see BLC_FACET.

FACET_DISPLAY_ORDER

Deprecated since 2.1.0, see BLC_FACET.

FACET_MULTI_SELECT

Deprecated since 2.1.0, see BLC_FACET.

FACET_RANGED

Deprecated since 2.1.0, see BLC_FACET.

FACET_RANGES

Deprecated since 2.1.0, see BLC_FACET.

FACET_RULE

Deprecated since 2.1.0, see BLC_FACET.

FACET_VARIANT_TYPE

Deprecated since 2.1.0, see BLC_FACET.

SORTABLE

Deprecated since 2.1.0, see BLC_FIELD_SORT.

SORT_LABEL

Deprecated since 2.1.0, see BLC_FIELD_SORT.

SORT_DISPLAY_ORDER

Deprecated since 2.1.0, see BLC_FIELD_SORT.

SORT_VARIANT_TYPE

Deprecated since 2.1.0, see BLC_FIELD_SORT.

SEARCHABLE

Whether this field is searchable.

FIELD_QUERIES

Defines how this field should be queried by variants on particular query types. See FieldQuery.

ATTRIBUTES

Arbitrary attributes.

Tracking

Sandbox Trackable.

JpaFieldVariant

A specific variant of a field representing the concrete indexed version with a type.

Field Description

type

The general type of value stored in this field. Should be a value of FieldType.

includeInResponse

Determines whether this variant should be included in the search response. This must be a stored value in the search index.

FieldQuery

Associates a JpaFieldVariant for a field to make it searchable based on a particular query type. For example, this could enable the String variant of the Product Name field to be searched based on a word-level match. A boost amount can also be added, to weight the results based on this query.

Field Description

queryType

The query type which should be boosted on.

variantType

The field variant type which should be boosted on.

boost

The amount to boost this variant for this query type.

Search Settings

Tip
Since 2.1.0

Represents a group of search settings for an application or tenant to allow sharing Facets and SortOptions between different environments. Settings are discriminated by both a "settings context" and Application. Application tracking is applied implicitly through the Settings being within a "Search Group" type Catalog. Search Group Catalogs are used to allow inheritance and overrides by Applications of a Tenant-level default. The context indicates whether the settings are for the admin or storefront (or some arbitrary type of context).

Important
There should only be one Search Settings per context per Application. E.g., each app should have only one Settings configured for Admin and one for Storefront.
Search Settings Model

BLC_SEARCH_SETTINGS

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

SETTINGS_CONTEXT

The context these settings apply within: Admin or Storefront. Only one Search Settings should apply in a particular context and Application.

SEARCH_ENABLED

Whether advanced search is enabled for the context. This is typically only used for Admin contexts where Search Service may be used by Entity Grids. It is expected that when Search undergoes maintenance or if there are problems that this can be used to have those grids revert to use the database instead to allow users to continue operating.

ATTRIBUTES

Arbitrary attributes.

Tracking

Catalog Trackable.

BLC_FACET

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

FIELD_DEFINITION_ID

ID of the Field Definition this Facet applies to.

FIELD_INDEXABLE_TYPE

The Indexable Type the Facet applies to, e.g., PRODUCT.

VARIANT_TYPE

The field variant to target for faceting.

LABEL

A friendly label to show in search results.

DISPLAY_ORDER

The relative display order of this facet. Can be overridden when assigned to a group.

MULTI_SELECT

Whether multiple facet values may be selected at once.

RANGED

Whether to use ranges of values.

FACET_RANGES

The ranges to use if RANGED. See FacetRange.

FACET_RULE

The rule required to be met for this facet to be active. This is by default a SpEL expression, but may be any expression language with additional customization.

ATTRIBUTES

Arbitrary attributes.

Tracking

Catalog Trackable.

FacetRange

Represents a selectable option of a search facet. This could be a range (e.g. price range) a color, or any other attribute.

Field Description

label

The label for this facet range, suitable for display.

displayOrder

Order in which to display this range on a list of facet ranges. A lower number indicates this item will occur earlier in the returned facet range list.

minValue

The lowest value included in this facet range.

The highest value included in this facet range.

maxValue

BLC_FACET_GROUP

Allows grouping Facets together for easier reuse in different Search Settings configurations.

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

NAME

A name for the Group.

GROUP_INDEXABLE_TYPE

The Indexable Type the Group of Facets applies to, e.g., PRODUCT.

ATTRIBUTES

Arbitrary attributes.

Tracking

Catalog Trackable.

BLC_FACET_GROUP_FACET

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

SORT_CONTEXT_ID

ID of the Facet to link to the Group.

SORT_GROUP_CONTEXT_ID

ID of the Facet Group to link the Facet to.

SORTING

Defines the sort order of the related Facet relative to others belonging to the same Group. Default value is z that indicates the option is unsorted. This allows lexicographical sorting on this field. See SortPositionStrategy.

Tracking

Catalog Trackable.

BLC_SETTINGS_FACET_GROUP

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

SETTINGS_CONTEXT_ID

ID of the Search Settings the Facet Group is linked to.

SORT_GROUP_CONTEXT_ID

ID of the Facet Group to link to a Search Settings.

GROUP_INDEXABLE_TYPE

The Indexable Type the Group of Facets applies to, e.g., PRODUCT.

Tracking

Catalog Trackable

BLC_FIELD_SORT

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

FIELD_DEFINITION_ID

ID of the Field Definition this Sort applies to.

FIELD_INDEXABLE_TYPE

The Indexable Type the Sort Option applies to, e.g., PRODUCT.

VARIANT_TYPE

The field variant to target for sorting.

LABEL

A friendly label to show in search results.

NAME

The name of the sort. Typically, this is the same as the Field’s abbreviation.

DISPLAY_ORDER

The relative display order of this option. Can be overridden when assigned to a group.

ATTRIBUTES

Arbitrary attributes.

Tracking

Catalog Trackable.

BLC_SORT_GROUP

Allows grouping Sort Options together for easier reuse in different Search Settings configurations.

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

NAME

A name for the Group.

GROUP_INDEXABLE_TYPE

The Indexable Type the Group of Sorts applies to, e.g., PRODUCT.

ATTRIBUTES

Arbitrary attributes.

Tracking

Catalog Trackable.

BLC_SORT_GROUP_SORT

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

SORT_CONTEXT_ID

ID of the Sort Option to link to the Group.

SORT_GROUP_CONTEXT_ID

ID of the Sort Group to link the Option to.

SORTING

Defines the sort order of the related Sort Option relative to others belonging to the same Group. Default value is z that indicates the option is unsorted. This allows lexicographical sorting on this field. See SortPositionStrategy.

Tracking

Catalog Trackable.

BLC_SETTINGS_SORT_GROUP

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

SETTINGS_CONTEXT_ID

ID of the Search Settings the Sort Group is linked to.

SORT_GROUP_CONTEXT_ID

ID of the Sort Group to link to a Search Settings.

GROUP_INDEXABLE_TYPE

The Indexable Type the Group of Sorts applies to, e.g., PRODUCT.

Tracking

Catalog Trackable.

Type Ahead

Provides configuration for type-ahead search suggestions.

Search Settings Model

BLC_TYPE_AHEAD_CONFIG

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

CONFIG_NAME

The name of this configuration.

HIGHLIGHT_FIELDS

The fields to highlight. These are the fields that autocomplete is supported for. These fields must be searchable.

INDEXABLE_TYPE

The IndexableType (e.g., PRODUCT) this configuration applies to.

AUTOCOMPLETE_LIMIT

The number of autocomplete suggestions to return on a TypeAhead search.

PHRASE_SLOP

This allows matches of a phrase that is N distance away from a match. For example, consider the term "Red Wicker Basket". With a phrase slop of 2, this would allow "Red Basket" to match this term, as it is two words away.

HIGHLIGHT_PREPEND

When highlighting, this is a string that will be prepended to a matching keyword. For example, a query of 'bla' may match 'black', and, if HIGHLIGHT_PREPEND is <strong> and HIGHLIGHT_APPEND is </strong>, then the result would be <strong>black</strong> to mark the word that was matched.

HIGHLIGHT_APPEND

See HIGHLIGH_PREPEND.

TYPE_AHEAD_SUGGEST_CONFIGS

Configurations defining what should be returned on a TypeAhead query. This might represent a list of recommended products, categories, etc. See JpaTypeAheadSuggestionConfig

HIGHLIGHT_FRAGMENT_SIZE

The approximate size, in characters, of fragments to consider for highlighting. Default is 30.

Tracking

Type-Ahead Config is Sandbox trackable.

JpaTypeAheadSuggestionConfig

Represents a suggestion to be returned in a Type-Ahead response.

For example, let’s assume that in addition to text prediction, we want to return a set of the top 5 products with their name and price that relate to the suggestion terms. A (shortened) configuration might look as follows:

{
    "name": "products",
    "suggestionFields":
    [
        {
            "fieldDefinition":
            {
                "id": "nameField",
                "label": "Name",
                "indexableType": "PRODUCT",
                "abbreviation": "name"
            },
            "variantType": "TEXT"
        },
        {
            "fieldDefinition":
            {
                "id": "priceField",
                "label": "Price",
                "indexableType": "PRODUCT",
                "abbreviation": "price"
            },
            "variantType": "DOUBLE"
        }
    ],
    "showResultCount": false,
    "faceted": false,
    "resultLimit": 5
}

When doing a query for "iPhone", for instance, we would get back a result for a product in the following form, with up to 5 matching products:

{
    "products":
    [
        {
            "price": 619.0,
            "name": "iPhone 8 64GB (Silver)"
        }
    ]
}
Field Description

name

The name to be displayed in the results. For instance, "Products". This may also be a translatable key.

suggestionFields

The list of fields to be returned with this suggestion.

faceted

Is this configuration faceted? Required for showing a result count. Note that when a result is faceted, it can only be faceted on a single SuggestionField

resultLimit

The maximum number of results to return for this configuration.

SuggestionField

Field Description

fieldDefinitionContextId

The field definition to provide suggestions for. The most common scenario would be a product’s name.

variantType

The variant type to use when building suggestions. If this is an autocomplete field, this should be a searchable field, tokenized in such a way that it returns useful autocomplete results.

Search Redirect

Additional domain that provides the ability to short circuit a search request and instead redirect directly to a particular landing page by URI based on the search term.

Redirect Data Model

BLC_SEARCH_REDIRECT

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

LABEL

Logical ID. Allows for sandbox versions.

NAME

Logical ID. Allows for sandbox versions.

IS_REGEX

Whether the QUERY_MATCH should be applied as a Regex.

QUERY_MATCH

The value that a query must match to activate the redirect. If IS_REGEX, the match will be applied as a Regex. Otherwise, an exact match is required.

REDIRECT_TYPE

The type of HTTP redirect to perform: Permanent or Temporary.

REDIRECT_URI

The URI to redirect to if the query is matched.

Tracking

Search Redirects are Application trackable.