SolarWinds understands that not everyone is a programmer or a database administrator. Every individual comes to the SolarWinds solutions in their own unique way: be they a network engineer, a systems administrator, a virtualization specialist, or a storage aficionado. That doesn’t change the fact that your monitoring data is critical to making informed business decisions.
Currently, many people are probably wondering why we didn’t begin this chapter talking about SWQL Studio. We could have done so, but the inherent problem with SWQL Studio is that it is a data-tool first and does not enforce best practices (mandatory aliasing, formatting with parenthesis, checking Boolean logic, etc.) Therefore, the authors elected to ground this chapter in the practical recommendations before moving onto the tools to assist.
A Data Tool for Non-DBAs
SWQL Studio is an open-source project maintained by SolarWinds which provides a graphical data navigator for the SolarWinds Platform API. It can be downloaded from GitHub and runs on most modern Windows operating systems.
After installation, you’ll be asked to authenticate with a server of your choosing. Enter the server’s name or IP address, your username and password and click Connect.
Authentication in SWQL Studio can take many forms, but the two most used are “Orion (v3)” and “Orion (v3) AD.” Orion (v3) is for basic Orion logins where you enter a username and password. “Orion (v3) AD” uses your current domain credentials and sends those to the server for validation. This behavior is like Windows Integrated Authentication.
The object explorer on the left will contain all the relevant data points where you can retrieve data. Expand, your server, then the Orion namespace, then the Orion.Nodes entity, and finally, the Unmanage verb. This will show each type of identifier in your data set.
Your specific namespaces, entities, and counts may not match to that of another Orion installation. This is by design. The number of entries is dependent on the installed version of your server. However, the definition of the namespaces and entities will be common. (
Orion.Nodesis alwaysOrion.Nodesregardless of the version installed).
Data Source
You can think of your data source as the monitoring database, but it’s more than just a single database – it encompasses the data among all the connected SQL databases running your SolarWinds Orion platform products.
Namespaces
Namespace is a programming term which contains multiple element definitions. For the purposes of our discussion, it’s safe to think of namespaces as collections of like entities.
Entities
In database parlance, one can think of entities as tables. They behave much the same way, but their underlying construction is different. Unlike traditional database tables, entities in the Orion API only support SELECT queries. Creation, updates, and deletion are either handled by verbs or other mechanisms. Entities will commonly (but erroneously) be called “tables” – we have no preference among the pages in this book but will do our best to use the term ‘entity.’
Any entity which is represented with a strikethrough is considered deprecated. This means that as of your current build of the SolarWinds Platform, that entity still exists, but will be removed in a subsequent version.
Properties
Quite simply, properties are the fields that are returned when you query an entity. You’ll find people referring to them by either name for the same reasons that entities are called tables – because it’s a term for a concept with which people are already familiar.
During your exploration you will probably come across two special properties. The first will be the primary key (or keys) which help uniquely identify the record in the entity. The second is rarer, but still exists. Any property which is formatted with a strike-through is a deprecated property. As previously stated, these are rare, but they have occurred over the lifetime of the API. If you have a query that is currently utilizing a deprecated property, it will need to be updated. Refer to the in-product documentation (typically below the Object explorer) for the updated property to use.
Inherited Properties
Grouped with properties are Inherited Properties. These are values which are inherited from another entity or from another constructor to alter the output. They are not automatically selected when you create a new query using the right-click menu on an entity to create a query. The most important inherited property to notice is URI (Uniform Resource Indicator). This is a string unique to a specific entity within your entire monitoring infrastructure and is used in multiple verbs and functions.
Navigation Properties
The chain link icon indicates a Navigation Property. These are properties which do not exist in this entity, but where a connection exists to another, related entity. These are frequently used as a replacement for various JOIN operations in queries. The important thing to notice is the name of the Navigation Property, which will always be in the format “NavPropName (Entity).” Using the above example, Orion.VIM.Nas has a navigation property Hosts (Orion.VIM.Hosts). When a query is made against the Orion.VIM.Nas entity, you can simultaneously request properties about the host by using the Hosts keyword followed by the property from the Orion.VIM.Hosts entity.
Fundamentally, this is identical to building a JOIN between the two entities on a primary key but eliminates the need to know the primary key or the inheritance direction. This is covered more in depth in Decreasing JOINs - the Power of Navigation Properties .
Verbs
We all heard that verbs are “action words” and that’s no different for the Orion API. The verbs are where you take an action on one of your monitored elements. There are verbs to manage and unmanage elements, mute them, change settings, and more. After you are comfortable with building your own SWQL queries, investigating verbs should be your next step.
Verb Parameters
Verbs require parameters to define the work to be done, the target, timespans, settings, and other details. These are important to review within the SWQL Studio explorer because the data types and order are important. For the verbs exposed via the Orion API, the parameters are strictly typed and ordered.
Search
At the top of the object explorer, there is a search field. This will search across all existing elements and filter for only to elements where the name matches your search term (either as parent entries or child objects). To clear the current filter, remove any typed text from the search field.