> ## 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.

# Langage de requête

> Langage de requête XML pour les scripts d’extraction FlexiCapture : créez des requêtes Contain avec les éléments Required, Optional et Except, les distances et la recherche floue.

Une requête définit les mots ou combinaisons de mots qu’un document doit contenir. Le langage de requête utilisé par les scripts d’extraction est basé sur XML.

<div id="basic-query-structure">
  ## Structure de base d’une requête
</div>

Une requête simple se présente ainsi :

```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>
```

Les éléments suivants constituent une requête :

| Élément     | Description                                                                                                                                                                                                                                        |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<Request>` | Élément racine d’une requête.                                                                                                                                                                                                                      |
| `<Query>`   | Requête de base. Contient un arbre de requête qui spécifie les conditions auxquelles doit répondre la combinaison de mots. Une requête de base peut faire partie d’une chaîne de formes de mots dans une requête de niveau supérieur. Obligatoire. |
| `<Contain>` | Indique les mots ou combinaisons de mots qu’un document doit contenir. Une requête ne peut contenir qu’un seul élément `<Contain>`. Obligatoire.                                                                                                   |

L’élément `<Contain>` peut inclure un nombre quelconque des éléments suivants, dans n’importe quel ordre :

| Élément      | Description                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| `<Required>` | Indique une forme de mot ou une sous-requête que la combinaison de mots doit contenir. Facultatif.        |
| `<Optional>` | Indique une forme de mot ou une sous-requête que la combinaison de mots peut contenir. Facultatif.        |
| `<Except>`   | Indique une forme de mot ou une sous-requête que la combinaison de mots ne doit pas contenir. Facultatif. |

Chacun de ces éléments doit contenir l’un des éléments suivants :

| Élément   | Description                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `<Query>` | Indique si une chaîne de formes de mots doit être incluse dans la combinaison de mots ou en être exclue. |
| `<Form>`  | Indique si une forme de mot doit être incluse dans une combinaison de mots ou en être exclue.            |

<Note>
  L’élément `<Contain>` doit contenir au moins un élément `<Required>` ou `<Optional>`.
</Note>

<div id="attributes-of-the-contain-element">
  ## Attributs de l'élément Contain
</div>

Des restrictions supplémentaires sur les combinaisons de formes de mots peuvent être définies dans les attributs de la balise `<Contain>`.

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

Spécifiez le nombre minimal d’éléments dans une combinaison de formes de mots à l’aide de l’attribut `MinCount`. Chaque élément est soit une forme de mot, soit une chaîne de formes de mots renvoyée par la sous-requête. La valeur par défaut de l’attribut est `1`. La valeur de ce paramètre ne doit pas être supérieure au nombre total d’éléments `<Required>` et `<Optional>` dans la combinaison de formes de mots.

Ce paramètre est utile lorsqu’une combinaison de formes de mots contient un ou plusieurs éléments `<Optional>`.

La requête suivante recherche soit le premier paramètre, soit le second :

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

La requête suivante permet de trouver au moins trois des quatre mots spécifiés dans la requête, dont deux sont obligatoires :

```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>
```

Cette requête trouve les expressions suivantes : “président des États-Unis Barack Obama”, “président Barack Obama” et “président des États-Unis Obama.”

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

Pour spécifier un ordre fixe d'éléments dans une combinaison de formes de mots, utilisez l'attribut `KeepOrder` de type booléen. La valeur par défaut de l'attribut est `false`.

La requête suivante indique que l'ordre des éléments est fixe :

```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>
```

La combinaison « first third second third » ne correspondra pas à la requête, même si la requête contient bien une suite de mots dans l’ordre requis.

`KeepOrder` s’applique également à tous les éléments `<Except>`. Les mots correspondant aux éléments `<Except>` dans une requête ne doivent pas apparaître entre les mots qu’ils séparent dans la requête. Cependant, ils peuvent apparaître à n’importe quelle autre position en dehors des suites de mots de la requête à ordre fixe.

Par exemple, si vous modifiez la requête précédente en plaçant la forme de mot « second » dans un élément `<Except>` au lieu de `<Required>`, un document contenant la combinaison de formes de mot « first third second » correspondra à la requête (mais la forme de mot « second » ne sera pas incluse dans le résultat). Si vous supprimez ensuite l’attribut `KeepOrder`, un document contenant la combinaison de formes de mot « first third second » ne sera pas inclus dans le résultat, car la forme de mot « second » ne doit apparaître nulle part dans le texte du document.

<div id="mindistance-and-maxdistance-attributes">
  ### Attributs MinDistance et MaxDistance
</div>

Les attributs `MinDistance` et `MaxDistance` spécifient les distances minimale et maximale entre les mots d’une requête. Ces attributs n’ont pas de valeur par défaut. Si l’un des deux attributs n’est pas spécifié, aucune contrainte de distance ne s’applique.

La distance entre les mots est mesurée en nombre de mots et correspond à la différence entre les positions des deux mots concernés. La distance entre deux mots voisins est égale à 1 ; la valeur minimale de chacun de ces attributs est donc 1. `MaxDistance` doit être supérieur ou égal à `MinDistance`.

La distance entre deux suites de mots est calculée comme suit. Si les suites ne se chevauchent pas, la distance correspond à la différence entre la position du mot le plus à gauche dans la suite de droite et la position du mot le plus à droite dans la suite de gauche. Si les suites se chevauchent, la distance est considérée comme égale à 0.

Par exemple, dans l’expression « The quick brown fox jumped over the lazy dog, », la distance entre les suites « quick fox » et « lazy dog » est de 4, et la distance entre les suites « quick fox » et « brown lazy dog » est de 0.

Pour les éléments `<Except>`, la distance entre les mots est calculée comme suit :

* Si `KeepOrder="true"`, le mot ne doit pas apparaître à l’intérieur de la distance spécifiée par rapport aux mots voisins dans la suite (c’est-à-dire les mots entre lesquels il apparaît dans la requête). En même temps, la distance entre les voisins de l’élément `<Except>` doit être comprise dans la plage spécifiée.
* Si `KeepOrder="false"`, le mot ne doit pas apparaître à l’intérieur de la distance spécifiée par rapport à un autre mot de la suite.

La requête suivante utilise `KeepOrder="true"` et `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>
```

Cette requête permet de trouver des expressions telles que « sodium carborate decahydrate » et « sodium sulfate decahydrate ».

La requête suivante utilise `KeepOrder="false"` et `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>
```

Cette requête renvoie uniquement « sodium sulfate decahydrate », car le mot "tetraborate" est placé dans les balises `<Except>` et que la distance maximale entre "tetraborate" et « sodium » est de deux mots.

<div id="form-element">
  ## Élément Form
</div>

Une requête pour une forme de mot est définie à l’aide d’un élément `<Form>`. Cet élément peut contenir les éléments suivants :

* `<Attributes>` — Élément facultatif contenant une requête sur les attributs d’une forme de mot. Pour plus d’informations, consultez [Quand utiliser les scripts d’extraction](/fr/flexi-capture/nlp-extraction-scripts).
* `<Text>` — Élément facultatif contenant le texte Unicode d’une forme de mot. Si aucun texte n’est spécifié, tout mot correspondant à la requête sur les attributs correspondra à la requête. Dans ce cas, la requête sur les attributs est obligatoire.

Des conditions de recherche supplémentaires pour une forme de mot peuvent être spécifiées dans les attributs de la balise `<Form>`.

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

Le type de recherche de formes de mots peut être spécifié dans l’attribut `SearchType` de la balise `<Form>`. Cet attribut peut prendre les valeurs suivantes :

| Valeur              | Description                                                                                                                                                                                                                                                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AllFormsSearch`    | Recherche toutes les formes du mot spécifié.                                                                                                                                                                                                                                                                                                                   |
| `ExactSearch`       | Recherche uniquement la forme spécifiée du mot.                                                                                                                                                                                                                                                                                                                |
| `PrefixSearch`      | Recherche toutes les formes de mots commençant par la chaîne spécifiée.                                                                                                                                                                                                                                                                                        |
| `FuzzySearch`       | Effectue une recherche floue sur le mot spécifié. Utile si vos textes peuvent contenir des erreurs d’OCR et que `ExactSearch` ne fonctionne pas. Ne peut être utilisé que pour les mots contenant au moins 3 caractères. Pour les mots de 3 à 5 caractères, autorise 1 erreur d’OCR ; pour les mots de plus de 5 caractères, autorise jusqu’à 2 erreurs d’OCR. |
| `FuzzyPrefixSearch` | Effectue une recherche floue sur tous les mots commençant par la chaîne spécifiée.                                                                                                                                                                                                                                                                             |

