Adding filters to a deep link URL

Note that Studio ignores any filters for base filter attributes.

The basic format syntax for the deep link filter is:

http://<portalhost>:<port>/<pathToPage>?deeplink=[<dataState>]

Where <dataState> contains the corresponding filters to apply, either:

deeplink=[{"queryFunctions": [<queryFunctionFilters>]}]

or

deeplink=[{"navByValue": {<navByValueFilters>}}]

If the deep link is also pointing to a specific tab on a Tabbed Component Container (see Navigating to a specific tab on a Tabbed Component Container), then the full URL syntax is:

http://<portalhost>:<port>/<pathToPage>?com.endeca.discovery.
pageTransitionTabState=<tabcomponentname>[<tabnumber>]&deeplink=[<dataState>]

The filters use JSON syntax.

Types of queryFunctions filters

The queryFunctions parameter can include the following types of filters:

DataSourceFilter
SelectionFilter
RefinementFilter
NegativeRefinementFilter
RangeFilter
SearchFilter

DataSourceFilter

A DataSourceFilter uses EQL to filter the data.

A DataSourceFilter is not added to the Selected Refinements component.

The properties for a DataSourceFilter are:

Property	Description
filterString	The EQL snippet containing the filter information. This is essentially the content of a `WHERE` clause for an EQL statement. For example: "Regions='Napa Valley' and P_Price<40" Remember that if an attribute name contains EQL reserved characters, such as a dot, then the attribute name must be enclosed in double quotes. Because the filters use JSON syntax, you must also use a backslash to escape those double quotes. For example: "\"wine.region\"='Napa Value'" For details on EQL syntax, see the Oracle Endeca Server EQL Guide.
viewKey	The key name (not the display name) of the data set against which to execute the EQL.

Property

Description

filterString

The EQL snippet containing the filter information.

This is essentially the content of a WHERE clause for an EQL statement.

For example:

"Regions='Napa Valley' and P_Price<40"

Remember that if an attribute name contains EQL reserved characters, such as a dot, then the attribute name must be enclosed in double quotes. Because the filters use JSON syntax, you must also use a backslash to escape those double quotes.

For example:

"\"wine.region\"='Napa Value'"

For details on EQL syntax, see the Oracle Endeca Server EQL Guide.

viewKey

The key name (not the display name) of the data set against which to execute the EQL.

In the following example, the data is filtered to only show records from the Napa Valley region with a price lower than 40 dollars.

"queryFunctions":[{
"class":"DataSourceFilter",
"filterString":"Regions='Napa Valley' and P_Price<40",
"viewKey":"Wines"
}]

SelectionFilter

You can also use SelectionFilter. SelectionFilter uses the same syntax as DataSourceFilter. Also like DataSourceFilter, SelectionFilter is not added to the Selected Refinements component.

For example:

"queryFunctions":[{
"class":"SelectionFilter",
"filterString":"WineType='White'",
"viewKey":"Wines"
}]

RefinementFilter

A RefinementFilter is used to filter data to include records with the provided attribute values. The properties for a RefinementFilter are:

Property	Description
attributeValue	String The attribute value to use for the refinement.
attributeKey	String The attribute key. Identifies the attribute to use for the refinement.
multiSelect	AND \|OR \| NONE For multi-select attributes, how to do the refinement if the filters include multiple values for the same attribute. If set to AND, then matching records must contain all of the provided values. If set to OR, then matching records must contain at least one of the provided values. If set to NONE, then multi-select is not supported. Only the first value is used for the refinement.
viewKey	The key name (not the display name) of the data set that contains the attribute.

In the following example, the data is refined to only include records that have a value of 1999 for the Year attribute.

"queryFunctions":[{
"class":"RefinementFilter",
"attributeValue":"1999",
"attributeKey":"Year",
"viewKey":"Wines"
}]

NegativeRefinementFilter

A NegativeRefinementFilter is used to filter data to exclude records that have the provided attribute value. The properties for a NegativeRefinementFilter are:

Property	Description
attributeValue	String The attribute value to use for the refinement.
attributeKey	String The attribute key. Identifies the attribute to use for the refinement.
attributeType	BOOLEAN \| STRING \| DOUBLE \| LONG \| GEOCODE \| DATETIME \| TIME \| DURATION The type of value to use for the refinement. The default is STRING. If the attribute is a standard attribute of a type other than string, then you must provide the type.
attributeValueName	String Optional. The value to display on the Selected Refinements component for the refinement. If you do not provide a value for attributeValueName, then the Selected Refinements component displays the value of attributeValue. You may want to provide a separate display value if the selected attribute is a managed attribute for which the value names are different from the actual stored value.
ancestors	String List Optional. A list of the display names of the ancestor values to display on the Selected Refinements component. You would most likely want to provide ancestor values when selecting a managed attribute value from a value hierarchy.
viewKey	The key name (not the display name) of the data set that contains the attribute.

In the following example, the data is refined to only include records that do NOT have a value of Washington for the Region attribute. Because Region is a string attribute, no other configuration is needed.

"queryFunctions":[{
"class":"NegativeRefinementFilter",
"attributeValue":"Washington",
"attributeKey":"Region",
"viewKey":"Wines"
}]

In the following example, the data is refined to only include records that do NOT have a value of 1997 for the P_Year attribute. Because P_Year is not a string attribute, the attribute type LONG is specified.

