Using -Filter in Graph PowerShell for Microsoft 365

Mastering the -Filter parameter in Graph PowerShell is essential for efficient Microsoft 365 management. In this guide, we'll explore powerful filter techniques to query your M365 tenant with precision. Boost your productivity and streamline your M365 tasks with these expert Graph PowerShell tips.

Basic Syntax

Here’s the basic syntax for -Filter usage: Get-MgUser -Filter "property operator 'value'"

1. Get-MgUser: This cmdlet is used to retrieve user objects from Microsoft 365. You can replace this with other cmdlets depending on the type of object you are querying (e.g., Get-MgGroup for groups).
2. -Filter: This parameter specifies the filtering criteria to narrow down the results based on specific properties.
3. "property operator 'value'": This is the actual filter expression:
• property: The attribute you want to filter on (e.g., displayName, jobTitle, department).
• operator: The comparison operator (e.g., eq for equal, ne for not equal, gt for greater than, lt for less than).
• 'value': The value you are comparing the property against. Always enclose the value in single quotes.

Find Users by Department

To get all users who belong to a specific department, use the -Filter parameter to filter by the department attribute.

Find Users by Job Title

You can filter users based on their job title to find all users who hold a particular position.

Find Users Based On Country

To find all users located in a specific country or region, you can filter by the country attribute.

Find Disabled User Accounts

To find all user accounts that are currently disabled, filter by the accountEnabled attribute.

Find Users Created After a Specific Date

To get users who were created after a certain date, use the createdDateTime attribute with a date filter.

Find Users Based on Sign-in Activity

To find users who haven't signed in for a specific period, use the signInActivity attribute (requires Azure AD Premium P1 or P2 license).

Find Groups by Display Name

To find groups with a specific display name, use the displayName attribute.

Find Users by Mail

To find users by mail, use the mail attribute in your filter.

Frequently Asked Questions

• Can I use any property with the -Filter parameter?

No, only a subset of Microsoft Graph properties support filtering. If you attempt to filter on unsupported properties, you’ll receive a Request_UnsupportedQuery error. Always check the Microsoft Graph documentation for filterable fields.

• How is -Filter different from Where-Object in PowerShell?

-Filter executes the query server-side in Microsoft Graph, returning only the matching objects. In contrast, Where-Object applies filtering locally after all results are retrieved, which can be slower and more resource-intensive.

• Do I need to use quotes in my filter string?

Yes, string values must be enclosed in single quotes (e.g., "department eq 'Finance'"). Missing quotes or using double quotes inside the filter often leads to syntax errors.

• Can I combine multiple conditions in one filter?

Yes, you can chain conditions with and or or. For example:

Get-MgUser -Filter "accountEnabled eq true and startswith(displayName,'A')"

This returns only enabled users whose display name begins with “A”.

Tips for Using Filter with Microsoft Graph PowerShell

• Enclose Values in Single Quotes: Always enclose string values in single quotes within the filter expression to avoid syntax errors.
• Combine Multiple Filters with Logical Operators: You can combine multiple filters using logical operators like and, or, and not to create more complex queries. Example: Get-MgUser -Filter "jobTitle eq 'Manager' or jobTitle eq 'Director'"
• Limit the Data Returned: Combine the -Filter parameter with -Top and -Select to limit and streamline the data returned, making your queries more efficient. Example: Get-MgUser -Filter "department eq 'Sales'" -Top 5 -Select "displayName,jobTitle"
• Test Filters in the Graph Explorer: Use the Microsoft Graph Explorer to test and validate your filter expressions. This can help you refine your queries before using them in PowerShell scripts.
• Stay Updated with Graph API Changes: Keep an eye on updates and changes to the Microsoft Graph API, as new properties and features might affect how you construct your filters.

By following these tips, you'll be able to create more efficient and effective queries using the -Filter parameter in Graph PowerShell, making your Microsoft 365 management tasks smoother and more productive.

Get-MgUser -Filter "accountEnabled eq true and department eq 'HR'"

Suggested Reading: