about_Pfa2Filtering.help.txt

TOPIC
    about_Pfa2Filtering

SHORT DESCRIPTION
    Describes how the Pure Storage PowerShell SDK cmdlets support filtering to narrow down results.

LONG DESCRIPTION
    The Pure Storage PowerShell SDK supports filtering for various methods that might return multiple objects. The filter query parameter narrows down the results of a request to only the response objects that satisfy the filter criteria. Cmdlets that support filtering expose the -Filter parameter that takes a string representing the filter criteria.
    
    FILTERING WITH OPERATORS
    
    The Pure Storage PowerShell SDK filter parameter supports common comparison operators.

    Syntax: -Filter <field_name> <operator> <field_value> 

        field_name
            Name of the field on which to create the filter. Field_name can be any of the fields in the response. 
        
        operator
            Type of filter match used to compare <field_name> to <field_value>.
            
        field_value
            Search value (number, date, or string) that determines the fields to be included in or excluded from the response. Literal strings must be wrapped in quotes. To refine the filter, include the asterisk (*) symbol as a wildcard character in the field value to represent zero or more characters. Field_value can include multiple asterisks, and the asterisks can appear anywhere in the value. For example, the filter name='*cat*' lists all hosts with names that contain cat, including ones that begin or end with cat, such as cat, catnap, happycats, and lolcat. If the asterisks were not included, only the host named cat would be returned.
  
    Filters support the following operators:
        =
            Example: Get a list of all volumes with volume names that include v1.
                Get-Pfa2Volume $arr -Filter "name='*v1*'"
        !=
            Example: Get a list of all volumes with volume names that do not include v1.
                Get-Pfa2Volume $arr -Filter "name!='*v1*'"
        <
            Example: Get a list of all volumes that are less than 100 gigabytes in size.
                Get-Pfa2Volume $arr -Filter size<107374182400
        >
            Example: Get a list of all volumes that were created after 2016-04-25T23:02:23Z.
                Get-Pfa2Volume $arr -Filter "created>'2016-04-25T23:02:23Z'"
        <=
            Example: Get a list of all volumes that were created on or before 2016-04-25T23:02:23Z.
                Get-Pfa2Volume $arr -Filter "created<='2016-04-25T23:02:23Z'"
        >=
            Example: Get a list of all volumes that are greater than or equal to 100 gigabytes in size.
                Get-Pfa2Volume $arr -Filter size>=107374182400

    All comparison operators are case-insensitive


    FILTERING WITH FUNCTIONS
    
    The Pure Storage PowerShell SDK filter parameter supports the CONTAINS and NOT functions.
    
    Syntax: -Filter function(parameters)
    
    Filters support the following functions:

        contains(<field_name<,<string>)
            Description: Contains the enclosed string. Takes exactly two parameters, where field_name represents the name of the field on which to create the filter, and string represents the string to search within field_name.
            Example: Get a list of all host groups with names that include cluster02.
                Get-Pfa2Volume $arr -Filter "contains(hgroup,'cluster02')"

        not(<expression>)
            Description: Inverse of the enclosed expression.
            Example: Get a list of all host groups with names that do not include cluster02.
                Get-Pfa2Volume $arr -Filter "not(hgroup='cluster02')"


    FILTERING WITH EXISTENCE CHECKS
    
    PureStoragePowerShellSDK filter parameter supports existence checks. For example, the operation Get-Pfa2Volume $arr -Filter "source" returns volumes where the "source" exists for the volume.
                
EXAMPLES

    Example 1: Get the volume with serial number 31F52075433543110001103F.
        Get-Pfa2Volume $arr -Filter "serial='31F52075433543110001103F'"

    Example 2: Get a list of hosts that are associated with host group ESXi-IT-Cluster02-hg2.
        Get-Pfa2Host $arr -Filter "hgroup='ESXi-IT-Cluster02-hg2'"

    Example 3: Get a list of all Fibre Channel ports on controller ct0.
        Get-Pfa2Volume $arr -Filter "name='ct0.fc*'"

    Example 4: Get a list of all volumes that have been destroyed and will be eradicated within the next 2 hours (7200 seconds).
        Get-Pfa2Volume $arr -Filter "time_remaining<=7200"

    Example 5: Get a list of all hosts that are associated with host groups that include hg3 in the host group name. 
        Get-Pfa2Host $arr -Filter "contains(hgroup,'hg3')"

    Example 6: Get a list of all volumes with names that do not include vol01.
        Get-Pfa2Volume $arr -Filter "not(contains(name,'vol01'))"
        
    Example 7: Get a list of all hosts that are associated with a host group.
        Get-Pfa2Host $arr -Filter "hgroup"

    Example 8: Get a list of all volumes that were not created from another source.
        Get-Pfa2Volume $arr -Filter "not(source)"
        
KEYWORDS


SEE ALSO
    See the "Sorting, Filtering, and Pagination" section of the FlashArray REST API guide.