Share via

2.2.1.1 WQL Schema and Data Query

  • Article

The syntax for the WQL schema and data queries is provided in Augmented Backus-Naur Form (ABNF).

             
 ; -----------------------------------
 ; WQL schema and data queries
 ; -----------------------------------
  
 DATA-WQL = 
  ("SELECT" <PROPERTY-LIST> "FROM" <CLASS-NAME> 
    <OPTIONAL-SEL-WHERE>)/ 
  ("SELECT" ASTERISK "FROM" <CLASS-NAME> <OPTIONAL-SEL-WHERE>)/ 
  ("SELECT" ASTERISK "FROM META_CLASS" <OPTIONAL-META-WHERE>)/
  ("ASSOCIATORS OF {" <OBJECT-REL-PATH> "}" 
    <OPTIONAL-ASSOC-WHERE>)/
  ("REFERENCES OF {" <OBJECT-REL-PATH> "}" <OPTIONAL-REF-WHERE>)
  
 PROPERTY-LIST = <PROPERTY-NAME> <PROPERTY-LIST2>
 PROPERTY-LIST2 = [COMMA <PROPERTY-LIST>]
  
 OPTIONAL-SEL-WHERE = ["WHERE" <EXPR>]
 OPTIONAL-META-WHERE = ["WHERE __THIS ISA" <CLASS-NAME>]
 OPTIONAL-ASSOC-WHERE = 
  ["WHERE" [ "AssocClass=" <CLASS-NAME> BLANK ] 
  [ "RequiredAssocQualifier=" <QUALIFIER-NAME> BLANK ]
  [ "RequiredQualifier=" <QUALIFIER-NAME> BLANK ]
  [ "ResultClass=" <CLASS-NAME> BLANK ]
  [ "ResultRole=" <PROPERTY-NAME> BLANK ] 
  [ "Role=" <PROPERTY-NAME> BLANK ]
  [ "KeysOnly" BLANK ] 
  [ "ClassDefsOnly" BLANK ]
                        ]
 OPTIONAL-REF-WHERE = 
  ["WHERE" [ "RequiredQualifier=" <QUALIFIER-NAME> BLANK ]
  [ "ResultClass=" <CLASS-NAME> BLANK ]
  [ "Role=" <PROPERTY-NAME> BLANK ]
  [ "KeysOnly" BLANK ] 
  [ "ClassDefsOnly" BLANK ]
                      ] 
  
 OBJECT-REL-PATH = 
  <CLASS-NAME> "=" <TYPED-CONSTANT> <OBJECT-REL-PATH2>
 OBJECT-REL-PATH2 = 
  [COMMA <OBJECT-REL-PATH>]
  
 ; -----------------------------------
 ; Expression
 ; -----------------------------------
  
 EXPR =  
  ( [OPEN-PARENTHESIS] <PROPERTY-EVALUATION> 
     <EXPR2> [CLOSE-PARENTHESIS] ) / 
      ( [OPEN-PARENTHESIS] "__CLASS" <EQUIVALENT-OPERATOR> 
        <CLASS-NAME> <EXPR2> [CLOSE-PARENTHESIS] )
  
 EXPR2 = ( ["OR"  [OPEN-PARENTHESIS] <EXPR> [CLOSE-PARENTHESIS] ])/
         ( ["AND" [OPEN-PARENTHESIS] <EXPR> [CLOSE-PARENTHESIS] ])
  
 PROPERTY-EVALUATION = 
    ( <PROPERTY-NAME> <OPERATOR> <TYPED-CONSTANT> ) / 
     ( <PROPERTY-NAME> <IS-OPERATOR> "NULL" )
  
 OPERATOR = <EQUIVALENT-OPERATOR> /
            <COMPARE-OPERATOR>
  
 EQUIVALENT-OPERATOR = "=" / "!=" / "<>" 
  
 COMPARE-OPERATOR = "<=" / ">=" / "<" / ">" / "LIKE"
 IS-OPERATOR = "IS" / "IS NOT"
  
 ; -----------------------------------
 ; Characters
 ; -----------------------------------
  
 ALPHA = %x41-5A
 DIGIT = %x30-39
 COMMA = ","
 ASTERISK = "*"
 OPEN-PARENTHESIS = "("
 CLOSE-PARENTHESIS = ")"
 BLANK = " " / "\x09"
 DOUBLEUNDERSCORE = %x5f %x5f
  
  
 STRING-IDENTIFIER = ALPHA *(ALPHA / DIGIT / (*("_") ALPHA / DIGIT)) 
  
 CLASS-NAME = [DOUBLEUNDERSCORE] <STRING-IDENTIFIER>
 PROPERTY-NAME = [DOUBLEUNDERSCORE] <STRING-IDENTIFIER>
 QUALIFIER-NAME = <STRING-IDENTIFIER>
  
  
 TYPED-CONSTANT = INT /
                  REAL /
                  UNICODE-STRING / 
                  DATETIME / 
                  BOOL
  
  
 INT = "[-+]?\d+"
 REAL = "[-+]?(\d*\.\d+)|(\d+)"
 STRING = ["]([a-z][A-Z]\d)*["]
 ; DATETIME is specified in section 2.2.1 of [DMTF-DSP0004]
 BOOL = "TRUE" / "FALSE"
  
  
          

