Querying workspaces

This section provides example workspace queries, and describes the workspace fields that may be used in query expressions.

Workspace query overview

For detailed information on Queries go to the Helix IPLM query language page. For information on Saved queries go to the Saved queries page.

Workspace related fields for use in queries

Workspace

  • all_resources (list of workspace resources): all the workspace resources, including the top resource

  • creation_timestamp (integer)

  • creator (user)

  • last_update_timestamp (integer)

  • last_updater (user)

  • path (string)

  • p4_client (string)

  • resources (list of workspace resources): the workspace resources, excluding the top resource

  • top_ipv (workspace resource): the top resource

  • view (workspace view)

Workspace resource

  • alias (alias): the alias of the workspace resource, if any

  • last_update_timestamp (integer)

  • last_updater (user)

Workspace view

  • description (string)

  • name (string)

  • patterns (list of workspace view patterns)

Workspace view pattern

  • exclude (boolean)

  • file (string)

  • head (boolean)

  • ip (string)

Update or creation time related queries

Workspaces with Creation Timestamp in the Last 2 Weeks

pi ws list -q 'creation_timestamp>now()-weeks(2)' 
┌───────────────────────────┬────────────┬───────────────────────────────┬───────────────┐
│ TOP IPV                   │ CREATED BY │ CREATED ON                    │ PATH          │
╞═══════════════════════════╪════════════╪═══════════════════════════════╪═══════════════╡
│ tutorial.L1@3.TRUNK       │ admin      │ 2017-09-19 14:10:45 -0700 PDT │ /tmp/work/ws2 │
│ tutorial.tutorial@5.TRUNK │ admin      │ 2017-09-19 09:22:31 -0700 PDT │ /tmp/work/ws1 │
└───────────────────────────┴────────────┴───────────────────────────────┴───────────────┘

Workspaces Created by a User and Not Updated Within a Specific Range of Days

The following example displays how a user looks for workspaces created by the 'admin' user that have not updated in the last 13 days:

pi ws list -q 'creator="admin" && last_update_timestamp<now()-days(13)' 
┌───────────────────────────┬────────────┬───────────────────────────────┬──────────┐
│ TOP IPV                   │ CREATED BY │ CREATED ON                    │ PATH     │
╞═══════════════════════════╪════════════╪═══════════════════════════════╪══════════╡
│ tutorial.tutorial@5.TRUNK │ admin      │ 2018-03-16 07:16:02 -0700 PDT │ /tmp/ws1 │
└───────────────────────────┴────────────┴───────────────────────────────┴──────────┘

Note:  The piclient can be customized to report the last updated time either by default or in a special report mode, see Listing workspaces for details.

Querying workspaces by path

Workspaces with a Specific Path Name

pi ws ls -q 'path="/tmp/work/ws2"' 
┌───────────────────────────┬────────────┬───────────────────────────────┬───────────────┐
│ TOP IPV                   │ CREATED BY │ CREATED ON                    │ PATH          │
╞═══════════════════════════╪════════════╪═══════════════════════════════╪═══════════════╡
│ tutorial.L1@3.TRUNK       │ admin      │ 2017-09-19 14:10:45 -0700 PDT │ /tmp/work/ws2 │
└───────────────────────────┴────────────┴───────────────────────────────┴───────────────┘

Workspace path name is stored in the 'path' field, search using 'path="the/full/path/name"' to match the full path.

Workspace Path Name Ends in a Particular String

pi ws ls -q 'path~=".*ws2"' 
┌───────────────────────────┬────────────┬───────────────────────────────┬───────────────┐
│ TOP IPV                   │ CREATED BY │ CREATED ON                    │ PATH          │
╞═══════════════════════════╪════════════╪═══════════════════════════════╪═══════════════╡
│ tutorial.L1@3.TRUNK       │ admin      │ 2017-09-19 14:10:45 -0700 PDT │ /tmp/work/ws2 │
└───────────────────────────┴────────────┴───────────────────────────────┴───────────────┘

The Query language regex capability (see the query language section and this Java pattern here) can be used to search for workspace paths that end in a certain string.

In this case 'path~=".*ws2"'

String Definition
~= indicates the pattern should be treated as a regular expression
.* indicates any character ('.') zero or more times ('*'). You would use '.+' to match any character one or more times
ws2 is the string to match at the end of the path. No additional characters follow this string so it will have to appear at the end of the path to match

Workspace Path Name Contains a Particular String

pi ws ls -q 'path*="ws"' 
┌───────────────────────────┬────────────┬───────────────────────────────┬───────────────┐
│ TOP IPV                   │ CREATED BY │ CREATED ON                    │ PATH          │
╞═══════════════════════════╪════════════╪═══════════════════════════════╪═══════════════╡
│ tutorial.L1@3.TRUNK       │ admin      │ 2017-09-19 14:10:45 -0700 PDT │ /tmp/work/ws2 │
│ tutorial.tutorial@5.TRUNK │ admin      │ 2017-09-19 09:22:31 -0700 PDT │ /tmp/work/ws1 │
└───────────────────────────┴────────────┴───────────────────────────────┴───────────────┘

