M365 PowerShell

Master Microsoft Graph Filter Query Parameter in PowerShell

This guide explores the Filter query parameter in Microsoft Graph PowerShell. Learn how to create refined queries to retrieve specific data efficiently using practical examples and tips.

The filter query parameter in Graph PowerShell is used to specify conditions for filtering the data returned from Microsoft Graph API requests. This is part of the OData query options, which allow for more precise queries by restricting the results to those that meet certain criteria.

When using PowerShell to interact with Microsoft Graph, the -Filter query can be applied in cmdlets to perform operations such as retrieving, updating, or deleting resources based on specific conditions.

Basic Syntax

The -Filter parameter typically expects a string that specifies the filter conditions. These conditions can include comparisons like equality, non-equality, greater than, and less than. Here’s the basic syntax: Get-<Resource> -Filter "Property Operator 'Value'"

Get Users by Job Title

To retrieve users whose job title is "Software Developer", you should pass the Software Developer value to the jobTitle -Filter query parameter of the Get-MgUser cmdlet.

Get Users in a Specific Department and Location

To find users who are in the "HR" department and located in "New York", you should pass "HR" value to the department filter parameter and "New York" value to the city filter query parameter.

Using filter with startsWith

To find users with similar display names you need to pass the DisplayName parameter to the startswith function along with the alphabets of users you are searching for.

Combining multiple conditions using AND operator

You can combine multiple conditions using AND operator. For example, you can search for active users (condition 1) in the country United States (condition 2) by executing this command.

Retrieve users with specific license

You can use -Filter parameter with the Microsoft Graph PowerShell SDK to retrieve users from Microsoft Graph API who have a specific license assigned to them. The command you should execute is shown below. (Note: To execute the command you should know the license ID assigned. Get-MgSubscribedSKU is the cmdlet that fetches all available license IDs within your tenant. You should select the license ID you are interested in and pass it to the -Filter).

Command Breakdown

Cmdlet: Get-MgUser

This is the cmdlet used to fetch user information from Microsoft Graph. It can retrieve one or more user objects from Azure Active Directory.

-Filter

This parameter allows you to specify an OData filter expression that restricts the results returned by the query. It's used to filter the users based on various properties associated with their Microsoft Graph user profile.

Filter Expression: "assignedLicenses/any(s:s/skuId eq c42b9cae-ea4f-4ab7-9717-81576235ccac)"

assignedLicenses/any(s: s/skuId eq 'GUID'): This part of the filter expression uses a lambda operator any. Here's what each part means:

assignedLicenses: This is a collection property on the user object that contains information about the licenses assigned to the user.
any(s: ...): This is a lambda operator used in OData queries to filter on collection properties. It returns true if any element in the collection satisfies the condition specified within the lambda function.
s: This is a lambda variable that represents an individual element within the assignedLicenses collection. It's used as a placeholder to refer to each item in the collection as the filter is applied.
s/skuId: This navigates to the skuId property of each assignedLicense object in the collection. The skuId is a unique identifier for the license type.
eq: This is the equality operator used to compare the skuId of each license to the specified GUID.
c42b9cae-ea4f-4ab7-9717-81576235ccac: This is the GUID of the license SKU you're filtering on. It specifies the exact license type you are interested in.

This command is particularly useful in large organizations where administrators need to identify which users have been assigned a specific license, perhaps as part of compliance checks, licensing audits, or simply to manage license allocations more effectively. By using this command, you can quickly filter out all users who have a particular license, making it easier to manage and report on license usage within the organization.

Notes

The properties you can filter on and the operators you can use depend on the Microsoft Graph API and the specific resource you are querying.
Some properties might not be filterable, and attempting to filter on them can result in errors.
The syntax and capabilities may vary slightly based on updates to the API and the specific version of the PowerShell SDK you are using.
Read Microsoft Documentaton on -Filter Query for more info.

Using the -Filter parameter effectively can help you narrow down API responses to just the relevant data, making your scripts more efficient and easier to manage.

Frequently Asked Questions

What is the Filter query parameter used for?
The Filter query parameter is used in Microsoft Graph PowerShell to refine queries by specifying conditions. It allows retrieving only the data that meets the defined criteria.
How can I filter users by their account status?
You can filter users by their account status using the -Filter parameter. Example:
```
Get-MgUser -Filter "accountEnabled eq true"
```
Can I combine multiple conditions in a filter query?
Yes, you can use logical operators like and or or to combine multiple conditions. Example:
```
Get-MgUser -Filter "accountEnabled eq true and userType eq 'Member'"
```
How can I filter groups based on their display name?
Use the -Filter parameter with the displayName property to filter groups. Example:
```
Get-MgGroup -Filter "startsWith(displayName, 'Team')"
```

Script With -Filter Query

To further understand how -Filter query works, check out this script that implements -Filter query. The script filters for guest users and checks (and outputs) their invitation status.

⚠️ Filter Only Works on Server-Supported Properties

The -Filter parameter works only on properties explicitly supported by the Microsoft Graph API for filtering. Trying to filter on unsupported properties (like nested objects or computed fields) will result in errors such as Request_UnsupportedQuery.

🔍 eq, ne, startswith Are Commonly Used Operators

When building filter expressions, operators like eq (equals), ne (not equals), and startswith are the most commonly supported. Refer to the Microsoft Graph OData docs for a complete list of supported expressions per entity.