Руководство по синтаксису языка запросов по ключевым словам (KQL)Keyword Query Language (KQL) syntax reference

Узнайте, как создавать KQL-запросы для Поиск в SharePoint. Этот справочник по синтаксису описывает элементы KQL-запросов, а также порядок использования ограничений свойств и операторов в таких запросах.Learn to construct KQL queries for Search in SharePoint. This syntax reference describes KQL query elements and how to use property restrictions and operators in KQL queries.

Элементы KQL-запросаElements of a KQL query

KQL-запрос состоит из одного или нескольких элементов, перечисленных далее.A KQL query consists of one or more of the following elements:

  • Ключевые слова с произвольным текстом (слова или фразы)Free text-keywords—words or phrases

  • Ограничения свойствProperty restrictions

Элементы KQL-запросов можно комбинировать с одним или несколькими доступными операторами.You can combine KQL query elements with one or more of the available operators.

KQL-запросы, которые содержат только операторы, а также пустые KQL-запросы являются недопустимыми. KQL-запросы не учитывают регистр, однако операторы указываются с учетом регистра (прописными буквами).If the KQL query contains only operators or is empty, it isn't valid. KQL queries are case-insensitive but the operators are case-sensitive (uppercase).

Примечание

Ограничение длины KQL-запроса зависит от способа его создания.The length limit of a KQL query varies depending on how you create it. Если KQL-запрос создан при помощи внешнего интерфейса поиска SharePoint, доступного по умолчанию, максимальная длина составляет 2048 символов.If you create the KQL query by using the default SharePoint search front end, the length limit is 2,048 characters. Если же вы создаете KQL-запрос программным путем с помощью объектной модели запроса, ограничение длины по умолчанию составляет 4096 знаков.However, KQL queries you create programmatically by using the Query object model have a default length limit of 4,096 characters. Вы можете изменить это ограничение, увеличив количество знаков до 20 480, с помощью свойства MaxKeywordQueryTextLength или DiscoveryMaxKeywordQueryTextLength (для обнаружения электронных данных).You can increase this limit up to 20,480 characters by using the MaxKeywordQueryTextLength property or the DiscoveryMaxKeywordQueryTextLength property (for eDiscovery).

Создание запросов с произвольным текстом при помощи KQLConstructing free-text queries using KQL

При создании KQL-запроса с использованием произвольных выражений Поиск в SharePoint подбирает результаты с совпадениями для выбранных вами терминов, основываясь на терминах, хранящихся в полнотекстовом индексе. Сюда входят значения управляемых свойств, в которых параметр FullTextQueriable имеет значение true.When you construct your KQL query by using free-text expressions, Search in SharePoint matches results for the terms you chose for the query based on terms stored in the full-text index. This includes managed property values where FullTextQueriable is set to true.

KQL-запросы с произвольным текстом не чувствительны к регистру, однако операторы должны быть записаны заглавными буквами. Вы можете строить KQL-запросы с помощью одного или нескольких произвольных выражений:Free text KQL queries are case-insensitive but the operators must be in uppercase. You can construct KQL queries by using one or more of the following as free-text expressions:

  • word (содержит один или несколько символов без пробелов и знаков препинания);A word (includes one or more characters without spaces or punctuation)

  • phrase (содержит два и более слов, разделенных пробелами и обязательно заключенных в двойные кавычки).A phrase (includes two or more words together, separated by spaces; however, the words must be enclosed in double quotation marks)

Чтобы создать сложные запросы, вы можете комбинировать несколько произвольных выражений с помощью операторов KQL-запросов. Если операторы между выражениями отсутствуют, запрос будет выполняться так же, как при использовании оператора AND.To construct complex queries, you can combine multiple free-text expressions with KQL query operators. If there are multiple free-text expressions without any operators in between them, the query behavior is the same as using the AND operator.

Использование слов в KQL-запросе с произвольным текстомUsing words in the free-text KQL query

Если вы используете слова в KQL-запросе с произвольным текстом, служба Поиск в SharePoint возвращает результаты с точным совпадением этих слов с терминами, хранящимися в полнотекстовом индексе. Можно указывать только начальную часть слова, применяя оператор подстановочного знака (*) для включения сопоставления префиксов. При таком сопоставлении служба Поиск в SharePoint подбирает совпадения с терминами, содержащими искомое слово, за которым могут следовать другие символы.When you use words in a free-text KQL query, Search in SharePoint returns results based on exact matches of your words with the terms stored in the full-text index. You can use just a part of a word, from the beginning of the word, by using the wildcard operator (*) to enable prefix matching. In prefix matching, Search in SharePoint matches results with terms that contain the word followed by zero or more characters.

Например, следующие KQL­-запросы вернут элементы, содержащие термины "federated" и "search":For example, the following KQL queries return content items that contain the terms "federated" and "search":

federated search

federat* search

search fed*

KQL­-запросы не поддерживают сопоставление суффиксов.KQL queries don't support suffix matching.

Использование фраз в KQL-запросе с произвольным текстомUsing phrases in the free-text KQL query

