This documentation is for Insight for Jira Cloud only.



IQL is a logical language that can be used to return a list of Insight objects that match the statement. IQL can be very simple, or you can use variables, operators, and functions to create a dynamic and powerful query. In this section, you will learn the general syntax of IQL queries and how to use their functions.

General syntax

A standard IQL query includes an attribute, an operator, and a value or function: 

<attribute> <operator> <value/function>

Dot-notation can also be used to reference the attributes of objects.

 <attribute>.<attribute> <operator> <value/function>
  • Attributes in IQL are case-sensitive.
  • Attributes containing spaces must be surrounded by quotes.
  • If you are searching for an object that itself contains quotes, you must escape the quotes using a forward slash. For example, if you were searching for a 15-inch (") screen, you would search for:
Name= "15\" Screen"

Ordering IQL results

You can order the results of your IQL query using the following syntax:

order by [AttributeName|label] [asc|desc]
  • 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. This can be done in unlimited depth. Note that the every dot in the order by clause will decrease the performance of that particular IQL. 
order by "My object reference"."Attribute on referenced object" asc
  • Values that are missing will be considered to be last (using asc) or first (using desc).
  • 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 filtered objects does not contain the attribute specified in the order by clause the order of the objects returned will be arbitrary. 

Placeholders

Placeholders are used to refer to an object type, object, or attribute.

PlaceholderDescription
objectType

Limit the search result to a specific object type.

objectType = Servers
objectTypeId

Limit the search results by object type ID.

objectTypeId in (1, 2) 
anyAttribute

Search on any attribute.

anyAttribute = 123.123.123.123
object

Limit the search to the object.

object having inboundReferences()

Operators

Standard logical operators are accepted, as well as reference operators like "having" and "not having".

OperatorDescription
=

The value is equal (not case sensitive) to input.

"Operating System" = "Linux"
<

The value is less then input.

"System Date" < "1/Nov/18"
>
The value is more then input.
<=
The value is less or equal then value.
>=
The value is more or equal then value.
like

The input is a subset of value.

Name like "Micro"
not like
The input does not contain the value.
in
The input is a set of values.
!=
The value is not equal to input.
not in
The input is not a set of values.
startswith
The input starts with input.
endswith
The input ends with input.
is

The input is something or not. It is followed by "empty" or "not empty". It represents if a value is existing or not.

Manager IS NOT EMPTY
"License Date" IS EMPTY
.The attributes reference attribute is queried.
==The value is strict (case sensitive) equal to input.
having
The input is having a property like inbound references.
not having
The input is not having a property like outbound references.
Logic operatorDescription
AND
Combines IQL expressions where both parts of the expression must apply.
OR
Combines IQL expressions where either part of the expression may apply.

Date-time functions

Date-time functions can prove very useful in IQL. The following functions are available.

Date-time functionsDescription

now()

Returns the current date.

startOfDay()

Returns the start time of the current day.

endOfDay()

Returns the end time of the current day

startOfWeek()

Returns the start time of the current week.

endOfWeek()

Returns the end time of the current week.

startOfMonth()

Returns the start time of the current month.

endOfMonth()

Returns the end time of the current month.

startOfYear()

Returns the start date of the current year.

endOfYear()

Returns the end date of the current year.

We use m for minutes, h for hours, d for days and w for weeks to represent relative time, e.g. Created > "-2h 15m" returns all objects created in the last 2 hours and 15 minutes.

User functions

User functions return information linked to a user, reporter, or multiple users.

The currentUser() and currentReporter() functions do not currently work as part of an Asset Type Configuration.

User FunctionsDescription
currentUser()
Filter on user attributes connected to the current (logged in) user. Attribute needs to be of type User.
currentReporter() 
Filter on user attributes connected to current reporter in custom fields. Attribute needs to be of type User.
user(user1, user2, ...) 

Filter on user attributes having the specified users.

User in group("jira-users", "jira-administrators")
User having user("admin")

Group functions

Group functions return information linked to one or more groups.

Group FunctionsDescription
group(group1, group2, ...)

Filter on any object connected to a user within a specific group.

Group having user("currentReporter()")
user(user1, user2, ...)
Filter on any object connected to a user within a specific group.

Project functions

Project functions return information linked to the current project. This only works within the context of a ticket.

Project FunctionsDescription
currentProject()

Filter on any object connected to the current project in a custom field. Works only in the context of a ticket.

Project = currentProject()

Reference functions

The reference functions can take two arguments: an IQL and/or Reference Types Names. The IQL argument can be an arbitrary IQL including an IQL with reference function. The Reference Type argument is optional.

Reference FunctionsDescription
inboundReferences(IQL)
inR(IQL)

Filter objects having inbound references where the objects referencing to the object matches the IQL, e.g. object having inboundReferences() filters all objects having inbound references since the empty IQL will match all objects. If the query is changed to object having inboundReferences(Name="My Name") all objects that are referenced by an object with the name "My Name" are filtered.

outboundReferences(IQL)
outR(IQL)
Filter objects having outbound references where the referenced objects match the IQL, e.g. object having outboundReferences() filters all objects having outbound references since the empty IQL will match all objects.
inboundReferences(IQL, referenceTypes)
inR(IQL, refTypes)

Filter object having inbound references where the objects referencing to the object matches the IQL. E.g. object having inboundReferences() will filter all objects having inbound references since the empty IQL will match all objects. If the query is changed to object having inboundReferences(Name="My Name") all objects that is referenced by an object with the name My Name will be filtered.

The Reference Type argument can be simple or advanced:

simple can take only one Reference Type name as parameter and looks like "Installed", e.g. object having inR("", "Installed")

advanced has the following structure: argumentName + operator + ("value 1", "value 2", "value 3"), where

      • argumentName: refType or referenceType
      • operator: IN or NOT IN
outboundReferences(IQL, referenceTypes)
outR(IQL, refTypes)

Filter object having outbound references where the referenced objects match the IQL. E.g. object having outboundReferences() will filter all objects having outbound references since the empty IQL will match all objects.

The Reference Type argument can be simple or advanced:

simple can take only one Reference Type name as parameter and looks like "Installed"

e.g. object having outR("", "Installed")

advanced has the following structure: argumentName + operator + ("value 1", "value 2", "value 3"), where

      • argumentName: refType or referenceType
      • operator: IN or NOT IN
    e.g. object having inR(label = application, refType IN ("depends", "installed", "using"))

Connected tickets 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.

Connected tickets function

Description

connectedTickets()

All objects having tickets connected to them are returned.

object having connectedTickets()
connectedTickets(JQL)

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

object having connectedTickets(labels is not empty)

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 interprete them one should think about the query as a two step action: 1. JQL execution 2. IQL execution operating on the JQL result.

Object type functions

These functions return a set of all object and their children based upon the object type name or ID.

Object type functionDescription
objectTypeAndChildren(Name) 

Filter objects based on the object type specified by the Name and its children.

objectType in objectTypeAndChildren("Object Type Name")
objectTypeAndChildren(ID)
Filter objects based on the object type specified by the ID and its children.
  • No labels