a!smartSearch() Function

Searches record data using smart search. You can narrow the search scope to specific records using record identifiers, ensuring that search results are confined to a targeted subset of data.

Parameters

a!smartSearch( searchField, searchType, searchTerms, identifiers, similarityScoreThreshold, applyWhen )

Returns

QueryFilter

Using the function

The following sections cover important details about the a!smartSearch() function.

Where to use this function

The a!smartSearch() function can be used in the filters parameter of the following functions:

• a!queryRecordType()
• a!recordData() (Only in read-only grids)
• a!relatedRecordData()

When to use a!smartSearch() versus a!queryFilter()

It's recommended to use a!smartSearch() for all smart search queries. You can also implement smart search using the "semantic search" and "lexical search" operators in a!queryFilter(), but a!smartSearch() offers additional capabilities like narrowing the search scope to specific records and filtering by similarity score in a single parameter.

Use a!smartSearch() to:

• Search an entire record type: Leave the identifiers parameter null.
• Search a specific subset: Pass record identifiers to the identifiers parameter to narrow the scope before the search executes.
• Set a similarity threshold: Use the similarityScoreThreshold parameter to control minimum match quality.

Using the searchType parameter

The searchType parameter determines the type of search applied to your field. Both search types require the target field to be enabled for smart search.

• "semantic search": Performs an AI-powered search based on intent and meaning. Matches are based on how closely their content relates to the search terms, even if the exact words are different.
• "lexical search": Performs a full-text search. Matches the full, consecutive search term and is not case sensitive.

Using the identifiers parameter

The identifiers parameter narrows the search scope to a specific subset of records. When you supply record identifiers, the search only evaluates those records rather than the entire record type.

Use the identifiers parameter when you want to:

• Search a single document or small set of documents: Pass the identifiers for the specific records you want to search, such as a contract or support case a user is currently viewing.
• Search within user-filtered results: First query for records that match the user's selected filters (such as status, category, or location), then pass those identifiers to identifiers so the search only evaluates the filtered subset. See an example retrieving identifiers from a separate query.
• Improve result relevance for large record types: For record types with a high volume of data, narrowing the scope ensures the search results reflect the records that matter to the user.

Valid values for the identifiers parameter

The identifiers parameter accepts a list of valid primary key values for the record type specified in the query. When the parameter is null, a!smartSearch() searches the entire record type. This allows a single expression to handle both full-scope and narrowed-scope queries depending on runtime context.

You can populate the identifiers parameter with:

• The result of a separate query: Use a!queryRecordType() to retrieve identifiers based on filter criteria, then pass those IDs to identifiers. See an example retrieving identifiers to search on.
• A constant or local variable: Pass a predefined list of IDs directly.
• A rule input: Accept IDs from a calling interface or process model.

Why use the identifiers parameter in a!smartSearch() instead of combining filters

When a!smartSearch() and a!queryFilter() are both in the same a!queryLogicalExpression() without specifying identifiers, the a!smartSearch() function evaluates the full record type. The a!queryFilter() in the same expression does not control which records the search evaluates, it only filters the results after the search has already run. This means relevant records can be excluded from the results entirely.

For example, the following expression searches the entire Case record type for "connectivity issues" and then further filters the already-returned search results to only In Progress cases:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
filters: a!queryLogicalExpression(
  operator: "AND",
  filters: {
    a!smartSearch(
      searchType: "semantic search",
      searchField: recordType!Case.fields.description,
      searchTerms: "connectivity issues"
    ),
    /* This filter does NOT narrow what the search evaluates */
    a!queryFilter(
      field: recordType!Case.fields.status,
      operator: "=",
      value: "In Progress"
    )
  }
)

Sample output (2 results):

1
2
3
4
5
6
7
8
9
data (List of Case)
Case
  id: 107
  title: "VPN drops during peak hours"
  description: "Users experience intermittent connectivity drops when connected to the corporate VPN during peak usage."
Case
  id: 892
  title: "Wireless network instability"
  description: "Office wireless network loses connection every 30 minutes. IT replaced the access point but issue persists."