Если вы используете фразы в KQL-запросе с произвольным текстом, служба Поиск в SharePoint возвращает только элементы, в которых есть слова из вашей фразы, следующие друг за другом. Чтобы задать фразу в KQL-запросе, необходимо использовать двойные кавычки.When you use phrases in a free-text KQL query, Search in SharePoint returns only the items in which the words in your phrase are located next to each other. To specify a phrase in a KQL query, you must use double quotation marks.

KQL-запросы не поддерживают сопоставление суффиксов, поэтому в запросах с произвольным текстом нельзя использовать оператор подстановочного знака перед фразой. Однако вы можете использовать оператор подстановочного знака после фразы.KQL queries don't support suffix matching, so you can't use the wildcard operator before a phrase in free-text queries. However, you can use the wildcard operator after a phrase.

Запросы с ограничениями свойств в KQLProperty restriction queries in KQL

С помощью KQL вы можете строить запросы, использующие ограничения свойств, чтобы получать результаты запроса только по заданному условию.Using KQL, you can construct queries that use property restrictions to narrow the focus of the query to match only results based on a specified condition.

Задание ограничений свойствSpecifying property restrictions

Базовое ограничение свойств состоит из перечисленных ниже элементов.A basic property restriction consists of the following:

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

В таблице 1 приведены некоторые примеры допустимого синтаксиса ограничений свойств в KQL-запросах.Table 1 lists some examples of valid property restrictions syntax in KQL queries.

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

СинтаксисSyntax Возвращаемое значениеReturns
author:"John Smith"
Возвращает элементы контента, автором которого является John Smith.Returns content items authored by John Smith.
filetype:docx
Возвращает документы Microsoft Word.Returns Microsoft Word documents.
filename:budget.xlsx
Возвращает элементы, содержащие имя файла budget.xlsx.Returns content items with the file name budget.xlsx.

Ограничение свойства не должно содержать пробелы между именем, оператором и значением этого свойства. Иначе это ограничение будет обрабатываться как запрос с произвольным текстом. Максимальная длина ограничения свойства составляет 2048 символов.The property restriction must not include white space between the property name, property operator, and the property value, or the property restriction is treated as a free-text query. The length of a property restriction is limited to 2,048 characters.

В следующих примерах наличие пробела приводит к тому, что запрос возвращает элементы, содержащие термины "author" и "John Smith", вместо элементов контента, автором которого является John Smith:In the following examples, the white space causes the query to return content items containing the terms "author" and "John Smith", instead of content items authored by John Smith:

author: "John Smith"

author :"John Smith"

author : "John Smith"

Другими словами, описанные выше ограничения свойств эквивалентны следующему запросу:In other words, the previous property restrictions are equivalent to the following:

author "John Smith"

Указание имен свойств для ограничений свойствSpecifying property names for property restrictions

Необходимо указать допустимое имя управляемого свойства для ограничения свойства. По умолчанию в Поиск в SharePoint входит несколько управляемых свойств для документов.You must specify a valid managed property name for the property restriction. By default, Search in SharePoint includes several managed properties for documents.

Чтобы задать ограничение для значения свойства, извлеченного при обходе контента, сначала необходимо сопоставить это свойство с управляемым свойством. См. раздел Управляемые свойства и свойства для обхода статьи Планирование методов поиска для конечных пользователей (Office SharePoint Server).To specify a property restriction for a crawled property value, you must first map the crawled property to a managed property. See Managed and crawled properties in Plan the end-user search experience.

Управляемое свойство должно относиться к типу Queryable , чтобы вы могли искать это управляемое свойство в документе. Кроме того, управляемое свойство может относиться к типу Retrievable , чтобы можно было его извлечь. Однако управляемое свойство не обязательно должно относиться к типу Retrievable , чтобы можно было найти свойство.The managed property must be Queryable so that you can search for that managed property in a document. In addition, the managed property may be Retrievable for the managed property to be retrieved. However, the managed property doesn't have to be Retrievable to carry out property searches.

Операторы свойств, поддерживаемые в ограничениях свойствProperty operators that are supported in property restrictions

Служба Поиск в SharePoint поддерживает несколько операторов свойств для ограничений свойств, приведенных в таблице 2.Search in SharePoint supports several property operators for property restrictions, as shown in Table 2.

Таблица 2. Допустимые операторы свойств для ограничений свойствTable 2. Valid property operators for property restrictions

