Adding filters to a data source

The baseFunctions setting in the data source definition allows you to include filters in order to restrict the returned data. Some filters are permanent, while others provide a starting point only and can be removed by end users.

The basic format for the baseFunctions setting is: 
"baseFunctions": [
 {
  "class":"com.endeca.portal.data.functions.<class name>",
  "<property name>":"<property value>"
 }
]
Where:

Note that the filters may require you to escape special characters. For details, see the Oracle Endeca Server Developer's Guide.

This escaping is in addition to the escaping required for JSON. So for example, if a filter includes a backslash, then:

When a data source includes filters, all components that use that data source automatically use those filters.

Studio comes with the following filters:

DataSourceFilter

A DataSourceFilter uses EQL to filter the data.

A DataSourceFilter is permanent. It is not added to the Breadcrumbs component and cannot be removed.

The properties for a DataSourceFilter are:

Property Description
filterString The EQL snippet containing the filter information.

For a DataFilter, this would essentially be the content of a WHERE clause for an EQL statement.

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

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

{
"class":"com.endeca.portal.data.functions.DataSourceFilter",
"filterString":"Regions='Napa Valley' and P_Price<40"
}

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.

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

{
"class":"com.endeca.portal.data.functions.RefinementFilter",
"attributeValue":"1999",
"attributeKey":"Year"
}

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 Breadcrumbs component for the refinement.

If you do not provide a value for attributeValueName, then the Breadcrumbs 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 Breadcrumbs component.

You would most likely want to provide ancestor values when selecting a managed attribute value from a value hierarchy.

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. 

{
"class":"com.endeca.portal.data.functions.NegativeRefinementFilter",
"attributeValue":"Washington",
"attributeKey":"Region"
}

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. 

{
"class":"com.endeca.portal.data.functions.NegativeRefinementFilter",
"attributeValue":"1997",
"attributeKey":"P_Year",
"attributeType":"LONG"
}

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 breadcrumb is provided. Also, Outlet is a hierarchical attribute, and the breadcrumb indicates that Caterer is a subcategory of Nonstore Retailers under the category Retail Sales. 

{
"class":"com.endeca.portal.data.functions.NegativeRefinementFilter",
"attributeValue":"454210",
"attributeKey":"Outlet",
"attributeValueName":"Caterer",
"ancestors":"[\"Retail Sales\",\"Nonstore Retailers\"]"
}

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.

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.

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: 

{
"class":"com.endeca.portal.data.functions.RangeFilter",
"attributeKey":"P_Score",
"rangeOperator":"BTWN",
"rangeType":"INTEGER",
"value1":"80",
"value2":"100"
}

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 relevance ranking on the display order of results.

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 Managing the list of search configurations.

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.

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. 

{
"class":"com.endeca.portal.data.functions.SearchFilter",
"searchInterface":"default",
"terms":"red, California",
"matchMode":"ALL",
"searchWithin":"true",
"enableSnippeting":"true",
"snippetLength":"100"
}

Permanent versus removable filters

Only a DataSourceFilter provides permanent filtering for the data.

Other types of filters only provide a starting point. They are displayed on the Breadcrumbs component and can be removed.

For a DataSourceFilter, there is no indication on the Studio user interface that the filter has been applied.

Example data source with filters

The following example data source contains a DataSourceFilter and a RefinementFilter. The data is filtered to only include transaction records from the Midwest region for the year 1999. 

{
 "server":"server01.lab.acme.com",
 "port":"15000",
 "dataDomainName":"acmeDB",
 "name":"Wine Transactions",
 "description":"Transaction data for the Midwest Region",
 "baseFunctions": [
  {
   "class":"com.endeca.portal.data.functions.DataSourceFilter",
   "filterString":"Regions='Midwest'"
  },
  {
   "class":"com.endeca.portal.data.functions.RefinementFilter",
   "attributeValue":"1999",
   "attributeKey":"Year"
  }
 ]
}