For simpler searches the Query language provides a wildcard matching mode, where '*' matches more than one character, '?' matches one character, and '/' escapes characters. To search for workspace paths containing the string 'ws' you use 'path*="*ws*"':

String Definition
*= Treat the pattern as a wildcard match expression
* match one or more characters
ws match the string 'ws'
* match one or more characters

Workspace Path does Not Contain a Particular Directory

pi ws list -q 'path~="(?!./workspaces/)."' 
┌────────────────────────────────────┬────────────┬───────────────────────────────┬───────────────────────────────────┐
│ TOP IPV                            │ CREATED BY │ CREATED ON                    │ PATH                              │
╞════════════════════════════════════╪════════════╪═══════════════════════════════╪═══════════════════════════════════╡
│ tutorial.tutorial@HEAD.TRUNK [@12] │ admin      │ 2018-03-21 12:36:35 -0700 PDT │ /tmp/ws2                          │
│ tutorial.tutorial@12.TRUNK         │ admin      │ 2018-04-04 11:16:30 -0700 PDT │ /tmp/someworkspaces/proj3/ws7      │
│ tutorial.tutorial@10.TRUNK         │ admin      │ 2018-03-26 09:30:44 -0700 PDT │ /tmp/ws3                          │
│ tutorial.tutorial@5.TRUNK          │ admin      │ 2018-03-16 07:16:02 -0700 PDT │ /tmp/ws1                          │
└────────────────────────────────────┴────────────┴───────────────────────────────┴───────────────────────────────────┘

The Query language regex capability (see the query language section and this Java pattern here) can be used to search for workspace paths that do not contain a particular directory.

In this case 'path~="(?!.*/workspaces/).*"'

String Definition
~= indicates the pattern should be treated as a regular expression
(?! start of Java negative look ahead expression, indicates the following expression should not be matched:
.* Zero or more occurrences of any character
/workspaces/ the directory name to exclude from the search
) end of the Java negative look ahead expression
.* zero or more occurrences of any character (this will match all other workspace paths)

Querying workspaces by IP

For some cases the built in pi cli command 'pi ws list --contains' should be considered as an alternative to writing a full query to search for workspaces by their IP contents.

Workspace contains resources @HEAD which haven't been updated in 1 week

pi ws list -q 'any(all_resources, { alias == "HEAD" && last_update_timestamp<now()-weeks(1) })' 
┌────────────────────────────────────┬────────────┬───────────────────────────────┬──────────┐
│ TOP IPV                            │ CREATED BY │ CREATED ON                    │ PATH     │
╞════════════════════════════════════╪════════════╪═══════════════════════════════╪══════════╡
│ tutorial.tutorial@HEAD.TRUNK [@12] │ admin      │ 2018-03-21 12:36:35 -0700 PDT │ /tmp/ws2 │
│ tutorial.tutorial@10.TRUNK         │ admin      │ 2018-03-26 09:30:44 -0700 PDT │ /tmp/ws3 │
│ tutorial.tutorial@5.TRUNK          │ admin      │ 2018-03-16 07:16:02 -0700 PDT │ /tmp/ws1 │
└────────────────────────────────────┴────────────┴───────────────────────────────┴──────────┘

Resource IPs are returned in list format, so we use the query language's list processing capabilities to work with the results.

pi ws list -q 'any(all_resources, { alias == "HEAD" && last_update_timestamp<now()-weeks(1) })'

String Definition
any( A list function (see the query language section) which evaluates to true if the expression is true for ANY of the items in the list
all_resources, Grabs all IPVs in the workspace, including the top IPV
{ Beginning of the expression to check against each of the IPVs in the workspace
alias == "HEAD" Checks if the IPV is loaded "@HEAD" in the workspace
&& Applies the previous AND the subsequent filter
last_update_timestamp<now()-weeks(1) Checks the last_upate_timestamp is between now and one week ago
})' Closes out the expression section and the 'any()' function

Workspace contains an IP with a prefix from a certain Library

pi ws ls -a -q 'any(all_resources,{lib="PDK" && name*="MS90*"})' 
┌──────────────────────┬────────────┬───────────────────────────────┬──────────────────────┐
│ TOP IPV              │ CREATED BY │ CREATED ON                    │ PATH                 │
╞══════════════════════╪════════════╪═══════════════════════════════╪══════════════════════╡
│ PDK.MS90G_LP@0.TRUNK │ admin      │ 2018-10-30 17:51:27 -0500 CDT │ /tmp/root_temptutdir │
└──────────────────────┴────────────┴───────────────────────────────┴──────────────────────┘

pi ws ls -a -q 'any(all_resources,{lib="PDK" && name*="MS90*"})'

String Definition
any( a list function (see query language) which evaluates to true if the expression is true for ANY of the items in the list
all_resources, grab all IPVs in the workspace, including the top IPV
{ Beginning of the expression to check against each of the IPVs in the workspace
lib == "PDK" Filter the results for the Library named "PDK"
&& apply the previous AND the subsequent filter
name*="MSG90*" Filter the results for any IP that starts with the prefix "MSG90"
})' Close out the expression section and the 'any()' function