ОператорOperator ОписаниеDescription Поддерживаемый тип управляемого свойстваSupported managed property type
.:
Возвращает результаты, в которых указанное в ограничении свойства значение равно значению свойства, хранящегося в базе данных хранилища свойств, или совпадает с отдельными терминами в значении свойства, хранящегося в полнотекстовом индексе.Returns results where the value specified in the property restriction is equal to the property value that is stored in the Property Store database, or matches individual terms in the property value that is stored in the full-text index.
TextText
DateTimeDateTime
IntegerInteger
DecimalDecimal
DoubleDouble
YesNoYesNo
=
Возвращает результаты поиска со значениями свойств, равными значению, определенному при ограничении свойств.Returns search results where the property value is equal to the value specified in the property restriction.
Примечание. Не рекомендуем сочетать оператор = со знаком звездочки (*), если нужно найти точное совпадение.Note: We do not recommend combining the = operator together with asterisk ( *) when you do exact matching.
TextText
DateTimeDateTime
IntegerInteger
DecimalDecimal
DoubleDouble
YesNoYesNo
<
Возвращает результаты, в которых значение свойства меньше значения, указанного в ограничении свойства.Returns results where the property value is less than the value specified in the property restriction.
DateTimeDateTime
IntegerInteger
DecimalDecimal
DoubleDouble
>
Возвращает результаты, в которых значение свойства больше значения, указанного в ограничении свойства.Returns search results where the property value is greater than the value specified in the property restriction.
DateTimeDateTime
IntegerInteger
DecimalDecimal
DoubleDouble
<=
Возвращает результаты со значением свойства, меньшим или равным значению, указанному в ограничении свойства.Returns search results where the property value is less than or equal to the value specified in the property restriction.
DateTimeDateTime
IntegerInteger
DecimalDecimal
DoubleDouble
>=
Возвращает результаты со значением свойства, большим или равным значению, указанному в ограничении свойства.Returns search results where the property value is greater than or equal to the value specified in the property restriction.
DateTimeDateTime
IntegerInteger
DecimalDecimal
DoubleDouble
<>
Возвращает результаты со значением свойства, не равным значению, указанному в ограничении свойства.Returns search results where the property value does not equal the value specified in the property restriction.
DateTimeDateTime
IntegerInteger
DecimalDecimal
TextText
DoubleDouble
YesNoYesNo
....
Возвращает результаты, в которых значение свойства включено в диапазон, указанный в ограничении свойства.Returns search results where the property value falls within the range specified in the property restriction.
Например, диапазон A..B представляет собой набор значений от A до B со значениями A и B включительно. Для диапазонов дат такая запись означает диапазон от начала дня A до конца дня B.For example, the range A..B represents a set of values from A to B where both A and B are inclusive. For date ranges this means from the beginning of day A to the end of day B.
DateTimeDateTime
IntegerInteger
DecimalDecimal
DoubleDouble

Указание значений свойствSpecifying property values

Укажите значение свойства, имеющего допустимый тип данных для типа управляемого свойства. В таблице 3 приведен перечень сопоставлений типов.You must specify a property value that is a valid data type for the managed property's type. Table 3 lists these type mappings.

Таблица 3. Соответствие допустимых типов данных типам управляемых свойствTable 3. Valid data type mappings for managed property types

Тип управляемых свойствManaged type Тип данныхData type
TextText
StringString
IntegerInteger
Int64Int64
DoubleDouble
System.DoubleSystem.Double
DecimalDecimal
DecimalDecimal
DateTime()DateTime()
DateTimeDateTime
YesNoYesNo
BooleanBoolean

Значения текстовых свойствText property values

В случае значений текстовых свойств ход сопоставления зависит от того, хранится ли свойство в полнотекстовом индексе или в индексе поиска.For text property values, the matching behavior depends on whether the property is stored in the full-text index or in the search index.

Значения свойств в полнотекстовом индексеProperty values in the full-text index

Значения свойств хранятся в полнотекстовом индексе, когда свойству FullTextQueriable присвоено значение true для управляемого свойства. Эту настройку можно использовать только для строковых свойств. Значения свойств, указанные в запросе, сопоставляются с отдельными терминами, которые хранятся в полнотекстовом индексе. Используйте свойство NoWordBreaker , чтобы указать, должен ли проводиться поиск совпадений с полным значением свойства.Property values are stored in the full-text index when the FullTextQueriable property is set to true for a managed property. You can configure this only for string properties. Property values that are specified in the query are matched against individual terms that are stored in the full-text index. Use the NoWordBreaker property to specify whether to match with the whole property value.

Например, если вы ищете элемент контента, созданный пользователем Paul Shakespear, такой KQL-запрос возвращает результаты с совпадениями:For example, if you're searching for a content item authored by Paul Shakespear, the following KQL query returns matching results:

author:Shakespear

author:Paul

Кроме того, поддерживается сопоставление префиксов. Вы можете использовать оператор подстановочного знака (*), однако он не требуется при указании отдельных слов. Перейдем к следующему примеру. Этот KQL-запрос тоже возвращает элементы контента, созданные пользователем Paul Shakespear:Prefix matching is also supported. You can use the wildcard operator (*), but isn't required when you specify individual words. Continuing with the previous example, the following KQL query returns content items authored by Paul Shakespear as matches:

author:Shakesp*

Когда вы указываете фразу для значения свойства, результаты должны содержать указанную фразу в значении свойства, хранящегося в полнотекстовом индексе. Такой запрос возвращает элементы контента с текстом "Advanced Search" в названии, например "Advanced Search XML" и "Learning About the Advanced Search Web Part":When you specify a phrase for the property value, matched results must contain the specified phrase within the property value that is stored in the full-text index. The following query example returns content items with the text "Advanced Search" in the title, such as "Advanced Search XML", "Learning About the Advanced Search web part", and so on:

