Local Instance Vipers

The facetedsearchquerybuilder macro heavily depends on local instance vipers to be able to generate the appropriate and most optimal SQL query. This article describes the available local instance vipers, which can/should be used within the query xml.

Notice that in the query xml, any xml element in which local instance vipers are used must be enclosed within a CDATA section.

this.tableorview()

Resolves to the tableorview parameter set on the facetedsearchquerybuilder macro, or when this parameter hasn't been set resolves to the active channel view or vwActive when multiple channels have been specified within the ChannelCodes parameter.

this.searchgroupviewname()

Returns the Faceted Search / Full-text indexing view-name for the specified Search Group (either as searchgroup parameter on the macro or as searchgroup configuration element within the query xml), e.g.: vwTsContentPUB.

this.mode()

Returns the mode as set on the facetedsearchquerybuilder macro. Can be used to execute certain logic when e.g. a search query is being assembled and skip this logic when a count query or facet query is being assembled:

Smartsite SXML	Copy Code
{sys.iif(this.isbasequery() || this.mode()!=SearchQuery, '1', 'NULL')} AS BaseSearch

this.searchquery()

Resolves to the generated search query. This search query may differ dependent on the mode parameter set on the facetedsearchquerybuilder macro.

For this viper you should specify a default query, which must be executed when the user hasn't specify a search term. You have two options here:

1. Specify a default query which returns no rows ("No results" will be displayed as search result):
   
   this.searchquery(default="SELECT Nr, 0 AS SearchRank FROM Contents WHERE Nr=-1")
   
2. Specify a default query which returns all rows (then all facets will display the "distribution" of all records among the facet-specific meta property):
   
   this.searchquery(default="SELECT Nr, 0 AS SearchRank FROM " + this.searchgroupviewname())

Notice that you have to include two fields within the default query: Nr and SearchRank.

this.selectfields()

Resolves to the value of the fields element when the mode is set to searchquery. When the mode is set to countquery, it resolves to "count(*)". And when the mode is set to facetquery, it resolves to the value of the search_fields element of the appropriate facet element.

this.joinclause()

This viper returns the required JOIN clause, which is assembled from the joins element within the masterquery element and one or more joins element(s) from selected/active facets. For this viper you should specify an empty string as default:

Smartsite SXML	Copy Code
this.joinclause(default="")

this.whereclause()

This viper returns the WHERE clause, which is assembled from the where element(s) from all active/selected facets. For this viper you should specify a default:

Smartsite SXML	Copy Code
this.whereclause(default="(1=1)")

this.orderby()

The this.orderby() viper can be used to adjust the order of the search results. The viper resolves to the OrderBy parameter as set on the facetedsearchquerybuilder macro, which e.g. can be set to "c.moddate" to order the results by moddate. When this parameter hasn't been set, the viper will resolve to its specified default:

Smartsite SXML	Copy Code
this.orderby(default="SearchRank DESC")

this.rankingfields()

Resolves to the value of the rankingfields element, as specified within the masterquery element.

this.isbasequery()

Resolves to true when the base search query for a specific source is being assembled. Resolves to false when additional search queries (to apply specific weights on physical fields) are assembled, which will be appended to the base search query.

Should be used to restrict expensive weight calculations (such as popularityweight and contenttypeweight) to the base search query only, e.g.:

Smartsite SXML	Copy Code
sys.iif(this.isbasequery(),   "+" + this.seopriority("c.seopriority") +   "+" + this.contenttypeweight("c.contenttype_weight") +   "+" + this.popularityweight("LOG(ISNULL(pr.visits,1))/LOG(" +  sys.eval(maxvisits(), smartlet.number()) + ")"))

this.seopriority()

The this.seopriority() local instance viper can be used to take SEO priority for individual items into account. It uses the seopriority setting from the query xml as SEO priority weight. The seopriority for a specific item (defaults to 0.5) is then multiplied with this weight.

this.contenttypeweight()

For each contenttype a specific weight (between 0 and 10) can be assigned (defaults to 5) using the cms manager action Contenttype Weights within the Faceted Search Console. This weight(-factor) multiplied with the contenttype-weight value as defined within the query xml will be the result of this local instance viper.

this.popularityweight()

More popular items (based on the number of page requests) can be given a higher search rank using this local instance viper. In the example query xml a logarithmic scale is being used to calculate a popularity weight factor, which is multiplied with the popularity-weight value as defined within the query xml. The database logic calculating the weight factor must be provided to this viper as argument:

Smartsite SXML	Copy Code
this.popularityweight("LOG(ISNULL(pr.visits,1))/LOG(" + sys.eval(maxvisits(), smartlet.number()) + ")")

(assuming a LEFT JOIN on the table PageRequests have been added as well, using alias "pr"; also using the translation maxvisits() to determine the maximum number of visits using a 30 minute cache period.)

this.fieldweight()

The this.fieldweight() viper should be used to take physical field weights into account, which can be set using the (Physical) Field Weights cms manager action within the Faceted Search Console. At the same time (when the base search query is being assembled) it can be used to take an age-factor into account using the modification date of an item:

Smartsite SXML	Copy Code
this.fieldweight("dbo.fn_tsAgeInDays(c.moddate)", default="c."+this.fieldname()+"_weight")

this.fieldname()

Returns the fieldname for which an additional search query is being assembled (to apply specific weights on physical fields). When used within an CONTAINSTABLE expression to indicate which columns must be used, you should specify an appropriate default:

Smartsite SXML	Copy Code
this.fieldname(default="(QueryData,CTSpecificBinary1)")

this.rankingstatement(sourcename)

The this.rankingstatement(sourcename) viper should be used within the definition of the (search) query for a source which has been configured to use native queries (that is, LIKE statements).

Based on the fieldnames listed within the wherefields element (required element for native queries!), the this.rankingstatement(sourcename) viper returns a statement which calculates the number of occurrence for each search term within each specified (physical) field, using the Faceted Search database function fn_tsCountWord(), e.g.:

SQL	Copy Code
(dbo.fn_tsCountWord(?:searchterm1,c.Field1)*3 + dbo.fn_tsCountWord(?:searchterm1,c.Field2)*3 + dbo.fn_tsCountWord(?:searchterm2,c.Field1)*1 + dbo.fn_tsCountWord(?:searchterm2,c.Field2)*1)

The sourcename attribute must match with the name attribute of the enclosing source element.

this.searchcondition(sourcename)

The this.searchcondition(sourcename) viper should also be used within the definition of a native query. Based on the fieldnames listed within the wherefields element, this viper will return the appropriate WHERE statement for the search query, e.g.:

SQL	Copy Code
(c.Field1 LIKE ?:searchterm1 OR c.Field2 LIKE ?:searchterm1) AND (c.Field1 LIKE ?:searchterm2 OR c.Field2 LIKE ?:searchterm2)

The sourcename attribute must match with the name attribute of the enclosing source element.

this.facet()

Returns the name of the facet for which a query is being assembled. Equals the facet parameter setting as set on the facetedsearchquerybuilder macro.

this.facetselectfields()

Returns the field-selection as specified within the facet_fields element of the currently active facet. Only applicable within facet query definitions.

this.resultchanneljoins(prefix)

When multiple channel-codes have been specified using the ChannelCodes parameter, this viper returns a JOIN construction using these channels, which can be used in combination with the this.resultchannelcode() viper to get the channelcode for each result (representing in which channel a search result is available).

this.resultchannelcode()

When multiple channel-codes have been specified, resolves to "pcv.channelcode". When just one channel code has been specified, resolves to this channel code.