Синтаксис фильтра SQL для правил подписки

Статья
08/16/2023

Фильтр SQL — это один из доступных типов фильтров для подписок на разделы служебной шины. Это текстовое выражение, которое является эффективным для подмножества стандарта SQL-92. Выражения фильтра используются с элементом sqlExpression свойства sqlFilter в служебной шине Rule в шаблоне Azure Resource Manager или в аргументе --filter-sql-expression команды Azure CLI az servicebus topic subscription rule create, а также в нескольких функциях пакета SDK, которые позволяют управлять правилами подписки. Допустимые выражения показаны в этом разделе.

Служебная шина категории "Премиум" также поддерживает синтаксис селектора сообщений SQL JMS через API JMS 2.0.

<predicate ::=  
      { NOT <predicate> }  
      | <predicate> AND <predicate>  
      | <predicate> OR <predicate>  
      | <expression> { = | <> | != | > | >= | < | <= } <expression>  
      | <property> IS [NOT] NULL  
      | <expression> [NOT] IN ( <expression> [, ...n] )  
      | <expression> [NOT] LIKE <pattern> [ESCAPE <escape_char>]  
      | EXISTS ( <property> )  
      | ( <predicate> )

<expression> ::=  
      <constant>   
      | <function>  
      | <property>  
      | <expression> { + | - | * | / | % } <expression>  
      | { + | - } <expression>  
      | ( <expression> )

<property> :=   
       [<scope> .] <property_name>

Аргументы

<scope> — необязательная строка, указывающая область <property_name>. Допустимые значения — sys или user.
- Значение sys указывает системную область, где <property_name> — любое из свойств сообщения служебной шины, как описано в разделе Сообщения, полезные данные и сериализация.
- Значение user указывает на область действия пользователя, где <property_name> — это ключ нAstraиваемых свойств, которые можно задать для сообщения при отправке в служебную шину.
- Область user является областью по умолчанию, если значение <scope> не указано.

Замечания

Попытка доступа к несуществующему системном свойству является ошибкой, а попытка доступа к несуществующему свойству пользователя не является ошибкой. Вместо этого несуществующее свойство пользователя внутренне оценивается как неизвестное значение. Неизвестное значение обрабатывается особым образом во время вычисления оператора.

property_name

<property_name> ::=  
     <identifier>  
     | <delimited_identifier>  
  
<identifier> ::=  
     <regular_identifier> | <quoted_identifier> | <delimited_identifier>

Аргументы

<regular_identifier> — строка, представленная следующим регулярным выражением:

[[:IsLetter:]][_[:IsLetter:][:IsDigit:]]*

Это любая строка, которая начинается с буквы, после которой идет один или несколько символов подчеркивания, букв или цифр.

[:IsLetter:] — любой символ Юникода, который относится к категории букв Юникода. System.Char.IsLetter(c) возвращает значение true, если c является буквой Юникода.

[:IsDigit:] — любой символ Юникода, который относится к категории десятичных цифр. System.Char.IsDigit(c) возвращает значение true, если c является цифрой Юникода.

<regular_identifier> не может быть зарезервированным ключевым словом.

<delimited_identifier> — любая строка, заключенная в квадратные скобки ([]). Закрывающая квадратная скобка представляется в виде двух закрывающих квадратных скобок. Ниже приведены примеры <delimited_identifier>.

[Property With Space]  
[HR-EmployeeID]

<quoted_identifier> — любая строка, заключенная в двойные кавычки. Двойные кавычки в идентификаторе представляются в виде двух пар двойных кавычек. Мы не рекомендуем использовать заключенные в кавычки идентификаторы, так как их можно легко спутать со строковой константой. По возможности используйте идентификаторы с разделителем. Ниже приведен пример <quoted_identifier>.

"Contoso & Northwind"

pattern

<pattern> ::=  
      <expression>

Замечания

Свойство <pattern> должно быть выражением, которое будет вычисляться как строка. Оно используется в качестве шаблона для оператора LIKE. Оно может содержать следующие подстановочные знаки:

% — любая строка, содержащая ноль или более символов.
_ — любой один символ.

escape_char

<escape_char> ::=  
      <expression>

Замечания

Свойство <escape_char> должно быть выражением, которое будет вычисляться в качестве строки с 1 символом. Оно используется в качестве escape-символа для оператора LIKE.

Например, property LIKE 'ABC\%' ESCAPE '\' соответствует ABC%, а не строке, начинающейся с ABC.

constant

