Summary

Understand the Insight Query Language (IQL), and learn how to use it with some simple
examples.
In this article

 Basic syntax
 Syntax for special characters
 Dot notation
 Keywords
 Operators
 Combination operators
 Functions 
 Date
 IP Address
 User
 Group
 Project
 Reference functions
 Using the connectedTickets() function
 Using the objectTypeAndChildren() function
 Ordering

IQL (Insight Query Language) is a language format used in Insight to create search queries for
one or more objects. Using IQL, you can return any object or group of objects in Insight in a
search, filter objects, modify objects, create custom fields, automations and post-functions, and
more.
This is one of Insight's most powerful and dynamic features.

Basic syntax
The basic syntax of an IQL query is <attribute> <operator> <value/function>. One or more
objects is returned by the query when the attributes of these objects match the operator and value
specified. 
A basic IQL query that returns all objects for which the Owner is "Ted Anderson". Note the
quotations around "Ted Anderson", since there is a space in the value name.
 Syntax for special characters
IQL has a defined syntax and must be entered exactly.

 IQL is case-sensitive.
 If you are using an expression where the value or attribute contain a space, you must
include quotations surrounding the value, as in the above example for "Ted Anderson".
 If you are using an expression where the value or attribute contain quotation marks, you
must escape the quotes by surrounding them with backslashes. For example, if you have an
object name such as 15" Screen, to search for it enter: "15\" Screen"
 The attribute name that you specify in the IQL must exist in your Insight schema. If not,
the IQL will be considered invalid. The attribute name is case sensitive.

IQL can be helpful in accomplishing the following tasks:

 Automation
 Insight Searching & Filtering
 Insight Custom Field
 Insight Referenced Custom Field

Dot notation
Dot notation is used in IQL to travel down a reference chain of objects. The
format <attribute>.<attribute> <operator> <value/function> will return information based
upon objects referenced by the parent object.
In this case,  the Employee object type has a referenced attribute called "Belongs to
Department". The query returns all the Employees which belong to the "HR" department.
Note that since the referenced attribute contains spaces, it has been enclosed with a pair of
double quotes.
Keywords
You can use keywords in IQL to return one or more objects based upon properties of those
objects instead of the object's attributes. The syntax looks like this: <keyword> <operator>
<value/function>.
For example, you could return all objects of a specific object type using
the objectType keyword, or all objects of any type with a certain attribute by using
the anyAttribute keyword. The table below describes the keywords supported along with their
respective examples.

Keyword Description

objectSchema You can limit the search result to a specific object schema name, e.g.
objectSchema = "ITSM Schema". Note that since the name contains spaces, it
is enclosed within a pair of double quotes.

objectSchemaId You can limit the search result on object schema ids. e.g. objectSchemaId in
(1, 2).

objectType You can limit the search result to a specific object type name, e.g. objectType
= "Employment Start Date". Note that since the name contains spaces, it is
enclosed within a pair of double quotes.

objectTypeId You can limit the search result on object type ids. e.g. objectTypeId in (1, 2).

anyAttribute You can search all attributes on all objects for a relevant match. e.g.
"anyAttribute = 123.123.123.123".
Note that use of this keyword may incur delays in searching results. The
larger the Insight installation, the more time it will take to execute a query
with this keyword.

object You can limit the search to the object, e.g. "object having
inboundReferences()" will search all objects having any inbound references to
it.

objectId You can find an object by object Id, e.g. "objectId = 114". Note that the object
id is the number from the Key of the object, but without the prefix. E.g. if the
Key of your object is ITSM-1111, then the prefix is ITSM and the object id is
 Keyword Description

1111. Note that the Key could change when you move objects across
schemas. 
In older installations of Insight, the key and the object id were different. E.g.
the Key for an object could be "ITSM-1" but the objectId could be "1234". 
So, depending on the Insight version you use, pick up the respective objectId.

An IQL query that returns all objects with the "Host" object type.
Note that if you are in the Insight User  role,  you will not get to see the object type id and the
schema id. You can get those values from your Insight Administrator or Insight Manager and
then use it to perform IQL queries.

