About WQL

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 from

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.

__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.

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:

Cast the WQL string into a ManagementObjectSearcher
object.

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.

__GENUS : 2

__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

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.

WHERE STATEMENT COMPARISON OPERATORS

Operator Description

<= 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.

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.

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.

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.

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.

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 or ...

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.

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.

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.

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.