Schema objects and keywords

Description

UNICODE-STRING

A string constant with Unicode characters. This string constant is surrounded by ("") or a ('').

CLASS-NAME

Identifies the CIM class name to be queried.

PROPERTY-NAME

Identifies the name of a property of the CIM class.

QUALIFIER-NAME

In the context of a WQL query, QUALIFIER-NAME is an attribute of a PROPERTY-NAME defining the nature of an association with another CIM class. All qualifiers, including any custom-defined qualifier, MUST be supported within the context of a WQL query.

DATA-WQL

A string expressing the WQL query. The WQL string uses different WQL reserved keywords to select the type of information desired.

SELECT

A keyword expressing the selection of information requested (similar to SQL SELECT). SELECT expresses the CIM class or CIM instance to be queried. It MUST be specified when the ASSOCIATORS OF or the REFERENCES OF keyword is not used. It MUST NOT be used when the ASSOCIATORS OF or the REFERENCES OF keyword is used.

PROPERTY-LIST

A list of PROPERTY-NAME values. PROPERTY-NAME values in the list MUST be separated by a comma (",").

ASTERISK

Requires all properties of a CIM class or a CIM instance.

FROM

 A keyword that MUST be specified with the SELECT statement to express the CIM class or CIM instance the query MUST be executed against.

OPTIONAL-SEL-WHERE

The WHERE statement narrows the scope of a SELECT.

OPTIONAL-META-WHERE

The WHERE statement narrows the scope of a SELECT. The WHERE statement followed by the __THIS ISA statement is narrowing the scope of the WQL query to return CIM instances according to the following rule: The only CIM instances returned are the instances of the class CLASS-NAME and all the subclasses in CLASS-NAME's class inheritance hierarchy.

__CLASS

A keyword referring to the CIM object, indicating the class of the current CIM object. The __CLASS keyword in a WHERE clause only selects CIM instances of derived classes made out of the CLASS-NAME.

ASSOCIATORS OF

 A keyword that is a WQL statement to locate associated CIM classes or CIM instances. It MUST NOT be used in combination with the SELECT keyword and the REFERENCES OF keyword.

OPTIONAL-ASSOC-WHERE

If the WHERE statement is specified in an ASSOCIATORS OF WQL query, it narrows the scope to one or several characteristics of the association and associated CIM classes. The filter expression can be made of several specific keywords and expressions to validate these characteristics. Each expression MUST be separated by a BLANK character, as specified in the preceding ABNF notation. Each expression MUST NOT be used more than once in a single WQL query. The keyword supported to narrow the scope of an ASSOCIATORS OF query are AssocClass, RequiredAssocQualifier, RequiredQualifier, ResultClass, ResultRole, Role, KeysOnly, and ClassDefsOnly.

REFERENCES OF

A keyword that is a WQL statement to locate the CIM classes or CIM instances associating CIM classes or CIM instances. It MUST NOT be used in combination with the SELECT keyword and the ASSOCIATORS OF keyword.

OPTIONAL-REF-WHERE

If the WHERE statement is specified in a REFERENCES OF query, it narrows the scope to one or several characteristics of the association and associated classes. The filter expression can be made of several specific keywords and expressions to express these characteristics. Each expression MUST be separated by a BLANK character. Each expression MUST NOT be used more than once in a single WQL query. The keywords supported to narrow the scope of a REFERENCES OF query are RequiredQualifier, ResultClass, Role, KeysOnly, and ClassDefsOnly.