L’attribut `SearchType` est facultatif et sa valeur par défaut est `AllFormsSearch`.

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

Pour les recherches sensibles à la casse, utilisez l’attribut `CaseSensitive` de la balise `<Form>`. Cet attribut est facultatif et vaut `false` par défaut.

La requête suivante utilise les attributs `SearchType` et `CaseSensitive` de la balise `<Form>` :

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

Cette requête recherche l’acronyme WHO exactement sous cette forme, ce qui permet d’éviter un grand nombre de résultats redondants contenant « who », « whom » ou « whose ».

<div id="attributes-element">
  ## Élément Attributes
</div>

Une requête sur les attributs des formes de mots est une expression logique construite à l’aide des opérateurs AND, OR et NOT. NOT est un opérateur unaire, tandis que AND et OR sont *n*-aires. Les opérandes de cette expression logique sont des valeurs de type Bool. Cette expression logique s’écrit sous forme d’arborescence. Le résultat de la requête correspond aux formes de mots du texte d’un document qui satisfont cette expression logique.

Pour obtenir les attributs des formes de mots, utilisez un élément `<Attributes>`. Cet élément peut contenir les éléments suivants :

| Élément       | Description                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| `<Attribute>` | Contient le texte de l’attribut de mot requis. Il s’agit d’une feuille de l’arborescence de l’expression logique. |
| `<Or>`        | L’opérateur OR. Un nœud de l’arbre.                                                                               |
| `<And>`       | L’opérateur AND. Un nœud de l’arbre.                                                                              |
| `<Not>`       | L’opérateur NOT. Un nœud de l’arbre.                                                                              |

