Merge pull request #219205 from cebundy/web-pubsub-odata-ref

[Web Pub-Sub]: developmental review of odata filter syntax reference

Author: jborsecnik

articles/azure-web-pubsub/reference-odata-filter.md

@@ -10,15 +10,17 @@ ms.date: 11/11/2022
 
 # OData filter syntax in Azure Web PubSub service
 
-In Azure Web PubSub service, the **filter** parameter specifies inclusion or exclusion criteria for the connections to send messages to. This article describes the OData syntax of **filter** and provides examples.
+Azure Web PubSub's **filter** parameter defines inclusion or exclusion criteria for sending messages to connections. This parameter is used in the [Send to all](/rest/api/webpubsub/dataplane/web-pub-sub/send-to-all), [Send to group](/rest/api/webpubsub/dataplane/web-pub-sub/send-to-group), and [Send to user](/rest/api/webpubsub/dataplane/web-pub-sub/send-to-user) operations.
 
-The complete syntax is described in the [formal grammar](#formal-grammar).
+This article provides the following resources:
 
-There is also a browsable [syntax diagram](https://aka.ms/awps/filter-syntax-diagram) that allows you to interactively explore the grammar and the relationships between its rules.
+- A description of the OData syntax of the **filter** parameter with examples.
+- A description of the complete [Extended Backus-Naur Form](#formal-grammar) grammar.
+- A browsable [syntax diagram](https://aka.ms/awps/filter-syntax-diagram) to interactively explore the syntax grammar rules.
 
 ## Syntax
 
-A filter in the OData language is a Boolean expression, which in turn can be one of several types of expression, as shown by the following EBNF ([Extended Backus-Naur Form](https://en.wikipedia.org/wiki/Extended_Backus–Naur_form)):
+A filter in the OData language is boolean expression, which in turn can be one of several types of expression, as shown by the following EBNF ([Extended Backus-Naur Form](https://en.wikipedia.org/wiki/Extended_Backus–Naur_form)) description:
 
 ```
 /* Identifiers */
@@ -35,40 +37,37 @@ boolean_expression ::= logical_expression
                      | '(' boolean_expression ')'
 ```
 
-An interactive syntax diagram is also available:
+An interactive syntax diagram is available at, [OData syntax diagram for Azure Web PubSub service](https://aka.ms/awps/filter-syntax-diagram).
 
-> [!div class="nextstepaction"]
-> [OData syntax diagram for Azure Web PubSub service](https://aka.ms/awps/filter-syntax-diagram)
-
-> [!NOTE]
-> See [formal grammar section](#formal-grammar) for the complete EBNF.
+For the complete EBNF, see [formal grammar section](#formal-grammar) .
 
 ### Identifiers
 
-The filter syntax is used to filter out the connections matching the filter expression to send messages to.
-
-Azure Web PubSub supports below identifiers:
+Using the filter syntax, you can control sending messages to connections matching the identifier criteria.  Azure Web PubSub supports below identifiers:
 
-| Identifier | Description | Note | Examples
-| --- | --- | -- | --
+| Identifier | Description | Note | Examples |
+| --- | --- |--| --
 | `userId` | The userId of the connection. | Case insensitive. It can be used in [string operations](#supported-operations). | `userId eq 'user1'`
 | `connectionId` | The connectionId of the connection. | Case insensitive. It can be used in [string operations](#supported-operations). | `connectionId ne '123'`
 | `groups` | The collection of groups the connection is currently in. | Case insensitive. It can be used in [collection operations](#supported-operations). | `'group1' in groups`
 
-Identifiers are used to refer to the property value of a connection. Azure Web PubSub supports 3 identifiers matching the property name of the connection model. and supports identifiers `userId` and `connectionId` in string operations, supports identifier `groups` in [collection operations](#supported-operations). For example, to filter out connections with userId `user1`, we specify the filter as `userId eq 'user1'`. Read through the below sections for more samples using the filter.
+Identifiers refer to the property value of a connection. Azure Web PubSub supports three identifiers matching the property name of the connection model. and supports identifiers `userId` and `connectionId` in string operations, supports identifier `groups` in [collection operations](#supported-operations). For example, to filter out connections with userId `user1`, we specify the filter as `userId eq 'user1'`. Read through the below sections for more samples using the filter.
 
 ### Boolean expressions
 
-The expression for a filter is a boolean expression. When sending messages to connections, Azure Web PubSub sends messages to connections with filter expression evaluated to `true`.
+The expression for a filter is a boolean expression. Azure Web PubSub sends messages to connections with filter expressions evaluated to `true`.
 
-The types of Boolean expressions include:
+The types of boolean expressions include:
 
-- Logical expressions that combine other Boolean expressions using the operators `and`, `or`, and `not`. 
+- Logical expressions that combine other boolean expressions using the operators `and`, `or`, and `not`. 
 - Comparison expressions, which compare fields or range variables to constant values using the operators `eq`, `ne`, `gt`, `lt`, `ge`, and `le`.
-- The Boolean literals `true` and `false`. These constants can be useful sometimes when programmatically generating filters, but otherwise don't tend to be used in practice.
-- Boolean expressions in parentheses. Using parentheses can help to explicitly determine the order of operations in a filter. For more information on the default precedence of the OData operators, see [operator precedence section](#operator-precedence).
+- The boolean literals `true` and `false`. These constants can be useful sometimes when programmatically generating filters, but otherwise don't tend to be used in practice.
+- Boolean expressions in parentheses. Using parentheses helps to explicitly determine the order of operations in a filter. For more information on the default precedence of the OData operators, see [operator precedence section](#operator-precedence).
 
 ### Supported operations
+
+The filter syntax supports the following operations:
+
 | Operator | Description | Example
 | --- | --- | ---
 | **Logical Operators**
@@ -93,14 +92,14 @@ The types of Boolean expressions include:
 | `string substring(string p, int startIndex)`,</br>`string substring(string p, int startIndex, int length)` | Substring of the string | `substring(userId,5,2) eq 'ab'` can match connections for user `user-ab-de` 
 | `bool endswith(string p0, string p1)` | Check if `p0` ends with `p1` | `endswith(userId,'de')` can match connections for user `user-ab-de` 
 | `bool startswith(string p0, string p1)` | Check if `p0` starts with `p1` | `startswith(userId,'user')` can match connections for user `user-ab-de` 
-| `int indexof(string p0, string p1)` | Get the index of `p1` in `p0`. Returns `-1` if `p0` does not contain `p1`. | `indexof(userId,'-ab-') ge 0` can match connections for user `user-ab-de`
+| `int indexof(string p0, string p1)` | Get the index of `p1` in `p0`. Returns `-1` if `p0` doesn't contain `p1`. | `indexof(userId,'-ab-') ge 0` can match connections for user `user-ab-de`
 | `int length(string p)` | Get the length of the input string | `length(userId) gt 1` can match connections for user `user-ab-de`
 | **Collection Functions**
-| `int length(collection p)` | Get the length of the collection | `length(groups) gt 1` can match connections in 2 groups
+| `int length(collection p)` | Get the length of the collection | `length(groups) gt 1` can match connections in two groups
 
 ### Operator precedence
 
-If you write a filter expression with no parentheses around its sub-expressions, Azure Web PubSub service will evaluate it according to a set of operator precedence rules. These rules are based on which operators are used to combine sub-expressions. The following table lists groups of operators in order from highest to lowest precedence:
+If you write a filter expression with no parentheses around its subexpressions, Azure Web PubSub service will evaluate it according to a set of operator precedence rules. These rules are based on which operators are used to combine subexpressions. The following table lists groups of operators in order from highest to lowest precedence:
 
 | Group | Operator(s) |
 | --- | --- |
@@ -116,7 +115,7 @@ length(userId) gt 0 and length(userId) lt 3 or length(userId) gt 7 and length(us
 ((length(userId) gt 0) and (length(userId) lt 3)) or ((length(userId) gt 7) and (length(userId) lt 10))
 ```
 
-The `not` operator has the highest precedence of all -- even higher than the comparison operators. That's why if you try to write a filter like this:
+The `not` operator has the highest precedence of all, even higher than the comparison operators. If you write a filter like this:
 
 ```odata-filter-expr
 not length(userId) gt 5
@@ -136,7 +135,7 @@ not (length(userId) gt 5)
 
 ### Filter size limitations
 
-There are limits to the size and complexity of filter expressions that you can send to Azure Web PubSub service. The limits are based roughly on the number of clauses in your filter expression. A good guideline is that if you have over 100 clauses, you are at risk of exceeding the limit. We recommend designing your application in such a way that it doesn't generate filters of unbounded size.
+There are limits to the size and complexity of filter expressions that you can send to Azure Web PubSub service. The limits are based roughly on the number of clauses in your filter expression. A good guideline is that if you have over 100 clauses, you are at risk of exceeding the limit. To avoid exceeding the limit, design your application so that it doesn't generate filters of unbounded size.
 
 ## Examples
 
@@ -164,7 +163,7 @@ There are limits to the size and complexity of filter expressions that you can s
 
 ## Formal grammar
 
-We can describe the subset of the OData language supported by Azure Web PubSub service using an EBNF ([Extended Backus-Naur Form](https://en.wikipedia.org/wiki/Extended_Backus–Naur_form)) grammar. Rules are listed "top-down", starting with the most complex expressions, and breaking them down into more primitive expressions. At the top is the grammar rule for `$filter` that correspond to specific parameter `filter` of the Azure Azure Web PubSub service `Send*` REST APIs:
+We can describe the subset of the OData language supported by Azure Web PubSub service using an EBNF ([Extended Backus-Naur Form](https://en.wikipedia.org/wiki/Extended_Backus–Naur_form)) grammar. Rules are listed "top-down", starting with the most complex expressions, then breaking them down into more primitive expressions.  The top is the grammar rule for `$filter` that corresponds to specific parameter `filter` of the Azure Web PubSub service `Send*` REST APIs:
 
 
 ```