title:"Advanced Search"

Сопоставление префиксов также поддерживается для фраз, указанных в значениях свойств. Но в этом случае в запросе следует использовать оператор подстановочного знака (*), который допустим только в конце фразы, например:Prefix matching is also supported with phrases specified in property values, but you must use the wildcard operator (*) in the query, and it is supported only at the end of the phrase, as follows:

title:"Advanced Sear*"

Следующие запросы не возвращают ожидаемые результаты:The following queries do not return the expected results:

title:"Advan* Search"

title:"Advanced Sear"

Числовые значения свойствNumerical values for properties

В случае числовых значений свойств, к которым относятся управляемые типы Integer, Double и Decimal, ограничение свойства сопоставляется с полным значением свойства.For numerical property values, which include the Integer, Double, and Decimal managed types, the property restriction is matched against the entire value of the property.

Значения даты и времени для свойствDate or time values for properties

В языке KQL для даты и времени предназначен тип данных datetime. В запросах поддерживаются следующие форматы даты и времени, совместимые с ISO 8601:KQL provides the datetime data type for date and time.The following ISO 8601-compatible datetime formats are supported in queries:

  • ГГГГ-ММ-ДДYYYY-MM-DD

  • YYYY-MM-DDThh:mm:ssYYYY-MM-DDThh:mm:ss

  • ГГГГ-ММ-ДДTчч:мм:ссZYYYY-MM-DDThh:mm:ssZ

  • ГГГГ-ММ-ДДTчч:мм:ссfrZYYYY-MM-DDThh:mm:ssfrZ

В этих форматах datetime:In these datetime formats:

  • ГГГГ задает год из четырех цифр.YYYY specifies a four-digit year.

    Примечание

    Поддерживается только формат года из четырех цифр.Only four-digit years are supported.

  • ММ задает месяц в формате двух цифр. Например, 01 — это январь.MM specifies a two-digit month. For example, 01 = January.

  • Параметр DD задает двузначное значение дня месяца (от 01 до 31).DD specifies a two-digit day of the month (01 through 31).

  • Параметр T обозначает букву "T".T specifies the letter "T".

  • Параметр hh обозначает часы в формате двух цифр (от 00 до 23). Обозначения a.m. и p.m. не допускаются.hh specifies a two-digits hour (00 through 23); A.M./P.M. indication is not allowed.

  • Параметр mm обозначает минуты в формате двух цифр (от 00 до 59).mm specifies a two-digit minute (00 through 59).

  • Параметр сс обозначает секунды в формате двух цифр (от 00 до 59).ss specifies a two-digit second (00 through 59).

  • Параметр fr задает доли секунды (необязательно). В этом случае используется от 1 до 7 цифр после разделителя (" ."), отделяющего доли секунды от секунд. Например, 2012-09-27T11:57:34.1234567.fr specifies an optional fraction of seconds, ss; between 1 to 7 digits that follows the . after the seconds. For example, 2012-09-27T11:57:34.1234567.

Все значения даты и времени необходимо указывать в часовом поясе UTC (другое название GMT). Идентификатор часового пояса UTC (символ "Z" в конце) указывать необязательно.All date/time values must be specified according to the UTC (Coordinated Universal Time), also known as GMT (Greenwich Mean Time) time zone. The UTC time zone identifier (a trailing "Z" character) is optional.

Соответствующие интервалы дат, поддерживаемые KQLRelevant date intervals supported by KQL

Язык KQL поддерживает реляционные запросы в диапазоне day, для которых зарезервированы ключевые слова, как показано в таблице 4. Используйте двойные кавычки ("") для интервалов дат, между их названиями ставьте пробел.KQL enables you to build search queries that support relative "day" range query, with reserved keywords as shown in Table 4. Use double quotation marks ("") for date intervals with a space between their names.

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

LastModifiedTime=today

Совпадения будут включать элементы от начала текущего года до его окончания:Represents the time from the beginning of the current year until the end of the current year.

LastModifiedTime="this year"

Совпадения будут включать элементы с 1 января 2019 г. до 26 апреля 2019 г.:Matches would include items from January 1st of 2019 until April 26th of 2019:

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

Имя интервала датName of date interval ОписаниеDescription
todaytoday
Представляет период времени с начала текущего дня до его окончания.Represents the time from the beginning of the current day until the end of the current day.
yesterdayyesterday
Представляет период времени с начала предшествующего дня до его окончания.Represents the time from the beginning of the day until the end of the day that precedes the current day.
this weekthis week
Представляет период времени от начала текущей недели до ее окончания. При определении первого дня недели учитываются традиции региона, в котором формируется текст запроса.Represents the time from the beginning of the current week until the end of the current week. The culture in which the query text was formulated is taken into account to determine the first day of the week.
this monththis month
Представляет период времени с начала текущего месяца до его окончания.Represents the time from the beginning of the current month until the end of the current month.
last monthlast month
Представляет период времени от начала предыдущего месяца до его окончания.Represents the entire month that precedes the current month.
this yearthis year
Представляет период времени от начала текущего года до его окончания.Represents the time from the beginning of the current year until the end of the current year.
last yearlast year
Представляет весь год, предшествующий текущему.Represents the entire year that precedes the current year.

