Removing a Facet when using the MarkLogic Visualization Widgets

Author: Dave Cassel  |  Category: Software Development

Suppose you’ve built an application using MarkLogic’s Visualization Widgets. At some point you decide you have too many and decide to remove one. I’ve seen a couple cases where someone does an incomplete removal, so I figured it’s worth laying out the steps. This write-up assumes that you’ve built an application using Application Builder, but generalizes to any application based on the Search API.

Facet Configuration

In an application based on MarkLogic’s Visualization Widgets, displaying a facet involves a number of steps:

  • there has to be a range index to support the facet
  • the Search API/REST API options define it (how the values will be retrieved)
  • app-config.js configures the facet display (“var sidebar_config = {…}”)
  • the HTML shows where the sidebar will go

Removing a facet by removing the portion of the sidebar_config that sets it up means that MarkLogic will still maintain the index, search for values that go with each query, find the counts of those values, and include them in the response to the client. A more thorough removal reduces the memory use of the database (index), the CPU usage related to a search (finding values and counts) and the size of the response, as well as letting the client do less work.

Constraints and Facets

Sometimes parts of this are worth leaving around. The Search API (which the REST API is built on) has two related concepts: constraints and facets. A facet is a type of constraint. A constraint is a way of targeting a query. What makes a facet different is that MarkLogic will actively look up values for it at query time. Consider:

  <search:constraint name="food">
    <search:range collation="" type="xs:string" facet="true">
      <search:element ns="" name="food-type"/>

This is a constraint called food, which is also a facet. Because we have this constraint, we can do queries like food:pretzel. That will find us documents where the food-type element has precisely that value. We can do that whether the facet attribute on the search:range element is true or false.

When the facet attribute is true, MarkLogic also looks up the 10 (in this case) most common food-type element values that match the query for each search and their frequencies. That information gets included in the search results and transmitted back to the client.

This process is fast, of course, since it’s based on indexes. All the same, it’s not uncommon for no-longer-used indexes and facets to accumulate, taking up disk space and requiring processing that isn’t contributing to the user’s experience.


When you decide to remove a facet, it’s worthwhile to figure out what your real goal is:

  1. The users might want to search against the constraint, but I don’t want to show a facet (list of values). 
  2. The application will never need to search against this constraint.

For #1, take these steps:

  • remove the facet’s configuration from app_config.js (removing the facet from the display)
  • set the facet attribute on the corresponding search:range element to false (telling MarkLogic it doesn’t need to look up values)

For #2, do both of those and go a little further:

  • remove the search:constraint element from the options 
  • if the application doesn’t need the index for some other purpose, delete it

Taking these extra steps will keep your code and configuration cleaner, which makes it easier to maintain.

Tags: , , , ,

Leave a Reply