Kibana_manual/Руководство по синтаксису языка запросов по ключевым словам (KQL).md

# Руководство по синтаксису языка запросов по ключевым словам (KQL) | Microsoft Learn


## Элементы KQL-запроса

KQL-запрос состоит из одного или нескольких элементов, перечисленных далее.

- Ключевые слова с произвольным текстом (слова или фразы)
- Ограничения свойств

Элементы KQL-запросов можно комбинировать с одним или несколькими доступными операторами.

Недопустимы те KQL-запросы, которые пустые или содержат только операторы. KQL-запросы не чувствительны к регистру, а операторы чувствительны (верхний регистр).

Примечание

Ограничение длины KQL-запроса зависит от способа его создания. Если KQL-запрос создан при помощи внешнего интерфейса поиска SharePoint, доступного по умолчанию, максимальная длина составляет 2048 символов. Если же вы создаете KQL-запрос программным путем с помощью объектной модели запроса, ограничение длины по умолчанию составляет 4096 знаков. Это ограничение можно увеличить до 20480 символов с помощью свойства [MaxKeywordQueryTextLength](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.SearchServiceApplication.MaxKeywordQueryTextLength.aspx) или [DiscoveryMaxKeywordQueryTextLength](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.SearchServiceApplication.DiscoveryMaxKeywordQueryTextLength.aspx) (для обнаружения электронных данных).

## Создание запросов с произвольным текстом при помощи KQL

При создании KQL-запроса с использованием произвольных выражений Поиск в SharePoint подбирает результаты с совпадениями для выбранных вами терминов, основываясь на терминах, хранящихся в полнотекстовом индексе. Сюда входят значения управляемых свойств, для которых [для FullTextQueriable](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedProperty.FullTextQueriable.aspx) задано **значение true**.

KQL-запросы с произвольным текстом не чувствительны к регистру, однако операторы должны быть записаны заглавными буквами. Вы можете строить KQL-запросы с помощью одного или нескольких произвольных выражений:

- **word** (содержит один или несколько символов без пробелов и знаков препинания);
- **phrase** (содержит два и более слов, разделенных пробелами и обязательно заключенных в двойные кавычки).

Чтобы создать сложные запросы, вы можете комбинировать несколько произвольных выражений с помощью операторов KQL-запросов. Если операторы между выражениями отсутствуют, запрос будет выполняться так же, как при использовании оператора **AND**.

### Использование слов в KQL-запросе с произвольным текстом

Если вы используете слова в KQL-запросе с произвольным текстом, служба Поиск в SharePoint возвращает результаты с точным совпадением этих слов с терминами, хранящимися в полнотекстовом индексе. Можно указывать только начальную часть слова, применяя оператор подстановочного знака (*) для включения сопоставления префиксов. При таком сопоставлении служба Поиск в SharePoint подбирает совпадения с терминами, содержащими искомое слово, за которым могут следовать другие символы.

Например, следующие KQL-запросы вернут элементы, содержащие термины "federated" и "search":

`federated search`

`federat* search`

`search fed*`

Запросы KQL не поддерживают сопоставление префиксов с подстановочным знаком * в качестве префикса.

### Использование фраз в KQL-запросе с произвольным текстом

Если вы используете фразы в KQL-запросе с произвольным текстом, служба Поиск в SharePoint возвращает только элементы, в которых есть слова из вашей фразы, следующие друг за другом. Чтобы задать фразу в KQL-запросе, необходимо использовать двойные кавычки.

Запросы KQL не поддерживают сопоставление префиксов с подстановочным знаком * в качестве префикса, поэтому нельзя использовать оператор с подстановочными знаками перед фразой в запросах свободного текста. Однако вы можете использовать оператор подстановочного знака после фразы.

## Запросы с ограничениями свойств в KQL

С помощью KQL вы можете строить запросы, использующие ограничения свойств, чтобы получать результаты запроса только по заданному условию.

