Export-CUQuery
    • Dark
      Light
    • PDF

    Export-CUQuery

    • Dark
      Light
    • PDF

    Article Summary

    Introduction

    The Export-CUQuery cmdlet queries the current state of the monitor cluster and exports the results to a CSV or JSON file. The export to a file is what makes the difference between this cmdlet and the Invoke-CUQuery. Use the latter to query a small dataset. If the result set is expected to be higher than 100, as this is the limitation of the Invoke-CUQuery cmdlet, we recommend using the Export-CUQuery cmdlet to reduce the load on the monitor cluster.

    Before using this cmdlet, we recommend reading the Monitor Cluster PowerShell API cmdlets article in which you can learn how to use the new PowerShell cmdlets.

    Prerequisites

    • ControlUp version 8.6.5 or higher
    • At least one ControlUp Monitor installed
    • Permissions to run scripts on the monitor machines

    Syntax

    Export-CUQuery
    [[-OutputFolder] <string>] 
    [[-Scheme] <string>] 
    [-Table] <string> 
    [-Fields] <string[]> 
    [[-Where] <string>] 
    [[-Focus] <string>] 
    [[-Search] <string>] 
    [[-SearchField] <string>] 
    [[-TranslateEnums] <SwitchParameter>] 
    [[-FileName] <string>] 
    [[-FileFormat] <int>] [<CommonParameters>]
    

    Parameters

    OutputFolder

    Defines the folder for the output file. If you do not use this parameter, the current directory is used.

    Parameter Syntax
    Type: String
    Mandatory: no
    Position: 1
    Default value:
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    Scheme

    Scheme is the name of the index the table is queried on. There are several indices for internal use of the cluster. The "Main" index holds all ControlUp entities. If you do not specify a scheme, the Main scheme is used per default.

    Parameter Syntax
    Type: String
    Mandatory: no
    Position: 2
    Default value: Main
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    Table

    Tables are logical containers for ControlUp entities. This parameter is mandatory and you can find all values here.
    The logic is as follows: If you are looking for data pertaining to processes, you should use -table Processes. To retrieve information about monitored sessions, use -table Sessions, etc.

    Parameter Syntax
    Type: String
    Mandatory: yes
    Position: 3
    Default value:
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    Fields

    The fields argument represents the column name of a specific table. Refer to the column reference table in the ControlUp Monitor: PowerShell Cmdlet Overview article to see which arguments you can use in the Fields parameter.

    Another way to see which fields are available for a specific table is to use an asterix (*) after the Fields parameter. For example, to see all the fields of the Computers table, you can use:

    (Invoke-CUQuery -Table Computers -Fields *).Data | get-member -MemberType NoteProperty
    

    SeeAllFields

    Parameter Syntax
    Mandatory: yes
    Position: 4
    Default value:
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    Where

    Use the Where parameters if you want to specify a filter for query results. You can use the following logical operators: OR, AND, NOT. In comparison operators, string values must be enclosed in single quotes.

    Parameter Syntax
    Type: String
    Mandatory: no
    Position: 5
    Default value:
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    Focus

    With the Focus parameter you can define a folder name in your ControlUp organization tree, to show results only from a specific folder. If no value is provided, all objects from your ControlUp organization tree are returned.

    Parameter Syntax
    Type: String
    Mandatory: no
    Position: 6
    Default value:
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    Search

    The Search parameter specifies a filter for text fields. Use an asterix (*) to match a sequence of any characters (including empty string). The Search pattern is case-insensitive.

    Parameter Syntax
    Type: String
    Mandatory: no
    Position: 7
    Default value:
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    SearchField

    If you want to search your result set then using the Search parameters is a great way to do so. If you are using multiple selectors in the Fields parameter then using the Search parameters without SearchField might not be the right choice for your use case. A simple definition: You search for a string (Search argument) in a specific field (SpecificField argument).

    Parameter Syntax
    Type: String
    Mandatory: no
    Position: 8
    Default value:
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    TranslateEnums

    The TranslateEnums parameter converts an enumerator into a human-readable format. In some cases the connection states are shown as integers (e.g. 0 for "Disconnected" or 1 for "Connected").

    Parameter Syntax
    Type: SwitchParameter
    Mandatory: no
    Position: 9
    Default value: False
    Accept pipeline input: false
    Accept wildcard characters: false

    FileName

    Specifies the file name for the export file.

    Parameter Syntax
    Type: String
    Mandatory: no
    Position: 10
    Default value:
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    FileFormat

    Specifies the format of the output file. You can either use “CSV“ or “JSON”.

    Parameter Syntax
    Type: String
    Mandatory: no
    Position: 11
    Default value: 0
    Accept pipeline input: true (ByPropertyName)
    Accept wildcard characters: false

    Examples

    The following examples demonstrate how to use Export-CUQuery. We extend the examples from the Invoke-CUQuery cmdlet with the three parameters specific to the Export-CUQuery cmdlet.

    Example 1 - Get all monitored machines and save result set to specific folder

    (Export-CUQuery -OutputFolder C:\temp -Table Computers -Fields *).Data
    

    This command creates a CSV file that contains information about machines. The OutputFolder parameter defines the location of the exported file. The file that is created is a CSV file with the file name Table_YYYY_MM_DD_HH_mm_ss.csv.

    Example 2 - Get all running monitored processes and save result to a JSON file

    (Export-CUQuery -OutputFolder C:\temp -Table Processes -Fields * -FileName AllProcesses -FileFormat Json).Data
    

    As mentioned above, the only difference between the Invoke-CUQuery and Export-CUQuery commands are the three parameters OutputFolder, FileName and FileFormat. All three are used in this example which exports information about all processes to a AllProcesses.json file in the C:\temp folder.

    Example 3 - Search for a process name and export all information related to this process

    Export-CUQuery -Fields * -Table Processes -FileName ProcessesInfo -Search chrome -SearchField sName
    

    This example illustrates how to search for a string in a particular field. Here, we search for chrome in the sName field in the Processes table. The ProccessInfo.csv file contains data for the results found by this command.

    image.png

    Example 4 - Query all user sessions (without system sessions)

    In this example, all user sessions are exported, excluding system sessions.

    Export-CUQuery -Scheme Main -Table Sessions -Fields iSessionID,sUserAccount -TranslateEnums -Where "sUserAccount!=''"
    

    Was this article helpful?