The search evaluated all cases and returned the top matches. Only 2 of those top matches happened to be In Progress. Other In Progress cases that are strong matches for "connectivity issues" were not returned because they scored lower than non-In-Progress cases across the full record type.

When identifiers is populated, the search is confined to only those records:

1
2
3
4
5
6
7
filters: a!smartSearch(
  searchType: "semantic search",
  searchField: recordType!Case.fields.description,
  searchTerms: "connectivity issues",
  /* The search only evaluates these records */
  identifiers: local!inProgressIds
)

Sample output (5 results):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
data (List of Case)
Case
  id: 107
  title: "VPN drops during peak hours"
  description: "Users experience intermittent connectivity drops when connected to the corporate VPN during peak usage."
Case
  id: 892
  title: "Wireless network instability"
  description: "Office wireless network loses connection every 30 minutes. IT replaced the access point but issue persists."
Case
  id: 456
  title: "Recurring connectivity issues in Building B"
  description: "Multiple users in Building B report recurring connectivity issues with the office Wi-Fi since last Monday."
Case
  id: 301
  title: "Remote desktop disconnections"
  description: "Remote desktop sessions drop intermittently when users connect over VPN from home offices."
Case
  id: 780
  title: "Latency spikes on internal network"
  description: "Internal applications experience high latency and occasional timeouts during business hours."

The search evaluated only In Progress cases, so all relevant matches within that subset are returned.

Using the similarityScoreThreshold parameter

The similarityScoreThreshold parameter controls how closely search results must match the search term to be returned. Only results with a similarity score at or above the threshold are returned. Only use this parameter when the searchType parameter is set to "semantic search".

When null (the default), all search results are returned regardless of their similarity score. Decrease the threshold value to return a broader range of semantic matches. Increase it to return a more narrow set of results. Learn how to interpret similarity scores.

Combining a!smartSearch() with other functions

You can combine multiple a!smartSearch() functions or mix a!smartSearch() with a!queryFilter() in the same query using a!queryLogicalExpression(). Common patterns include:

• Search multiple fields: Use a separate a!smartSearch() function for each field you want to search, combined in a!queryLogicalExpression(). See an example searching multiple fields.
• Combine semantic and lexical search: Use two a!smartSearch() functions—one with searchType set to "semantic search" and another set to "lexical search". This returns records that match the exact search term or records that are conceptually related. When a record matches both functions, it appears only once in the results. See an example performing semantic and lexical search.
• Apply standard filters to search results: Add a!queryFilter() calls alongside a!smartSearch() to filter results by other criteria like status or priority. Note that other a!queryFilter() calls in the same expression do not narrow which records the search evaluates—use the recordIds parameter for that. See an example combining a!smartSearch() with a!queryFilter().

Examples

The following examples demonstrate the a!smartSearch() function.

These examples reference record types from another environment and will error if you try to use them in yours. Use them as a reference only.

Search an entire record type

The following example performs a semantic search across all records in the Case record type. When the identifiers parameter is not specified, a!smartSearch() searches the entire record type. The similarityScoreThreshold parameter ensures only results with a similarity score at or above 0.3 are returned.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
a!queryRecordType(
  recordType: recordType!Case,
  fields: {
    recordType!Case.fields.id,
    recordType!Case.fields.title,
    recordType!Case.fields.description,
    recordType!Case.searchResults.description
  },
  filters: a!smartSearch(
    searchField: recordType!Case.fields.description,
    searchType: "semantic search",
    searchTerms: "software outage",
    similarityScoreThreshold: 0.3
  ),
  pagingInfo: a!pagingInfo(
    startIndex: 1, 
    batchSize: 10,
    sort: a!sortInfo(
      field: recordType!Case.searchResults.description.similarityScore,
      ascending: false
    )
  )
)

Sample output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
data (List of Case)
Case
  id: 2
  title: "Software update failure"
  description: "Attempted to update ERP system, update failed midway. Rolled back to previous version."
  searchResults.description
    similarityScore: 0.82
    sourceContent: "Attempted to update ERP system, update failed midway. Rolled back to previous version."