<constant> ::=  
      <integer_constant> | <decimal_constant> | <approximate_number_constant> | <boolean_constant> | NULL

Аргументы

<integer_constant> — строка чисел без кавычек и десятичного разделителя. Значения хранятся в виде System.Int64 внутри системы и попадают в тот же диапазон.

Ниже приведены примеры длинных констант.
```
1894  
2  
```
<decimal_constant> — строка чисел без кавычек и с десятичным разделителем. Значения хранятся в виде System.Double внутри системы и попадают в тот же диапазон и точность.

В следующих версиях это число может храниться в другом типе данных для обеспечения поддержки более точной числовой семантики. Поэтому не следует полагаться на тот факт, что базовым типом данных для <decimal_constant> является System.Double.

Ниже приведены примеры констант типа decimal.
```
1894.1204  
2.0  
```
<approximate_number_constant> — число, записанное в экспоненциальном представлении чисел. Значения хранятся в виде System.Double внутри системы и попадают в тот же диапазон и точность. Ниже приведены примеры констант с приближенными числами.
```
101.5E5  
0.5E-2  
```

boolean_constant

<boolean_constant> :=  
      TRUE | FALSE

Замечания

Логические константы представлены в виде ключевого слова TRUE или FALSE. Значения хранятся в виде System.Boolean.

string_constant

<string_constant>

Замечания

Строковые константы заключаются в одинарные кавычки и включают любые допустимые символы Юникода. Одинарная кавычка, внедренная в строковую константу, представляется в виде двух одинарных кавычек.

function

<function> :=  
      newid() |  
      property(name) | p(name)

Замечания

Функция newid() возвращает значение System.Guid, созданное методом System.Guid.NewGuid().

Функция property(name) возвращает значение свойства, на которое указывает name. В качестве значения name может использоваться любое допустимое выражение, возвращающее строковое значение.

Рекомендации

Рассмотрим следующую семантику Sql Filter:

В именах свойств не учитывается регистр.
Во всех сценариях операторы следуют семантике неявного преобразования C#.
Системные свойства — это любые свойства сообщения служебной шины, как описано в разделе Сообщения, полезные данные и сериализация.

Рассмотрим следующую семантику IS [NOT] NULL:
- property IS NULL возвращает значение true, если свойство не существует или его значение равно null.

Семантика оценки свойств

Попытка оценить несуществующее системное свойство вызывает FilterException исключение.
Несуществующее свойство вычисляется внутри системы как неизвестное.

Вычисление неизвестного свойства в арифметических операторах:
Если левая и/или правая часть операнда вычисляется как неизвестная, то результат неизвестный (для бинарных операторов).
Если операнд вычисляется как неизвестный, то результат тоже неизвестный (для унарных операторов).

Неизвестный результат вычисления в двоичных операторах сравнения:
Если левая и/или правая часть операнда вычисляется как неизвестная, то результат неизвестный.

Неизвестный результат вычисления в [NOT] LIKE:
Если любой операнд вычисляется как неизвестный, то результат тоже неизвестный.

Неизвестный результат вычисления в [NOT] IN:
Если левый операнд вычисляется как неизвестный, то результат тоже неизвестный.

Неизвестный результат вычисления в операторе AND:

+---+---+---+---+  
|AND| T | F | U |  
+---+---+---+---+  
| T | T | F | U |  
+---+---+---+---+  
| F | F | F | F |  
+---+---+---+---+  
| U | U | F | U |  
+---+---+---+---+

Неизвестный результат вычисления в операторе OR:

+---+---+---+---+  
|OR | T | F | U |  
+---+---+---+---+  
| T | T | T | T |  
+---+---+---+---+  
| F | T | F | U |  
+---+---+---+---+  
| U | T | U | U |  
+---+---+---+---+

Семантика привязки операторов

Операторы сравнения, такие как >, >=, <, <=, !=, и = следуют той же семантике, что и операторы C#: связываются повышения типов данных и неявные преобразования.
Арифметические операторы, такие как +, -, *, / и % следуют той же семантике, что и операторы C#: связываются повышения типов данных и неявные преобразования.

Примеры

Примеры см. в разделе Примеры фильтров служебной шины.

Синтаксис фильтра SQL для правил подписки

Аргументы

Замечания

property_name

Аргументы

pattern

Замечания

escape_char

Замечания

constant

Аргументы

boolean_constant

Замечания

string_constant

Замечания

function

Замечания

Рекомендации

Семантика оценки свойств

Семантика привязки операторов

Примеры

Следующие шаги

Дополнительные ресурсы