Cartridge-specific URL query parameters

For some cartridges, it is appropriate for aspects of their configuration to be overridden at query time. Typically, request-based configuration is specified as URL query parameters. This section covers the URL query parameters for the core cartridges included with Tools and Frameworks.

By default, the Assembler is configured to use the following parameters:

URL Parameter

Cartridge

Feature

Dy

Dimension Search Results

Enables or disables the display of returned dimension refinements.

Ntp

Search Adjustments

Specifies whether to display automatic phrasing; core parameter, see Ntp (Auto-Phrasing).

Nty

Search Adjustments

Specifies whether to display automatic spelling correction / "Did You Mean"

Nrmc

Refinement Menu, Navigation Container

The Nrmc parameter takes multiple arguments allow you to configure dimension refinement behavior in a cartridge.

Nrpp

Results List

Records per page

Ns

Results List

Sort key and sort order

No

Results List

Record offset (used for paging)

Nrt

Results List

Relevance Ranking search terms

Nrk

Results List

Relevance Ranking search key

Nrm

Results List

Relevance Ranking strategy

whymatch

Results List

Includes record matching information if query debugging is enabled

whyrank

Results List

Includes record ranking information if query debugging is enabled

These parameters are described in detail in the following sections. For additional information about the URL query parameters for the core cartridges, refer to the Assembler API Reference (Javadoc) for the relevant RequestParamMarshaller subclass. These classes define the URL parameters that each cartridge accepts, and their mappings to properties on the cartridge configuration model.

The Dy parameter controls the display of the Dimension Search Results cartridge.

Parameter

Dy

Name

Dimension Search

Type and format

[0|1]

Object

DimensionSearchResultsConfig

Description

Set to 1 to enable cartridge display, or 0 to disable it.

Dependencies

N,Ntt

Example 16. Examples

The following example returns records with a match for the term "Silver," with the Dimension Search Results cartridge enabled: 

N=0&Ntt=Silver&Dy=1


The Nty parameter controls the display of auto-correct and "Did You Mean" results in the Search Adjustments cartridge.

Parameter

Nty

Name

Auto-Correct / "Did You Mean"

Type and format

[0|1]

Object

SearchAdjustmentsConfig

Description

Set to 1 to enable display, or 0 to disable it.

Dependencies

N,Ntt

Example 17. Examples

The following example returns records with a match for the term "Sliver," with auto-correct enabled to correct the query to "silver": 

N=0&Ntt=Sliver&Nty=1


The Nrmc parameter takes multiple arguments that configure dimension refinement behavior in the Refinement Menu cartridge.

Because the Navigation Container cartridge returns a list of RefinementMenu objects, it takes the same Nrmc URL parameter as the Refinement Menu cartridge.

Parameter

Nrmc

Name

Refinement Menu Config

Type and format

<Dimension ID>+show:[all|some|none] | <dimension ID>+show:[all|some|none]...

Object

RefinementMenuConfig

Description

The Nrmc parameter takes the following values:

Configuration for multiple dimensions is separated with a vertical pipe (|) character.

Dependencies

N

Example 18. Examples

The following modifies the Refinement Menu to display all of the dimension refinements for the "Features" dimension, and hides all refinements for the "Color" dimension: 

N=0?Nrmc=100031+show:all||101908+show:none


The following URL query parameters determine the display of search results in the Results List cartridge. They are typically set in the front-end application by the end user.

The Nrpp parameter limits the records returned from the MDEX Engine.

Parameter

Nrpp

Name

Records Per Page

Type and format

<integer>

Object

ResultsListConfig

Description

Sets the maximum number of records to include in the ResultsList object.

Dependencies

N

Example 19. Examples

The following example shows ten records per page: 

N=0&Nrpp=10


The Ns parameter controls sorting options for the current query. It enables the end user to override default sorting behavior on a per-query basis.

Parameter

Ns

Name

Sort Key and Sort Order

Type and format