Использование нескольких ограничений свойств в KQL-запросеUsing multiple property restrictions within a KQL query

Служба Поиск в SharePoint поддерживает использование нескольких ограничений свойств в одном KQL-запросе. Можно использовать либо одно свойство для нескольких ограничений свойств, либо разные свойства для каждого ограничения свойств.Search in SharePoint supports the use of multiple property restrictions within the same KQL query. You can use either the same property for more than one property restriction, or a different property for each property restriction.

Если вы используете несколько экземпляров ограничений свойств, поиск совпадений основан на объединении ограничений свойств в KQL-запросе. В этом примере совпадения включают элементы контента, автором которого является John Smith или Jane Smith:When you use multiple instances of the same property restriction, matches are based on the union of the property restrictions in the KQL query. Matches would include content items authored by John Smith or Jane Smith, as follows:

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

Результат будет таким же, как и при использовании логического оператора OR в запросе, например:This functionally is the same as using the OR Boolean operator, as follows:

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

Если вы используете различные ограничения свойств, поиск совпадений основан на пересечении ограничений свойств в KQL-запросе, например:When you use different property restrictions, matches are based on an intersection of the property restrictions in the KQL query, as follows:

author:"John Smith" filetype:docx

Совпадения будут содержать документы Microsoft Word, созданные пользователем John Smith. Такой же результат будет при использовании логического оператора AND, как показано в следующем примере:Matches would include Microsoft Word documents authored by John Smith. This is the same as using the AND Boolean operator, as follows:

author:"John Smith" AND filetype:docx

Операторы KQL для сложных запросовKQL operators for complex queries

Синтаксис языка KQL включает несколько операторов, которые можно использовать для создания сложных запросов.KQL syntax includes several operators that you can use to construct complex queries.

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

Используйте логические операторы, чтобы расширить или сузить область поиска. Логические операторы в KQL-запросах можно использовать с произвольными выражениями и ограничениями свойств. В таблице 5 перечислены поддерживаемые логические операторы.You use Boolean operators to broaden or narrow your search. You can use Boolean operators with free text expressions and property restrictions in KQL queries. Table 5 lists the supported Boolean operators.

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

ОператорOperator ОписаниеDescription
ANDAND
Возвращает результаты поиска, содержащие все произвольные выражения или ограничения свойств, заданные оператором AND. Укажите допустимое произвольное текстовое выражение и (или) допустимое ограничение свойств перед оператором AND и после него. Представьте, что используете знак "+". Returns search results that include all of the free text expressions, or property restrictions specified with the AND operator. You must specify a valid free text expression and/or a valid property restriction both preceding and following the AND operator. This is the same as using the plus ("+") character.
NOTNOT
Возвращает результаты поиска, не содержащие заданных произвольных выражений или ограничений свойств. Укажите допустимое произвольное текстовое выражение и (или) допустимое ограничение свойств после оператора NOT. Представьте, что используете знак "-".Returns search results that don't include the specified free text expressions or property restrictions. You must specify a valid free text expression and/or a valid property restriction following the NOT operator. This is the same as using the minus ("-") character.
ИЛИOR
Возвращает результаты поиска, содержащие одно или несколько заданных произвольных выражений или ограничений свойств. Укажите допустимое произвольное текстовое выражение и (или) допустимое ограничение свойств перед оператором OR и после него.Returns search results that include one or more of the specified free text expressions or property restrictions. You must specify a valid free text expression and/or a valid property restriction both preceding and following the OR operator.

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

Используйте операторы поиска с учетом расположения, чтобы получить результаты, в которых заданные термины находятся в непосредственной близости друг от друга. Такие операторы вы можете использовать только с произвольными текстовыми выражениями: они не предназначены для использования с ограничениями свойств в KQL-запросах. Существует два оператора операторы поиска с учетом расположения: NEAR и ONEAR.You use proximity operators to match the results where the specified search terms are within close proximity to each other. Proximity operators can be used with free-text expressions only; they are not supported with property restrictions in KQL queries. There are two proximity operators: NEAR and ONEAR.

Оператор NEARNEAR operator

Оператор NEAR возвращает совпадения, в которых заданные термины поиска находятся в непосредственной близости друг от друга (при этом не учитывается порядок следования терминов). Синтаксис оператора NEAR:The NEAR operator matches the results where the specified search terms are within close proximity to each other, without preserving the order of the terms. The syntax for NEAR is as follows:

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

n — необязательный параметр, указывающий максимальное расстояние между терминами. Параметр n может принимать целые значения >= 0, значение по умолчанию: 8.Where n is an optional parameter that indicates maximum distance between the terms. The value of n is an integer >= 0 with a default of 8.