Instead of the objectId, you can always use the Key attribute on any object type to search for a
particular object.
E.g. Key="ITSM-1111" will return the unique object whose key is ITSM-1111

Operators
Operators allow you to create more detailed logical expressions.
The table describes the operators supported in IQL.

Operator Description Example IQL query

= Equality test for case "Office = Stockholm"

insensitive values.
Checks if the Office attribute has a value
equal to Stockholm or STOCKHOLM

== Equality test for case "Office==Stockholm"

sensitive values.
Checks if the Office attribute has a value
equal to Stockholm considering the case
of the input provided.

                         ! Inequality test objecttype-Employee and Office!

= =Stockholm
Checks if the Employee object has an
attribute Office whose value is NOT
equal to Stockholm.
Operator Description Example IQL query

< Less than test. "Price < 2000"

Checks if the Price is less
than 2000 dollars.

> Greater than test. "Price > 2000"

Checks if the Price is greater
than 2000 dollars.

<= Less than or equal to test "Price <= 2000"

Checks if the Price is less than or equal
to  2000 dollars.

>= Greater than or equal to test. "Price >= 2000"

Checks if the Price is greater than or
equal to 2000 dollars.

like Matches a value with any "objecttype=Employees and Office like

subset of input in the query. It Stock"
is case insensitive.
Returns all objects of Employees
type which have an Office attribute value
that contains the characters 'Stock' or
'STOCK'

not like Excludes values which match "objecttype=Employees and Office not
with any subset of input in the like Stock"
query.
Returns all objects of Employees
type which have an Office attribute value
that DO NOT contain the characters
'Stock'

