Saved queries

Query language expressions can be saved as Saved queries, and either kept for personal use or shared with the wider organization. Queries can be developed with the streamlined interface of Query Builder in IPLM Web or configured directly using query language.

Saved query overview

Query expressions can be captured for quick reuse as Saved queries. Saved queries can be created and used from IPLM Web, PiCLI and the API. By default Saved queries are only available to the user that created them, but they can be optionally shared by an admin with other users.

Saved query configuration fields

Configuration Option	Required	Description
name	Required	The name of the query
description	Optional	Description of the query
shared	Optional	True: Query is visible to all users False: Query is only visible to Creator Only Admin users can share queries. By default, queries are not shared
query	Required	The query expression
icon	Optional	Icon for display in IPLM Web

Saved query access controls

Saved queries are only visible to the user that creates them, unless they get 'shared' by an admin. Once they are shared any user in the system can use them to run queries, but only an admin can edit or delete a shared query.

Saved query naming restrictions

The following restrictions apply to Saved queries:

Saved query names cannot contain any Unix special characters, '/', '\', '*', '?' or white-space
The max length of a query description is 1000 characters
The max length of the query language string is 1000 characters

Managing Saved queries on IPLM Web

Saved queries are created, edited, and run on IPLM Web from the Advanced search page, available under the Catalogs->Advanced search menu item on the top menu bar. Queries created and saved from IPLM Web are available from PiCLi and vice versa. Queries can be saved in both query and Query Builder mode.

Saved query in Query Builder

Saved query in query mode

Creating queries

Queries can be constructed by selecting the desired search fields through the Query Builder interface, or entered directly into the search box in the Query interface. Note that IPLM Web supports queries for IP and IP Version (IPV) object types only. Examples of IP and IPV queries can be found in the Querying IPs in the System section. Queries for other types of objects can be run from PiCLI or the API.

Note: IPLM Web supports queries for IP and IP Version (IPV) object types only.

Adding, editing, and deleting Saved queries

Query expressions can be saved as Saved queries for future use by entering a name for the query and clicking Save. Once saved, the query appears on the left sidebar. Queries created from IPLM Web are not shared, Admins can share them via the pi query edit command from PiCLI.

To edit a Saved query, select the existing Saved query on the left sidebar, make the desired edits, and then click Save.

Note: If a Saved query is shared, only an admin can edit or delete it.

Organizing Saved queries with query folders in IPLM Web

Admins can group Saved queries in query folders on IPLM Web. To create a new query folder, open Administration->Query folders and select Create new folder.

Enter a name and description for the Query folder. Use the + button to add Saved queries to the query folder. Users can also add Saved queries that have been shared by the Admin to folders.

Use the + button to add Saved queries that have been shared by the Admin to the query folder. Once configured, select Save.

The Query folder is now visible from the Advanced search page. The built in Query folder Shared shows shared Saved queries and Mine shows the logged in user's Saved queries.

Command line

Saved queries are managed with the 'pi query' command on PiCLI.

pi query Command

> pi query -h
Usage: pi query [-h] SUBCOMMAND ...

Description: Commands related to Queries. These subcommands are used to add,
edit, delete and list information about Queries.

Optional arguments:
  -h, --help            Show this help message and exit

Available sub-commands:
  SUBCOMMAND
    add                 Create a new Query.
    attribute (attr)    Commands related to Query Attributes.
    delete (del, remove, rm)
                        Delete an existing Query.
    edit                Edit an existing Query.
    list (ls)           List all matching Queries.

Query template

The Query template

Query Template Example

[QUERY]

# The name of the Query is required.
name = qualified

# An optional description of the Query.
description = query to show all qualified IPs

# Only Admin users can share queries
# By default, queries are not shared
shared = True

# The Query is required.
query = ip_lifecycle="qualified"# The Icon is optional.
icon = clock

Adding queries

The 'pi query add' command is used to add a new Saved query.

pi query add Command

> pi query add -h
Usage: pi query add [-h] [--template TEMPLATE | identifier]

Description: Create a new Query. The command puts the Query specification into
a temporary file and invokes the editor specified by the EDITOR environment
variable. Saving the file adds the Query.

Positional arguments:
  identifier            The name of the Query being created.

