Category Component 26.1
Category Component Help

# WHEN and NOTWHEN Search Operators

If you set `XMLFullStructure` to `True` in the configuration file, you can use the `WHEN` and `NOTWHEN` search operators to return documents in which XML fields occur with a common parent field. When you set `XMLFullStructure` to `True`, The Content component gives each occurrence of the same XML field name a different field code, so that it can identify each one uniquely.

To return only XML documents in which fields or attributes that have a specific value occur together, apply the `WHEN` operator to words or phrases. You can use the `WHEN` operator to return only those XML documents in which:

- two fields with the same parent field contain specified terms or phrases. See Example 1.

- two attributes that occur in the same field contain specified terms or phrases. See Example 2.

- a field contains a specified term or phrase, and has an attribute with a specific value. See Example 3.

To return only XML documents in which one field or attribute that has a specific value does not occur in the same parent field as another specified field or attribute and value, use the `NOTWHEN` operator. You can use the `NOTWHEN` operator in the same way as the `WHEN` operator. See Example 4.

## Example 1

You can use `WHEN` to return only XML documents in which two fields with the same parent field contain specified terms or phrases.

For example:

    action=Query&Text=audi:make+WHEN+red:color

This query returns only XML documents in which the `make` and `color` fields are children of the same parent field, and contain the values audi and red respectively.

For example, this query returns the following document:

    <XML>
          <car>
             <make>audi</make>
             <color>red</color>
          </car>
          <car>
    >         <make>mercedes</make>
             <color>silver</color>
          </car>
       </DOC>
    </XML>

It does not return the following document:

    <XML>
       <DOC>
          <car>
             <make>audi</make>
             <color>silver</color>
          </car>
          <car>
             <make>mercedes</make>
             <color>red</color>
          </car>
       </DOC>
    </XML>

You can also use complex nested expressions with the `WHEN` operator in query text. For example:

    action=Query&Text=(London:CITY WHEN English:LANG) WHEN ("United Kingdom":COUNTRY)

## Example 2

You can use `WHEN` to return only XML documents in which two attributes that occur in the same field contain specified terms or phrases. For example:

    action=Query&Text=English:_ATTR_LANG WHEN "Cape Town":_ATTR_CAPITAL

This query returns only XML documents in which the `LANG` and `CAPITAL` attributes occur in the same field, and contain the values English (in the `LANG` attribute) and Cape Town (in the `CAPITAL` attribute).

For example, this query returns the following document:

    <XML>
       <DOC>
          <COUNTRY CAPITAL="Cape Town" LANG="English" POP="44">South Africa</COUNTRY>
          <COUNTRY CAPITAL="Berlin" LANG="German" POP="80">Germany</COUNTRY>
       </DOC>
    </XML>

It does not return the following document:

    <XML>
       <DOC>
          <COUNTRY CAPITAL="Cape Town" LANG="Afrikaans" POP="10">South Africa</COUNTRY>
          <COUNTRY CAPITAL="London" LANG="English" POP="80">England</COUNTRY>
       </DOC>
    </XML>

## Example 3

You can also use `WHEN` to return only XML documents in which a field contains a specified term or phrase, and has an attribute that has a specific value. For example:

    action=Query&Text=Fr.html:_ATTR_HREF WHEN France:A

This query returns only XML documents in which an `A` field contains the value France, and has an `HREF` attributes with the value Fr.html.

For example, this query returns the following document:

    <XML>
       <DOC>
          <A HREF="Fr.html">France</A>
       </DOC>
    </XML>

## Example 4

You can use `NOTWHEN` to return XML documents that contain one field with a specified term and phrase, but that do not contain another field and value in the same parent field.

    action=Query&Text=audi:make+NOTWHEN+red:color

This query returns only XML documents in which the `make` field contains the value `audi`, under a parent field that does not also have a `color` field with the value `red`.

For example, this query returns the following document:

    <XML>
       <DOC>
          <car>
             <make>audi</make>
             <color>silver</color>
          </car>
          <car>
             <make>mercedes</make>
             <color>red</color>
          </car>
       </DOC>
    </XML>

It does not return the following document:

    <XML>
       <DOC>
          <car>
             <make>audi</make>
             <color>red</color>
          </car>
          <car>
             <make>mercedes</make>
             <color>silver</color>
          </car>
       </DOC>
    </XML>

## Specify the Number of Levels from the XML Root

You can add a numeric value to the `WHEN` operator to indicate the number of hierarchical levels from the XML root from which to match the terms or phrases.

For example, if you have the following XML document:

    <?xml version="1.0"?>
    <XML>
       <DOCUMENT>
          <DREREFERENCE>Reference_1</DREREFERENCE>
          <car>
             <make>ford</make>
             <color>
                <exterior>blue</exterior>
                <interior>black</interior>
             </color>
          </car>
       </DOCUMENT>
       <DOCUMENT>
          <DREREFERENCE>Reference_2</DREREFERENCE>
          <car>
             <make>ferrari</make>
             <color>
                <exterior>blue</exterior>
                <interior>brown</interior>
             </color>
          </car>
          <car>
             <make>ford</make>
             <color>
                <exterior>yellow</exterior>
                <interior>blue</interior>
             </color>
          </car>
       </DOCUMENT>
    </XML>

The following query returns both documents, because the `exterior` and `make` fields share the same parent field (`<DOCUMENT>`), which is two levels from the root, and contain blue and ford respectively.

    action=Query&Text=blue:EXTERIOR+WHEN2+ford:MAKE

The following query returns only `Reference_1`, because the `exterior` and `make` fields share the same parent field (`<car>`), which is three levels from the root, and contain blue and ford respectively.

    action=Query&Text=blue:EXTERIOR+WHEN3+ford:MAKE

The following query does not return either document, because the `exterior` and `make` fields do not share the same parent field four levels from the root.

    action=Query&Text=blue:EXTERIOR+WHEN4+ford:MAKE

Copyright 2025 Open Text
Version 26.1 | Last updated January 2026

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: Knowledge Discovery Category Component 26.1

Topic Title: WHEN and NOTWHEN Search Operators