Параметр n может быть задан как n=v, где v — это значение. Можно указать и сокращенную форму: v. Например, в выражении NEAR(4) параметр v равен 4.The parameter n can be specified as n=v where v represents the value, or shortened to only v; such as NEAR(4) where v is 4.

Примеры:For example:

"acquisition" NEAR "debt"

Результатом запроса будут элементы, в которых термины "acquisition" и "debt" появляются в одном элементе, в котором за термином "acquisition" следует до восьми других терминов, а за ними "debt" (или наоборот). Порядок терминов при поиске совпадений не учитывается.This query matches items where the terms "acquisition" and "debt" appear within the same item, where an instance of "acquisition" is followed by up to eight other terms, and then an instance of the term "debt"; or vice versa. The order of the terms is not significant for the match.

Если вам нужно меньшее расстояние между терминами, укажите его. Результатом следующего запроса будут элементы, в которых термины "acquisition" и "debt" появляются в одном элементе, при этом между ними не более трех терминов. Порядок следования терминов также не учитывается.If you need a smaller distance between the terms, you can specify it. The following query matches items where the terms "acquisition" and "debt" appear within the same item, where a maximum distance of 3 between the terms. Once again the order of the terms does not affect the match.

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

Примечание

В SharePoint оператор NEAR больше не сохраняет порядок токенов.In SharePoint the NEAR operator no longer preserves the ordering of tokens. Кроме того, оператор NEAR теперь принимает необязательный параметр, который указывает максимальное расстояние до токена.In addition, the NEAR operator now receives an optional parameter that indicates maximum token distance. Однако значение по умолчанию все еще равно 8.However, the default value is still 8. Если нужно реализовать предыдущее поведение, используйте оператор ONEAR.If you must use the previous behavior, use ONEAR instead.

Оператор ONEARONEAR operator

Оператор ONEAR возвращает совпадения, в которых заданные термины поиска находятся в непосредственной близости друг от друга, при этом сохраняется порядок их следования. Ниже приведен синтаксис оператора ONEAR, где n — необязательный параметр, указывающий максимальное расстояние между терминами. Параметр n может принимать целые значения >= 0. Значение по умолчанию: 8.The ONEAR operator matches the results where the specified search terms are within close proximity to each other, while preserving the order of the terms. The syntax for ONEAR is as follows, where n is an optional parameter that indicates maximum distance between the terms. The value of n is an integer >= 0 with a default of 8.

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

Параметр n может быть задан как n=v, где v — это значение. Можно указать и сокращенную форму: v. Например, в выражении ONEAR(4) параметр v равен 4.The parameter n can be specified as n=v where v represents the value, or shortened to only v; such as ONEAR(4) where v is 4.

Например, результатом следующего запроса будут элементы, в которых термины "acquisition" и "debt" появляются в одном элементе, при этом за термином "acquisition" следует до восьми других терминов, а за ними "debt". Порядок следования терминов должен совпадать с их порядком в возвращаемом элементе:For example, the following query matches items where the terms "acquisition" and "debt" appear within the same item, where an instance of "acquisition" is followed by up to eight other terms, and then an instance of the term "debt". The order of the terms must match for an item to be returned:

"acquisition" ONEAR "debt"

Если требуется меньшее расстояние между терминами, укажите его, как показано в примере ниже. Результатом следующего запроса будут элементы, в которых термины "acquisition" и "debt" появляются в одном элементе, при этом между ними не более 3 терминов. Порядок следования терминов должен совпадать с их порядком в возвращаемом элементе:If you require a smaller distance between the terms, you can specify it as follows. This query matches items where the terms "acquisition" and "debt" appear within the same item, where a maximum distance of 3 between the terms. The order of the terms must match for an item to be returned:

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

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

Используйте оператор WORDS, чтобы указать, что термины в запросе синонимичны, и возвращаемые результаты должны совпадать с любым из заданных терминов. Оператор WORDS вы можете использовать только с произвольными текстовыми выражениями. Его использование с ограничениями свойств в KQL-запросах не поддерживается.You use the WORDS operator to specify that the terms in the query are synonyms, and that results returned should match either of the specified terms. You can use the WORDS operator with free text expressions only; it is not supported with property restrictions in KQL queries.

Указанный ниже пример запроса выдает результаты, содержащие термин "TV" или "television". Под ним приведен еще один запрос, его результаты аналогичны предыдущим.The following query example matches results that contain either the term "TV" or the term "television". This matching behavior is the same as if you had used the following query:

WORDS(TV, Television)

TV OR Television

Эти запросы отличаются ранжированием результатов. При использовании оператора WORDS термины "TV" и "television" рассматриваются как синонимы, а не как отдельные термины. Поэтому оба эти термина ранжируются, как если бы они были одним термином. Например, элемент контента, содержащий один термин "television" и пять терминов "TV", ранжируется так же, как элемент контента с шестью терминами "TV".These queries differ in how the results are ranked. When you use the WORDS operator, the terms "TV" and "television" are treated as synonyms instead of separate terms. Therefore, instances of either term are ranked as if they were the same term. For example, a content item that contained one instance of the term "television" and five instances of the term "TV" would be ranked the same as a content item with six instances of the term "TV".

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

