Export (0) Print
Expand All
Expand Minimize

about_WQL

Updated: May 8, 2014

Applies To: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0

TOPIC
    about_WQL

SHORT DESCRIPTION
    Describes WMI Query Language (WQL), which can be 
    used to get WMI objects in Windows PowerShell.

LONG DESCRIPTION
    WQL is the Windows Management Instrumentation (WMI)
    query language, which is the language used to get
    information from WMI. 

    You are not required to use WQL to perform a WMI
    query in Windows PowerShell. Instead, you can 
    use the parameters of the Get-WmiObject or 
    Get-CimInstance cmdlets. WQL queries are somewhat 
    faster than standard Get-WmiObject commands and 
    the improved performance is evident when the commands 
    run on hundreds of systems. However, be sure that 
    the time you spend to write a successful WQL query 
    doesn't outweigh the performance improvement.

    The basic WQL statements you need to use WQL are 
    Select, Where, and From.

 
WHEN TO USE WQL
    
    When working with WMI, and especially with WQL, 
    do not forget that you are also using Windows 
    PowerShell. Often, if a WQL query does not work as
    expected, it's easier to use a standard Windows
    PowerShell command than to debug the WQL query.

    Unless you are returning massive amounts of data 
    from across bandwidth-constrained remote systems, 
    it is rarely productive to spend hours trying to 
    perfect a complicated and convoluted WQL query 
    when there is a perfectly acceptable Windows 
    cmdlet that does the same thing, if a bit more
    slowly.


 USING THE SELECT STATEMENT

    A typical WMI query begins with a Select statement
    that gets all properties or particular properties
    of a WMI class. To select all properties of a WMI 
    class, use an asterisk (*). The From keyword 
    specifies the WMI class.

    A Select statement has the following format:

        Select <property> from <WMI-class> 

    For example, the following Select statement selects
    all properties (*) from the instances of the Win32_Bios 
    WMI class.

        Select * from Win32_Bios

    To select a particular property of a WMI class,  
    place the property name between the Select and
    From keywords. 

    The following query selects only the name of 
    the BIOS from the Win32_Bios WMI class. The 
    command saves the query in the $queryName
    variable.

        Select Name from Win32_Bios

    To select more than one property, use commas to
    separate the property names. The following WMI 
    query selects the name and the version of the 
    Win32_Bios WMI class. The command saves the 
    query in the $queryNameVersion variable.

        Select name, version from Win32_Bios


 USING THE WQL QUERY

    There are two ways to use WQL query in Windows
    PowerShell command. 

    -- Use the Get-WmiObject cmdlet
    -- Use the Get-CimInstance cmdlet
    -- Use the [wmisearcher] type accelerator.
    
  USING THE GET-WMIOBJECT CMDLET
    The most basic way to use the WQL query is to enclose
    it in quotation marks (as a string) and then use the 
    query string as the value of the Query parameter of 
    the Get-WmiObject cmdlet, as shown in the following 
    example.

        PS C:\> Get-WmiObject -Query "Select * from Win32_Bios"

        SMBIOSBIOSVersion : 8BET56WW (1.36 )
        Manufacturer      : LENOVO
        Name              : Default System BIOS
        SerialNumber      : R9FPY3P
        Version           : LENOVO – 1360


    You can also save the WQL statement in a variable
    and then use the variable as the value of the Query
    parameter, as shown in the following command.

        PS C:\> $query = "Select * from Win32_Bios"
        PS C:\> Get-WmiObject –Query $query


    You can use either format with any WQL statement.
    The following command uses the query in the 
    $queryName variable to get only the name and 
    version properties of the system BIOS.

        PS C:\> $queryNameVersion = "Select Name, Version from Win32_Bios"
        PS C:\> Get-WmiObject -Query $queryNameVersion
        
        __GENUS          : 2
        __CLASS          : Win32_BIOS
        __SUPERCLASS     :
        __DYNASTY        :
        __RELPATH        :
        __PROPERTY_COUNT : 1
        __DERIVATION     : {}
        __SERVER         :
        __NAMESPACE      :
        __PATH           :
        Name             : Default System BIOS
        Version          : LENOVO - 1360

    Remember that you can use the parameters of the 
    Get-WmiObject cmdlet to get the same result. For
    example, the following command also gets the values 
    of the Name and Version properties of instances of 
    the Win32_Bios WMI class.
    
        PS C:\> Get-WmiObject –Class Win32_Bios -Property Name, Version

        __GENUS          : 2
        __CLASS          : Win32_BIOS
        __SUPERCLASS     :
        __DYNASTY        :
        __RELPATH        :
        __PROPERTY_COUNT : 1
        __DERIVATION     : {}
        __SERVER         :
        __NAMESPACE      :
        __PATH           :
        Name             : Default System BIOS
        Version          : LENOVO - 1360


  USING THE GET-CIMINSTANCE CMDLET

    Beginning in Windows PowerShell 3.0, you can use 
    the Get-CimInstance cmdlet to run WQL queries.

    Get-CimInstance gets instances of CIM-compliant 
    classes, including WMI classes. The CIM cmdlets, 
    introduced Windows PowerShell 3.0, perform the same
    tasks as the WMI cmdlets. The CIM cmdlets comply 
    with WS-Management (WSMan) standards and with the 
    Common Information Model (CIM) standard, which enables 
    the cmdlets to use the same techniques to manage 
    Windows computers and computers that are running 
    other operating systems.
    
    The following command uses the Get-CimInstance    
    cmdlet to run a WQL query. 

    Any WQL query that can be used with Get-WmiObject 
    can also be used with Get-CimInstance.

        PS C:\> Get-CimInstance -Query "Select * from Win32_Bios"

        SMBIOSBIOSVersion : 8BET56WW (1.36 )
        Manufacturer      : LENOVO
        Name              : Default System BIOS
        SerialNumber      : R9FPY3P
        Version           : LENOVO – 1360

    Get-CimInstance returns a CimInstance object, instead of 
    the ManagementObject that Get-WmiObject returns, but 
    the objects are quite similar.

        PS C:\>(Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName
        Microsoft.Management.Infrastructure.CimInstance
        PS C:\>(Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName
        System.Management.ManagementObject


  USING THE [wmisearcher] TYPE ACCELERATOR

    The [wmisearcher] type accelerator creates a 
    ManagementObjectSearcher object from a WQL 
    statement string. The ManagementObjectSearcher 
    object has many properties and methods, but the 
    most basic method is the Get method, which 
    invokes the specified WMI query and returns 
    the resulting objects. 


    By using the [wmisearcher], you gain easy access 
    to the ManagementObjectSearcher .NET Framework class.   
    This lets you query WMI and to configure the way 
    the query is conducted. 

    To use the [wmisearcher] type accelerator:

    1. Cast the  WQL string into a ManagementObjectSearcher 
       object.
    2. Call the Get method of the ManagementObjectSearcher 
       object.


    For example, the following command casts the "select
    all" query, saves the result in the $bios variable,
    and then calls the Get method of the ManagementObjectSearcher
    object in the $bios variable.
 
        PS C:\> $bios = [wmisearcher]"Select * from Win32_Bios"
        PS C:\> $bios.Get()
        
        SMBIOSBIOSVersion : 8BET56WW (1.36 )
        Manufacturer      : LENOVO
        Name              : Default System BIOS
        SerialNumber      : R9FPY3P
        Version           : LENOVO – 1360


    NOTE: Only selected object properties are displayed
    by default. These properties are defined in the 
    Types.ps1xml file.


    You can use the [wmisearcher] type accelerator to 
    cast the query or the variable. In the following 
    example, the [wmisearcher] type accelerator is
    used to cast the variable. The result is the same.

        PS C:\> [wmisearcher]$bios = "Select * from Win32_Bios"
        PS C:\> $bios.Get()
        
        SMBIOSBIOSVersion : 8BET56WW (1.36 )
        Manufacturer      : LENOVO
        Name              : Default System BIOS
        SerialNumber      : R9FPY3P
        Version           : LENOVO – 1360

    When you use the [wmisearcher] type accelerator, it    
    changes the query string into a ManagementObjectSearcher 
    object, as shown in the following commands. 

        PS C:\>$a = "Select * from Win32_Bios"
        PS C:\>$a.GetType().FullName
        System.String

        PS C:\>$a = [wmisearcher]"Select * from Win32_Bios"
        PS C:\>$a.GetType().FullName
        System.Management.ManagementObjectSearcher


    This command format works on any query. The following
    command gets the value of the Name property of the 
    Win32_Bios WMI class.

        PS C:\> $biosname = [wmisearcher]"Select Name from Win32_Bios"
        PS C:\> $biosname.Get()
        
        __GENUS          : 2
        __CLASS          : Win32_BIOS
        __SUPERCLASS     :
        __DYNASTY        :
        __RELPATH        :
        __PROPERTY_COUNT : 1
        __DERIVATION     : {}
        __SERVER         :
        __NAMESPACE      :
        __PATH           :
        Name             : Default System BIOS


    You can perform this operation in a single command,
    although the command is a bit more difficult to 
    interpret.

    In this format, you use the [wmisearcher] type 
    accelerator to cast the WQL query string to a 
    ManagementObjectSearcher, and then call the Get 
    method on the object -- all in a single command.
    The parentheses () that enclose the casted string
    direct Windows PowerShell to cast the string before
    calling the method.

        PS C:\> ([wmisearcher]"Select name from Win32_Bios").Get()

        __GENUS          : 2
        __CLASS          : Win32_BIOS
        __SUPERCLASS     :
        __DYNASTY        :
        __RELPATH        :
        __PROPERTY_COUNT : 1
        __DERIVATION     : {}
        __SERVER         :
        __NAMESPACE      :
        __PATH           :
        Name             : Default System BIOS



 USING THE BASIC WQL WHERE STATEMENT

    A Where statement establishes conditions
    for the data that a Select statement returns.

    The Where statement has the following format:

        where <property> <operator> <value>

    For example:

        where Name = 'Notepad.exe'

    The Where statement is used with the Select
    statement, as shown in the following example.

        Select * from Win32_Process where Name = 'Notepad.exe'

    When using the Where statement, the property name
    and value must be accurate. 

    For example, the following command gets the Notepad    
    processes on the local computer.

        PS C:\> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad.exe'"

    However, the following command fails, because the 
    process name includes the ".exe" file name
    extension.

        PS C:\> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad'"


  WHERE STATEMENT COMPARISON OPERATORS
    The following operators are valid in a
    WQL Where statement.  

    Operator    Description
    -----------------------
    =           Equal
    !=          Not equal
    <>          Not equal
    <           Less than
    >           Greater than
    <=          Less than or equal
    >=          Greater than or equal
    LIKE        Wildcard match
    IS          Evaluates null 
    ISNOT       Evaluates not null
    ISA         Evaluates a member of a WMI class

    There are other operators, but these are the ones
    used for making comparisons. 

    For example, the following query selects the Name  
    and Priority properties from processes in the 
    Win32_Process class where the process priority
    is greater than or equal to 11. The Get-WmiObject 
    cmdlet runs the query. 

        $highPriority = "Select Name, Priority from Win32_Process where Priority >= 11"
        Get-WmiObject -Query $highPriority


  USING THE WQL OPERATORS IN THE FILTER PARAMETER

    The WQL operators can also be used in the value
    of the Filter parameter of the Get-WmiObject or
    Get-CimInstance cmdlets, as well as in the value 
    of the Query parameters of these cmdlets.
 
    For example, the following command gets the Name 
    and ProcessID properties of the last five processes
    that have ProcessID values greater than 1004. The 
    command uses the Filter parameter to specify the 
    ProcessID condition.
    
        PS C:\> Get-WmiObject -Class Win32_Process `
        -Property Name, ProcessID -Filter "ProcessID >= 1004" | 
        Sort ProcessID | Select Name, ProcessID -Last 5
        
        Name                                 ProcessID
        ----                                 ---------
        SROSVC.exe                                4220
        WINWORD.EXE                               4664
        TscHelp.exe                               4744
        SnagIt32.exe                              4748
        WmiPrvSE.exe                              5056


 USING THE LIKE OPERATOR
    The Like operator lets you use wildcard characters
    to filter the results of a WQL query.

    Like Operator  Description
    -------------------------------------------------- 
    []             Character in a range [a-f] or a set 
                   of characters [abcdef]. The items in
                   a set do not need to be consecutive or
                   listed in alphabetical order.

    ^              Character not in a range [^a-f] or 
                   not in a set [^abcdef]. The items in
                   a set do not need to be consecutive or
                   listed in alphabetical order.

    %              A string of zero or more characters
    
    _              One character. 
   (underscore)    NOTE: To use a literal underscore 
                   in a query string, enclose it in 
                   square brackets [_].


    When the Like operator is used without any wildcard 
    characters or range operators, it behaves like the 
    equality operator (=) and returns objects only
    when they are an exact match for the pattern.

    You can combine the range operation with the percent
    wildcard character to create simple, yet powerful 
    filters. 

 
LIKE OPERATOR EXAMPLES

  EXAMPLE 1: [<range>]
    The following commands start Notepad and then
    search for an instance of the Win32_Process
    class that has a name that starts with a letter 
    between "H" and "N" (case-insensitive). 

    The query should return any process from Hotpad.exe 
    through Notepad.exe. 

        PS C:\> Notepad   # Starts Notepad
        PS C:\> $query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'"
        PS C:\> Get-WmiObject -Query $query | Select Name, ProcessID
        
        Name                                ProcessID
        ----                                ---------
        notepad.exe                              1740



  EXAMPLE 2: [<range>] and %
    The following commands select all process
    that have a name that begins with a letter between     
    A and P (case-insensitive) followed by zero or more 
    letters in any combination. 

    The Get-WmiObject cmdlet runs the query, the 
    Select-Object cmdlet gets the Name and ProcessID 
    properties, and the Sort-Object cmdlet sorts the 
    results in alphabetical order by name.

        PS C:\>$query = "Select * from win32_Process where name LIKE '[A-P]%'"
        PS C:\>Get-WmiObject -Query $query | 
                  Select-Object -Property Name, ProcessID | 
                  Sort-Object -Property Name

  EXAMPLE 3: Not in Range (^)
    The following command gets processes whose names
    do not begin with any of the following letters:
    A, S, W, P, R, C, U, N     
    and followed zero or more letters. 

        PS C:\>$query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'"
        PS C:\>Get-WmiObject -Query $query | 
                  Select-Object -Property Name, ProcessID | 
                  Sort-Object -Property Name

  EXAMPLE 4: Any characters -- or none (%)
    The following commands get processes that have 
    names that begin with "calc". The % symbol in
    WQL is equivalent to the asterisk (*) symbol in
    regular expressions.

        PS C:\> $query = "Select * from win32_Process where Name LIKE 'calc%'"
        PS C:\> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID
        
        Name                               ProcessID
        ----                               ---------
        calc.exe                                4424

  EXAMPLE 5: One character (_)
    The following commands get processes that
    have names that have the following pattern,
    "c_lc.exe" where the underscore character
    represents any one character. This pattern
    matches any name from calc.exe through 
    czlc.exe, or c9lc.exe, but does not match 
    names in which the "c" and "l" are separated 
    by more than one character. 

      PS C:\> $query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'"
      PS C:\> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID
        
        Name                                 ProcessID
        ----                                 ---------
        calc.exe                                  4424


  EXAMPLE 6: Exact match
    The following commands get processes named
    WLIDSVC.exe. Even though the query uses the
    Like keyword, it requires an exact match, 
    because the value does not include any 
    wildcard characters.

        $query = "Select * from win32_Process where name LIKE 'WLIDSVC.exe'"
        Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID

        Name                                 ProcessID
        ----                                 ---------
        WLIDSVC.exe                                84


 USING THE OR OPERATOR
    To specify multiple independent conditions, use the Or 
    keyword. The Or keyword appears in the Where clause. It 
    performs an inclusive OR operation on two (or more) 
    conditions and returns items that meet any of the 
    conditions.

    The Or operator has the following format:

        Where <property> <operator> <value> or <property> <operator> <value> ...

    For example, the following commands get all instances
    of the Win32_Process WMI class but returns them
    only if the process name is winword.exe or excel.exe.

        PS C:\>$q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe'"
        PS C:\>Get-WmiObject -Query $q

    The Or statement can be used with more than two 
    conditions. In the following query, the Or statement 
    gets Winword.exe, Excel.exe, or Powershell.exe. 

        $q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe' or Name = 'powershell.exe'"


  USING THE AND OPERATOR
    To specify multiple related conditions, use the And 
    keyword. The And keyword appears in the Where clause. It 
    returns items that meet all of the conditions.
 
    The And operator has the following format:

        Where <property> <operator> <value> and <property> <operator> <value> ...

    For example, the following commands get processes
    that have a name of "Winword.exe" and the process 
    ID of 6512.

    Note that the commands use the Get-CimInstance cmdlet.

        PS C:\>$q = "Select * from Win32_Process where Name = 'winword.exe' and ProcessID =6512"
        PS C:\> Get-CimInstance -Query $q

        ProcessId        Name             HandleCount      WorkingSetSize   VirtualSize
        ---------        ----             -----------      --------------   -----------
        6512             WINWORD.EXE      768              117170176        633028608



    All operators, including the Like operators are
    valid with the Or and And operators. And, you can   
    combine the Or and And operators in a single query
    with parentheses that tell Windows PowerShell which
    clauses to process first.

    This command uses the Windows PowerShell continuation
    character (`) divide the command into two lines.

        PS C:\> $q = "Select * from Win32_Process `
        where (Name = 'winword.exe' or Name = 'excel.exe') and HandleCount > 700"

        PS C:\> Get-CimInstance -Query $q
        ProcessId        Name             HandleCount      WorkingSetSize   VirtualSize
        ---------        ----             -----------      --------------   -----------
        6512             WINWORD.EXE      797              117268480        634425344
        9610             EXCEL.EXE        727               38858752        323227648


  SEARCHING FOR NULL VALUES
    Searching for null values in WMI is challenging, 
    because it can lead to unpredictable results. Null 
    is not zero and it is not equivalent or to an empty 
    string. Some WMI class properties are initialized and 
    others are not, so a search for null might not work 
    for all properties.
 
    To search for null values, use the Is operator with
    a value of "null".

    For example, the following commands get processes 
    that have a null value for the IntallDate property.
    The commands return many processes.

        PS C:\>$q = "Select * from Win32_Process where InstallDate is null"
        PS C:\>Get-WmiObject -Query $q

    In contrast, the following command, gets user
    accounts that have a null value for the Description     
    property. This command does not return any user
    accounts, even though most user accounts do not have
    any value for the Description property.

        PS C:\>$q = "Select * from Win32_UserAccount where Description is null"
        PS C:\>Get-WmiObject -Query $q

    To find the user accounts that have no value for 
    the Description property, use the equality operator 
    to get an empty string. To represent the empty string,
    use two consecutive single quotation marks.

        $q = "Select * from Win32_UserAccount where Description = '' "


  USING TRUE OR FALSE
    To get Boolean values in the properties of WMI
    objects, use True and False. They are not case 
    sensitive.

    The following WQL query returns only local user 
    accounts from a domain joined computer.

        PS C:\>$q = "Select * from Win32_UserAccount where LocalAccount = True"
        PS C:\>Get-CimInstance -Query $q

    To find domain accounts, use a value of False, 
    as shown in the following example.

        PS C:\>$q = "Select * from Win32_UserAccount where LocalAccount = False"
        PS C:\>Get-CimInstance -Query $q


  USING THE ESCAPE CHARACTER
    WQL uses the backslash (\) as its escape
    character. This is different from Windows
    PowerShell, which uses the backtick
    character (`).

    Quotation marks, and the characters used for 
    quotation marks, often need to be escaped so
    that they are not misinterpreted.

    To find a user whose name includes a single quotation 
    mark, use a backslash to escape the single quotation 
    mark, as shown in the following command.

        PS C:\> $q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'"
        PS C:\> Get-CimInstance -Query $q
        Name             Caption          AccountType      SID              Domain
        ----             -------          -----------      ---              ------
        Tim O'Brian      FABRIKAM\TimO    512              S-1-5-21-1457... FABRIKAM

   
    In some case, the backslash also needs to be 
    escaped. For example, the following commands
    generate an Invalid Query error due to the 
    backslash in the Caption value.

        PS C:\> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'"
        PS C:\> Get-CimInstance -Query $q
        Get-CimInstance : Invalid query
        At line:1 char:1
        + Get-CimInstance -Query $q
        + ~~~~~~~~~~~~~~~~~~~~~~~~~
            + CategoryInfo          : InvalidArgument: (:) [Get-CimInstance], CimException
            + FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastructure.CimCmdlets

    To escape the backslash, use a second backslash
    character, as shown in the following command.

        PS C:\> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\\TimO'"
        PS C:\> Get-CimInstance -Query $q



SEE ALSO
    about_Escape_Characters
    about_Quoting_Rules
    about_WMI
    about_WMI_Cmdlets



Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft