PowerShell Basics Level: Beginner Chapter 3: Think in Objects, Not Text

The Filter parameter

The Filter parameter asks the source to do the filtering, before results reach PowerShell. It is often faster than filtering afterwards, but its syntax is not the same as Where-Object.

Lesson 7 of 7 in Chapter 3: Think in Objects, Not Text. Previous step in this path: Custom objects. 3 learning objectives, 6 examples, and a knowledge check.

Start: what you will learn

The Filter parameter asks the source to do the filtering, before results reach PowerShell. It is often faster than filtering afterwards, but its syntax is not the same as Where-Object.

Learning objectives

  • Explain why -Filter can be faster than Where-Object
  • Write a correct -Filter expression
  • Explain when to prefer Where-Object instead

Concept in simple words

What it is: The Filter parameter, written as -Filter, asks the source of the data, such as Active Directory, which is the directory service that stores users and computers on a Windows network, to return only matching items, before the results reach PowerShell. The source does the searching, and PowerShell receives only the matches, rather than receiving everything and throwing most of it away.

Why it works

Why it exists: Without -Filter, every item travels to PowerShell first, and Where-Object then throws most of them away, which wastes time and network traffic. With -Filter, the source does the filtering, so less data travels, and the command often finishes faster, especially when the source holds many items. The saving is largest when the source is remote or very large, and smallest when the list is already tiny and local.

Why it works this way: The source knows its own data and its own search language, so it can search efficiently and return only matches. PowerShell, by contrast, can only filter after it has received the data, because Where-Object works on objects already in PowerShell. So -Filter moves the work to where the data lives, while Where-Object does the work after the data has travelled.

Think of it like this

Think of it like this: Where-Object is like asking a shop to send you every item in stock, and then keeping only the ones you want at home. The -Filter parameter is like telling the shop exactly what you want before it posts anything, so only the matching items arrive. The second way saves postage, time, and sorting at home, but it only works when the shop understands your request in its own language.

How it works, step by step

How it works, step by step: First, check in Get-Help whether the command you are using actually has a -Filter parameter, because not every command has one. For example, Get-ADUser has -Filter, while Get-Service does not offer the same kind of source filter, so for services you filter afterwards with Where-Object. Never assume -Filter exists, check the help for that exact command.

How it works, step by step, continued: Next, write the filter in the language that command expects, not automatically in PowerShell syntax, because filter languages differ between sources. The Active Directory filter language looks similar to PowerShell, with operators such as -eq, -like, -and, and -or, but it is not identical, and some PowerShell operators do not work there. The file system filter for Get-ChildItem is different again, because it uses a wildcard pattern, such as "*.txt", rather than a full expression.

How the Active Directory filter works, in detail: For Active Directory commands, you can use a script block form, such as -Filter { Name -like "Iz*" }, where -like means matches a pattern, and the star means any text after Iz. Or you can use a string form, with the pattern in single quotes inside double quotes, and you should copy the quoting pattern from Get-Help for that command, because the two forms quote differently. In both forms, you write the attribute name directly, such as Name, with no $_, because the filter runs at the source, not on objects already in PowerShell.

How wildcards work in an Active Directory filter: In an Active Directory filter, the star * is the wildcard, meaning any text, including no text. Other PowerShell wildcards, such as ? for a single character, are not supported by the Active Directory filter syntax, so do not copy a ? pattern from a Where-Object test into an Active Directory filter and expect it to work. When you need a single character match in an Active Directory filter, rethink the pattern as a star pattern, or filter the smaller result afterwards with Where-Object.

How quoting and variables work in a filter: In the script block form, you can use a variable as part of the filter, and PowerShell handles the value for you, which is why script block examples are common for Active Directory. In the string form, the whole filter is text, so a value that is text must be quoted inside that text, and a variable placed in a double quoted string without its own quotes can produce a filter the source cannot parse. When a string form filter fails with a parsing error, check the quoting first, and try the script block form as a clearer alternative for that command.