L’élément `<Not>` est construit de la même manière que l’élément `<Attributes>` et ne peut contenir qu’un seul de ces éléments.

Les éléments `<Or>` et `<And>` doivent contenir au moins deux de ces éléments.

La balise `<Attribute>` possède un attribut `SearchType` facultatif qui spécifie le type de recherche d’attribut. Cet attribut peut avoir les valeurs suivantes :

* `ExactSearch` — Recherche l’attribut exactement sous la forme spécifiée dans la requête.
* `PrefixSearch` — Recherche tous les attributs commençant par le texte spécifié.

La recherche d’attributs respecte toujours la casse. L’attribut `SearchType` est défini sur `ExactSearch` par défaut.

Supposons que vous disposiez d’un document dans lequel vous avez déjà identifié :

* des objets NER, en appelant la fonction `ExtractNerObjects`
* des formes de mots à partir d’un dictionnaire utilisateur nommé `dictionary`, en appelant la fonction `ExtractWordsFromUserDictionary`
* tous les objets qui satisfont une expression régulière passée en paramètre, en appelant la fonction `ExtractRegularExpression`

Supposons que la collection résultante de ces objets soit nommée `regExp`.

<Note>
  Le nom de la collection peut être utilisé dans les requêtes XML exécutées sur le document indexé. La collection résultante elle-même est accessible par son nom.
</Note>

Une requête sur les attributs de forme se présente alors comme suit :

```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>
```

Cette requête recherche une expression de deux mots, dans laquelle le premier mot doit correspondre à l’expression régulière spécifiée et le second doit être un nom d’organisation autorisé.

Les chiffres placés après les noms d’attributs désignent les mots requis dans les objets à plusieurs mots détectés et indexés avec les attributs correspondants. Par exemple, une expression régulière nommée `date` peut trouver une date au format « 31 mai 2019 ». Ainsi, `date1` correspond au mot « 31 », `date2` à « mai » et `date3` à « 2019 ».

<div id="formset-element">
  ## Élément FormSet
</div>

Une requête portant sur plusieurs formes de mot est spécifiée à l’aide d’un élément `<FormSet>`.

Ce type de requête combine plusieurs requêtes portant chacune sur une seule forme à l’aide de OR. Elle est équivalente à une requête `<Query>` dans laquelle toutes les sous-requêtes sont des requêtes facultatives sur des formes de mot.

Avec une requête `<FormSet>`, vous pouvez toutefois spécifier une requête d’attribut commune à toutes les formes. Cela permet d’effectuer des recherches plus efficaces lorsque `ExactSearch` est utilisé pour trouver toutes les formes de mot, qu’une requête d’attribut est définie pour chaque forme et que toutes ces requêtes d’attribut ont un fragment commun.

Un élément `<FormSet>` contient les éléments suivants :

* `<Attributes>` — Élément facultatif contenant une requête sur les attributs de forme. Cette requête est combinée avec les requêtes d’attribut de forme à l’aide de AND.
* `<Form>` — Élément obligatoire contenant une requête sur une forme de mot. Un élément `<FormSet>` doit contenir au moins un élément `<Form>`.

## <a id="xml-parsing" />Exemple de requête XML d’extraction d’adresse

Le résultat d’une requête d’extraction d’adresse est une chaîne de caractères contenant le premier mot du pays, le premier mot de la rue, le premier mot de la ville, le premier mot de l’État et le premier mot du code ZIP (dans cet ordre, à condition qu’ils ne soient pas espacés de plus de 5 mots).

Les mots consécutifs qui composent un composant (par ex. un nom de rue) sont également numérotés dans l’indice, à partir de 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>";
```

Le résultat d’une requête d’extraction d’adresse est enregistré dans le champ répétitif `xmlQueryResult` :

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