Skip to main content

Highlight Search Results

Highlight - basic example​

// Make a full-text search dynamic query:
// ======================================
List<Employee> employeesResults = session
   // Make a dynamic query on 'Employees' collection
  .Query<Employee>()
   // Search for documents containing the term 'sales' in their 'Notes' field
  .Search(x => x.Notes, "sales")
   // Request to highlight the searched term by calling 'Highlight'
  .Highlight(
      x => x.Notes, // The document-field name in which we search
      35,           // Max length of each text fragment
      4,            // Max number of fragments to return per document
      out Highlightings salesHighlights) // An out param for getting the highlighted text fragments
   // Execute the query
  .ToList();
// Process results:
// ================

// 'employeesResults' contains all Employee DOCUMENTS that have 'sales' in their 'Notes' field.
// 'salesHighlights' contains the text FRAGMENTS that highlight the 'sales' term.

StringBuilder builder = new StringBuilder().AppendLine("<ul>");

foreach (var employee in employeesResults)
{
  // Call 'GetFragments' to get all fragments for the specified employee Id
  string[] fragments = salesHighlights.GetFragments(employee.Id);
  foreach (var fragment in fragments)
  {
      builder.AppendLine(
          $"<li>Doc: {employee.Id} Fragment: {fragment}</li>");
  }
}

string fragmentsHtml = builder.AppendLine("</ul>").ToString();

// The resulting fragmentsHtml:
// ============================

// <ul>
//   <li>Doc: employees/2-A Fragment: company as a <b style="background:yellow">sales</b></li>
//   <li>Doc: employees/2-A Fragment: promoted to <b style="background:yellow">sales</b> manager in</li>
//   <li>Doc: employees/2-A Fragment: president of <b style="background:yellow">sales</b> in March 1993</li>
//   <li>Doc: employees/2-A Fragment: member of the <b style="background:yellow">Sales</b> Management</li>
//   <li>Doc: employees/3-A Fragment: hired as a <b style="background:yellow">sales</b> associate in</li>
//   <li>Doc: employees/3-A Fragment: promoted to <b style="background:yellow">sales</b> representativ</li>
//   <li>Doc: employees/5-A Fragment: company as a <b style="background:yellow">sales</b> representativ</li>
//   <li>Doc: employees/5-A Fragment: promoted to <b style="background:yellow">sales</b> manager in</li>
//   <li>Doc: employees/5-A Fragment: <b style="background:yellow">Sales</b> Management." </li>
//   <li>Doc: employees/6-A Fragment: for the <b style="background:yellow">Sales</b> Professional.</li>
// </ul>

Highlight tags​

  • By default, the highlighted term is wrapped with the following html:
    <b style="background:yellow">term</b>

  • When requesting to highlight multiple terms,
    the background color returned for each different term will be in the following order:

    • <span style="border-left: 10px solid yellow"> </span>yellow,
    • <span style="border-left: 10px solid lawngreen"> </span>lawngreen,
    • <span style="border-left: 10px solid aquamarine"> </span>aquamarine,
    • <span style="border-left: 10px solid magenta"> </span>magenta,
    • <span style="border-left: 10px solid palegreen"> </span>palegreen,
    • <span style="border-left: 10px solid coral"> </span>coral,
    • <span style="border-left: 10px solid wheat"> </span>wheat,
    • <span style="border-left: 10px solid khaki"> </span>khaki,
    • <span style="border-left: 10px solid lime"> </span>lime,
    • <span style="border-left: 10px solid deepskyblue"> </span>deepskyblue,
    • <span style="border-left: 10px solid deeppink"> </span>deeppink,
    • <span style="border-left: 10px solid salmon"> </span>salmon,
    • <span style="border-left: 10px solid peachpuff"> </span>peachpuff,
    • <span style="border-left: 10px solid violet"> </span>violet,
    • <span style="border-left: 10px solid mediumpurple"> </span>mediumpurple,
    • <span style="border-left: 10px solid palegoldenrod"> </span>palegoldenrod,
    • <span style="border-left: 10px solid darkkhaki"> </span>darkkhaki,
    • <span style="border-left: 10px solid springgreen"> </span>springgreen,
    • <span style="border-left: 10px solid turquoise"> </span>turquoise,
    • <span style="border-left: 10px solid powderblue"> </span>powderblue

  • The html tags that wrap the highlighted terms can be customized to any other tags.
    See customize tags below.

Highlight results in Studio​

Figure 1. Fragments results

  1. Auto-Index
    This is the auto-index that was created by the server to serve the dynamic-query.

  2. Results tab
    The results tab contains the resulting documents that match the provided RQL query.

  3. Highlight tab
    The highlight tab shows the resulting fragments that were included in the query result.

Highlight - customize tags​

  • The html tags that wrap the highlighted terms can be customized to any other tags.