How to combine tests in a filter: Use -and to require both tests to be true, -or to require at least one test to be true, and -not to reverse a test, such as -Filter { Enabled -eq $true -and Name -like "Sa*" }. Here Enabled -eq $true tests the enabled flag, Name -like "Sa*" tests a name pattern, and -and requires both to pass, so only enabled users whose names start with Sa travel back. Build combined filters one test at a time, and test each test on its own before you combine them, so a combined failure is easier to trace.

How to get all items, and how to limit them: Use -Filter * to ask for all items of that type, such as Get-ADUser -Filter * for all users. On a large directory, asking for all items and then keeping only two with Select-Object -First 2 still asks the source for everything first, so it does not save travel. When you only need a few items, use a source limit where the command offers one, such as -ResultSetSize on Get-ADUser, which limits how many results the source returns, rather than filtering after everything has arrived.

How to see properties that are not shown by default: Get-ADUser returns a default set of properties, and other properties are not shown unless you ask for them with -Properties, such as -Properties Department, followed by Select-Object to display the property you asked for. Filtering and displaying are separate steps, because a filter can test an attribute at the source, while -Properties controls which attributes PowerShell shows you afterwards. If a column is missing from your output, check whether you need to add it with -Properties, rather than assuming the data does not exist.

How -Filter differs from -LDAPFilter: Get-ADUser also offers -LDAPFilter, which uses LDAP syntax, a different query language for directory searches, rather than the PowerShell Expression Language used by -Filter. Do not mix the two languages in one parameter, because a filter written for one language will fail or behave differently in the other. For this chapter, use -Filter with the PowerShell style expression, and treat -LDAPFilter as a separate option for when you already have an LDAP query string.

When to use it

When to use Where-Object instead: Use Where-Object instead when there is no -Filter, when the test is complex, when you need a PowerShell only operator such as -match for a regular expression, or when you are working with objects already in PowerShell. Where-Object works on any object, in any pipeline, and it uses full PowerShell syntax, including $_, so it is the flexible fallback when source filtering cannot express your test. A common clean pattern is to filter broadly at the source with -Filter, and then refine the smaller result in PowerShell with Where-Object.

How to work with a filtered result afterwards: Objects returned by a -Filter search are still real objects, so you can pipe them to Select-Object to keep only some properties, to Sort-Object to order them, or to Where-Object for a second, more detailed test. Source filtering does not change the kind of result, it only changes how much data travels to reach you, so every pipeline skill from earlier in this chapter still applies after a -Filter step.

What you need before Get-ADUser works: Get-ADUser comes from the Active Directory module, and it needs access to a directory to search. On a computer without that module, or without directory access, the command will not be found or will not return directory users, and that is an environment issue, not a filter syntax issue. If you see a command not found message, check the module and the environment first, before you rewrite a filter that may already be correct. The filter examples in this lesson assume a directory environment where Get-ADUser is available.

Common mistakes, in plain words: The most common mistake is using PowerShell comparison syntax inside a -Filter string without checking that command filter language, because the two languages are not always the same. Another is assuming -Filter exists on every command, when many commands offer no source filter at all. A third is writing $_ inside an Active Directory filter, when the filter uses attribute names directly and runs at the source, not on pipeline objects. A fourth is using -match or a ? wildcard in an Active Directory filter, when neither is supported there. A fifth is filtering after retrieving everything, when a source filter could have saved the travel. A sixth is forgetting that a missing column may need -Properties, rather than meaning the data does not exist.

How to spot a filter problem: If a -Filter command returns nothing, check the attribute name with Get-Help, check the wildcard, and test a broader filter, such as -Filter *, to confirm the command works at all. If a filter gives a parsing error, check the quoting, and try the script block form. If a filter works but a column is missing, add that property with -Properties. If a test works with Where-Object but fails with -Filter, check whether the operator or the pattern is supported by that source filter language.