Optional arguments:
  --template TEMPLATE, -t TEMPLATE
                        Use the specified template to add the Query. The
                        template is an ASCII file that defines the Query. This
                        can be used to add Queries with a script and avoid the
                        interactive editor. To read the template from STDIN,
                        set TEMPLATE='-'.
  -h, --help            Show this help message and exit

Deleting queries

Saved queries are deleted with the 'pi query delete' command.

Note:

If the query is shared, it can only be deleted by an admin.

pi query delete Command

> pi query delete -h
Usage: pi query delete [-h] identifier

Description: Delete an existing Query. This command will mark a Query as
inactive.

Positional arguments:
  identifier  The name of the Query to delete.

Optional arguments:
  -h, --help  Show this help message and exit

Editing queries

Saved queries are edited with the 'pi query edit' command.

Note: If the query is shared, it can only be edited by an admin.

pi query edit Command

> pi query edit -h
Usage: pi query edit [-h] [--template TEMPLATE] identifier

Description: Edit an existing Query. The command puts the Query specification
into a temporary file and invokes the editor specified by the EDITOR
environment variable. Saving the file edits the Query.

Positional arguments:
  identifier            The name of the Query being edited.

Optional arguments:
  --template TEMPLATE, -t TEMPLATE
                        Use the specified template to edit the Query. The
                        template is an ASCII file that defines the Query. This
                        can be used to edit Queries with a script and avoid
                        the interactive editor. To read the template from
                        STDIN, set TEMPLATE='-'.
  -h, --help            Show this help message and exit

Listing queries

Saved queries are listed with the 'pi query list' command.

pi query list Command

> pi query list -h
Usage: pi query list [-h]
                     [--format {csv,json,long,table,template} | --verbose]
                     [--model MODEL] [--all]
                     [identifier [identifier ...]]

Description: List all matching Queries. A variety of format and filtering
options are supported.

Positional arguments:
  identifier            Filter Queries by name.

Optional arguments:
  --all, -a             Include all shared Queries.
  --format {csv,json,long,table,template}
                        Return the results using the specified data structure.
                        The template format produces files that can be used by
                        the pi add|edit commands with the --template option.
  --model MODEL         Use the specified report model (table report only).
  --verbose, -v         Alias for --format long.
  -h, --help            Show this help message and exit

Controlling the number of Saved queries displayed

By default only unshared queries created by the user will be displayed by 'pi query list' shared queries can be shown via this option

Command Option	Description
--all, -a	By default only (unshared) queries created by the user will be displayed by 'pi query list' shared queries can be shown via this option

Configuring the Output Format

Helix IPLM can display the list output in a number of different formats

Command Option	Format	Description
--format	table	The default format option, a list of values in table format.
	template	Lists the queries in the 'pi query edit' CLI template format. The template format returns at most one result.
	long	Displays detailed information about the query, equivalent to --verbose, v output
	json	Display the list of Saved queries in json format.
	csv	Display the list of Saved queries in comma separated value format.
--verbose, -v		Displays detailed information about the query, equivalent to --format long output
--model MODEL		Display a custom table format MODEL defined in piclient.conf. See here for more information on configuring display models.

Managing Saved query attributes

Saved queries are displayed in IPLM Web and support Attributes. Saved queries are used to group specific sets of IP by their various data model fields (including properties). Adding Widgets to Saved query allows linking the Saved query group to information about the IP Family the query gathers. The 'pi query attribute' command is used to configure attributes on Saved queries. Note that if a query is shared its attributes can only be modified by an admin.

pi query attribute Command

> pi query attr -h
Usage: pi query attribute [-h] SUBCOMMAND ...

Description: Commands related to Query Attributes. These subcommands are used
to delete, get, list information about and set Attributes on Queries.

Optional arguments:
  -h, --help            Show this help message and exit

Available sub-commands:
  SUBCOMMAND
    delete (del, remove, rm)
                        Delete an Attribute from a Query.
    get                 Get the value of an Attribute from a Query.
    list (ls)           List the Attributes on a Query.
    set                 Set the value of an Attribute on a Query.

Setting Attributes on Saved queries

The 'pi query attribute set' command is used to set an attribute on a Saved query.