<sort key>[<geocode reference>]|[0|1] || <sort key>|[0|1]...

Object

ResultsListConfig

Description

The <sort key> specifies the property or dimension to sort by. Optionally, each key can be followed by a suffix of "|1" to indicate descending sort order, or "|0" to indicate ascending order (the default).

Multiple entries are separated with a double vertical pipe (||), and each entry after the first applies its sorting within the strata created by preceding entries.

To sort records by a geocode property, add the optional geocode argument to the parameter (the <sort key> must be a geocode property). Records are sorted by the distance from the geocode reference point to the geocode point indicated by the <sort key> value.

Dependencies

N

Example 20. Examples

The following settings sort query results by product rating in descending order (higher rated products first). For each rating, it then sorts by price in ascending order (cheaper products first): 

N=0&Ns=product.rating|0||product.price

The following example sorts records with a store.geocode property based on proximity to the Statue of Liberty in NYC, NY: 

N=0&Ns=store.geocode|40.6893,-74.0446


The No parameter sets the record offset in the query results list.

Parameter

No

Name

Record Offset

Type and format

<integer>

Object

ResultsListConfig

Description

Offsets the results set by the number of records specified. The offset is applied to a zero-based index; If No=20, the list of records starts at record 21. If an offset is greater than the number of items in a navigation object’s record list, an empty record list is returned.

Dependencies

N,Nrpp

Example 21. Examples

The following example displays the second page of a results set (since the results list is configured to display 36 records per page, and is offset by that amount to start at the 37th record): 

N=0&Nrpp=36&No=36


The Nrt parameter optionally sets search terms for a Relevance Ranking enabled record search query.

You can apply Relevance Ranking to a subset of your MDEX Engine query by specifying the desired terms in the Nrt parameter.

Note

If you specify a Relevance Ranking strategy on the cartridge without specifying Relevance Ranking search terms and a search key (Nrt and Nrk), the MDEX Engine evaluates the query using the Record Search Terms and Record Search Key (Ntt and Ntk) parameters. For additional information about relevance ranking strategies, see the MDEX Engine Development Guide.

Parameter

Nrt

Name

Relevance Ranking Search Terms

Type and format

<string>+<string>+<string>...

Object

ResultsListConfig

Description

Sets the terms of the record search for a navigation query with relevance ranking. Each term is delimited by a plus sign (+).

Note

Unlike the Ntt parameter, Nrt does not support using multiple sets of terms.

Dependencies

N, Nrk. Additionally, you must set the relRankStrategy on the cartridge.

Example 22. Examples

Because the Discover Electronics application uses Spring as a configuration mechanism, the cartridge-wide default values for Relevance Ranking in the Results List cartridge are specified in the reference\discover-electronics-authoring\WEB-INF\assembler-context.xml file: 

<bean id="CartridgeHandler_ResultsList" class="com.endeca.infront.cartridge.ResultsListHandler"
          parent="NavigationCartridgeHandler" scope="prototype">
    <property name="contentItemInitializer">
        <bean class="com.endeca.infront.cartridge.ConfigInitializer" scope="request">
            <property name="defaults">
                <bean class="com.endeca.infront.cartridge.ResultsListConfig" scope="singleton">
                    <!-- additional configuration omitted from this example -->
                           <property name="relRankKey" value="All" />
                    <property name="relRankMatchMode" value="ALLPARTIAL" />
                    <property name="relRankStrategy" value="nterms,maxfield,exact,static(product.analytics.conversion_rate,descending)" />
                           <!-- additional configuration omitted from this example -->
                </bean>
            </property>
            <!-- additional configuration omitted from this example -->
        </bean>
    </property>
    <!-- additional configuration omitted from this example -->
</bean>

The following example returns records with a match for the terms "cameras" and "silver" in the product.description record property, and applies the Relevance Ranking strategy specified at the cartridge level: 

N=0&Ntk=product.description&Ntt=cameras+silver


