Share via


2.2.3.6.1.1 Common Expression Syntax

The Filter and OrderBy query options are specified in the data service URI via the common expression syntax defined in following Augmented BNF for query option expressions listing.

 commonExpression = [WSP] (boolCommonExpression / methodCallExpression /
              parenExpression / literalExpression / addExpression /
              subExpression / mulExpression / divExpression /
              modExpression /  negateExpression / memberExpression
              / firstMemberExpression / castExpression / functionCallExpression ) [WSP]
  
 boolCommonExpression = [WSP] (boolLiteralExpression / andExpression /
              orExpression /
              boolPrimitiveMemberExpression / eqExpression / neExpression /
              ltExpression / leExpression / gtExpression /
              geExpression / notExpression / isofExpression/
              boolCastExpression / boolMethodCallExpression  /
              firstBoolPrimitiveMemberExpression / boolParenExpression /
              boolFunctionCallExpression) [WSP]
  
 parenExpression = "(" [WSP] commonExpression [WSP] ")"
  
 boolParenExpression = "(" [WSP] boolCommonExpression [WSP] ")"
  
 andExpression = boolCommonExpression WSP "and" WSP boolCommonExpression
  
 orExpression = boolCommonExpression WSP "or" WSP boolCommonExpression
  
 eqExpression = commonExpression WSP "eq" WSP commonExpression
  
 neExpression = commonExpression WSP "ne" WSP commonExpression
  
 ltExpression = commonExpression WSP "lt" WSP commonExpression
  
 leExpression = commonExpression WSP "le" WSP commonExpression
  
 gtExpression = commonExpression WSP "gt" WSP commonExpression
  
 geExpression = commonExpression WSP "ge" WSP commonExpression
  
 addExpression = commonExpression WSP "add" WSP commonExpression
  
 subExpression = commonExpression WSP "sub" WSP commonExpression
  
 mulExpression = commonExpression WSP "mul" WSP commonExpression
  
 divExpression = commonExpression WSP "div" WSP commonExpression
  
 modExpression = commonExpression WSP "mod" WSP commonExpression
  
 negateExpression = "-" [WSP] commonExpression
  
 notExpression = "not" WSP commonExpression
  
 isofExpression = "isof" [WSP] "("[[WSP] commonExpression [WSP] ","][WSP]
                  stringUriLiteral [WSP] ")"
  
 castExpression = "cast" [WSP] "("[[WSP] commonExpression [WSP] ","][WSP]
                  stringUriLiteral [WSP] ")"
  
 boolCastExpression = "cast" [WSP]
                      "("[[WSP] commonExpression [WSP] ","][WSP]
                      "Edm.Boolean" [WSP] ")"
  
 firstMemberExpression = [WSP] [namespaceQualifiedEnitityType "/"]
                         [lambdaPredicatePrefixExpression]
                         ; A lambdaPredicatePrefixExpression is only defined inside a 
                         ; lambdaPredicateExpression. A lambdaPredicateExpression is required   
                         ; inside a lambdaPredicateExpression.
                         entityNavProperty /
                         ; section 2.2.3.1
                         entityComplexProperty /
                         ; section 2.2.3.1
                         entityProperty /
                         ; section 2.2.3.1
                         entityCollectionProperty
                         ; section 2.2.3.1
  
 firstBoolPrimitiveMemberExpression = [namespaceQualifiedEntityType "/"]entityProperty
                                      ; section 2.2.3.1
  
 memberExpression = commonExpression [WSP]  "/" [WSP] [namespaceQualifiedEntityType "/"]
                    entityNavProperty /      ; section 2.2.3.1
                    entityComplexProperty /      ; section 2.2.3.1
                    entityProperty /    ; section 2.2.3.1
                    entityCollectionProperty  ; section 2.2.3.1
  
 boolPrimitiveMemberExpression = commonExpression [WSP]  "/" [WSP]
                                 [namespaceQualifiedEntityType "/"]entityProperty
                                 ; section 2.2.3.1
  
 literalExpression = stringUriLiteral ; section 2.2.2
           / dateTimeUriLiteral ; section 2.2.2
           / dateTimeOffsetUriLiteral ; section 2.2.2
           / timeUriLiteral ; section 2.2.2 
           / decimalLiteral ; section 2.2.2
           / guidUriLiteral ; section 2.2.2
           / singleLiteral ; section 2.2.2
           / doubleLiteral ; section 2.2.2
           / int16Literal ; section 2.2.2
           / int32Literal ; section 2.2.2
           / int64Literal ; section 2.2.2
           / binaryLiteral ; section 2.2.2
           / nullLiteral ; section 2.2.2
           / byteLiteral ; section 2.2.2
           / fullPointLiteral ; section 2.2.2
           / fullLineStringLiteral ; section 2.2.2
           / fullPolygonLiteral ; section 2.2.2
           / fullGeoCollectionLiteral ; section 2.2.2
           / fullMultiPointLiteral ; section 2.2.2
           / fullMultiLineStringLiteral ; section 2.2.2
           / fullMultiPolygonLiteral ; section 2.2.2
  
 boolLiteralExpression = boolLiteral ; section 2.2.2
  
 methodCallExpression = boolMethodCallExpression
                        / indexOfMethodCallExpression
                        / replaceMethodCallExpression
                        / toLowerMethodCallExpression
                        / toUpperMethodCallExpression
                        / trimMethodCallExpression
                        / substringMethodCallExpression
                        / concatMethodCallExpression
                        / lengthMethodCallExpression
                        / yearMethodCallExpression
                        / monthMethodCallExpression
                        / dayMethodCallExpression
                        / hourMethodCallExpression
                        / minuteMethodCallExpression
                        / secondMethodCallExpression
                        / roundMethodCallExpression
                        / floorMethodCallExpression
                        / ceilingMethodCallExpression
                        / distanceMethodCallExpression
                        / geoLengthMethodCallExpression
  
 boolMethodCallExpression = endsWithMethodCallExpression
                        / startsWithMethodCallExpression
                        / substringOfMethodCallExpression
                        / intersectsMethodCallExpression
                        / anyMethodCallExpression
                        / allMethodCallExpression
  
 endsWithMethodCallExpression = "endswith" [WSP]
                                "(" [WSP] commonexpression [WSP]
                                "," [WSP] commonexpression  [WSP] ")"
  
 indexOfMethodCallExpression = "indexof" [WSP]
                               "(" [WSP] commonexpression [WSP]
                               "," [WSP] commonexpression [WSP] ")"
  
 replaceMethodCallExpression =  "replace" [WSP]
                                "(" [WSP] commonexpression [WSP]
                                "," [WSP] commonexpression [WSP]
                                "," [WSP] commonexpression [WSP] ")"
  
 startsWithMethodCallExpression = "startswith" [WSP]
                                  "(" [WSP] commonexpression [WSP]
                                  "," [WSP] commonexpression  [WSP] ")"
  
 toLowerMethodCallExpression = "tolower" [WSP]
                               "(" [WSP] commonexpression [WSP] ")"
  
 toUpperMethodCallExpression = "toupper" [WSP]
                               "(" [WSP] commonexpression [WSP] ")"
  
 trimMethodCallExpression = "trim" [WSP]
                            "(" [WSP] commonexpression [WSP] ")"
  
 substringMethodCallExpression = "substring" [WSP]
                                 "(" [WSP] commonexpression [WSP]
                                 "," [WSP] commonexpression [WSP]
                                 [ "," [WSP] commonexpression  [WSP] ] ")"
  
 substringOfMethodCallExpression = "substringof" [WSP]
                                   "(" [WSP] commonexpression [WSP]
                                   [ "," [WSP] commonexpression [WSP] ] ")"
  
 concatMethodCallExpression = "concat" [WSP]
                              "(" [WSP] commonexpression [WSP]
                              [ "," [WSP] commonexpression [WSP] ] ")"
  
 lengthMethodCallExpression = "length" [WSP]
                              "(" [WSP] commonexpression [WSP] ")"
  
 getTotalOffsetMinutesMethodCallExpression = "gettotaloffsetminutes" [WSP]
                              "(" [WSP] commonexpression [WSP] ")" 
  
 yearMethodCallExpression = "year" [WSP]
                            "(" [WSP] commonexpression [WSP] ")"
  
 monthMethodCallExpression = "month" [WSP]
                             "(" [WSP] commonexpression [WSP] ")"
  
 dayMethodCallExpression = "day" [WSP]
                           "(" [WSP] commonexpression [WSP] ")"
  
 hourMethodCallExpression = "hour" [WSP]
                            "(" [WSP] commonexpression [WSP] ")"
  
 minuteMethodCallExpression = "minute" [WSP]
                              "(" [WSP] commonexpression [WSP] ")"
  
 secondMethodCallExpression = "second" [WSP]
                              "(" [WSP] commonexpression [WSP] ")"
  
 roundMethodCallExpression = "round" [WSP]
                             "(" [WSP] commonexpression [WSP] ")"
  
 floorMethodCallExpression = "floor" [WSP]
                             "(" [WSP] commonexpression [WSP] ")"
  
 ceilingMethodCallExpression = "ceiling" [WSP]
                               "(" [WSP] commonexpression [WSP] ")"
  
 distanceMethodCallExpression = "geo.distance" [WSP]
                                "(" [WSP] commonexpression [WSP]
                                "," [WSP] commonexpression  [WSP] ")"
  
 geoLengthMethodCallExpression = "geo.length" [WSP]
                                 "(" [WSP] commonexpression [WSP] ")"
  
 intersectsMethodCallExpression = "geo.intersects" [WSP]
                                  "(" [WSP] commonexpression [WSP]
                                  "," [WSP] commonexpression  [WSP] ")"
  
 implicitVariableExpression = "$it"
     ; references the unnamed outer variable of the query
  
 lambdaVariableExpression     = *pchar   
     ; section 3.3 of [RFC3986]
     ; a identifier/name that complies with EDM identifier rules
  
 lambdaPredicatePrefixExpression = inscopeVariableExpression  "/"
  
 lambdaPredicateExpression = boolCommonExpression
     ; this is a boolCommonExpression with the added restriction that any 
     ; firstMemberExpression expressions that are inside the methodPredicateExpression
     ; MUST have a prefix of lambdaPredicatePrefixExpression.
  
 inscopeVariableExpression = implicitVariableExpression | lambdaVariableExpression
     ; the lambdaVariableExpression must be the name of a variable introduced by either the 
     ; current lambdaMethodCallExpression’s lambdaVariableExpression or via a wrapping    
     ; lambdaMethodCallExpression’s lambdaVariableExpression.
  
 lambdaMethodCallExpression = anyMethodCallExpression | allMethodCallExpression.
  
 anyMethodCallExpression = pathExpression-collection "/" 
                           "any" 
                           "("  
                           [ lambdaVariableExpression ":" lambdaPredicateExpression ]
                             ")"
  
 allMethodCallExpression = pathExpression-collection "/" 
                           "all" 
                           "("  
                           lambdaVariableExpression ":" lambdaPredicateExpression
                             ")"
  
 singlePathExpression = [WSP]
                        "("singlePathExpression / inscopeVariableExpression  
                        "/" entityNavProperty-et | entityComplexProperty
  
 collectionPathExpression = [WSP] commonexpression [WSP]
                            singlePathExpression / inscopeVariableExpression  
                            "/"
                            (entityNavProperty-es | entityCollectionProperty)
  
 functionCallExpression = [ ( memberExpression / firstMemberExpression ) "/"]
                          functionFQName ; section 2.2.3.1
                          "(" [functionParametersExpression] ")"
  
 boolFunctionCallExpression = functionCallExpression
     ; with the added restriction that the specified FunctionImport
     ; has a ReturnType of Edm.Boolean
  
 functionParametersExpression =
                        functionParameterExpression *( "," functionParameterExpression)
  
 functionParameterExpression = [WSP] 
                               functionParameterName ; section 2.2.3.1
                               [WSP] "=" 
                               [WSP]
                               literalExpression / structuralValue / entityReference
                               [WSP]
  
 structuralValue = ; a JSON or Verbose JSON encoding of a complex type, multi-value,
     ; entity, or collection of entities
  
 entityReference =      "KEY("
                        [ entityContainer "." ] 
                        entitySet 
                        "("keyPredicate")"  
                        ")" 
                        ["/" namespaceQualifiedEntityType ]
                        ; refers a single Entity by key, and optionally allows a cast to a 
                        ; derived type.

Listing: Augmented BNF for Query Option Expressions

A data service MAY<7> support some or all of the boolCommonExpression expressions for the Filter ($filter) system query option. A data service MAY<8> support some or all of the commonExpression expressions for the OrderBy ($orderby) query option.

If a data service does not support a given expression, it MUST reject any requests which contain the unsupported expression.

A data service MAY reject any requests that contain expressions not defined in this document.

Common expressions SHOULD be constructed and evaluated according to the rules defined in common expression syntax for each specific expression type.