Используйте оператор подстановочного знака (символ звездочки, "*"), чтобы включить сопоставление префиксов.You use the wildcard operator—the asterisk character (" * ")—to enable prefix matching. Вы можете указать в запросе начальную часть слова, поставив далее оператор подстановочного знака, как показано ниже.You can specify part of a word, from the beginning of the word, followed by the wildcard operator, in your query, as follows. Результат следующего запроса — термины, начинающиеся на "serv" (при этом далее могут следовать другие знаки), например "serve", "server", "service":This query would match results that include terms beginning with "serv", followed by zero or more characters, such as serve, server, service, and so on:

serv*

Операторы включения и исключенияInclusion and exclusion operators

С помощью операторов включения и исключения, описанных в таблице 6, вы можете указать, будут ли возвращаемые результаты включать или исключать контент, совпадающий со значением, указанным в произвольном текстовом выражении или ограничении свойств.You can specify whether the results that are returned should include or exclude content that matches the value specified in the free text expression or the property restriction by using the inclusion and exclusion operators, described in Table 6.

Таблица 6. Операторы для включения и исключения контента в результатахTable 6. Operators for including and excluding content in results

ИмяName ОператорOperator ПоведениеBehavior
ВключениеInclusion
" + "
Включает в результаты контент со значениями, совпадающими с теми, которые нужно включить.Includes content with values that match the inclusion.
Это поведение по умолчанию, если символы не указаны. Аналогичный результат будет при использовании оператора AND.This is the default behavior if no character is specified. This is the same as using the AND operator.
ИсключенияExclusion
" - "
Исключает контент со значениями, совпадающими с теми, которые нужно исключить. Аналогичный результат будет при использовании оператора NOT.Excludes content with values that match the exclusion. This is the same as using the NOT operator.

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

Применяйте оператор XRANK, чтобы повысить динамический рейтинг элементов в зависимости от повторений определенных терминов в match expression, не меняя состав элементов, удовлетворяющих критериям запроса. Выражение XRANK содержит один компонент, совпадение с которым обязательно (match expression), и один или несколько компонентов, которые влияют только на динамическое ранжирование (rank expression). Должен быть задан хотя бы один параметр (за исключением n), чтобы выражение XRANK было допустимым.You use the XRANK operator to boost the dynamic rank of items based on certain term occurrences within the match expression, without changing which items match the query. An XRANK expression contains one component that must be matched, the match expression, and one or more components that contribute only to dynamic ranking, the rank expression. At least one of the parameters, excluding n, must be specified for an XRANK expression to be valid.

Примечание

Задержка при выполнении запроса (и вероятность превышения времени ожидания) растет при использовании сложных запросов, особенно с операторами xrank.Query latency (and probability of timeout) increases when using complex queries and especially when using xrank operators. Увеличение задержки при выполнении запроса зависит от количества операторов XRANK и количества совпадений в компонентах совпадение выражения и ранжирующее выражение в дереве запросов.The increase in query latency depends on the number of XRANK operators and the number of hits in the match expression and rank expression components in the query tree.

Параметр Match expressions может быть любым допустимым выражением KQL, включая вложенные выражения XRANK. Параметр Rank expressions может быть любым допустимым выражением в языке KQL, кроме выражений XRANK. Если KQL-запросы содержат несколько операторов XRANK, итоговое значение динамического рейтинга рассчитывается как сумма увеличений по всем операторам XRANK.Match expressions may be any valid KQL expression, including nested XRANK expressions. Rank expressions may be any valid KQL expression without XRANK expressions. If your KQL queries have multiple XRANK operators, the final dynamic rank value is calculated as a sum of boosts across all XRANK operators.

Примечание

Используйте скобки, чтобы явно указать порядок вычисления для KQL-запросов, содержащих более одного оператора XRANK на одном уровне.Use parenthesis to explicitly indicate the order of computation for KQL queries that have more than one XRANK operator at the same level.

Можно использовать следующий синтаксис оператора XRANK:You can use the XRANK operator in the following syntax:

<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 вычисляется по формуле:The XRANK operator's dynamic ranking calculation is based on this formula:

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

В таблице 7 перечислены основные параметры, доступные для оператора XRANK.Table 7 lists the basic parameters available for the XRANK operator.

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

ПараметрParameter ЗначениеValue ОписаниеDescription
nn
<integer_value><integer_value>
Указывает количество результатов для вычисления статистики.Specifies the number of results to compute statistics from.
Этот параметр не влияет на количество результатов, на которые влияет динамический рейтинг. С его помощью из вычисления статистики просто исключаются ненужные элементы.This parameter does not affect the number of results that the dynamic rank contributes to; it is just a means to exclude irrelevant items from the statistics calculations.
По умолчанию: *0*. Нулевое значение означает *все документы* . Default: 0. A zero value carries the semantic of all documents .
nbnb
<float_value><float_value>
Параметр nb относится к нормированному увеличению. Этот параметр определяет коэффициент, на который умножается произведение дисперсии и среднего арифметического значений рейтингов в наборе результатов.The nb parameter refers to normalized boost. This parameter specifies the factor that is multiplied with the product of the variance and average score of the rank values of the results set.
Параметр f в формуле XRANK.f in the XRANK formula.