Worked examples

Read each example in order. Each one explains its parts, then shows what to look for in the output.

Syntax

Syntax
Get-ADUser -Filter { Name -like "Iz*" }

Example 1

Asks Active Directory for users whose name starts with Iz. Only matches travel back.

Example 1
Get-ADUser -Filter { Name -like "Iz*" }

Illustrative output: Name ---- Izaz

Example 2

When no -Filter exists, filter afterwards with Where-Object. This works on any object.

Example 2
Get-Process | Where-Object { $_.Name -like "pw*" }

Illustrative output: Name ---- pwsh

Example 3

This is the string form of the same kind of filter, for use in an Active Directory environment. The whole filter is in double quotes, and the pattern is in single quotes inside those double quotes. Name is the property, -like means matches a pattern, and Sa* means a name starting with Sa, so only matching users are returned by the source.

Example 3
Get-ADUser -Filter "Name -like 'Sa*'"

Illustrative output: Name ---- Sam

Example 4

This shows that -Filter does not mean the same thing on every command. For Get-ChildItem, -Filter is a file system wildcard pattern, not an Active Directory expression, so "*.txt" means any file name ending in .txt, and there is no attribute name or -like operator here. The pipe then keeps only the first three names, so you see a short list instead of every matching file.

Example 4
Get-ChildItem -Filter "*.txt" | Select-Object -First 3 Name

Illustrative output: Name ---- notes.txt report.txt todo.txt

Example 5

This combines two tests at the source with -and, so both must pass. Enabled -eq $true tests the enabled flag, Name -like "Sa*" tests a name starting with Sa, and only users passing both tests travel back. Select-Object then keeps only the Name and Enabled columns for display, so you can confirm both parts of the test in the output.

Example 5
Get-ADUser -Filter { Enabled -eq $true -and Name -like "Sa*" } | Select-Object Name, Enabled

Illustrative output: Name Enabled ---- ------- Sam True

Example 6

The star filter asks for all users, but -ResultSetSize 2 limits the result at the source to two users, so the source does not need to return the whole directory. Select-Object then keeps only the Name column. Use a source limit like this when you only need a few items for a check, rather than retrieving everything and keeping two afterwards.

Example 6
Get-ADUser -Filter * -ResultSetSize 2 | Select-Object Name

Illustrative output: Name ---- Izaz Sam

Nothing on this page executes PowerShell code. The outputs above are illustrative only.

Common mistakes and troubleshooting

Read these before you try the examples, so you can spot the same problems in your own work.

  • Using PowerShell comparison syntax inside a -Filter string without checking that command filter language. They are not always the same.
  • Assuming -Filter exists on every command. Check Get-Help for that command first.
  • Copying PowerShell comparison syntax into a -Filter string without checking that command filter language, when the two languages are not always the same.
  • Writing $_ inside an Active Directory filter, when the filter uses attribute names directly and runs at the source, not on pipeline objects.
  • Using -match or a ? wildcard in an Active Directory filter, when neither is supported by that filter language. Use -like with a star pattern at the source, or refine with Where-Object afterwards.
  • Forgetting that a missing column may need -Properties on Get-ADUser, rather than meaning the data does not exist.

Knowledge check

Knowledge check

Why can -Filter be faster than Where-Object?

Pick one answer. Feedback appears right away, and you can try again.

Remember this and next step

Remember this: -Filter filters at the source so less data travels, its syntax depends on the command, the Active Directory filter uses attribute names directly with no $_, only the star wildcard is supported there, -match does not work in an Active Directory filter, the script block form and the string form quote differently, -Filter * asks for all items, -ResultSetSize can limit results at the source, -Properties adds properties that are not shown by default, and Where-Object is the right tool when -Filter does not exist or cannot express your test.

Next step: Select-Object, Where-Object, and Sort-Object