You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/azure-web-pubsub/reference-odata-filter.md
+49-19Lines changed: 49 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,27 +47,57 @@ An interactive syntax diagram is also available:
47
47
48
48
The filter syntax is used to filter out the connections matching the filter expression to send messages to.
49
49
50
-
The model for a connection is defined as below:
51
-
52
-
```ts
53
-
{
54
-
connectionId : string,
55
-
userId: string,
56
-
groups: string[]
57
-
}
58
-
```
50
+
Azure Web PubSub supports below identifiers:
51
+
| Identifier | Description | Note | Examples
52
+
| --- | --- | -- | --
53
+
| `userId` | The userId of the connection. | Case insensitive. It can be used in [string operations](#string-operations). | `userId eq 'user1'`
54
+
| `connectionId` | The connectionId of the connection. | Case insensitive. It can be used in [string operations](#string-operations). | `connectionId ne '123'`
55
+
| `groups` | The collection of groups the connection is currently in. | Case insensitive. It can be used in [collection operations](#string-operations). | `'group1' in groups`
59
56
60
-
Identifiers are used to refer to the property value of a connection. 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.
57
+
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](#collection-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.
61
58
62
59
### Boolean expressions
60
+
61
+
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`.
62
+
63
63
The types of Boolean expressions include:
64
64
65
65
- Logical expressions that combine other Boolean expressions using the operators `and`, `or`, and `not`.
66
66
- Comparison expressions, which compare fields or range variables to constant values using the operators `eq`, `ne`, `gt`, `lt`, `ge`, and `le`.
67
67
- 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.
68
-
- 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 the next section.
69
-
70
-
### Operator precedence in filters
68
+
- 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).
69
+
70
+
### Supported operations
71
+
| Operator | Description | Example
72
+
| --- | --- | ---
73
+
| **Logical Operators**
74
+
| `and` | Logical and | `length(userId) le 10 and length(userId) gt 3`
75
+
| `or` | Logical or | `length(userId) gt 10 or length(userId) le 3`
| `ne` | Not equal | `userId ne 'user1'`, </br> `userId ne null`
80
+
| `gt` | Greater than | `length(userId) gt 10`
81
+
| `ge` | Greater than or equal | `length(userId) ge 10`
82
+
| `lt` | Less than | `length(userId) lt 3`
83
+
| `le` | Less than or equal | `'group1' in groups`, </br> `user in ('user1','user2')`
84
+
| **In Operator**
85
+
| `in` | The right operand MUST be either a comma-separated list of primitive values, enclosed in parentheses, or a single expression that resolves to a collection.| `userId ne 'user1'`
86
+
| **Grouping Operator**
87
+
| `()` | Controls the evaluation order of an expression | `userId eq 'user1' or (not (startswith(userId,'user2'))`
88
+
| **String Functions**
89
+
| `string tolower(string p)` | Get the lower case for the string value | `tolower(userId) eq 'user1'` can match connections for user `USER1`
90
+
| `string toupper(string p)` | Get the upper case for the string value | `toupper(userId) eq 'USER1'` can match connections for user `user1`
91
+
| `string trim(string p)` | Trim the string value | `trim(userId) eq 'user1'` can match connections for user ` user1 `
92
+
| `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`
93
+
| `bool endswith(string p0, string p1)` | Check if `p0` ends with `p1` | `endswith(userId,'de')` can match connections for user `user-ab-de`
94
+
| `bool startswith(string p0, string p1)` | Check if `p0` starts with `p1` | `startswith(userId,'user')` can match connections for user `user-ab-de`
95
+
| `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`
96
+
| `int length(string p)` | Get the length of the input string | `length(userId) gt 1` can match connections for user `user-ab-de`
97
+
| **Collection Functions**
98
+
| `int length(collection p)` | Get the length of the collection | `length(groups) gt 1` can match connections in 2 groups
99
+
100
+
### Operator precedence
71
101
72
102
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:
73
103
@@ -81,31 +111,31 @@ If you write a filter expression with no parentheses around its sub-expressions,
81
111
An operator that is higher in the above table will "bind more tightly" to its operands than other operators. For example, `and` is of higher precedence than `or`, and comparison operators are of higher precedence than either of them, so the following two expressions are equivalent:
82
112
83
113
```odata-filter-expr
84
-
length(userId) gt 0 and length(userId) lt 3 or length(userId) gt 7 and length(userId) lt 10
85
-
((length(userId) gt 0) and (length(userId) lt 3)) or ((length(userId) gt 7) and (length(userId) lt 10))
114
+
length(userId) gt 0 and length(userId) lt 3 or length(userId) gt 7 and length(userId) lt 10
115
+
((length(userId) gt 0) and (length(userId) lt 3)) or ((length(userId) gt 7) and (length(userId) lt 10))
86
116
```
87
117
88
118
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:
89
119
90
120
```odata-filter-expr
91
-
not length(userId) gt 5
121
+
not length(userId) gt 5
92
122
```
93
123
94
124
You'll get this error message:
95
125
96
126
```text
97
-
Invalid syntax for 'not length(userId)': Type 'null', expect 'bool'. (Parameter 'filter')
127
+
Invalid syntax for 'not length(userId)': Type 'null', expect 'bool'. (Parameter 'filter')
98
128
```
99
129
100
130
This error happens because the operator is associated with just the `length(userId)` expression, which is of type `null` when `userId` is `null`, and not with the entire comparison expression. The fix is to put the operand of `not` in parentheses:
101
131
102
132
```odata-filter-expr
103
-
not (length(userId) gt 5)
133
+
not (length(userId) gt 5)
104
134
```
105
135
106
136
### Filter size limitations
107
137
108
-
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 hundreds of 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.
138
+
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.
0 commit comments