Case
  id: 44
  title: "Application errors after update"
  description: "After applying a software update, users reported errors when accessing certain features."
  searchResults.description
    similarityScore: 0.65
    sourceContent: "After applying a software update, users reported errors when accessing certain features."

Search a single document

The following example performs a semantic search on a single contract document. The identifiers parameter limits the search to only the specified record, allowing users to search within a specific document. The similarityScoreThreshold parameter ensures only results with a similarity score at or above 0.3 are returned.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
a!queryRecordType(
  recordType: recordType!Contract,
  fields: {
    recordType!Contract.fields.id,
    recordType!Contract.fields.title,
    recordType!Contract.fields.document,
    recordType!Contract.searchResults.document.searchMatches
  },
  filters: a!smartSearch(
    searchField: recordType!Contract.fields.document,
    searchType: "semantic search",
    searchTerms: "termination clause",
    identifiers: { 42 },
    similarityScoreThreshold: 0.3
  ),
  pagingInfo: a!pagingInfo(
    startIndex: 1, 
    batchSize: 5,
    sort: a!sortInfo(
      field: recordType!Contract.searchResults.document.similarityScore,
      ascending: false
    )
  )
)

Sample output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
data (List of Contract)
Contract
  id: 42
  title: "Vendor Services Agreement - Acme Corp"
  searchResults.document.searchMatches
    - similarityScore: 0.91
      sourceContent: "Either party may terminate this agreement with 30 days written notice to the other party."
      page: 5
    - similarityScore: 0.85
      sourceContent: "Upon termination, the receiving party must return or destroy all confidential materials within 10 business days."
      page: 7
    - similarityScore: 0.72
      sourceContent: "Early termination fees apply if the agreement is cancelled before the end of the initial term."
      page: 12

Perform semantic search on a subset of records

The following example searches only In Progress cases for semantic matches to "connectivity issues". The record IDs are retrieved in a separate query and passed to the identifiers parameter. The similarityScoreThreshold parameter ensures only results with a similarity score at or above 0.3 are returned.

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
a!localVariables(
  /* Get the identifiers of all In Progress cases */
  local!inProgressIds: a!queryRecordType(
    recordType: recordType!Case,
    fields: recordType!Case.fields.id,
    filters: a!queryFilter(
      field: recordType!Case.relationships.status.fields.value,
      operator: "=",
      value: "In Progress"
    ),
    pagingInfo: a!pagingInfo(startIndex: 1, batchSize: 100)
  ).data[recordType!Case.fields.id],
  /* Search only In Progress cases */
  a!queryRecordType(
    recordType: recordType!Case,
    fields: {
      recordType!Case.fields.id,
      recordType!Case.fields.title,
      recordType!Case.fields.description,
      recordType!Case.relationships.status.fields.value,
      recordType!Case.searchResults.description
    },
    filters: a!smartSearch(
      searchField: recordType!Case.fields.description,
      searchType: "semantic search",
      searchTerms: "connectivity issues",
      identifiers: local!inProgressIds,
      similarityScoreThreshold: 0.3
    ),
    pagingInfo: a!pagingInfo(
      startIndex: 1, 
      batchSize: 10,
      sort: a!sortInfo(
      field: recordType!Case.searchResults.description.similarityScore,
      ascending: false
      )
    )
  ).data
)

Sample output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
data (List of Case)
Case
  id: 107
  title: "VPN drops during peak hours"
  description: "Users experience intermittent connectivity drops when connected to the corporate VPN during peak usage."
  status.value
    id: 2
    value: "In Progress"
  searchResults.description
    similarityScore: 0.74
    sourceContent: "Users experience intermittent connectivity drops when connected to the corporate VPN during peak usage."
Case
  id: 892
  title: "Wireless network instability"
  description: "Office wireless network loses connection every 30 minutes. IT replaced the access point but issue persists."
  status.value
    id: 2
    value: "In Progress"
  searchResults.description
    similarityScore: 0.61
    sourceContent: "Office wireless network loses connection every 30 minutes. IT replaced the access point but issue persists."