"queryFunctions":[{
"class":"NegativeRefinementFilter",
"attributeValue":"1997",
"attributeKey":"P_Year",
"attributeType":"LONG",
"viewKey":"Wines"
}]

In the following example, the data is refined to only include records that do NOT have Caterer as the value for the Outlet attribute. The values for Outlet are stored as codes, so a display name to use for the refinement is provided. Also, Outlet is a hierarchical attribute, and the refinement indicates that Caterer is a subcategory of Nonstore Retailers under the category Retail Sales.

"queryFunctions":[{
"class":"NegativeRefinementFilter",
"attributeValue":"454210",
"attributeKey":"Outlet",
"attributeValueName":"Caterer",
"ancestors":"[\"Retail Sales\",\"Nonstore Retailers\"]",
"viewKey":"Wines"
}]

RangeFilter

A RangeFilter is used to filter data to include records with attribute values within the specified range. The properties for a RangeFilter are:

Property	Description
attributeKey	String The attribute key. Identifies the attribute to use for the filter.
rangeOperator	LT \| LTEQ \|GT \|GTEQ\| BTWN \|GCLT \|GCGT \| GCBTWN The type of comparison to use. LT - Less than LTEQ - Less than or equal to GT - Greater than GTEQ - Greater than or equal to BTWN - Between. Inclusive of the specified range values. GCLT - Geocode less than GCGT - Geocode greater than GCBTWN - Geocode between
rangeType	DECIMAL \| INTEGER \| DATE \| GEOCODE \| TIME \| DURATION The type of value that is being compared.
selectionLevel	YEAR \| MONTH \| DAY If rangeType is DATE, then this is the date/time subset to use for the range. YEAR - Use year for the range. This is the default. MONTH - Use year-month for the range. DAY - Use year-month-day for the range.
value1	Numeric The value to use for the comparison. For BTWN, this is the low value for the range. For the geocode range operators, the origin point for the comparison.
value2	Numeric For a BTWN, this is the high value for the range. For GCLT and GCGT, this is the value to use for the comparison. For GCBTWN, this is the low value for the range.
value3	Numeric Only used for the GCBTWN operator. The high value for the range.
viewKey	The key name (not the display name) of the data set that contains the attribute.

In the following example, the data is refined to only include records where the value of P_Score is a number between 80 and 100:

"queryFunctions":[{
"class":"RangeFilter",
"attributeKey":"P_Score",
"rangeOperator":"BTWN",
"rangeType":"INTEGER",
"value1":"80",
"value2":"100",
"viewKey":"Wines"
}]

SearchFilter

A SearchFilter is used to filter the data to include records that have the provided search terms. The properties for a SearchFilter are:

Property	Description
searchInterface	String Either the name of the search interface to use, or the name of an attribute that is enabled for text search. Note that if the search interface supports relevance ranking, it can affect the display order of results on certain components. For more information on how relevance ranking affects search results, see Effect of a Search Box search.
terms	String The search terms for the search.
matchMode	ALL \| PARTIAL \| ANY \| ALLANY \| ALLPARTIAL \| PARTIALMAX \| BOOLEAN The match mode to use for the search. The match modes are described in Configuring search options for the Search Box component.
searchWithin	boolean Whether to only search only within the refined set of data. The default is false, indicating to search the entire set of data, without applying any filters. If you are applying any other filters before the SearchFilter, and only want to search within the filtered data, you must set searchWithin to true.
enableSnippeting	boolean Whether to enable snippeting. Optional. If not provided, the default is false.
snippetLength	int The number of characters to include in the snippet. Required if enableSnippeting is true. To enable snippeting, set enableSnippeting to true, and provide a value for snippetLength.
viewKey	The key name (not the display name) of the data set against which to execute the search. If you do not provide a data set key, then the search is executed against the entire data domain.

In the following example, the filter uses the default search interface to search for the terms "California" and "red". The matching records must include all of the search terms, and the search is only within the current refinement. Snippeting is supported, with a 100-character snippet being displayed.

"queryFunctions":[{
"class":"SearchFilter",
"searchInterface":"default",
"terms":"red, California",
"matchMode":"ALL",
"searchWithin":"true",
"enableSnippeting":"true",
"snippetLength":"100",
"viewKey":"Wines"
}]

Using a navByValue filter for managed attributes

Deep linking URLS also support navByValue filters, which are similar to RefinementFilter in that they refine the data based on attribute values.

For the navByValue filters, the parameters are:

Property	Description
viewKey	The key name (not the display name) of the data set that contains the attributes.
values	Contains the list of attribute values for the filter: "values":{ "attributeKey1":"value1", "attributeKey2":"value2" } To specify multiple values for an attribute, use the format: "values":{ "attributeKey":["value1","value2"] }

Property

Description

viewKey

The key name (not the display name) of the data set that contains the attributes.

values

Contains the list of attribute values for the filter:

"values":{
"attributeKey1":"value1",
"attributeKey2":"value2"
}

To specify multiple values for an attribute, use the format:

"values":{
"attributeKey":["value1","value2"]
}

For example:

"navByValue":{
   "viewKey":"Wines",
   "values":{
			    "Wine Type":"Red",
			    "Region":"Other France",
			    "Body":["Fresh","Full","Rich","Ripe"]
    }
}

In most cases, it is preferable to use a RefinementFilter, because it is usually faster and more reliable.