Introduction

When you visit the inventory browser, you will now see the following:

Click the "search for resources" text, and you'll see:

These are called Search Suggestions. The suggestions pop-up offers advice on what can be searched, and provides syntax assistance along the way. There are three different types of suggestions:

• "Saved" – a previously executed search pattern that was saved for quick and easy retrieval

• "Query" – advanced suggestions that allow for finer-grained search within various properties

• "Text" – simplified suggestions of the most common searches, usually name-based matching

Simple Text Suggestions

As you begin to type, the results in the suggestions pop-up will change to match what you're typing. For instance, if you type "agent":

You will only get the suggestions with "agent" in the name. The pop-up will help to guide your search by highlighting the portion of the name that matched. As you can see, it found results where "agent" occurs at the start, in the middle, and at the end of the names of various resources in inventory.

If, however, you only wanted the results beginning with "C", start your search with "^" instead:

Just as easily, if you wanted only the results ending with "e", type "$" at the end of your search:

The "^" and "$" characters are referred to as boundary characters, since they force the search to bind to the beginning or ending of the property being searched for (in this case, resource names).

If you were to use both characters simultaneously, as in "^event$" then it will search for resources whose name is precisely "event". This kind of search could be useful if you have a lot of very similarly named resources in your inventory, and you're looking to constrain the search suggestions as much as possible.

Advanced Query Terms

The SearchBar allows for fine-grained searches of specific properties through the use of advanced query terms. Instead of searching on resource name, let's start typing one of the suggestions prefixed with "Query":

As you can see, the pop-up list will continue to provide simple suggestions as long as the start to any of the advanced query terms is incomplete. If we select the first entry in the list:

It will formally enter the advanced query mode and bind the current search to the "configuration" context. Here, the pop-up is providing suggestions for any resource configuration property in the system. We can narrow our search to a subset of properties by continuing to type more characters:

Just as with simplified name searches, it's doing a substring match. You can either continue typing at this point, or select one of the items from the list.

Note: keep in mind that you can use the boundary charcters "^" and {{"$"} to refine your search to property names that, respectively, start with or end with the specified filter.

Let's say that I wanted to search for resources that contain ANY of the 6 matching results. Type "]" to complete the property name filter. At this point, you'll see a series of available comparison operators:

Each of these changes the nature of the search every so slightly:

• '=' results will match the value on the right-hand side of the operator, case-insensitively

• '==' results will match the value on the right-hand side of the operator, respecting case

• '!=' negated match for the value on the right-hand side of the operator, case-insensitively

• '!==' negated match for the value on the right-hand side of the operator, respecting case

Usually, if you don't know precisely what you're looking for, using the "=" operator is your best bet since it will match the widest array of results. After you choose your operator, the suggestion pop-up will display all of the possible values for the resources in your inventory for the configuration properties whose name contains "address":

As you can see, we have one service bound to the local loopback adapter, one service bound to all network interfaces on its box, and another listening on a multicast address. Selecting any of these from the list and then pressing enter (or clicking the "GO" button on the far right) will execute the search and return resources containing at least one configuration property matching the specified value.

Again, if there were too many suggestions for the specified property, you are allowed to use "^" and "$" boundary characters to try and match more specifically. For instance, I might want to find all of the JBossAS Server instances that are running out of my home directory. I could do that with the following search expression:

connection[jbossHomeDir]=^/home/jmarques

Saved Searches

Over time, as the SearchBar becomes part of the standard way to navigate around your inventory, you're going to want the system to remember some of the searches you've done, and provide a convenient mechanism for re-retrieving their corresponding search results. That's where Saved Searches come in.

Let's say that one of your daily tasks is to monitor the health of your JBossAS clusters. If the incoming load on some cluster is too high, you might want to add more instances to it. So you provision a couple new instances, which by default won't belong to any cluster yet. You can find these non-clustered resources with the following search pattern:

trait[partitionName]=null

If you have to execute this pattern often, you might not want to have to remember that you need to search for the measurement traits for a resource, or that the trait which determines cluster membership is called 'partitionName'. You can save this search pattern with a symbolic name by clicking on the star icon on the far right:

The icon will get a gold border and a text box will appear that allows you to name the search pattern. You can name it whatever you want, and hit the enter key to finish the creation of your saved search.
Over time, as you add more and more saved searches, you will need a convenient way of accessing these. One way is just to use the standard suggestion mechanism. When the SearchBar is empty and gets focus, your saved search patterns will be suggested to you at the top of the pop-up:

You can select one of them from the list, and it will "activate" that saved search. An active saved search will populate the SearchBar with the saved pattern, and indicate which saved search is selected by using a green label on the far right:

You can see above what happened when I selected my "unsecured JBAS" saved search pattern. Not only did it fill in the SearchBar with the necessary pattern, but it also executed the search immediately. In this case, it found 4 resources in my inventory that have an empty value for a connection property named 'principal'. These refer to to either:

1. my JBossAS resources with unsecured JNP endpoints in my inventory

2. resources that I have yet to supply the necessary credentials required for remote communication with them, e.g. my local Postgres server

If, in the future, I decide that I need to update the name of my saved search pattern, all I have to do is double-click on the green label (presuming the saved search is already active):

This will change the label into an editable input text box. After editing the name, simply hit enter and it will update the name of your saved search pattern.

An alternate way of accessing saved searches is through the drop-down menu on the far right. If you click the down-arrow next to the star, you'll see the following menu:

This is a slightly enhanced view over the suggestions pop-up because it will show you the names (in green) and patterns (in black) of your saved searches. It will also show you a number in parentheses, which indicates the last known number of results that the pattern matched against your inventory. Selecting any of the items from this list will active the saved search just the same as it would if you selected it from the search suggestions pop-up.

Over time, you'll find that some of your saved searches are no longer relevant. If that happens, you can remove saved searches in one of two ways. The first is to use the saved searches drop-down directly. Hover over any of the rows, and you'll see a trash icon to the far right of the grid:

If you click the trash icon, it will remove the saved search from the system. Alternatively, you can click on the pattern name instead, which will first activate that saved search:

Notice how an active saved search turns the star gold. If you click the gold star, it will also remove the saved search pattern from the system. The star will turn back to gray, the green label will disappear, but the pattern itself will remain in the SearchBar:

This type of deletion, since it keeps the pattern in the SearchBar, allows you to modify it (change some search terms, add more search terms, etc), and then potentially save the pattern as a new saved search.

Complex Search Expressions

• searchTermA searchTermB

  • find results that match both search terms

• searchTermA | searchTermB

  • find results that match either search term

• searchTermA | searchTermB searchTermC

  • find results that match search terms B and C, or which matches search term A. in other words, 'and' has a higher precendence than 'or'

• searchTermA (searchTermB | searchTermC)

  • find results that match search term A as well as one (or both) of search terms B and C. here, we use parentheses to override the default precedence, which forces the 'or'ed terms to be evaluated first, then 'and' the result of that together with search term A

Result Matching using Quotes

A search term can basically take one of three forms:

<value>
<context> <comparisonOperator> <value>
<context> [ <parameter> ] <comparisonOperator> <value>

Quote-handling mainly concerns how single-quotes and double-quotes are handled for <value> suggestions.

Note: in a future release, we will likely extend the sophisticated quote support to <parameter> name suggestions as well

As long as you don't have any white-space in the term you're searching for, you don't need quotes at all.

1a) portal-war
2a) plugin=jboss
3a) trait[partitionName]=mycoolcluster