The Nrk parameter sets which dimension, property, or search interface is evaluated for a Relevance Ranking enabled record search query.

Note

If you specify a Relevance Ranking strategy on the cartridge without specifying Relevance Ranking search terms and a search key (Nrt and Nrk), the MDEX Engine evaluates the query using the Record Search Terms and Record Search Key (Ntt and Ntk) parameters. For additional information about relevance ranking strategies, see the MDEX Engine Development Guide.

Parameter

Nrk

Name

Relevance Ranking Search Key

Type and format

<search key>

Object

ResultsListConfig

Description

Sets the search key for the record search query. This must be a navigable dimension, property name, or search interface defined in the MDEX Engine.

Dependencies

N, Nrt. Additionally, you must set the relRankStrategy on the cartridge.

Example 23. Examples

The following example returns records with a match for the terms "cameras" and "silver" in the product.description record property, and applies the Relevance Ranking strategy specified at the cartridge level: 

N=0&Ntk=product.description&Ntt=cameras+silver


The Nrm parameter sets the relevance ranking strategy for ranking the results of the record search.

You can override the default Relevance Ranking strategy on a per-query basis by using the Nrm parameter. For additional information about match modes, see the MDEX Engine Basic Development Guide.

Parameter

Nrm

Name

Relevance Ranking Strategy

Type and format

<string>

Object

ResultsListConfig

Description

Sets the options for record search in a relevance ranking enabled query.

Note

Unlike the Ntx parameter, Nrm does not support using multiple match modes.

Dependencies

N, both Nrt and Nrk, OR both Ntt and Ntk. Additionally, you must set the relRankStrategy on the cartridge.

Example 24. Examples

The following example returns records with a match for the terms "cameras" and "silver" in the product.description record property, and applies the Relevance Ranking strategy specified at the cartridge level. It overrides the default "MatchAllPartial" match mode with "MatchAllAny": 

N=0&Ntk=product.description&Ntt=cameras+silver&Nrm=matchallany


The whymatch parameter controls the logging of record match information about a per-query basis.

This property enables you to include record matching information about a per-query basis, rather than at the cartridge handler level.

Parameter

whymatch

Name

Record match debugging information

Type and format

[0|1]

Object

ResultsListConfig

Description

Set to 1 to include record matching information, or 0 to disable it.

Dependencies

N, as well as either Ntt and Ntk or Nrt and Nrk.

Additionally, you must have query debugging enabled in your application.

Example 25. Examples

The following example returns record matching information for a search against "silver cameras.": 

 N=0&Ntk=product.description&Ntt=silver+cameras&whymatch=1

A portion of the response (serialized to JSON) is shown below. The DGraph.WhyDidItMatch key contains the relevant debugging information: 

"DGraph.WhyDidItMatch": [
    "product.long_desc: <b>The high-quality 10.0 Megapixel Digital IXUS 870 IS - finished in gold or silver - 
     commands attention. 
     ... 
     Advanced compression technologies reduce file size, to free up valuable extra memory. (Stemming)"
],


The whyrank parameter controls the logging of relevance ranking information about a per-query basis.

This property enables you to include record relevance ranking information about a per-query basis, rather than at the cartridge handler level.

Parameter

whyrank

Name

Record ranking debugging information

Type and format

[0|1]

Object

ResultsListConfig

Description

Set to 1 to include record ranking information, or 0 to disable it.

Dependencies

N, as well as either Ntt and Ntk or Nrt and Nrk.

Additionally, you must have query debugging enabled in your application.

Example 26. Examples

The following example returns record ranking information for a search against "silver cameras.": 

 N=0&Ntk=product.description&Ntt=silver+cameras&whyrank=1

A portion of the response (serialized to JSON) is shown below. The DGraph.WhyRank key contains the relevant debugging information: 

"DGraph.WhyRank": [
    "stratify": [
      evaluationTime: "0.00048828125"
      stratumRank: "3"
      stratumDesc: "no match"
   ]
],


Copyright © Legal Notices