Perform lexical search on a subset of records

The following example performs a lexical (full-text) search on the same subset of In Progress cases used in the semantic search example. Unlike semantic search, lexical search only returns records that contain the exact, consecutive search term. Compare the results to see how the two search types return different matches from the same data.

This example sorts by similarity score to return the most exact matches first, but does not include the score in the query results. Similarity scores are intended for developer configuration and sorting—do not display them to end users.

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
a!localVariables(
  /* Get the identifiers of all In Progress cases */
  local!inProgressIds: a!queryRecordType(
    recordType: recordType!Case,
    fields: recordType!Case.fields.id,
    filters: a!queryFilter(
      field: recordType!Case.relationships.status.fields.value,
      operator: "=",
      value: "In Progress"
    ),
    pagingInfo: a!pagingInfo(startIndex: 1, batchSize: 100)
  ).data[recordType!Case.fields.id],
  /* Lexical search only In Progress cases */
  a!queryRecordType(
    recordType: recordType!Case,
    fields: {
      recordType!Case.fields.id,
      recordType!Case.fields.title,
      recordType!Case.fields.description
    },
    filters: a!smartSearch(
      searchField: recordType!Case.fields.description,
      searchType: "lexical search",
      searchTerms: "connectivity issues",
      identifiers: local!inProgressIds
    ),
    pagingInfo: a!pagingInfo(
      startIndex: 1,
      batchSize: 10,
      sort: a!sortInfo(
        field: recordType!Case.searchResults.description.similarityScore,
        ascending: false
      )
    )
  ).data
)

Sample output:

1
2
3
4
5
data (List of Case)
Case
  id: 456
  title: "Recurring connectivity issues in Building B"
  description: "Multiple users in Building B report recurring connectivity issues with the office Wi-Fi since last Monday."

The semantic search example returns records about VPN drops and network instability—concepts related to "connectivity issues" even though the exact phrase does not appear. The lexical search example returns only the record that contains the exact phrase "connectivity issues" in its description.

Search across multiple fields

The following example combines two a!smartSearch() functions in a single query to search both the title and description fields for semantic matches. Using a!queryLogicalExpression() with the "OR" operator returns records that match in either field. The similarityScoreThreshold parameter ensures only results with a similarity score at or above 0.3 are returned.

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
a!queryRecordType(
  recordType: recordType!Case,
  fields: {
    recordType!Case.fields.id,
    recordType!Case.fields.title,
    recordType!Case.fields.description,
    recordType!Case.searchResults.title,
    recordType!Case.searchResults.description
  },
  filters: a!queryLogicalExpression(
    operator: "OR",
    filters: {
      a!smartSearch(
        searchField: recordType!Case.fields.title,
        searchType: "semantic search",
        searchTerms: "software outage",
        identifiers: { 1, 2, 3, 4, 5 },
        similarityScoreThreshold: 0.3
      ),
      a!smartSearch(
        searchField: recordType!Case.fields.description,
        searchType: "semantic search",
        searchTerms: "software outage",
        identifiers: { 1, 2, 3, 4, 5 },
        similarityScoreThreshold: 0.3
      )
    }
  ),
  pagingInfo: a!pagingInfo(
    startIndex: 1, 
    batchSize: 10,
     a!sortInfo(
      field: recordType!Case.searchResults.allSearchFields.similarityScore,
      ascending: false
    )
  )
)

Sample output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
data (List of Case)
Case
  id: 2
  title: "Software update failure"
  description: "Attempted to update ERP system, update failed midway. Rolled back to previous version."
  searchResults.title
    similarityScore: 0.71
    sourceContent: "Software update failure"
  searchResults.description
    similarityScore: 0.82
    sourceContent: "Attempted to update ERP system, update failed midway. Rolled back to previous version."