If you add more search terms after these:

1b) portal-war rhq
2b) plugin=jboss rhq
3b) trait[partitionName]=mycoolcluster rhq

The whitespace is treated as a term separator. Thus, 2b means "search for resources whose name contains 'rhq' and whose type was defined by a plugin with 'jboss' in the name" and 3b means "search for resources whose name contains 'rhq' and whose partitionName trait contains 'mycoolcluster'".

If, however, the user wants to interpret white-space characters literally, then single-quotes or double-quotes must be used. The following search expressions are all equivalent.

"Agent Plugin Container"
'Agent Plugin Container'
name="Agent Plugin Container"
name='Agent Plugin Container'

Thus, there is no semantic difference between single-quotes and double-quotes; they exist purely to treat the white-space in between them as literal value characters.

But what happens if you have a resource whose name is:

joseph's cool resource

In this case, the resource name already has a single-quote in it, as well as white-space. So, the only way to find this resource unambiguously is to use the opposite style quotes for the boundary characters:

"joseph's cool resource"
name="joseph's cool resource"

Or even matching on part of the name, but still using opposite style quotes:

"joseph's"
name="joseph's"

Likewise, if your resource has double-quotes in the name:

silly " resource

Then you would use single-quotes to find it:

'silly " resource'
name='silly " resource'

Keep in mind that quotes are NOT necessary as boundary character unless you have white-space in the name. So, excluding boundary quotes, I could search for:

joseph's

And it will work just the same. In other words, single-quotes and double-quotes can freely occur anywhere inside the item being searched for; they only get special treatment when they are the boundary characters.

However, excluding boundary quotes, if I searched for:

joseph's cool resource

This search expression would actually be interpreted as searching for resources whose name contains all of the following 3 terms: joseph's, cool, and resource (because the white-space will be interpreted as term separators). Granted, it will still find the resource that you're looking for, but it may return other resources as well. So by adding quotes:

"joseph's cool resource"

You are ensuring that you search for resources whose names have those three terms exactly in the order presented and with precisely the amount of white-space you entered between the quotes.

Improper Usage of Quotes

If you start a search term with single-quotes or double-quotes, then the search system expects your term to end in the same type of quotes that it began. Thus, the following expressions are all invalid:

• "hello'

  • must end with same quote as it began

• 'world"

  • must end with same quote as it began

• "foo

  • must end with double-quote

• 'bar

  • must end with single-quote

• "cat"in

  • the last two characters are interpreted as junk, and should either be removed or white-space added to separate the quoted term (cat) from the unquoted one (in)

• "the"hat"

  • need to use alternating style quotes, if you wanted to search for terms containing double-quotes, simply enclose the term with single-quotes as follows 'the"hat' (recall, however, that boundary quotes are only necessary if the thing you're attempting to filter by contains white-space)

Search Suggestions using Quotes

The search suggestions are intelligent insofar as they will recognize whether you've started a search term with a quote, and then provide suggestions which respect that quote-style. For example, if a search term began with a double-quote character, here are what the suggestions would look like:

Notice how only some of the suggestions get quoted. This indicates that quotes were unnecessary for those results because they do not contain any white-space that needed to be escaped. However, if there are any suggestions that contained white-space, then those items will be wrapped with the quote-style that you began the current search term with, in this case double-quotes.

Here is an example of what it would look like if the search began with a single-quote:

Again, only some of the results are quoted – only ones that need to be quoted to escape the white-space in their values.

In general, though, you really don't have to worry about which, if any, style quotes you start your search term with. The search system is intelligent enough to wrap your suggestions in the appropriate quotes, and only as necessary. For example:

Here you see that the first suggestion contained data with double-quotes in it, so it was wrapped in single-quotes. The second suggestion was the opposite case, where the data contained single-quotes so it had to be wrapped in double-quotes. The last suggestion, because it did not contain any white-space, did not need to be wrapped in quotes at all.