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.