// Define customized tags to use for highlighting the searched terms
// =================================================================
HighlightingOptions tagsToUse = new HighlightingOptions
{
  // Provide strings of your choice to 'PreTags' & 'PostTags', e.g.:
  // the first term searched for will be wrapped with '+++'
  // the second term searched for will be wrapped with '<<<' & '>>>'
  PreTags = new[] { "+++", "<<<" },
  PostTags = new[] { "+++", ">>>" }
};

// Make a full-text search dynamic query:
// ======================================
List<Employee> employeesResults = session
  .Query<Employee>()
   // Search for:
   //   * documents containing the term 'sales' in their 'Notes' field
   //   * OR for documents containing the term 'manager' in their 'Title' field
  .Search(x => x.Notes, "sales")
  .Search(x => x.Title, "manager")
   // Call 'Highlight' for each field searched
   // Pass 'tagsToUse' to OVERRIDE the default tags used 
  .Highlight(x => x.Notes, 35, 1, tagsToUse, out Highlightings salesHighlights)
  .Highlight(x => x.Title, 35, 1, tagsToUse, out Highlightings managerHighlights)
  .ToList();
// The resulting salesHighlights fragments:
// ========================================

// "for the +++Sales+++ Professional."
// "hired as a +++sales+++ associate in"
// "company as a +++sales+++"
// "company as a +++sales+++ representativ"

// The resulting managerHighlights fragments:
// ==========================================

// "Sales <<<Manager>>>"

Highlight - projected results​

// Make a full-text search dynamic query & project results:
// ========================================================
var employeesProjectedResults = session
  .Query<Employee>()
   // Search for documents containing 'sales' or 'german' in their 'Notes' field
  .Search(x => x.Notes, "manager german")
   // Request to highlight the searched terms from the 'Notes' field 
  .Highlight(x => x.Notes, 35, 2, out Highlightings termsHighlights)
   // Define the projection
  .Select(x => new
  {
      // These fields will be returned instead of the whole document
      // Note: it is Not mandatory to return the field in which we search for the highlights 
      Name = $"{x.FirstName} {x.LastName}",
      x.Title
  })
  .ToList();
// The resulting fragments from termsHighlights:
// =============================================

// "to sales <b style=\"background:yellow\">manager</b> in March"
// "and reads <b style=\"background:lawngreen\">German</b>.  He joined"
// "to sales <b style=\"background:yellow\">manager</b> in January"
// "in French and <b style=\"background:lawngreen\">German</b>."

// NOTE: each search term is wrapped with a different color
// 'manager' is wrapped with yellow
// 'german' is wrapped with lawngreen

Syntax​

IRavenQueryable<T> Highlight(
  string fieldName,
  int fragmentLength,
  int fragmentCount,
  out Highlightings highlightings);

IRavenQueryable<T> Highlight(
  string fieldName,
  int fragmentLength,
  int fragmentCount,
  HighlightingOptions options,
  out Highlightings highlightings);

IRavenQueryable<T> Highlight(
  Expression<Func<T, object>> path,
  int fragmentLength,
  int fragmentCount,
  out Highlightings highlightings);

IRavenQueryable<T> Highlight(
  Expression<Func<T, object>> path,
  int fragmentLength,
  int fragmentCount,
  HighlightingOptions options,
  out Highlightings highlightings);
ParameterTypeDescription
fieldNamestringName of the field that contains the searched terms to highlight.
pathExpression<Func<T, object>>Path to the field that contains the searched terms to highlight.
fragmentLengthintMaximum length of a text fragment. Must be >= 18.
fragmentCountintMaximum number of text fragments that will be returned.
optionsHighlightingOptionsCustomizing options.
highlightingsHighlightingsAn 'out' param that will contain the highlighted text fragments for each returned result.

Highlighting options:

public string GroupKey { get; set; }
public string[] PreTags { get; set; }
public string[] PostTags { get; set; }
OptionTypeDescription
GroupKeystringGrouping key for the results.
Used when highlighting query results from a Map-Reduce index.
If null results are grouped by document ID (default).
Note: Highlighting is Not available for dynamic aggregation queries.
PreTagsstring[]Array of PRE tags used to wrap the highlighted search terms in the text fragments.
PostTagsstring[]Array of POST tags used to wrap the highlighted search terms in the text fragments.

Highlightings object:

public string FieldName { get; }
public IEnumerable<string> ResultIndents;
PropertyTypeDescription
FieldNamestringName of the field that contains the searched terms to highlight.
ResultIndentsIEumerable<string>The resulting keys (document IDs, or the map-reduce keys)
public string[] GetFragments(string key);
MethodDescription
GetFragmentsReturns the list of the highlighted text fragments for the passed document ID, or the map-reduce key