Case
  id: 44
  title: "Application errors after update"
  description: "After applying a software update, users reported errors when accessing certain features."
  searchResults.title
    similarityScore: null
    sourceContent: null
  searchResults.description
    similarityScore: 0.65
    sourceContent: "After applying a software update, users reported errors when accessing certain features."

Perform a semantic and lexical search

The following example applies both semantic and lexical search on the same field using two a!smartSearch() functions within a!queryLogicalExpression(). The semantic search returns records that are conceptually related to "software outage," while the lexical search returns records that contain the exact phrase. When a record matches both, it appears only once in the results.

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
a!queryRecordType(
  recordType: recordType!Case,
  fields: {
    recordType!Case.fields.id,
    recordType!Case.fields.title,
    recordType!Case.fields.description,
    recordType!Case.searchResults.description
  },
  filters: a!queryLogicalExpression(
    operator: "OR",
    filters: {
      a!smartSearch(
        searchField: recordType!Case.fields.description,
        searchType: "semantic search",
        searchTerms: "software outage",
        recordIds: { 1, 2, 3, 4, 5 },
        similarityScoreThreshold: 0.3
      ),
      a!smartSearch(
        searchField: recordType!Case.fields.description,
        searchType: "lexical search",
        searchTerms: "software outage",
        recordIds: { 1, 2, 3, 4, 5 }
      )
    }
  ),
  pagingInfo: a!pagingInfo(startIndex: 1, batchSize: 10)
)

Sample output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
data (List of Case)
Case
  id: 15
  title: "Software outage on March 3"
  description: "A software outage impacted the billing system for approximately two hours on March 3."
  searchResults.description
    similarityScore: 1.4
    sourceContent: "A software outage impacted the billing system for approximately two hours on March 3."
Case
  id: 2
  title: "Software update failure"
  description: "Attempted to update ERP system, update failed midway. Rolled back to previous version."
  searchResults.description
    similarityScore: 0.82
    sourceContent: "Attempted to update ERP system, update failed midway. Rolled back to previous version."

The sample output contains results with a range of similarity scores:

• Results with a similarity score greater than 1 are lexical matches (exact phrase found).
• Results with a score less than 1 are semantic matches (conceptually related).

In this example, the first result (score 1.4) is a lexical match because the description contains the exact phrase "software outage," while the second result (score 0.82) is a semantic match because the content is conceptually related to a software outage.

Combine a!smartSearch() with a!queryFilter()

The following example uses a!smartSearch() to perform a scoped semantic search, combined with a standard a!queryFilter() to further filter results by priority. The similarityScoreThreshold parameter ensures only results with a similarity score at or above 0.3 are returned.

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
a!queryRecordType(
  recordType: recordType!Case,
  fields: {
    recordType!Case.fields.id,
    recordType!Case.fields.title,
    recordType!Case.fields.description,
    recordType!Case.relationships.priority.fields.value,
    recordType!Case.searchResults.description
  },
  filters: a!queryLogicalExpression(
    operator: "AND",
    filters: {
      a!smartSearch(
        searchField: recordType!Case.fields.description,
        searchType: "semantic search",
        searchTerms: "software outage",
        identifiers: { 1, 2, 3 },
        similarityScoreThreshold: 0.3
      ),
      a!queryFilter(
        field: recordType!Case.relationships.priority.fields.value,
        operator: "=",
        value: "Critical"
      )
    }
  ),
  pagingInfo: a!pagingInfo(
    startIndex: 1, 
    batchSize: 10,
    sort: a!sortInfo(
      field: recordType!Case.searchResults.description.similarityScore,
      ascending: false
    )
  )
)

Sample output:

1
2
3
4
5
6
7
8
9
10
11
data (List of Case)
Case
  id: 2
  title: "Software update failure"
  description: "Attempted to update ERP system, update failed midway. Rolled back to previous version."
  status.priority
    id: 3
    value: "Critical"
  searchResults.description
    similarityScore: 0.82
    sourceContent: "Attempted to update ERP system, update failed midway. Rolled back to previous version."

Feature compatibility

Feedback