> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# クエリ言語

> FlexiCapture 抽出スクリプト用の XML クエリ言語: Required、Optional、Except 要素、距離、あいまい検索を使用して Contain クエリを構築します。

クエリでは、文書に含まれている必要がある単語や単語の組み合わせを指定します。抽出スクリプトで使用されるクエリ言語は XML ベースです。

<div id="basic-query-structure">
  ## 基本的なクエリ構造
</div>

基本的なクエリは次のようになります。

```xml theme={null}
<Request>
    <Query>
        <Contain>
            <Required>
                <Form><Text>first</Text></Form>
            </Required>
            <Optional>
                <Form><Text>second</Text></Form>
            </Optional>
            <Except>
                <Query>
                    <Contain>
                        <Required>
                            <Form><Text>third</Text></Form>
                        </Required>
                        <Optional>
                            <Form><Text>fourth</Text></Form>
                        </Optional>
                    </Contain>
                </Query>
            </Except>
        </Contain>
    </Query>
</Request>
```

クエリは、次の要素で構成されます。

| Element     | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `<Request>` | クエリのルート要素です。                                                                      |
| `<Query>`   | 基本クエリです。単語の組み合わせが満たすべき条件を指定するクエリツリーを含みます。基本クエリは、上位レベルのクエリで単語形の組み合わせの一部にできます。必須です。 |
| `<Contain>` | 文書に含まれている必要がある単語または単語の組み合わせを指定します。クエリに指定できる `<Contain>` 要素は 1 つだけです。必須です。         |

`<Contain>` 要素には、次の要素を任意の順序でいくつでも含めることができます。

| Element      | Description                                   |
| ------------ | --------------------------------------------- |
| `<Required>` | 単語の組み合わせに含まれている必要がある単語形またはサブクエリを指定します。省略可能です。 |
| `<Optional>` | 単語の組み合わせに含めることができる単語形またはサブクエリを指定します。省略可能です。   |
| `<Except>`   | 単語の組み合わせに含めてはならない単語形またはサブクエリを指定します。省略可能です。    |

これらの各要素には、次のいずれか 1 つを含める必要があります。

| Element   | Description                        |
| --------- | ---------------------------------- |
| `<Query>` | 単語形の文字列を単語の組み合わせに含めるか、除外するかを指定します。 |
| `<Form>`  | 単語形を単語の組み合わせに含めるか、除外するかを指定します。     |

<Note>
  `<Contain>` 要素には、少なくとも 1 つの `<Required>` 要素または `<Optional>` 要素が必要です。
</Note>

<div id="attributes-of-the-contain-element">
  ## Contain 要素の属性
</div>

単語形の組み合わせに対する追加の制約は、`<Contain>` タグの属性で指定できます。

<div id="mincount-attribute">
  ### MinCount 属性
</div>

`MinCount` 属性では、単語形の組み合わせに含まれる要素の最小数を指定します。各要素には、単語形、またはサブクエリによって返される単語形の並びを指定できます。この属性のデフォルト値は `1` です。このパラメーターの値は、単語形の組み合わせに含まれる `<Required>` 要素と `<Optional>` 要素の合計数を超えてはなりません。

このパラメーターは、単語形の組み合わせに 1 つ以上の `<Optional>` 要素が含まれる場合に便利です。

次のクエリは、1 番目または 2 番目のパラメーターを探します。

```xml theme={null}
<Query>
    <Contain>
        <Optional>
            <Form><Text>first</Text></Form>
        </Optional>
        <Optional>
            <Form><Text>second</Text></Form>
        </Optional>
    </Contain>
</Query>
```

次のクエリでは、クエリで指定した4つの単語のうち少なくとも3つに一致し、そのうち2つは必須です。

```xml theme={null}
<Query>
    <Contain MinCount="3">
        <Optional>
            <Form><Text>US</Text></Form>
        </Optional>
        <Required>
            <Form><Text>President</Text></Form>
        </Required>
        <Optional>
            <Form><Text>Barack</Text></Form>
        </Optional>
        <Required>
            <Form><Text>Obama</Text></Form>
        </Required>
    </Contain>
</Query>
```

このクエリでは、次のフレーズが検索されます: 「US President Barack Obama」、「President Barack Obama」、「US President Obama」。

<div id="keeporder-attribute">
  ### KeepOrder 属性
</div>

単語形の組み合わせにおけるアイテムの順序を固定するには、Boolean 型の `KeepOrder` 属性を使用します。属性のデフォルト値は `false` です。

次のクエリは、アイテムの順序が固定されることを指定しています。

```xml theme={null}
<Query>
    <Contain KeepOrder="true">
        <Required>
            <Form><Text>first</Text></Form>
        </Required>
        <Required>
            <Form><Text>second</Text></Form>
        </Required>
        <Required>
            <Form><Text>third</Text></Form>
        </Required>
    </Contain>
</Query>
```

「first third second third」という組み合わせは、クエリに必要な順序で並んだ単語列が含まれているにもかかわらず、クエリには一致しません。

`KeepOrder` は、すべての `<Except>` 要素にも適用されます。クエリ内で `<Except>` 要素に対応する単語は、クエリ内でその要素が区切る単語同士の間に出現してはなりません。ただし、固定順序クエリ文字列以外の位置であれば、どこに出現してもかまいません。

たとえば、前のクエリを変更して、単語形「second」を `<Required>` ではなく `<Except>` 要素に入れた場合、単語形「first third second」の組み合わせを含むドキュメントはクエリに一致します (ただし、単語形「second」は結果に含まれません) 。その後 `KeepOrder` 属性を削除すると、単語形「first third second」の組み合わせを含むドキュメントは結果に含まれなくなります。これは、単語形「second」がドキュメントのテキスト内のどこにも出現してはならないためです。

<div id="mindistance-and-maxdistance-attributes">
  ### MinDistance 属性と MaxDistance 属性
</div>

`MinDistance` 属性と `MaxDistance` 属性は、クエリ内の単語間の最小距離と最大距離を指定します。これらの属性にデフォルト値はありません。どちらか一方の属性が指定されていない場合、距離の制限は適用されません。

単語間の距離は単語数で表し、対応する 2 つの単語の位置の差として計算します。隣り合う 2 つの単語間の距離は 1 であるため、どちらの属性の最小値も 1 です。`MaxDistance` は `MinDistance` 以上でなければなりません。

2 つの複数単語から成る文字列間の距離は、次のように計算します。文字列同士が重なっていない場合、距離は右側の文字列の最も左にある単語の位置と、左側の文字列の最も右にある単語の位置との差になります。文字列同士が重なっている場合、距離は 0 と見なされます。

たとえば、語句 “The quick brown fox jumped over the lazy dog,” では、文字列 “quick fox” と “lazy dog” の間の距離は 4 で、文字列 “quick fox” と “brown lazy dog” の間の距離は 0 です。

`<Except>` 要素の場合、単語間の距離は次のように計算されます。

* `KeepOrder="true"` の場合、その単語は文字列内の隣接する単語 (つまり、クエリ内でその単語を挟む単語) の指定距離内に出現してはなりません。同時に、`<Except>` 要素の前後の単語間の距離は、指定した範囲内である必要があります。
* `KeepOrder="false"` の場合、その単語は文字列内の他のどの単語についても、指定距離内に出現してはなりません。

次のクエリでは、`KeepOrder="true"` と `MaxDistance="2"` を使用しています。

```xml theme={null}
<Query>
    <Contain KeepOrder="true" MaxDistance="2">
        <Required>
            <Form><Text>sodium /Text></Form>
        </Required>
        <Except>
            <Form><Text>tetraborate</Text></Form>
        </Except>
        <Optional>
            <Form><Text>carborate</Text></Form>
        </Optional>
        <Optional>
            <Form><Text>sulfate</Text></Form>
        </Optional>
        <Required>
            <Form><Text>decahydrate</Text></Form>
        </Required>
    </Contain>
</Query>
```

このクエリは、「sodium carborate decahydrate」や「sodium sulfate decahydrate」のようなフレーズに一致します。

次のクエリでは、`KeepOrder="false"` と `MaxDistance="2"` を使用します。

```xml theme={null}
<Query>
    <Contain KeepOrder="false" MaxDistance="2">
        <Required>
            <Form><Text>sodium /Text></Form>
        </Required>
        <Except>
            <Form><Text>tetraborate</Text></Form>
        </Except>
        <Optional>
            <Form><Text>carborate</Text></Form>
        </Optional>
        <Optional>
            <Form><Text>sulfate</Text></Form>
        </Optional>
        <Required>
            <Form><Text>decahydrate</Text></Form>
        </Required>
    </Contain>
</Query>
```

