Sintaxe de filtro SQL da Regra de Assinatura

  • Artigo

Um filtro SQL é um dos tipos de filtro disponíveis para assinaturas do tópico de Barramento de Serviço. É uma expressão de texto que se baseia em um subconjunto do padrão SQL-92. Expressões de filtro são usadas com o sqlExpressionelemento da propriedade 'sqlFilter' de um Barramento de Serviço Rule em um modelo de Azure Resource Manager, ou o argumento de comando az servicebus topic subscription rule create da CLI do Azure --filter-sql-expression e várias funções de SDK que permitem o gerenciamento de regras de assinatura. As expressões permitidas são mostradas nesta seção.

O Barramento de Serviço Premium também dá suporte à sintaxe de seletor de mensagem JMS SQL por meio da 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>

Argumentos

  • <scope> é uma cadeia de caracteres opcional que indica o escopo do <property_name>. Os valores válidos são sys ou user.
    • O valor sys indica o escopo do sistema em que <property_name> é qualquer uma das propriedades na mensagem do Barramento de Serviço, conforme descrito em Mensagens, cargas e serialização.
    • O valor user indica o escopo do usuário em que <property_name> é uma chave das propriedades personalizadas que você pode definir na mensagem ao enviar para o Barramento de Serviço.
    • O escopo user será o escopo padrão se <scope> não for especificado.

Comentários

Uma tentativa de acessar uma propriedade de sistema inexistente é um erro, enquanto uma tentativa de acessar uma propriedade de usuário inexistente não é um erro. Em vez disso, uma propriedade de usuário inexistente é avaliada internamente como um valor desconhecido. Um valor desconhecido é tratado especialmente durante a avaliação de operador.

property_name

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

Argumentos

<regular_identifier> é uma cadeia de caracteres representada pela seguinte expressão regular:

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

Essa gramática significa qualquer cadeia de caracteres que começa com uma letra e é seguida por um ou mais sublinhados/letras/dígitos.

[:IsLetter:] significa qualquer caractere Unicode categorizado como uma letra do Unicode. System.Char.IsLetter(c) retorna true se c é uma letra do Unicode.

[:IsDigit:] significa qualquer caractere Unicode categorizado como um dígito decimal. System.Char.IsDigit(c) retorna true se c é um dígito do Unicode.

Um <regular_identifier> não pode ser uma palavra-chave reservada.

<delimited_identifier> é qualquer cadeia de caracteres incluída em colchetes esquerdo/direito ([]). Um colchete direito é representado como dois colchetes direitos. Estes são exemplos de <delimited_identifier>:

[Property With Space]  
[HR-EmployeeID]

<quoted_identifier> é qualquer cadeia de caracteres entre aspas duplas. Aspas duplas no identificador são representadas como duas aspas duplas. Não é recomendável usar identificadores entre aspas, porque pode ser confundido facilmente com uma constante de cadeia de caracteres. Use um identificador delimitado, se possível. Aqui está um exemplo e <quoted_identifier>:

"Contoso & Northwind"

pattern

<pattern> ::=  
      <expression>

Comentários

<pattern> deve ser uma expressão avaliada como uma cadeia de caracteres. É usado como um padrão para o operador LIKE. Pode conter os seguintes caracteres curinga:

  • %: qualquer cadeia de zero ou mais caracteres.

  • _: qualquer caractere único.

escape_char

<escape_char> ::=  
      <expression>

Comentários

<escape_char> deve ser uma expressão avaliada como uma cadeia de caracteres de comprimento 1. É usado como um caractere de escape para o operador LIKE.

Por exemplo, property LIKE 'ABC\%' ESCAPE '\' corresponde a ABC%, em vez de a uma cadeia de caracteres que começa com ABC.

constante

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

Argumentos

  • <integer_constant> é uma cadeia de números que não são incluídos em aspas e que não contêm pontos decimais. Os valores são armazenados como System.Int64 internamente e seguem o mesmo intervalo.

    Estes são exemplos de constantes longas:

    1894  
2

  • <decimal_constant> é uma cadeia de números que não são incluídos em aspas e que contêm um ponto decimal. Os valores são armazenados como System.Double internamente e seguem o mesmo intervalo e a mesma precisão.

    Em uma versão futura, esse número poderá ser armazenado em outro tipo de dados para dar suporte à semântica de número exato; portanto, você não deve se basear no fato de que o tipo de dados subjacente é System.Double para <decimal_constant>.

    Estes são exemplos de constantes decimais:

    1894.1204  
2.0

  • <approximate_number_constant> é um número escrito em notação científica. Os valores são armazenados como System.Double internamente e seguem o mesmo intervalo e a mesma precisão. Estes são exemplos de constantes de número aproximado:

    101.5E5  
0.5E-2

boolean_constant

<boolean_constant> :=  
      TRUE | FALSE

Comentários

Constantes boolianas são representadas pelas palavras-chave TRUE ou FALSE. Os valores são armazenados como System.Boolean.

string_constant

<string_constant>

Comentários

Constantes de cadeia de caracteres são incluídas em aspas simples e incluem caracteres Unicode válidos. Uma aspa simples inserida em uma constante de cadeia de caracteres é representada como duas aspas simples.

função

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

Comentários

A função newid() retorna um System.Guid gerado pelo método System.Guid.NewGuid().

A função property(name) retorna o valor da propriedade referenciada por name. O valor name pode ser qualquer expressão válida que retorna um valor de cadeia de caracteres.

Considerações

Considere a seguinte semântica do Filtro SQL:

  • Os nomes de propriedade não diferenciam maiúsculas de minúsculas.

  • Os operadores seguem a semântica de conversão implícita do C# sempre que possível.

  • As propriedades do sistema são qualquer uma das propriedades na mensagem do Barramento de Serviço, conforme descrito em Mensagens, conteúdos e serialização.

    Considere a seguinte semântica de IS [NOT] NULL:

    • property IS NULL é avaliado como true se a propriedade não existe ou se o valor da propriedade é null.

Semântica de avaliação da propriedade

  • Uma tentativa de avaliar uma propriedade de sistema inexistente gera uma exceção FilterException.

  • Uma propriedade que não existe internamente é avaliada como desconhecida.

    Avaliação desconhecida em operadores aritméticos:

  • Em operadores binários, se o lado esquerdo ou direito dos operandos for avaliado como desconhecido, o resultado será desconhecido.

  • Em operadores unários, se um operando for avaliado como desconhecido, o resultado será desconhecido.

    Avaliação desconhecida em operadores de comparação binária:

  • Se o lado esquerdo ou direito dos operandos for avaliado como desconhecido, o resultado será desconhecido.

    Avaliação desconhecida em [NOT] LIKE:

  • Se um operando for avaliado como desconhecido, o resultado será desconhecido.

    Avaliação desconhecida em [NOT] IN:

  • Se o operando esquerdo for avaliado como desconhecido, o resultado será desconhecido.

    Avaliação desconhecida no operador AND:

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

Avaliação desconhecida no operador OR:

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

Semântica de associação do operador

  • Operadores de comparação, como >, >=, <, <=, != e = seguem a mesma semântica que a associação do operador do C# em promoções de tipo de dados e conversões implícitas.

  • Operadores aritméticos, como +, -, *, / e % seguem a mesma semântica que a associação do operador do C# em promoções de tipo de dados e conversões implícitas.

Exemplos

Para ver exemplos, consulte Exemplos de filtro do Barramento de Serviço.

Próximas etapas