# Create Synonym Rules

In all synonym rules, the IDX rule document has the same basic form.

The table shows all the fields that you must include in the IDX file for synonym rules. The value of the `KEYWORDS` and `CONCEPT` fields determines whether the rule is a synonym, hyponym, or hypernym rule.

Required IDX fields for synonym rules

Field | Description | Content type or value
--- | --- | ---
`#DREREFERENCE` | The reference for the rule. | String
`#DRETITLE` | The title of the rule. | String
`QMSTYPE` | The type of the QMS rule. | `4`
`QMSAGENTBOOL` | The AgentBoolean expression to use to match the original query text. | Boolean matching expression
`KEYWORDS` | A list of words to match in the original query text. | Comma-separated list of words or phrases.
`CONCEPT` | The expanded query text that replaces the matched query text. | Replacement string.
`DATABASERESTRICTION` | (Optional) The Content databases that this rule matches. If you include this field, QMS applies the synonym rule only if the original query includes a `DatabaseMatch` parameter with at least one database that matches the `DATABASERESTRICTION`. QMS applies this field only when the original query includes the `DatabaseMatch` and `SynonymDatabaseMatch` action parameters. | String
`SYNONYMDATABASEMATCH` | Set a value for this field to use synonym database matches in this rule. If this field is empty or missing, QMS does not apply the `DATABASERESTRICTION` for this rule. |
`SYNONYMREPLACE` | (Optional) A Boolean value that specifies whether to replace the whole query text with the `CONCEPT`. This field value overrides the value of the `SynonymReplace` action parameter for queries that match this rule. | `TRUE` or `FALSE`

When a query matches the rule, QMS replaces any of the specified `KEYWORDS` that exist in the text with the value in the `CONCEPT` field.

NOTE: If you set `SYNONYMREPLACE` to `TRUE`, the `KEYWORDS` field is not required, and QMS always replaces the whole query text.

`KEYWORDS` can be a list of individual words or phrases. Separate each word or phrase with a comma. For example:

    #DREFIELD KEYWORDS="Software Development Kit,SDK"

When you use phrases, the entire phrase must match the query text for QMS to apply the rule. For example, software does not match this keyword example.

If your keyword phrase contains a comma, you must percent-encode it in the rule. For example:

    #DREFIELD KEYWORDS="Hello%2C World,Goodbye"

NOTE: QMS does not apply synonyms to exact phrase searches by default. For more information, see Expand Exact Phrase Searches.

`CONCEPT` can be any valid query text string, which QMS inserts into the query text in place of the matching keyword or phrase. For example:

    #DREFIELD CONCEPT=""Software Development Kit" OR SDK"

QMS surrounds multiple-word query strings with brackets when it modifies the query. For example, if a user searches for `SDK OR API`, QMS expands the query to (`"Software Development Kit" OR SDK) OR API`.

TIP: You can use the `SYNONYM` query operator in the `CONCEPT` field. This operator contains a list of synonymous terms. When IDOL Server processes this query, it finds results that contain any of the synonymous terms. For result weighting, IDOL Server treats all the synonyms as if they are a single term, which can improve the result ordering. For example:

    #DREFIELD CONCEPT="SYNONYM("Software Development Kit" SDK)"

For more information, refer to the IDOL Server Administration Guide.

You can use the `$QUERYTEXT$` template string in the `CONCEPT` field, to insert the original query text. For example, if you have a Wildcard in your AgentBoolean rule, you can include the query text in `CONCEPT` to capture all possible variations of the wildcard expression without enumerating them individually. For example:

    #DREFIELD QMSAGENTBOOL "Al* AND Smith"
    #DREFIELD KEYWORDS "Al Smith"
    #DREFIELD CONCEPT "(Alexander Smith) OR ($QUERYTEXT$)"

TIP: You might want to use this template string with the `SYNONYMREPLACE` field, to avoid repeating the original text in the final modified query.

You can use an appropriate combination of `KEYWORDS` and `CONCEPTS` to create synonym, hyponym, and hypernym rules.

To create a synonym rule

- Set the `KEYWORDS` field to a list of all the synonymous terms, and set the `CONCEPT` field to the same list.

  QMS expands any query that matches one keyword to include all the other keyword terms.

To create a hyponym rule

- Set the `KEYWORDS` field to the parent term, and set the `CONCEPT` field to the list of terms that the parent term describes (the hyponyms).

  QMS alters a query that matches the parent term to include all the hyponyms, but not the original term.

To create a hypernym rule

- Set the `KEYWORDS` field to a list of the terms that the hypernym describes, and set the `CONCEPT` field to the parent term (hypernym).

  QMS alters any query that matches one of the list of child terms to query for the hypernym (and not the original term).

Related Topics

- Example Synonym Rules
- Example Hyponym Rule
- Example Hypernym Rule

_FT_HTML5_bannerTitle.htm