### Задание ограничений свойств

Базовое ограничение свойств состоит из перечисленных ниже элементов.

`<Property Name><Property Operator><Property Value>`

В таблице 1 приведены некоторые примеры допустимого синтаксиса ограничений свойств в KQL-запросах.

**Таблица 1. Допустимый синтаксис ограничений свойств**

| **Синтаксис** | **Возвращаемое значение** |
| --- | --- |
| `author:"John Smith"` | Возвращает элементы контента, автором которого является John Smith. |
| `filetype:docx` | Возвращает документы Microsoft Word. |
| `filename:budget.xlsx` | Возвращает элементы содержимого с именем `budget.xlsx`файла . |

Ограничение свойства не должно включать пробелы между именем свойства, оператором свойства и значением свойства, иначе ограничение свойства обрабатывается как запрос свободного текста. Длина ограничения свойства не должна превышать 2048 символов.

В следующих примерах наличие пробела приводит к тому, что запрос возвращает элементы, содержащие термины "author" и "John Smith", вместо элементов контента, автором которого является John Smith:

`author: "John Smith"`

`author :"John Smith"`

`author : "John Smith"`

Другими словами, описанные выше ограничения свойств эквивалентны следующему запросу:

`author "John Smith"`

### Указание имен свойств для ограничений свойств

Необходимо указать допустимое имя управляемого свойства для ограничения свойства. По умолчанию в Поиск в SharePoint входит несколько управляемых свойств для документов.

