Create an NLQ synonym

  • Release version: Xanadu
  • Updated August 1, 2024
  • 2 minutes to read

    • Add synonyms to improve the ability of NLQ to recognize the various ways your users request data. With synonyms, you can map commonly used words or terms to table columns.

    Before you begin

    Role required: admin, nlq_admin, or pa_analyst

    About this task

    NLQ synonyms enable you to map common words in your users' requests to the columns in your instance tables. When these words are detected in natural-language queries, NLQ replaces them with actual column and table names, then submits the formal query.

    Several synonyms are provided in the base system, and you can add more for your use cases and business requirements. Review NLQ logs of actual user utterances to find possible synonyms to add. For more information, see View NLQ logs.

    You can create a new synonym, or modify an existing synonym, as follows.

    • If any synonym already exists for your target table and column, you must add your new synonym to the current record. Separate multiple synonyms with a comma.
    • Synonyms can point to reference fields, using dot-walking. For more information, see Dot-walking examples.
    • Synonyms are case-insensitive in queries.
    • Synonyms can contain apostrophes and periods, but not commas.
    • Synonym records are associated to one table. You can use the same synonym term for more than one table, but you must create a record for each table.

    Procedure

    1. Ensure that you are in the application scope you want for your synonym, then navigate to All > NLQ > Synonyms.
    2. Select New.
      If you are updating an existing record, select its Column name in the list.
    3. On the form, fill in the fields.
      Field Description
      Synonym Type
      Type of synonym.
      • Table or Column: Synonym for a value on a table or a specific column in that table.
      • Record: Synonym for a value on the CMDB tables [cmdb_rel_type_table]. For more information, see Querying the CMDB.
        Note:
        Supports cmdb_rel_type,cmdb_group, cmdb_ci_service_technical, cmdb_ci_service_discovered, cmdb_ci_query_based_service tables.
      Application

      [Read only] Application scope that can use the synonym in a query. The default is Global.

      When creating a synonym, ensure that you are in the scope you want for the synonym.
      Table

      Source table.

      You can use the same term for more than one table, but you must create a synonym record for each table. The synonym's mapping is unique to the table.
      Column name

      Specific column on the source table.
      Language

      Language of the synonym. Should match the language of the source value.
      Synonyms

      Words or short phrases that the system should map to column names or tables, when converting the utterance to a formal query.

      Separate multiple synonyms with a comma.
      Extend to All Child Tables

      Table or Column type only.

      Select this option to make any child tables of the source table inherit the synonyms.
    4. Select Submit if new, or Update if you are modifying an existing record.

    Result

    The new synonym is available to your users as soon as they refresh the browser window of the list.

    NLQ Synonym for the Active field

    The following image shows an example of an NLQ synonym record for the Active field on a change request. The synonyms open and in progress are replaced by the term active when the system submits a query.

    NLQ synonym record form for a column synonym.

    With this synonym record, a user can type show open change requests or change requests in progressand the system displays active change requests.