このクエリで見つかるのは “sodium sulfate decahydrate” のみです。これは、単語 "tetraborate" が `<Except>` タグ内に配置されており、"tetraborate" と “sodium” の間の最大距離が 2 単語であるためです。

<div id="form-element">
  ## Form 要素
</div>

1 つの単語形を対象とするクエリは、`<Form>` 要素を使用して指定します。この要素には、次の要素を含めることができます。

* `<Attributes>` — 単語形の属性に対するクエリを含むオプション要素です。詳細は、[抽出スクリプトを使用する場合](/ja/flexi-capture/nlp-extraction-scripts)を参照してください。
* `<Text>` — 単語形の Unicode テキストを含むオプション要素です。テキストを指定しない場合は、属性クエリに一致する任意の単語がこのクエリに一致します。この場合、属性クエリは必須です。

単語形の追加の検索条件は、`<Form>` タグの属性で指定できます。

<div id="searchtype-attribute">
  ### SearchType 属性
</div>

単語形の検索の種類は、`<Form>` タグの `SearchType` 属性で指定できます。この属性には、次の値を設定できます。

| 値                   | 説明                                                                                                                                                  |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AllFormsSearch`    | 指定した単語のすべての単語形を検索します。                                                                                                                               |
| `ExactSearch`       | 指定した単語の指定した単語形のみを検索します。                                                                                                                             |
| `PrefixSearch`      | 指定した文字列で始まる任意の単語形を検索します。                                                                                                                            |
| `FuzzySearch`       | 指定した単語に対してあいまい検索を実行します。テキストにOCR誤認識が含まれていて `ExactSearch` が機能しない場合に役立ちます。使用できるのは、3文字以上の単語に限られます。3～5文字の単語では1つのOCR誤認識を許容し、5文字を超える単語では最大2つのOCR誤認識を許容します。 |
| `FuzzyPrefixSearch` | 指定した文字列で始まる任意の単語に対してあいまい検索を実行します。                                                                                                                   |

`SearchType` 属性は省略可能で、既定では `AllFormsSearch` に設定されています。

<div id="casesensitive-attribute">
  ### CaseSensitive 属性
</div>

大文字と小文字を区別する検索では、`<Form>` タグの `CaseSensitive` 属性を使用します。この属性は省略可能で、既定値は `false` です。

次のクエリでは、`<Form>` タグの `SearchType` 属性と `CaseSensitive` 属性の使用例を示します。

```xml theme={null}
<Query>
    <Contain KeepOrder="true">
        <Required>
            <Form SearchType="ExactSearch" CaseSensitive="true">
                <Text>WHO</Text>
            </Form>
        </Required>
    </Contain>
</Query>
```

このクエリは、略語 WHO をこの表記どおりに正確に検索します。これにより、「who」「whom」「whose」を含む不要な結果が大量に返されるのを防げます。

<div id="attributes-element">
  ## Attributes 要素
</div>

単語形の属性に対するクエリは、AND、OR、NOT 演算子で構成される論理式です。NOT は単項演算子であり、AND と OR は *n* 項演算子です。この論理式のオペランドは Bool 型の値です。この論理式はツリー形式で記述されます。クエリの結果は、この論理式を満たすドキュメントのテキスト内の単語形です。

単語形の属性を取得するには、`<Attributes>` 要素を使用します。この要素には、次の要素を含めることができます。

| Element       | Description                     |
| ------------- | ------------------------------- |
| `<Attribute>` | 必要な単語属性のテキストを含みます。論理式ツリーのリーフです。 |
| `<Or>`        | OR 演算子です。ツリー内のノードです。            |
| `<And>`       | AND 演算子です。ツリー内のノードです。           |
| `<Not>`       | NOT 演算子です。ツリー内のノードです。           |

`<Not>` 要素は `<Attributes>` 要素と同じ方法で構成され、これらの要素のうち 1 つだけを含めることができます。

`<Or>` 要素と `<And>` 要素には、これらの要素のうち少なくとも 2 つを含める必要があります。

`<Attribute>` タグには、属性検索の型を指定する省略可能な `SearchType` 属性があります。この属性には、次の値を指定できます。

* `ExactSearch` — クエリで指定したとおりの形式で属性を検索します。
* `PrefixSearch` — 指定したテキストをプレフィックスとして持つ属性を検索します。

属性検索では、常に大文字と小文字が区別されます。`SearchType` 属性の既定値は `ExactSearch` です。

たとえば、次のものをすでに識別済みのドキュメントがあるとします。

* `ExtractNerObjects` 関数を呼び出して取得した NER オブジェクト
* `ExtractWordsFromUserDictionary` 関数を呼び出して取得した、`dictionary` という名前のユーザー辞書の単語形
* `ExtractRegularExpression` 関数を呼び出して取得した、パラメーターとして渡された正規表現に一致するすべてのオブジェクト

これらのオブジェクトから成る結果のコレクションの名前を `regExp` とします。

<Note>
  コレクションの名前は、インデックス化されたドキュメントに対して実行される XML クエリで使用できます。結果のコレクション自体にも、その名前でアクセスできます。
</Note>

その場合、単語形属性クエリは次のようになります。

```xml theme={null}
<Query>
    <Contain>
        <Required>
            <Form>
                <Attributes>
                    <Attribute>regExp1</Attribute>
                </Attributes>
            </Form>
        </Required>
        <Required>
            <Form>
                <Attributes>
                    <And>
                        <Attribute>NerOrg1</Attribute>
                        <Not>
                            <Attribute> dictionary1</Attribute>
                        </Not>
                    </And>
                </Attributes>
            </Form>
        </Required>
    </Contain>
