Backend Interactive Data Projection and Filter Maps

FilterMaps are a data projection mechanism allowing the filter client to execute ad-hoc, paginatable queries against a pre-defined database query. Where ModelMaps can only be filtered by the C# code that is invoking them, FilterMaps are flexible and communicate their filterable facets to clients. This allows for a manipulation of the query constraints, sorting, and pagination by the front end.

User Interface

This user interface in Agent is what FilterMaps was built for. Notice how there are multiple potential entities whose count is retrieved.

FilterMaps powers a flexible database query mechanism which allows users to define add, and remove filter facets. The front end UI for this consumes meta-data in the results which provide details about what result fields are filterable and sortable.

The filter results also include pagination details: total count of potential results, and which page of results have returned. The pagination interface uses this information to render paging controls automatically.

We also support using filter maps for single entities. The result set can be rendered anyway you wish. The full power of the filtering mechanism and and pagination works here as well.

FilterMap Code Example

Back End

During development a *.filter.config file is created. Here is a very simple example:

<filter name="Modems" entity="Modem" allowAdhocQueries="true">
  <query from="modem">
    <addFacet key="id" field="objid" dataType="int" fieldType="identifier" />
    <addFacet key="hostName" field="hostname" dataType="string" fieldType="identifier" />
    <addFacet key="deviceName" field="device_name" dataType="string" fieldType="identifier" />
  </query>
</filter>

An endpoint on the back-end uses this map to project three database fields. The front-end will display the Modems item in the Query menu of Dovetail Agent because of the allowAdhocQueries attribute used at the root of the document. We will see this in action in a bit.

Front End Interaction

Invoking the filter map is done via the front-end (eventually) using the filterClient.js. Here is an example request and details about the results.

var request = {
  category: 'example',
  entity: 'modemmap',
  facets: [{
    key: 'HostName',
    operator: { key: 'Contains' },
    value: 'stanford'
  }],
  pagination: { pageSize: 5, page: 1 },
  sorts: [{ key: 'DeviceName', isAscending: true }]
};

var filterResult = filterClient.getEntityListing(request);

filterResult.results; // contains an array of TModels returned
filterResult.totalResults; // the total count of potential TModels for this query
filterResult.pagination; // paging details: pageSize, page, startRow, finishRow

// details about the configured filter facets and available facets to configure
filterResult.filterSpec;

Each bit of the result will be consumed by the front end view.

• The totalResults count will be displayed.
• The results array will go to a Backbone Collection for rendering.
• The pagination details will be consumed by the pagination module.
• Finally, the filterSpec will be used to render a view of the currently configuredFacets and if the user desires to add facets the availableFacets has all the details needed to do so.

Advanced

For more information on the Filter system, please see our Filter documentation.

FAQ

Why have a separate data projection mechanism?

Filter Maps have some nice features that ModelMaps hold a candle to, but they have some big limitations as well.

Better

• Pagination support
• Filterable and sortable facets are discoverable by the front end.
• Multiple maps can be grouped into Categories.
• Dynamic SQL. This improves on ModelMap in that all fields can be filtered not just fields on the "base table" of the map.
• Maps can be "joined" to other maps. See TagCaseFilterMap

Worse

• No child object support.
• A bit harder to wrap your head around. Also the back end code is quite complex.

What happens at the database level?

From the database point of view the end result of a filter map request is a dynamically generated SQL query which is then projected into the output model. Unlike ModelMap only SQL is generated with gives us more power to do Inner and Outer joins and constrain the query on any field that is selected or referenced in the FilterMap.

Why do I see that sometimes facets are marked as in-active?

When a filter request is executed with a configured facet that does not match any facets on the FilterMap being executed. That facet is still round tripped into the response as a configured facet but this facet is marked with a status of in-active.

Why do I see that sometimes facets cannot be removed?

It is possible to configure a facet as required which informs the front-end that this facet cannot be removed from the query. You can see this in action on individual Entity filters. On the site page there is a contacts FilterMap which marks the current contact as a required facet.

Next: Entity Search