in() Finds a match in the given Office in ("Stockholm", "Oslo", "San

arguments and returns results. Jose")
Returns all objects of Office  type which
HAVE one of these
values: Stockholm, Oslo or San Jose.

not in() Excludes the results for which Office not in ("Stockholm", "Oslo", "San
a match is found in the given Jose")
arguments.
Returns all objects of Office  type which
DO NOT HAVE one of these
values: Stockholm, Oslo or San Jose.
Operator Description Example IQL query

startswith Finds a match whose value "Office startsWith St"

starts with the given input. It is
Returns results which match values
case insensitive.
of Office type starting with the characters
"St" or "ST"

endswith Finds a match whose value "Office endsWith St"

ends with the given input. It is
Returns results which match values
case insensitive.
of Office type ending with the
characters "St" or "ST"

is Helps test whether a value "Office is EMPTY"

exists or not.
Checks whether the value of
the Office type exists and returns results
accordingly.
"Office is not EMPTY"
Checks whether the value of
the Office type is not empty.

dot operator(.) Helps navigate "Country.Office = Stockholm"

the Referenced types attributes
The dot operator here navigates to the
for an object.
referenced object Office in the
This operator is commonly attribute Country and
used in: compares Office with the
value Stockholm.
inboundReferences() or inR()
functions.
outboundReferences() or
outR() functions.
Order by clause.

having Used with either "object having inboundReferences()"

the inboundReferences()
Returns all objects having inbound
OR outboundReferences()
references.
functions

not having Used with either "object not having inboundReferences()"

the inboundReferences()
Excludes all objects having inbound
OR outboundReferences()
references and returns results.
functions
Below is a screenshot of Insight→ Search for objects screen where an IQL query is run that
uses the IN operator and objectType to return objects of three different object types. Notice that
the values in the IN clause which include spaces are enclosed in quotes.
Remember that if you want to check for case sensitive values in your queries, you need to use the
== operator.

Combination operators
You may use operators such as AND/OR to create larger and more complex IQL expressions.
An IQL query that includes two statements linked with the AND operator.
Functions 
You can use different functions to supply dynamic values to IQL expressions.

Type Function name Description

Date now() You can use a range of functions to write queries which involve date and ti
startOfDay()
We use m for minutes, h for hours, d for days and w for weeks to represen
endOfDay()
startOfWeek() e.g. A query with a condition like: Created > "now(-2h 15m)" returns all o
endOfWeek() hours and 15 minutes.
startOfMonth()
endOfMonth() e.g. A query containing something like: objectType =  Employees and "Em
startOfYear() endOfMonth(-90d)
 endOfYear()
returns all Employee objects whose Employment End Date falls before 90
end date.
e.g. You may also check for an upcoming date, e.g. check when the license
end of the year. Your query can then include something like : licenseEndD
You can use all other date functions in a similar manner.

IP CIDR(IP RANGE) CIDR(IP RANGE) - Filter on IP ranges

Address
e.g. 
"IP Address" IN CIDR("192.0.0.0/8")
"IP Address" IN CIDR("192.168.0.0/16")

User currentUser() You can filter on user attributes connected to the current (logged in) user b
your IQL query. Note that the attribute used in the query for filtering needs
e.g. objecttype = Computer and User = currentUser()

This function will work when a currentUser is selected, ie. the user is logge

currentReporter() You can filter on user attributes connected to current reporter in custom fie
in your IQL query. Note that the attribute used in the query for filtering nee
e.g. User = currentReporter()

This function will only work when an issue is selected, and refers to the rep
current issue.

user(user1, You can filter on objects which have a reference to the users that you prov
user2, ..) function. The attribute used to filter must be of User type. 
This function will work with multiple arguments only if the User type attri
multiple values i.e, the cardinality for it is more than one.
e.g. An object type Team has an attribute Member. This attribute is of User
attribute has been configured to have a cardinality of 3. If you want to sear
the users: admin and manager are its members, you can write the following
objecttype=Team and Member having user("admin", "manager")

Group group(group1, You can filter on any object connected to a user within a specific group. Th
group2,...) be of User type.
e.g. User in group("jira-users", "jira-administrators")

user(user1, Filter on any object connected to a user within a specific group. The attribu
user2, ...) of Group type.
 e.g. Group having user("currentReporter()")

Project currentProject() Filter on any object connected to the currently selected Jira project. Works
e.g. Project = currentProject()
This function will only work when a project is currently selected.

Reference functions
Reference functions are functions that take two arguments - IQL and/or a reference-type
argument. Essentially, you can use reference functions to run an IQL query on a subset of objects
of a particular reference type. Such a query will run on a small subset of the total objects, which
allows you to limit results and/or processing time.

 The IQL argument can be an arbitrary IQL including an IQL with reference function. 

 The Reference Type argument is optional.

S Name Description
r.
N
o

a  inboundRefere Filter objects having inbound references where the referenced

nces(IQL) objects match the IQL query provided as an argument to the
 inR(IQL) function.
e.g. An IQL query like: object having inboundReferences() will
return all objects having inbound references since the empty IQL
argument to the function will match all inbound referenced
objects.
But an example query like: object having
inboundReferences(Name="John") will return all objects which
have an inbound referenced object with an attribute Name and
value for Name as "John".

b  inboundRefere This is a variant of the inboundReferences(IQL) function

nces(IQL, described in (a)
referenceTypes)
Using this, you can filter the inbound referenced objects further
S Name Description
r.
N
o

 inR(IQL,
by providing the Reference Type as a single or multiple
refTypes)
value(s). You can do this with the help of the "IN" operator.
Reference Type is the Additional Value field that you provide on
an attribute when you define a referenced object for an object
type as shown in the screenshot below.

e.g. An IQL query like this: object having inR(objectType = "File

System", refType IN ("Depends"))
will return objects which have inbound referenced objects of
"File System" and only for those File System objects whose
Reference Type is "Depends".
Similarly, an IQL query like: object having inR(objectType =
"File System", refType IN ("Depends", "Installed", "Using"))
will return objects which have inbound referenced objects of File
System and for those File System objects whose Reference Type
is any of these: Depends, Installed, Using

c  outboundRefer Filter objects having outbound references where the referenced

ences(IQL) objects match the IQL query provided as an argument to the
 outR(IQL) function.
e.g. An IQL query like: object having outboundReferences() will
return all objects having outbound references since the empty
IQL argument to the function will match all outbound referenced
objects.
 S Name Description
r.
N
o

But an example query like: object having

outboundReferences(Name="John") will return all objects which
have an outbound referenced object with an attribute Name and
value for Name as "John".

d  outboundRefer This is a variant of the outboundReferences(IQL) function

ences(IQL, described in (b)
referenceTypes)
Using this, you can filter the outbound referenced objects further
 outR(IQL, by providing the Reference Type as a single or multiple
refTypes) value(s). You can do this with the help of the "IN" operator.
Reference Type is the Additional Value field that you provide on
an attribute when you define a referenced object for an object
type.
e.g. An IQL query like this: object having outR(objectType =
"Employees", refType IN ("Location"))
will return objects which have outbound referenced objects
of Employees and only for those Employees objects whose
Reference Type is "Location".
Similarly, an IQL query like: object having outR(objectType =
"Employees", refType IN ("Location", "Country"))
will return objects which have outbound referenced objects
of Employees and for those Employees objects whose Reference
Type is any of these: Location, Country

An IQL query that uses the inR function to return all objects that are of object type "File System"
and have inbound references of type "Installed", "Depends", or "Using".
An IQL query that uses the inboundReferences function to return all objects that have references
from other objects whose Status is "OK".
Using the connectedTickets() function
The connectedTickets() function is used to filter objects having tickets connected to them.
Specific Jira issues may be selected by providing a proper Jira Query Language (JQL) query. If
no JQL query is provided, all objects having Jira issues connected are returned.

Name Description

connectedTickets() All objects having tickets connected to them are returned.

connectedTickets(JQL Object having tickets connected to them that match given JQL
query) query are returned.

This query runs a JQL query (labels IS empty) on all connected tickets, and then returns objects
based on the results.
Using the objectTypeAndChildren() function
This function is used to return objects (and their children) of a specific object type.

Name Description

objectTypeAndChildren(Name Filter objects based on the object type specified by

) the Name and its children. If the name contains spaces, make
sure you enclose it within a pair of double quotes.

objectTypeAndChildren(ID) Filter objects based on the object type specified by the ID and
its children.

An IQL query that returns all objects and child objects from the "Asset Details" object type.
Functions, references, and IQL can be combined in powerful ways. For example, you could add
multiple object references to a custom field attached to an object, and then search those
references for a specific key:
object HAVING inboundReferences(Key IN (${MyCustomField${0}}))
Or a specific label, by using dot notation:
object HAVING inboundReferences(Label IN (${Portfolios.label${0}}))
Note that the above two queries make use of Insight placeholders. Read more about them here.

You can write out these functions using their long names (inboundReferences), or as
abbreviations (inR).
They do the same thing!
 Please observe that this powerful function may produce results that are not obvious at the first
sight especially when complex queries, that uses for example negation, are constructed. To help
interpret them one should think about the query as a two step action:

1. JQL execution
2. IQL execution operating on the JQL result.

To avoid confusion please remember that Insight Object Detail View

presents  Unresolved connected tickets by default.
 Ordering
You can order the results of your query by adding the following suffix to any IQL:
order by [AttributeName|label] [asc|desc]

 If you do not specify an order by clause, the default will be ascending order by
the label attribute of an object type.
 If the attribute specified in the order by clause is of the object reference type you can use
dot notation to order by attributes on the referenced object.  E.g. if you want to order by the
referenced Department object of an Employee object, you can mention the clause like: order by
Employee.Department. This can be done in unlimited depth. However, note that the every dot in
the order by clause will decrease the performance of that particular IQL. 
 Missing values will appear at the top of the list. This will hold true if the order in the
query is ascending order : "asc".
 The attribute name specified in the IQL must exist in Insight. If not, the IQL will be
considered invalid. The attribute name is case sensitive.
 If the results do not contain the attribute specified in the "order by" clause the order of
the objects returned will be arbitrary. 
 The placeholder label can be used instead of the attribute name to order the objects by
their configured label. 
 You can order search results by more than one attribute.

These search results are ordered in descending order by their keys.