</Query>
```

このクエリは、2語から成るフレーズを検索します。1語目は指定された正規表現に一致する必要があり、2語目は組織の許可された名称である必要があります。

属性名の後ろの数字は、それぞれの属性でインデックス付けされた、検出された複数語のオブジェクト内で必要な単語を識別します。たとえば、`date` という名前の正規表現は、「May 31, 2019.」形式の日付を見つけることがあります。その場合、`date1` は単語「May」に対応し、`date2` は「31」に対応し、`date3` は「2019」に対応します。

<div id="formset-element">
  ## FormSet 要素
</div>

複数の単語形に対するクエリは、`<FormSet>` 要素を使用して指定します。

この型のクエリでは、複数の単一単語形クエリを OR で結合します。これは、すべてのサブクエリがオプションの単語形クエリである `<Query>` クエリと同等です。

ただし、`<FormSet>` クエリでは、すべての form に共通する属性クエリを指定できます。これにより、`ExactSearch` を使用してすべての単語形を検索し、各 form に属性クエリがあり、それらの属性クエリがすべて共通のフラグメントを持つ場合に、検索効率が向上します。

`<FormSet>` 要素には、次の要素が含まれます。

* `<Attributes>` — form の属性に対するクエリを含むオプション要素。このクエリは、form の属性クエリと AND で結合されます。
* `<Form>` — 単語形に対するクエリを含む必須要素。`<FormSet>` 要素には、少なくとも 1 つの `<Form>` 要素が含まれている必要があります。

## <a id="xml-parsing" />住所抽出クエリの XML サンプル

住所抽出クエリの結果は、国名の先頭の単語、住所の先頭の単語、市区町村名の先頭の単語、州名の先頭の単語、ZIP コードの先頭の単語を含む文字列です (この順で、かつ各単語の間隔が 5 語以内である場合) 。

構成要素 (たとえば通り名) を構成する連続した単語には、さらにインデックス内で 1 から始まる番号が付けられます。

```javascript theme={null}
var xmlQuery = "<Request> \
<Query> \
     <Contain MaxDistance=\"5\" KeepOrder=\"true\"> \
          <Optional> \
               <Form><Attributes><Attribute>NerCountry1</Attribute></Attributes></Form> \
          </Optional> \
          <Optional> \
               <Form><Attributes><Attribute>NerStreet1</Attribute></Attributes></Form> \
          </Optional> \
          <Optional> \
               <Form><Attributes><Attribute>NerCity1</Attribute></Attributes></Form> \
          </Optional> \
          <Optional> \
               <Form><Attributes><Attribute>NerState1</Attribute></Attributes></Form> \
          </Optional> \
          <Required> \
               <Form><Attributes><Attribute>NerZipCode1</Attribute></Attributes></Form> \
          </Required> \
     </Contain> \
</Query> \
</Request>";
```

住所抽出クエリの結果は、繰り返しフィールドである `xmlQueryResult` に記録されます:

```javascript theme={null}
this.RunQueryAndSaveToField( xmlQuery, "query", "xmlQueryResult" );
```