Чтобы задать ограничение для значения свойства для обхода, необходимо сначала сопоставить свойство для обхода с управляемым свойством. См. раздел **Управляемые и обходные свойства** в [статье Планирование взаимодействия с поиском для конечных пользователей](https://technet.microsoft.com/library/cc263089.aspx).

Управляемое свойство должно быть [запрашиваемым](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedProperty.Queryable.aspx) , чтобы можно было искать это управляемое свойство в документе. Кроме того, управляемое свойство может относиться к типу [Retrievable](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedProperty.Retrievable.aspx) , чтобы можно было его извлечь. Однако управляемое свойство не обязательно должно относиться к типу [Retrievable](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedProperty.Retrievable.aspx) , чтобы можно было найти свойство.

### Операторы свойств, поддерживаемые в ограничениях свойств

Служба Поиск в SharePoint поддерживает несколько операторов свойств для ограничений свойств, приведенных в таблице 2.

**Таблица 2. Допустимые операторы свойств для ограничений свойств**

| **Описание** | **Описание** | **Поддерживаемый тип управляемого свойства** |
| --- | --- | --- |
| : | Возвращает результаты, в которых указанное в ограничении свойства значение равно значению свойства, хранящегося в базе данных хранилища свойств, или совпадает с отдельными терминами в значении свойства, хранящегося в полнотекстовом индексе. | [Text](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Text)  [DateTime](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#DateTime)  [Integer](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Integer)  [Decimal](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Decimal)  [Double](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Double)  [YesNo](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#YesNo) |
| = | Возвращает результаты поиска со значениями свойств, равными значению, определенному при ограничении свойств.  **Примечание.** Не рекомендуем сочетать оператор **=** со знаком звездочки (*****), если нужно найти точное совпадение. | [Text](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Text)  [DateTime](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#DateTime)  [Integer](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Integer)  [Decimal](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Decimal)  [Double](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Double)  [YesNo](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#YesNo) |
| < | Возвращает результаты, в которых значение свойства меньше значения, указанного в ограничении свойства. | [DateTime](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#DateTime)  [Integer](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Integer)  [Decimal](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Decimal)  [Double](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Double) |
| > | Возвращает результаты, в которых значение свойства больше значения, указанного в ограничении свойства. | [DateTime](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#DateTime)  [Integer](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Integer)  [Decimal](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Decimal)  [Double](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Double) |
| <= | Возвращает результаты со значением свойства, меньшим или равным значению, указанному в ограничении свойства. | [DateTime](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#DateTime)  [Integer](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Integer)  [Decimal](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Decimal)  [Double](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Double) |
| >= | Возвращает результаты со значением свойства, большим или равным значению, указанному в ограничении свойства. | [DateTime](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#DateTime)  [Integer](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Integer)  [Decimal](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Decimal)  [Double](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Double) |
| <> | Возвращает результаты со значением свойства, не равным значению, указанному в ограничении свойства. | [DateTime](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#DateTime)  [Integer](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Integer)  [Decimal](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Decimal)  [Text](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Text)  [Double](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Double)  [YesNo](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#YesNo) |
| .. | Возвращает результаты, в которых значение свойства включено в диапазон, указанный в ограничении свойства.  Например, диапазон A..B представляет собой набор значений от A до B со значениями A и B включительно. Для диапазонов дат такая запись означает диапазон от начала дня A до конца дня B. | [DateTime](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#DateTime)  [Integer](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Integer)  [Decimal](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Decimal)  [Double](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Double) |

### Указание значений свойств

Укажите значение свойства, имеющего допустимый тип данных для типа управляемого свойства. В таблице 3 приведен перечень сопоставлений типов.

**Таблица 3. Соответствие допустимых типов данных типам управляемых свойств**

| **Тип управляемых свойств** | **Тип данных** |
| --- | --- |
| [Text](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Text) | [String](https://msdn.microsoft.com/library/System.String.aspx) |
| [Integer](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Integer) | [Int64](https://msdn.microsoft.com/library/System.Int64.aspx) |
| [Double](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Double) | [System.Double](https://msdn.microsoft.com/library/System.Double.aspx) |
| [Decimal](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Decimal) | [Decimal](https://msdn.microsoft.com/library/System.Decimal.aspx) |
| [DateTime()](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#DateTime) | [DateTime](https://msdn.microsoft.com/library/System.DateTime.aspx) |
| [YesNo](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#YesNo) | [Boolean](https://msdn.microsoft.com/library/System.Boolean.aspx) |

### Значения текстовых свойств

В случае значений текстовых свойств ход сопоставления зависит от того, хранится ли свойство в полнотекстовом индексе или в индексе поиска.

### Значения свойств в полнотекстовом индексе

Значения свойств хранятся в полнотекстовом индексе, когда свойству **FullTextQueriable** присвоено значение **true** для управляемого свойства. Эту настройку можно использовать только для строковых свойств. Значения свойств, указанные в запросе, сопоставляются с отдельными терминами, которые хранятся в полнотекстовом индексе. Используйте свойство [NoWordBreaker](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedProperty.NoWordBreaker.aspx) , чтобы указать, должен ли проводиться поиск совпадений с полным значением свойства.

Например, если вы ищете элемент контента, созданный пользователем Paul Shakespear, такой KQL-запрос возвращает результаты с совпадениями:

`author:Shakespear`

`author:Paul`

Поддерживается также сопоставление префикса. Можно использовать оператор с подстановочными знаками (*), но он не требуется при указании отдельных слов. Продолжая работу с предыдущим примером, следующий запрос KQL возвращает элементы содержимого, созданные Полом Shakespear, в виде совпадений:

`author:Shakesp*`

Когда вы указываете фразу для значения свойства, результаты с совпадениями должны содержать указанную фразу в значении свойства, хранящегося в полнотекстовом индексе. В следующем примере запроса возвращаются элементы содержимого с текстом "Расширенный поиск" в заголовке, например "Расширенный поиск XML", "Изучение веб-части расширенного поиска" и т. д.

`title:"Advanced Search"`

Сопоставление префиксов также поддерживается для фраз, указанных в значениях свойств. Но в этом случае в запросе следует использовать оператор подстановочного знака (*), который допустим только в конце фразы, например:

`title:"Advanced Sear*"`

Следующие запросы не возвращают ожидаемые результаты:

`title:"Advan* Search"`

`title:"Advanced Sear"`

### Числовые значения свойств

В случае числовых значений свойств, к которым относятся управляемые типы **Integer**, **Double** и **Decimal**, ограничение свойства сопоставляется с полным значением свойства.

### Значения даты и времени для свойств

В языке KQL для даты и времени предназначен тип данных **datetime**. В запросах поддерживаются следующие форматы даты и времени, совместимые с ISO 8601:

- ГГГГ-ММ-ДД
- YYYY-MM-DDThh:mm:ss
- ГГГГ-ММ-ДДTчч:мм:ссZ
- ГГГГ-ММ-ДДTчч:мм:ссfrZ

В этих форматах **datetime**:

- *ГГГГ* задает год из четырех цифр.
    
    Примечание
    
    Поддерживается только формат года из четырех цифр.
    
- Параметр *MM* задает месяц в формате двух цифр. Например, 01 это январь.
- Параметр *DD* задает двузначное значение дня месяца (от 01 до 31).
- Параметр *T* обозначает букву "T".
- Параметр *hh* обозначает часы в формате двух цифр (от 00 до 23). Обозначения a.m. и p.m. не допускаются.
- Параметр *mm* обозначает минуты в формате двух цифр (от 00 до 59).
- Параметр *сс* обозначает секунды в формате двух цифр (от 00 до 59).
- *fr* задает необязательную долю секунд, ss; от 1 до 7 цифр, которые следуют за **.** после секунд. Например, 2012-09-27T11:57:34.1234567.

Все значения даты и времени необходимо указывать в часовом поясе UTC (другое название GMT). Идентификатор часового пояса UTC (символ "Z" в конце) указывать необязательно.

### Соответствующие интервалы дат, поддерживаемые KQL

Язык KQL поддерживает реляционные запросы в диапазоне day, для которых зарезервированы ключевые слова, как показано в таблице 4. Используйте двойные кавычки ("") для интервалов дат, между их названиями ставьте пробел.

Совпадения будут включать элементы, измененные сегодня:

`LastModifiedTime=today`

Совпадения будут включать элементы от начала текущего года до его окончания:

`LastModifiedTime="this year"`

Совпадения будут включать элементы с 1 января 2019 г. до 26 апреля 2019 г.:

`LastModifiedTime>=2019-01-01 AND LastModifiedTime<=2019-04-26`

**Табл. 4. Зарезервированные ключевые слова для интервала даты**

| **Имя интервала дат** | **Описание** |
| --- | --- |
| today | Представляет период времени с начала текущего дня до его окончания. |
| yesterday | Представляет период времени с начала предшествующего дня до его окончания. |
| this week | Представляет период времени от начала текущей недели до ее окончания. При определении первого дня недели учитываются традиции региона, в котором формируется текст запроса. |
| this month | Представляет период времени с начала текущего месяца до его окончания. |
| last month | Представляет период времени от начала предыдущего месяца до его окончания. |
| this year | Представляет период времени от начала текущего года до его окончания. |
| last year | Представляет весь год, предшествующий текущему. |

### Использование нескольких ограничений свойств в KQL-запросе

Служба Поиск в SharePoint поддерживает использование нескольких ограничений свойств в одном KQL-запросе. Можно использовать либо одно свойство для нескольких ограничений свойств, либо разные свойства для каждого ограничения свойств.

Если вы используете несколько экземпляров ограничений свойств, поиск совпадений основан на объединении ограничений свойств в KQL-запросе. В этом примере совпадения включают элементы контента, автором которого является John Smith или Jane Smith:

`author:"John Smith" author:"Jane Smith"`

Результат будет таким же, как и при использовании логического оператора **OR** в запросе, например:

`author:"John Smith" OR author:"Jane Smith"`

Если вы используете различные ограничения свойств, поиск совпадений основан на пересечении ограничений свойств в KQL-запросе, например:

`author:"John Smith" filetype:docx`

Совпадения будут содержать документы Microsoft Word, созданные пользователем John Smith. Такой же результат будет при использовании логического оператора **AND**, как показано в следующем примере:

`author:"John Smith" AND filetype:docx`

### Группирование ограничений свойств в KQL-запросе

***Область применения:** Office 365 | SharePoint Online | SharePoint 2019*

С помощью скобок `()` можно сгруппировать несколько ограничений, связанных с определенным свойством типа *Text* в следующем формате:

`<Property Name>:(<Expression>)`

В более сложных запросах может быть полезно использовать нотацию `()`, чтобы составлять более краткие и удобочитаемые выражения запросов.

Следующий запрос:

`author:"John Smith" AND author:"Jane Smith"`

можно перезаписать следующим образом:

`author:("John Smith" "Jane Smith")`

Следующий запрос:

`title:Advanced title:Search title:Query NOT title:"Advanced Search Query"`

можно перезаписать следующим образом:

`title:((Advanced OR Search OR Query) -"Advanced Search Query")`

Следующий запрос:

`title:Advanced XRANK(cb=1) title:Search XRANK(cb=1) title:Query`

можно перезаписать следующим образом:

`title:(Advanced XRANK(cb=1) Search XRANK(cb=1) Query)`

Примечание

При использовании символов `()` для группировки выражения в запросе свойства количество совпадений может увеличиваться, так как в этом случае отдельные ключевые слова запроса лемматизируются. Фразы в кавычках не лемматизируются.

Запрос `title:page` возвращает точные совпадения с термином *page*, а запрос `title:(page)` также возвращает совпадения с термином *pages*.

### Фильтрация по элементам, в которых текстовое свойство пусто или содержит значение

***Область применения:** Office 365 | SharePoint Online*

Для управляемых свойств типа [Text](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedDataType#Text) в схеме поиска, для которых задано значение [Queryable](https://msdn.microsoft.com/library/Microsoft.Office.Server.Search.Administration.ManagedProperty.Queryable.aspx) , можно использовать оператор подстановочных знаков (*) в качестве выражения свойства для фильтрации по элементам, которые имеют значение или не имеют значения.

Синтаксис для возврата элементов, в которых текстовое свойство имеет значение:

`<Property Name>:*`

Синтаксис для возврата элементов, в которых текстовое свойство не имеет значения:

`NOT <Property Name>:*`

В следующем примере возвращаются сайты, связанные с центральным сайтом, за исключением самих центральных сайтов:

`(DepartmentId:* OR RelatedHubSites:*) AND contentclass:sts_site NOT IsHubSite:true`

## Операторы KQL для сложных запросов

Синтаксис языка KQL включает несколько операторов, которые можно использовать для создания сложных запросов.

### Логические операторы

Используйте логические операторы, чтобы расширить или сузить область поиска. Логические операторы в KQL-запросах можно использовать с произвольными выражениями и ограничениями свойств. В таблице 5 перечислены поддерживаемые логические операторы.

**Таблица 5. Логические операторы, поддерживаемые в KQL**

| **Описание** | **Описание** |
| --- | --- |
| **AND** | Возвращает результаты поиска, содержащие все произвольные выражения или ограничения свойств, заданные оператором **AND**. Укажите допустимое произвольное текстовое выражение и (или) допустимое ограничение свойств перед оператором **AND** и после него. Представьте, что используете знак "+". |
| **NOT** | Возвращает результаты поиска, не содержащие заданных произвольных выражений или ограничений свойств. Укажите допустимое произвольное текстовое выражение и (или) допустимое ограничение свойств после оператора **NOT**. Представьте, что используете знак "-". |
| **ИЛИ** | Возвращает результаты поиска, содержащие одно или несколько заданных произвольных выражений или ограничений свойств. Укажите допустимое произвольное текстовое выражение и (или) допустимое ограничение свойств перед оператором **OR** и после него. |

### Операторы поиска с учетом расположения

Используйте операторы поиска с учетом расположения, чтобы получить результаты, в которых заданные термины находятся в непосредственной близости друг от друга. Такие операторы вы можете использовать только с произвольными текстовыми выражениями: они не предназначены для использования с ограничениями свойств в KQL-запросах. Существует два оператора операторы поиска с учетом расположения: **NEAR** и **ONEAR**.

### Оператор NEAR

Оператор **NEAR** возвращает совпадения, в которых заданные термины поиска находятся в непосредственной близости друг от друга (при этом не учитывается порядок следования терминов). Синтаксис оператора **NEAR**:

`<expression> NEAR(n=4) <expression>`

Где *n* — необязательный параметр, указывающий максимальное расстояние между терминами. Значение *n* является целым числом >= 0 и значением по умолчанию **8**.

Параметр *n* можно указать как `n=v` , где *v* представляет значение, или сокращен до *только v*; например `NEAR(4)` , где *v* равно 4.

Например:

`"acquisition" NEAR "debt"`

Результатом запроса будут элементы, в которых термины "acquisition" и "debt" появляются в одном элементе, в котором за термином "acquisition" следует до восьми других терминов, а за ними "debt" (или наоборот). Порядок терминов при поиске совпадений не учитывается.

Если вам нужно меньшее расстояние между терминами, укажите его. Результатом следующего запроса будут элементы, в которых термины "acquisition" и "debt" появляются в одном элементе, при этом между ними не более трех терминов. Порядок следования терминов также не учитывается.

`"acquisition" NEAR(n=3) "debt"`

Примечание

В SharePoint оператор **NEAR** больше не сохраняет порядок токенов. Кроме того, оператор **NEAR** теперь принимает необязательный параметр, который указывает максимальное расстояние до токена. Однако значение по умолчанию все еще равно **8**. Если нужно реализовать предыдущее поведение, используйте оператор **ONEAR**.

### Оператор ONEAR

Оператор **ONEAR** соответствует результатам, в которых указанные условия поиска находятся в непосредственной близости друг от друга, сохраняя при этом порядок терминов. Синтаксис **ONEAR** выглядит следующим образом, где *n* — необязательный параметр, указывающий максимальное расстояние между терминами. Значение *n* является целым числом >= 0 и значением по умолчанию **8**.

`<expression> ONEAR(n=4) <expression>`

Параметр *n* можно указать как `n=v` , где *v* представляет значение, или сокращен до *только v*; например `ONEAR(4)` , где *v* равно 4.

Например, результатом следующего запроса будут элементы, в которых термины "acquisition" и "debt" появляются в одном элементе, при этом за термином "acquisition" следует до восьми других терминов, а за ними "debt". Порядок следования терминов **должен** совпадать с их порядком в возвращаемом элементе:

`"acquisition" ONEAR "debt"`

Если требуется меньшее расстояние между терминами, укажите его, как показано в примере ниже. Результатом следующего запроса будут элементы, в которых термины "acquisition" и "debt" появляются в одном элементе, при этом между ними не более 3 терминов. Порядок следования терминов **должен** совпадать с их порядком в возвращаемом элементе:

`"acquisition" ONEAR(n=3) "debt"`

### Операторы поиска синонимов

Оператор **WORDS** используется, чтобы указать, что термины в запросе являются синонимами, а возвращаемые результаты должны соответствовать любой из указанных терминов. Оператор **WORDS** можно использовать только с свободными текстовыми выражениями; Он не поддерживается с ограничениями свойств в запросах KQL.

Указанный ниже пример запроса выдает результаты, содержащие термин "TV" или "television". Под ним приведен еще один запрос, его результаты аналогичны предыдущим.

`WORDS(TV, Television)`

`TV OR Television`

Эти запросы отличаются ранжированием результатов. При использовании оператора **WORDS** термины "TV" и "television" рассматриваются как синонимы, а не как отдельные термины. Поэтому оба эти термина ранжируются, как если бы они были одним термином. Например, элемент контента, содержащий один термин "television" и пять терминов "TV", ранжируется так же, как элемент контента с шестью терминами "TV".

### Оператор подстановочного знака

Используйте оператор подстановочного знака (символ звездочки, "*****"), чтобы включить сопоставление префиксов. Вы можете указать в запросе начальную часть слова, поставив далее оператор подстановочного знака, как показано ниже. Результат следующего запроса — термины, начинающиеся на "serv" (при этом далее могут следовать другие знаки), например "serve", "server", "service":

`serv*`

### Операторы включения и исключения

С помощью операторов включения и исключения, описанных в таблице 6, вы можете указать, будут ли возвращаемые результаты включать или исключать контент, совпадающий со значением, указанным в произвольном текстовом выражении или ограничении свойств.

**Таблица 6. Операторы для включения и исключения контента в результатах**

| **Имя** | **Оператор** | **Поведение** |
| --- | --- | --- |
| Включение | " **+** " | Включает в результаты контент со значениями, совпадающими с теми, которые нужно включить.  Это поведение по умолчанию, если символы не указаны. Аналогичный результат будет при использовании оператора **AND**. |
| Исключения | " **-** " | Исключает контент со значениями, совпадающими с теми, которые нужно исключить. Аналогичный результат будет при использовании оператора **NOT**. |

### Оператор динамического ранжирования

Применяйте оператор **XRANK**, чтобы повысить динамический рейтинг элементов в зависимости от повторений определенных терминов в *match expression*, не меняя состав элементов, удовлетворяющих критериям запроса. Выражение **XRANK** содержит один компонент, который должен быть сопоставлен, *выражение соответствия* и один или несколько компонентов, которые влияют только на динамическое ранжирование, *выражение ранжирования*. Должен быть задан хотя бы **один** параметр (за исключением *n*), чтобы выражение **XRANK** было допустимым.

Примечание

Задержка при выполнении запроса (и вероятность превышения времени ожидания) растет при использовании сложных запросов, особенно с операторами xrank. Увеличение задержки при выполнении запроса зависит от количества операторов **XRANK** и количества совпадений в компонентах *совпадение выражения* и *ранжирующее выражение* в дереве запросов.

Параметр *Match expressions* может быть любым допустимым выражением KQL, включая вложенные выражения **XRANK**. Параметр *Rank expressions* может быть любым допустимым выражением в языке KQL, кроме выражений **XRANK**. Если KQL-запросы содержат несколько операторов **XRANK**, итоговое значение динамического рейтинга рассчитывается как сумма увеличений по всем операторам **XRANK**.

Примечание

Используйте скобки, чтобы явно указать порядок вычисления для KQL-запросов, содержащих более одного оператора **XRANK** на одном уровне.

Можно использовать следующий синтаксис оператора **XRANK**:

`<match expression> XRANK(cb=100, rb=0.4, pb=0.4, avgb=0.4, stdb=0.4, nb=0.4, n=200) <rank expression>`

Динамического рейтинг с использованием оператора **XRANK** вычисляется по формуле:

![https://learn.microsoft.com/ru-ru/sharepoint/dev/images/xrankformula.gif](https://learn.microsoft.com/ru-ru/sharepoint/dev/images/xrankformula.gif)

Формула для оператора XRANK

В таблице 7 перечислены основные параметры, доступные для оператора **XRANK**.

**Таблица 7. Параметры оператора XRANK**

| **Параметр** | **Значение** | **Описание** |
| --- | --- | --- |
| *n* | *<целое_число>* | Задает количество результатов, для которых вычисляются статистические данные.  Этот параметр не влияет на количество результатов, на которые влияет динамический рейтинг. С его помощью из вычисления статистики просто исключаются ненужные элементы.  Значение по умолчанию: **0**. Нулевое значение содержит семантику *всех документов* . |
| *nb* | *<значение_с_плавающей_запятой>* | Параметр *nb* ссылается на нормированную величину. Этот параметр определяет коэффициент, на который умножается произведение дисперсии и среднего арифметического значений рейтингов в наборе результатов.  Параметр *f* в формуле XRANK. |

Как правило, нормализованный boost, *nb*, является единственным параметром, который изменяется. Этого параметра достаточно, чтобы понижать или повышать рейтинг отдельного элемента, не учитывая стандартное отклонение.

Доступны также дополнительные параметры, указанные ниже. Но обычно они не используются.

**Таблица 8. Дополнительные параметры оператора XRANK**

| **Параметр** | **Значение** | **Описание** |
| --- | --- | --- |
| *cb* | *<значение_с_плавающей_запятой>* | Параметр *cb* ссылается на постоянную величину.  Значение по умолчанию: **0**.  Параметр *a* в формуле XRANK. |
| *stdb* | *<значение_с_плавающей_запятой>* | Параметр *stdb* ссылается на величину стандартного отклонения.  Значение по умолчанию: **0**.  Параметр *e* в формуле XRANK. |
| *avgb* | *<значение_с_плавающей_запятой>* | Параметр *avgb* ссылается на среднее значение.  По умолчанию: **0**.  Параметр *d* в формуле XRANK. |
| *rb* | *<значение_с_плавающей_запятой>* | Параметр *rb* ссылается на диапазон значений. Этот коэффициент умножается на диапазон значений рейтингов в наборе результатов.  Значение по умолчанию: **0**.  Параметр *b* в формуле XRANK. |
| *pb* | *<значение_с_плавающей_запятой>* | Параметр *pb* ссылается на значение в процентах. Этот коэффициент умножается на собственный рейтинг элемента в сравнении с минимальным значением в наборе.  Значение по умолчанию: **0**.  Параметр *c* в формуле XRANK. |

### Примеры

**Пример 1.** Следующее выражение сопоставляет элементы, для которых полнотекстовый индекс по умолчанию содержит "cat" или "dog". Выражение увеличивает на постоянную величину 100 динамический рейтинг элементов, содержащих также термин "thoroughbred".

`(cat OR dog) XRANK(cb=100) thoroughbred`

**Пример 2.** Следующее выражение сопоставляет элементы, для которых полнотекстовый индекс по умолчанию содержит термины "cat" или "dog". Выражение увеличивает динамический рейтинг элементов на нормированную величину 1,5 для элементов, содержащих также термин "thoroughbred".

`(cat OR dog) XRANK(nb=1.5) thoroughbred`

**Пример 3.** Следующее выражение сопоставляет элементы, для которых полнотекстовый индекс по умолчанию содержит термины "cat" или "dog". Выражение увеличивает динамический рейтинг элементов на постоянную величину 100 и нормированную величину 1,5 для элементов, содержащих также термин "thoroughbred".

`(cat OR dog) XRANK(cb=100, nb=1.5) thoroughbred`

**Пример 4.** Следующее выражение сопоставляет все элементы, содержащие термин "animals", и увеличивает динамический рейтинг следующим образом:

- динамический ранг элементов, содержащих термин "dogs", увеличивается на 100 баллов;
- динамический ранг элементов, содержащих термин "cats", увеличивается на 200 баллов;
- динамический рейтинг элементов, содержащих и термин "dogs", и термин "cats", увеличивается на 300 баллов.

`(animals XRANK(cb=100) dogs) XRANK(cb=200) cats`

### Круглые скобки

Можно объединять разные части запросов по ключевым словам с помощью открывающей скобки " **(** " и закрывающей скобки " **)** ". Каждой открывающей скобке " **(** " должна соответствовать закрывающая скобка " **)** ". Пробел до или после скобки не влияет на запрос.