pi query attribute set Command

> pi query attr set -h
Usage: pi query attribute set [-h] [--file FILE]
                              identifier attr_name [attr_value]

Description: Set the value of an Attribute on a Query. Attributes are open
text fields in the Query. Users can set any key/value pair asan Attribute on a
Query. Helix IPLM performs no checks on Attributes. Optionally users can
define the Attribute value in a text file, location specified with --file
option (useful for complicated JSON strings, etc). Users may also read from
command STDIN directly and redirect with standard Unix. Note that the use of
attr_value and --file are mutually exclusive.

Positional arguments:
  identifier   Query identifier on which to set the Attribute.
  attr_name    Name of Attribute to set.
  attr_value   Value of Attribute to set.

Optional arguments:
  --file FILE  Specify path to file containing the Attribute value.
  -h, --help   Show this help message and exit

Examples:
# Set Attribute additional_info on Query my_query with value NONE
  pi query attr set my_query additional_info "NONE"# Set Attribute additional_info on Query my_query with value from contents of
file info.txt
  pi query attr set my_query additional_info --file info.txt

# Set Attribute test_results on Query my_query with value from STDOUT of
script run_regression.py
  run_regression.py | pi query attr set my_query test_results --file -

Example Query Attribute Set

Example Query Attribute Set

> pi query attr set qualified 'MDXDocBtn' '{"display": "button", "data":{"text":"Helix Docs", "url":"https://help.perforce.com/methodics/"}}'
Successfully set Attribute 'MDXDocBtn' on Query 'qualified'.

Listing Attributes on Saved queries

The 'pi query attribute list' command is used to list the attributes set on a Saved query. The target of the attribute list is set by the type of identifier supplied to the command.

pi query attribute list Command

> pi query attr list -h
Usage: pi query attribute list [-h] identifier

Description: List the Attributes on a Query. All Attributes on the Query are
listed.

Positional arguments:
  identifier  Query identifier the Attributes to list are on.

Optional arguments:
  -h, --help  Show this help message and exit

Examples:
# List the Attributes on Query my_query
  pi query attr list my_query

Example IPV Attribute List

Example IPV Attribute List

> pi query attr list qualified
┌───────────┬───────┬───────────────────────────────┐
│ NAME      │ USER  │ TIME                          │
╞═══════════╪═══════╪═══════════════════════════════╡
│ MDXDocBtn │ admin │ 2020-05-08 09:04:36 -0400 EDT │
│ Resources │ admin │ 2020-03-26 15:56:57 -0400 EDT │
└───────────┴───────┴───────────────────────────────┘
Found 2 matching object(s).

Getting attribute values from Saved queries

The 'pi query attribute get' command is used to retrieve the attribute set on Saved queries. The target of the attribute get is set by the identifier supplied to the command.

pi query attribute get Command

> pi query attr get -h
Usage: pi query attribute get [-h] identifier attr_name

Description: Get the value of an Attribute from a Query. The Attribute value
is returned directly by this command.

Positional arguments:
  identifier  Query identifier to get Attribute value from.
  attr_name   Name of Attribute to get.

Optional arguments:
  -h, --help  Show this help message and exit

Examples:
# Get the value of Attribute additional_info from Query my_query
  pi query attr get my_query additional_info

Example Query Attribute Get

> pi query attr get qualified MDXDocBtn
{"display": "button", "data":{"text":"Helix Docs", "url":"https://help.perforce.com/methodics/"}}

Deleting Attributes from Saved queries

The 'pi query attribute delete' command is used to delete an attribute set on a Saved query. The target of the attribute delete is set by the identifier supplied to the command.

pi query attribute delete Command

> pi query attr del -h
Usage: pi query attribute delete [-h] identifier attr_name

Description: Delete an Attribute from a Query.

Positional arguments:
  identifier  Query identifier to delete Attribute from.
  attr_name   Name of Attribute to delete.

Optional arguments:
  -h, --help  Show this help message and exit

Examples:
# Delete Attribute additional_info from Query my_query
  pi query attr del my_query additional_info

Example Saved query Attribute Delete

> pi query attr del qualified MDXDocBtn
Successfully removed Attribute 'MDXDocBtn' from Query 'qualified'.