Обычно нормированное увеличение ( nb) единственный изменяемый параметр. Этого параметра достаточно, чтобы понижать или повышать рейтинг отдельного элемента, не учитывая стандартное отклонение.Typically, normalized boost, nb, is the only parameter that is modified. This parameter provides the necessary control to promote or demote a particular item, without taking standard deviation into account.

Доступны также дополнительные параметры, указанные ниже. Но обычно они не используются.The following advanced parameters are also available. However, typically they're not used.

Таблица 8. Дополнительные параметры оператора XRANKTable 8. Advanced parameters for XRANK

ПараметрParameter ЗначениеValue ОписаниеDescription
cbcb
<float_value><float_value>
Параметр cb увеличивает рейтинг на постоянную величину.The cb parameter refers to constant boost.
Значение по умолчанию: 0.Default: 0.
Параметр a в формуле XRANK.a in the XRANK formula.
stdbstdb
<float_value><float_value>
Параметр stdb увеличивает рейтинг на величину стандартного отклонения.The stdb parameter refers to standard deviation boost.
Значение по умолчанию: 0.Default: 0.
Параметр e в формуле XRANK.e in the XRANK formula.
avgbavgb
<float_value><float_value>
Параметр avgb увеличивает рейтинг на среднее значение.The avgb parameter refers to average boost.
По умолчанию: 0.Default: 0.
Параметр d в формуле XRANK.d in the XRANK formula.
rbrb
<float_value><float_value>
Параметр rb увеличивает рейтинг в диапазоне. Этот коэффициент умножается на диапазон значений рейтингов в наборе результатов.The rb parameter refers to range boost. This factor is multiplied with the range of rank values in the results set.
Значение по умолчанию: 0.Default: 0.
Параметр b в формуле XRANK.b in the XRANK formula.
pbpb
<float_value><float_value>
Параметр pb задает увеличение в процентах. Этот коэффициент умножается на собственный рейтинг элемента в сравнении с минимальным значением в наборе.The pb parameter refers to percentage boost. This factor is multiplied with the item's own rank compared to the minimum value in the corpus.
Значение по умолчанию: 0.Default: 0.
Параметр c в формуле XRANK.c in the XRANK formula.

ПримерыExamples

Пример 1. Следующее выражение сопоставляет элементы, для которых полнотекстовый индекс по умолчанию содержит "cat" или "dog". Выражение увеличивает на постоянную величину 100 динамический рейтинг элементов, содержащих также термин "thoroughbred".Example 1. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases dynamic rank of those items with a constant boost of 100 for items that also contain "thoroughbred".

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

Пример 2. Следующее выражение сопоставляет элементы, для которых полнотекстовый индекс по умолчанию содержит термины "cat" или "dog". Выражение увеличивает динамический рейтинг элементов на нормированную величину 1,5 для элементов, содержащих также термин "thoroughbred".Example 2. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases dynamic rank of those items with a normalized boost of 1.5 for items that also contain "thoroughbred".

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

Пример 3. Следующее выражение сопоставляет элементы, для которых полнотекстовый индекс по умолчанию содержит термины "cat" или "dog". Выражение увеличивает динамический рейтинг элементов на постоянную величину 100 и нормированную величину 1,5 для элементов, содержащих также термин "thoroughbred".Example 3. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases dynamic rank of those items with a constant boost of 100 and a normalized boost of 1.5, for items that also contain "thoroughbred".

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

Пример 4. Следующее выражение сопоставляет все элементы, содержащие термин "animals", и увеличивает динамический рейтинг следующим образом:Example 4. The following expression matches all items containing the term "animals", and boosts dynamic rank as follows:

  • динамический рейтинг элементов, содержащих термин "dogs", увеличивается на 100 баллов;Dynamic rank of items that contain the term "dogs" is boosted by 100 points.

  • динамический рейтинг элементов, содержащих термин "cats", увеличивается на 200 баллов;Dynamic rank of items that contain the term "cats" is boosted by 200 points.

  • динамический рейтинг элементов, содержащих и термин "dogs", и термин "cats", увеличивается на 300 баллов.Dynamic rank of items that contain both the terms "dogs" and "cats" is boosted by 300 points.

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

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

Можно объединять разные части запросов по ключевым словам с помощью открывающей скобки " ( " и закрывающей скобки " ) ". Каждой открывающей скобке " ( " должна соответствовать закрывающая скобка " ) ". Пробел до или после скобки не влияет на запрос.You can combine different parts of a keyword query by using the opening parenthesis character " ( " and closing parenthesis character " ) ". Each opening parenthesis " ( " must have a matching closing parenthesis " ) ". A white space before or after a parenthesis does not affect the query.

См. такжеSee also