OBJECT-REL-PATH

The CIM relative path of the CIM class or CIM instance to be queried. It MUST be specified for ASSOCIATORS OF and REFERENCES OF queries.

KeysOnly

If the KeysOnly keyword is being used in ASSOCIATORS OF and REFERENCES OF queries, only the key properties of resulting CIM instances MUST be populated.

ClassDefsOnly

If the ClassDefsOnly keyword is being used in ASSOCIATORS OF and REFERENCES OF queries only the CIM class definitions of resulting CIM instances MUST be returned.

AssocClass

If the AssocClass keyword is being used in ASSOCIATORS OF queries, the resulting CIM instances MUST be associated with association class or CIM instances made out of the CLASS-NAME specified.

RequiredAssocQualifier

If the RequiredAssocQualifier keyword is being used in ASSOCIATORS OF queries, the returned CIM instances is associated with the source object through an association class that included the specified qualifier. For example, in the following query:

ASSOCIATORS OF {Win32_LogicalDisk.DeviceID="C:"} WHERE RequiredAssocQualifier = Association

the returned CIM instances is associated with the source object represented by {Win32_LogicalDisk.DeviceID="C:"} through an association class that includes the qualifier "association".

RequiredQualifier

If the RequiredQualifier keyword is being used in ASSOCIATORS OF and REFERENCES OF queries, the resulting CIM instances MUST have the CIM qualifier of the given name set.

ResultClass

If the ResultClass keyword is being used in ASSOCIATORS OF and REFERENCES OF queries, the resulting CIM instances MUST belong to or be derived from the class specified by CLASS-NAME.

Role

If the Role keyword is being used in ASSOCIATORS OF and REFERENCES OF queries, the result MUST only return CIM instances where the role matches the reference CIM property name of the association class.

ResultRole

If the ResultRole keyword is being used in ASSOCIATORS OF queries, the result MUST only return CIM instances where the role matches the reference CIM property name of the CIM instances.

Operator

Description

Applicable Type

=

Test the equivalence of two values.

string, numeric, reference, datetime

!=

Test the negated equivalence of two values.

string, numeric, reference, datetime

>

Test whether the value of the property is greater than that of the typed-constant.

string, numeric, datetime

<

Test whether the value of the property is less than that of the typed-constant.

string, numeric, datetime

>=

Test whether the value of the property is greater than or equal to that of the typed-constant.

string, numeric, datetime

<=

Test whether the value of the property is less than or equal to that of the typed-constant.

string, numeric, datetime

LIKE

Test whether a given character string of the property value matches a specified pattern of the typed-constant. The specified pattern can contain exactly the characters to match, or it can contain meta characters. The table below lists the meta characters. If used with a non-string property, the behavior is the same as the '=' operator, and it tests the equivalence of two values. The use of meta characters mentioned below with a non-string property results in the error WBEM_E_INVALID_QUERY.

string

IS

Test whether the value of the property is null.

string, numeric, reference, datetime, object

IS NOT

Test whether the value of property is not null.

string, numeric, reference, datetime, object

If typed-constant is string, the operator MUST perform a case-insensitive lexicographic relation test.  If the operator is not applicable to the property type, the server MUST return WBEM_E_INVALID_QUERY.

The following characters have special meaning within a LIKE clause:

Character

Description

[

Any one character within a range specified as a sequence of one or more of the following formats, terminated by a "]":

  • A non-caret followed by "-" or "=" followed by any character except the terminating "]" matches any character in a sequential range of characters.  For instance, "[a-f]" or "[a=f]" matches any character from "a" through "f".

  • A non-caret followed by "-" or "=" followed by the terminating "]" matches the two literal characters inside the brackets: the non-caret and the "-" or "=".

  • A caret followed by any character except the terminating "]" matches any character except those in the sequence(s) following the caret, up to the terminating "]". For example, "[^ad-f]" matches anything except an "a", "d", "e", or "f".

  • A caret followed by a closing bracket matches the caret itself: "[^]".

  • Any other character matches the literal character itself.

Note that "%", "_", and "[" serve as literals within a bracketed sequence.

%

Any string of 0 (zero) or more characters. The following example finds all instances where "Win" is found anywhere in the class name: SELECT * FROM meta_class WHERE __Class LIKE "%Win%"

_

Any one character. Any literal underscore used in the query string MUST be escaped by placing it inside [] (square brackets).