Free cookie consent management tool by TermsFeed

Display Semantic Search Match Quality in a Read-Only Grid

On This Page

Tip:  Interface patterns give you an opportunity to explore different interface designs. Be sure to check out How to Adapt a Pattern for Your Application.

Goal

Display a column in a read-only grid that illustrates if the semantic search results are strong, moderate, fair, or weak.

This design pattern is not recommended for offline interfaces because reflecting immediate changes in an interface based on user interaction requires a connection to the server.

images/grid-with-smartSearch-default.png

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to closeimages/grid-with-smartSearch-default.png

Design structure

This recipe shows how to configure a column in a read-only grid that indicates whether a semantic search result is strong, moderate, fair, or weak. This allows users to quickly understand why certain search results are higher than others.

The column in this grid will use the similarity score returned from each search result to determine which value to display.

In most cases, sorting results by similarity score is enough to surface the most relevant matches first, and you don't need to display a match quality indicator to end users. However, if your use case requires users to understand relative match strength, use qualitative labels (like "Strong" or "Moderate") rather than the raw similarity score. The similarity score is not a percentage match—it's a mathematical value based on semantic meaning that is only meaningful in the context of your specific data.

The expression for this recipe:

  • Displays the default search box on the grid.
  • Applies both keyword search and semantic search in the grid by setting the smartSearchType to "SEMANTIC".
  • Sets the similarityScoreThreshold to 0.5 to exclude semantic matches below that score. The right threshold depends on your data and use case.
  • Includes a column called "Match Quality" to indicate the quality of the search result with green circles and hover text. The range of similarity score values used in this recipe are for example purposes only. You must test semantic search with your data to determine which similarity score ranges are most meaningful for your data and use case.
  • Sorts the results by the primary similarity score in descending, since a row of data could have a match in both the title and description fields.

Note:  This recipe does not use the searchFields parameter because the two fields enabled for smart search (title and description) are already displayed as columns in the grid. The searchFields parameter is only needed when you want to search fields not displayed in the grid or limit which fields are searched for performance reasons.

Setup

To use this recipe in your own environment, you'll need a synced record type with smart search enabled on at least one field of type Text, Extra Long Text, or Document. In this recipe, the title and description fields both have smart search enabled.

The expression in this recipe uses a sample record type called ACME Case. To test this expression, you must replace it with the record type with smart search enabled in your environment.

Expression

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

a!gridField(
  labelPosition: "ABOVE",
  data: recordType!Case,
  /* Shows the default search box on the grid */
  showSearchBox: true,
  /* Sets the type of smart search to apply */
  smartSearchType: "SEMANTIC",
  /*Filters out semantic search matches under this threshold */
  /* This similarity score range is for example purposes only */
  /* The similarity scores you choose will depend on your data and search criteria */
  similarityScoreThreshold: 0.5,
  columns: {
    a!gridColumn(
      label: "Title",
      sortField: recordType!Case.fields.title,
      value: a!richTextDisplayField(
        value: {
          a!richTextItem(
            text: fv!row[recordType!Case.fields.title],
            link: a!recordLink(
              recordType: recordType!Case,
              identifier: fv!identifier
            ),
            linkStyle: "STANDALONE"
          )
        }
      ),
    ),
    a!gridColumn(
      label: "Description",
      sortField: recordType!Case.fields.description,
      value: a!defaultValue(
        fv!row[recordType!Case.fields.description],
        "-"
      )
    ),
    /*Displays labels and colors that align with similarity score meaning*/
    /* This similarity score range is for example purposes only */
    /* The similarity scores you choose will depend on your data and search criteria */
    a!gridColumn(
      label: "Match Quality",
      sortField: recordType!Case.searchResults.allSearchFields.similarityScore,
      value: a!localVariables(
        local!scoreValue: fv!row[recordType!Case.searchResults.allSearchFields.similarityScore],
        local!circleCount: { 1, 1, 1 },
        local!color: a!match(
          value: local!scoreValue,
          whenTrue: fv!value = 1,
          then: "#0f90FF",
          whenTrue: fv!value >= 0.8,
          then: "#0f9037",
          whenTrue: and(fv!value >= 0.7, fv!value < 0.8),
          then: "#119f3d",
          whenTrue: and(fv!value >= 0.5, fv!value < 0.7),
          then: "#12a740",
          default: "#83f9a8"
        ),
        if(
          a!isNullOrEmpty(local!scoreValue),
          "---",
          a!richTextDisplayField(
            value: a!forEach(
              items: local!circleCount,
              expression: a!richTextIcon(icon: "circle", color: local!color)
            ),
           /* This similarity score range is for example purposes only */
           /* The similarity scores you choose will depend on your data and search criteria */
            tooltip: a!match(
              value: local!scoreValue,
              whenTrue: fv!value = 1,
              then: "Exact",
              whenTrue: fv!value >= 0.8,
              then: "Strong",
              whenTrue: and(fv!value >= 0.5, fv!value < 0.8),
              then: "Moderate",
              whenTrue: and(fv!value >= 0.5, fv!value < 0.5),
              then: "Fair",
              default: "Weak"
            )
          )
        )
      )
    )
  },
  initialSorts: {
    /*Sorts by similarity score in descending order if applicable*/
    a!sortInfo(
      field: recordType!Case.searchResults.allSearchFields.similarityScore,
      ascending: false()
    ),
    /* Defaults to sorting by primary key */
    a!sortInfo(
      field: recordType!Case.fields.id,
      ascending: true
    )
  }
)

Test it out

To test the default search box:

  1. Enter a search term into the search box. This can be a few words or a phrase.
  2. Review the search results. Look for rows that are semantically related to your search term, even if the exact words aren't present. These are the semantic search matches, and they will have a similarityScore less than 1.

Notable implementation details

This recipe uses the default search box available in the read-only grid. If you want to create a custom search box and still use semantic search, see Configure a Custom Search Box with Semantic Search.

Feedback