2 Structures
A KQL expression consists of search tokens, operators, and property restrictions. A search token consists of a value or a range of values to search for, and an operator specifies how to include, exclude, and rank the search results. A property restriction specifies a Boolean predicate on one property of the searched items.
KQL operators are case sensitive, and operators use uppercase. Some operators are placed between operands, and other operators are placed before operands. Where noted in the following subsections, operators can have parameters that are placed after the operator in parentheses.
The following words are operators:
§ ALL
§ AND
§ ANY
§ NEAR
§ NONE
§ NOT
§ ONEAR
§ OR
§ WORDS
§ XRANK
A special class of operators, property operators, is used for property restrictions. The following are property operators:
§ :
§ =
§ <>
§ >
§ >=
§ <
§ <=
The structure of a KQL expression corresponds to the following rules, which themselves conform to Augmented Backus-Naur Form (ABNF) as specified in [RFC5234].
-
kql-expression = (operator-expression / expression-list) expression-list = (operator-expression operator-expression) / (expression-list operator-expression) operator-expression = (all / and / any / near / none / not / onear / or / words / xrank / basic-expression / paren-expression) paren-expression = "(" kql-expression ")" basic-expression = ([qualification] unquoted-string-value) / ([qualification] quoted-string-value) / property-restriction ; Operator expressions all = "ALL" "(" 1*string-value ")" and = operator-expression "AND" operator-expression any = "ANY" "(" 1*string-value ")" none = "NONE" "(" 1*string-value ")" not = "NOT" operator-expression or = operator-expression "OR" operator-expression near = operator-expression "NEAR" [proximity-param] operator-expression onear = operator-expression "ONEAR" [proximity-param] operator-expression proximity-param = "(" [["N" "="] integer-value] ")" words = "WORDS" "(" words-param-list ")" words-param-list = words-param *([","] words-param) words-param = [qualification] string-value xrank = operator-expression "XRANK" "(" xrank-param-list ")" operator-expression xrank-param-list = xrank-param *([","] xrank-param) xrank-param = ("pb" "=" float-value) / ("rb" "=" float-value) / ("cb" "=" float-value) / ("avgb" "=" float-value) / ("stdb" "=" float-value) / ("nb" "=" float-value) / ("n" "=" integer-value) ; Property restriction property-restriction = [qualification] property-name property-operator property-value property-name = property-token / quoted-string-value property-token = 1*(%x30-39 / %x41-5a / %x5f / %x61-7a / %xaa / %xb5 / %xba / %xc0-d6 / %xe0-ffffffff) property-value = property-typed-value / unquoted-property-token / quoted-string-value property-operator = ":" / "=" / "<>" / ">" / ">="/ "<" / "<=" unquoted-property-token = 1*(%x01-08 / %x0b-0c / %x0e-1f / %x21 / %x23-27 / %x2a-3b / %x3d / %x3f-ffffffff) property-typed-value = boolean-value / %x22 boolean-value %x22 / float-value [".." float-value] / %x22 float-value [".." float-value] %x22 / integer-value [".." integer-value] / %x22 integer-value [".." integer-value] %x22 / date-named / date-value-no-ws [".." date-value-no-ws] / %x22 date-value [".." date-value] %x22 date-named = "today" / %x22 "today" %x22 / "yesterday" / %x22 "yesterday" %x22 / %x22 "this week" %x22 / %x22 "this month" %x22 / %x22 "last month" %x22 / %x22 "this year" %x22 / %x22 "last year" %x22 ; Tokens boolean-value = "true" / "false" ; The following are culture dependent and are not specified here: ; float-value, integer-value, date-value, date-value-no-ws string-value = quoted-string-value / unquoted-string-value ; <quoted-string-value> can contain any characters, but a double quotation ; mark within the quoted string MUST be represented by two double quotation marks. quoted-string-value = DQUOTE 1*(%x00-21 / DQUOTE DQUOTE / %x23-ffffffff) DQUOTE ; <unquoted-string-value> cannot contain white space, ; double quotation mark, and parentheses. ; <unquoted-string-value> can contain property-chars in the beginning or at ; the end, but not in the middle unquoted-string-value = *property-chars *(%x01-08 / %x0b-0c / %x0e-1f / %x21 / %x23-27 / %x2a-39 / %x3b / %x3f-ffffffff) *property-chars property-chars = ":" / "=" / ">" / "<" ; General syntax element qualification = "+" / "-"
For readability, the preceding rules assume that no extra white space exists in the KQL expression. However, with the exception of property-operator (no white space before and after), qualification (no white space after), ".." in ranges (no white space before and after), and parameter assignment (no white space before and after =), KQL does permit white space to immediately precede and follow parentheses, commas, operators, tokens, and property restrictions.
Also, although ABNF as specified in [RFC5234] does not explicitly support any encoding other than US-ASCII, the quoted-string-value, unquoted-string-value, property-token, and unquoted-property-token elements support wide character values that have UTF-8 encoding.