サブスクリプションルールの SQL フィルター構文

[アーティクル]
10/23/2023

"SQL フィルター" は、Service Bus トピックサブスクリプションで使用できるフィルターの種類の 1 つです。これは、SQL-92 標準のサブセットに基づくテキスト式です。フィルター式は、Azure Resource Manager テンプレート内の Service Bus Rule の 'sqlFilter' プロパティの sqlExpression 要素、Azure CLI az servicebus topic subscription rule create コマンドの --filter-sql-expression 引数、とサブスクリプションルールの管理を可能にするいくつかの SDK 関数と共に使われます。このセクションでは、使用できる式が示されています。

Service Bus Premium では、JMS 2.0 API を介して JMS SQL メッセージセレクター構文もサポートされています。

<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> は「メッセージ、ペイロード、およびシリアル化」で説明されている Service Bus メッセージのプロパティのいずれかです。
- user 値はユーザースコープを示します。ここで、<property_name> は Service Bus に送信するときにメッセージに設定できるカスタムプロパティのキーです。
- <scope> が指定されていない場合、user スコープが既定のスコープです。

解説

存在しないシステムプロパティにアクセスしようとするとエラーになりますが、存在しないユーザープロパティにアクセスしようとしてもエラーにはなりません。代わりに、存在しないユーザープロパティは不明な値として内部的に評価されます。不明な値は演算子の評価時に特別に処理されます。

property_name

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

引数

<regular_identifier> は、次の正規表現で表される文字列です。

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

これは、文字で始まり、その後に 1 つ以上のアンダースコア/文字/数字が続くことを意味します。

[:IsLetter:] は、Unicode の文字として分類される任意の Unicode 文字を表します。 c が Unicode の文字の場合、System.Char.IsLetter(c) は true を返します。

[:IsDigit:] は、10 進数として分類される任意の Unicode 文字を表します。 c が Unicode の数字の場合、System.Char.IsDigit(c) は true を返します。

<regular_identifier> に予約キーワードを指定することはできません。

<delimited_identifier> は、左右の各かっこ ([]) で囲まれた任意の文字列です。右角かっこは 2 つの右角かっこで表されます。 <delimited_identifier> の例を次に示します。

[Property With Space]  
[HR-EmployeeID]

<quoted_identifier> は、二重引用符で囲まれた任意の文字列です。識別子の二重引用符は 2 つの二重引用符で表されます。引用符で囲まれた識別子は、文字列定数と混同されやすい可能性があるので使用しないことをお勧めします。可能であれば、区切られた識別子を使用してください。こちらに <quoted_identifier> の例を示します。

"Contoso & Northwind"

pattern

<pattern> ::=  
      <expression>

解説

<pattern> は、文字列として評価される式である必要があります。これは LIKE 演算子のパターンとして使用されます。次のワイルドカード文字を含めることができます。

%: 0 個以上の文字で構成される任意の文字列。
_: 1 つの任意の文字。

escape_char

<escape_char> ::=  
      <expression>

解説

<escape_char> は、長さ 1 の文字列として評価される式である必要があります。これは、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 であることに依存しないでください。

10 進定数の例を次に示します。
```
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>

解説

文字列定数は単一引用符で囲まれ、任意の有効な Unicode 文字が含まれます。文字列定数に組み込む単一引用符は、2 つの単一引用符で表されます。

関数 (function)

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

解説

newid() 関数は、System.Guid.NewGuid() メソッドによって生成された System.Guid を返します。

property(name) 関数は、name によって参照されるプロパティの値を返します。 name 値には、文字列値を返す任意の有効な式を指定できます。

考慮事項

次の SQL フィルターセマンティクスを考慮してください。

プロパティ名では大文字と小文字が区別されます。
可能であれば、演算子は C# の暗黙的な変換セマンティクスに従います。
システムプロパティは、「メッセージ、ペイロード、およびシリアル化」で説明されている Service Bus メッセージのプロパティのいずれかです。

次の IS [NOT] NULL セマンティクスを考慮してください。
- プロパティが存在しないか、プロパティの値が null の場合、property IS NULL は true として評価されます。

プロパティ評価セマンティクス

存在しないシステムプロパティを評価しようとすると、FilterException 例外がスローされます。
存在しないプロパティは、内部的に unknown として評価されます。

算術演算子での unknown 評価は次のとおりです。
2 項演算子では、左側または右側のオペランドが unknown と評価された場合、結果は unknown になります。
単項演算子では、オペランドが unknown と評価された場合、結果は unknown になります。

2 項比較演算子での unknown 評価は次のとおりです。
左側または右側のオペランドが unknown と評価された場合、結果は unknown になります。

[NOT] LIKE での unknown 評価は次のとおりです。
いずれかのオペランドが unknown と評価された場合、結果は unknown になります。

[NOT] IN での unknown 評価は次のとおりです。
左側のオペランドが unknown と評価された場合、結果は unknown になります。

AND 演算子での unknown 評価は次のとおりです。

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

OR 演算子での unknown 評価は次のとおりです。

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

演算子結合セマンティクス

比較演算子 (>、>=、<、<=、!=、= など) は、データ型の上位変換および暗黙的な変換で C# 演算子の結合と同じセマンティクスに従います。
算術演算子 (+、-、*、/、% など) は、データ型の上位変換および暗黙的な変換で C# 演算子の結合と同じセマンティクスに従います。

例

例については、Service Bus フィルターの例を参照してください。

次の方法で共有

サブスクリプションルールの SQL フィルター構文

引数

解説

property_name

引数

pattern

解説

escape_char

解説

定数 (constant)

引数

boolean_constant

解説

string_constant

解説

関数 (function)

解説

考慮事項

プロパティ評価セマンティクス

演算子結合セマンティクス

例

次のステップ

フィードバック

その他のリソース

次の方法で共有

サブスクリプション ルールの SQL フィルター構文

引数

解説

property_name

引数

pattern

解説

escape_char

解説

定数 (constant)

引数

boolean_constant

解説

string_constant

解説

関数 (function)

解説

考慮事項

プロパティ評価セマンティクス

演算子結合セマンティクス

例

次のステップ

フィードバック

その他のリソース

サブスクリプションルールの SQL フィルター構文