要約

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

In this article

IQL (Insight クエリ言語) は、Insight で 1 つ以上のオブジェクトの検索クエリを作成するための言語形式です。IQL によって、Insight で任意のオブジェクトまたはオブジェクトのグループを検索で返す、オブジェクトを絞り込む、オブジェクトを変更、カスタム フィールドを作成、自動化、事後操作などを行えます。

This is one of Insight's most powerful and dynamic features.




基本的な構文

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.

特殊文字の構文

IQL には定義された構文があり、正確に入力する必要があります。

  • IQL で大文字と小文字は区別されます。
  • 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"
  • IQL で指定する属性名は、Insight スキーマに存在する必要があります。そうでない場合、IQL は無効とみなされます。属性名は大文字と小文字が区別されます。

IQL can be helpful in accomplishing the following tasks:




ドット表記

ドット表記は、オブジェクトの参照チェーンを下に移動するために IQL で使用されます。フォーマット <attribute>.<attribute> <operator> <value/function> は、親オブジェクトで参照されるオブジェクトに基づく情報を返します。

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.

参照される属性にはスペースが含まれているため、二重引用符で囲まれています。







キーワード

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.

キーワード説明
objectSchemaYou 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.
objectSchemaIdYou can limit the search result on object schema ids. e.g. objectSchemaId in (1, 2).
objectTypeYou 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検索結果はオブジェクト タイプ ID に制限できます。例: 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 having inboundReferences()" では、インバウンド参照を持つすべてのオブジェクトを検索します。
objectId

オブジェクトをオブジェクト ID で検索できます (例: "objectId = 114")。オブジェクト ID はオブジェクトのキーにある番号ですが、プレフィックスがありません。たとえば、オブジェクトのキーが ITSM-1111 の場合、プレフィックスは ITSM でオブジェクト IDは 1111 です。スキーマ全体でオブジェクトを移動するとキーが変更される可能性があることにご注意ください。 

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




演算子

演算子を使用すると、より詳細な論理式を作成できます。

次の表は、IQL でサポートされている演算子を示します。

演算子説明 IQL クエリの例
=Equality test for case insensitive values.

"Office = Stockholm"

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

==Equality test for case sensitive values.

"Office==Stockholm"

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

                         !=不等式テスト

objecttype-Employee と Office!=Stockholm

Checks if the Employee object has an attribute Office whose value is NOT equal to Stockholm.

<指定の値より小さいかどうかのテスト。

"Price < 2000"

Checks if the Price is less than 2000 dollars.

>指定の値より大きいかどうかのテスト

"Price > 2000"

Checks if the Price is greater than 2000 dollars.

<=指定の値以下かどうかのテスト

"Price <= 2000"

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

>=指定の値以上かどうかのテスト

"Price >= 2000"

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

いいね！クエリ内の入力のサブセットと値を照合します。大文字と小文字は区別されません。

"objecttype=Employees and Office like Stock"

Returns all objects of Employees type which have an Office attribute value that contains the characters 'Stock' or 'STOCK'

not likeクエリの入力のサブセットと一致する値を除外します。

"objecttype=Employees and Office not like Stock"

Returns all objects of Employees type which have an Office attribute value that DO NOT contain the characters 'Stock'

in()指定された引数と一致するものを検索して、結果を返します。

Office in ("Stockholm", "Oslo", "San Jose")

Returns all objects of Office type which HAVE one of these values: Stockholm, Oslo or San Jose.

not in()指定された引数との一致が見つかった結果を除外します。

Office not in ("Stockholm", "Oslo", "San Jose")

Returns all objects of Office type which DO NOT HAVE one of these values: Stockholm, Oslo or San Jose.

startswith値が指定された入力で始まる一致を検索します。大文字と小文字は区別されません。

"Office startsWith St"

Returns results which match values of Office type starting with the characters "St" or "ST"

endswith値が指定された入力で終わる一致を検索します。大文字と小文字は区別されません。

"Office endsWith St"

Returns results which match values of Office type ending with the characters "St" or "ST"

is

値が存在するかどうかをテストするのに役立ちます。

"Office is EMPTY"

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 the Referenced types attributes for an object.

この演算子は一般に、次の場合に使用されます。

inboundReferences() または inR() 関数。

outboundReferences() または outR() 関数。

order by 句。

"Country.Office = Stockholm"

The dot operator here navigates to the referenced object Office in the attribute Country and compares Office with the value Stockholm.

havinginboundReferences() または outboundReferences() 関数で使用

"object having inboundReferences()"

インバウンド参照を持つすべてのオブジェクトを返します。

not havinginboundReferences() または outboundReferences() 関数で使用

"object not having inboundReferences()"

インバウンド参照を持つすべてのオブジェクトを除外して、結果を返します。


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.














組み合わせ演算子

AND/OR などの演算子を使用すると、さらに大規模で複雑な IQL 式を作成できます。

An IQL query that includes two statements linked with the AND operator.





関数 

複数の関数を使用して、IQL 式に動的な値を指定できます。

タイプ関数名説明

日付

now()
startOfDay()
endOfDay()
startOfWeek()
endOfWeek()
startOfMonth()
endOfMonth()
startOfYear()
endOfYear()

幅広い関数を使用して、日時を含むクエリを記述できます。

m は分、h は時間、d は日数、w は週数をそれぞれ表します。

例: Created > "now(-2h 15m)" のような条件のあるクエリは、直近 2 時間 15 分以内に作成されたすべてのオブジェクトを返します。

e.g. A query containing something like: objectType = Employees and "Employment End Date" < endOfMonth(-90d)

Employment End Date が今月の最終日までの 90 日前になるすべての Employee オブジェクトを返します。

e.g. You may also check for an upcoming date, e.g. check when the license of a software expires by the end of the year. Your query can then include something like : licenseEndDate = endOfYear()

他のすべての日付関数も同様の方法で使用できます。

IP アドレス

CIDR(IP RANGE)

CIDR(IP RANGE) - IP 範囲でのフィルター

例:
"IP Address" IN CIDR("192.0.0.0/8")
"IP Address" IN CIDR("192.168.0.0/16")

ユーザー



currentUser()

IQL クエリでこの関数を呼び出すと、現在の (ログイン) ユーザーに接続されているユーザー属性をフィルタリングできます。クエリでフィルタリングに使用する属性は、User タイプである必要があります。

例: objecttype = Computer and User = currentUser()


この関数は、CurrentUser が選択されている、つまりユーザーがログインしているときに機能します。

currentReporter()

IQL クエリでこの関数を呼び出すと、カスタム フィールドの現在の報告者に接続されているユーザー属性をフィルタリングできます。クエリでフィルタリングに使用する属性は、User タイプである必要があります。

e.g. User = currentReporter()


この関数は、課題が選択されている場合にのみ機能して、現在の課題に表示される報告者を参照します。

user(user1, user2, ..)

You can filter on objects which have a reference to the users that you provide in the argument list of the function. The attribute used to filter must be of User type. 

This function will work with multiple arguments only if the User type attribute that you filter on allows 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 type. Additionally, this attribute has been configured to have a cardinality of 3. If you want to search a set of Team objects where the users: admin and manager are its members, you can write the following query:

objecttype=Team and Member having user("admin", "manager")

グループ

group(group1, group2, ...)

You can filter on any object connected to a user within a specific group. The attribute used to filter has to be of User type.

例:User in group("jira-users", "jira-administrators")

user(user1, user2, ...)

Filter on any object connected to a user within a specific group. The attribute used to filter has to be of Group type.

例 Group having user("currentReporter()")

プロジェクト

currentProject()

現在選択されている Jira プロジェクトに接続されているオブジェクトを絞り込みます。チケットのコンテキスト内でのみ機能します。

例: Project = currentProject()

This function will only work when a project is currently selected.





参照関数

参照関数は、IQL や参照型引数の 2 つの引数を取る関数です。基本的に、参照関数を使用すると、特定の参照タイプのオブジェクトのサブセットに対して IQL クエリを実行できます。このようなクエリは、オブジェクト合計数が小さいサブセットで実行して、結果や処理時間を制限できます。

  • IQL 引数には、参照関数を持つ IQL を含む任意の IQL を指定できます。 
  • 参照型引数はオプションです。
Sr. No名前説明
a
  • inboundReferences(IQL)
  • inR(IQL)

インバウンド参照のあるオブジェクトをフィルタリングします。この参照は関数への引数として提供された IQL クエリに一致するものです。

例: object having inboundReferences() のような IQL クエリは、関数に対する空の IQL 引数がすべてのインバウンド参照オブジェクトと一致するため、インバウンド参照のあるすべてのオブジェクトを返します。

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
  • inboundReferences(IQL, referenceTypes)
  • inR(IQL, refTypes)

これは、(a) で説明されている inboundReferences(IQL) 関数から派生したものです

Using this, you can filter the inbound referenced objects further by providing the Reference Type as a single or multiple 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".

同様に、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
  • outboundReferences(IQL)
  • outR(IQL)

アウトバウンド参照のあるオブジェクトをフィルタリングします。この参照は、関数への引数として提供された IQL クエリに一致するものです。

例: object having outboundReferences() のような IQL クエリは関数への空の IQL 引数がすべてのアウトバウンド参照オブジェクトと一致するため、アウトバウンド参照のあるすべてのオブジェクトを返します。

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
  • outboundReferences(IQL, referenceTypes)
  • outR(IQL, refTypes)

これは、(b) で説明されている outboundReferences(IQL) 関数から派生したものです。

Using this, you can filter the outbound referenced objects further by providing the Reference Type as a single or multiple 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".

同様に、object having outR(objectType = "Employees", refType IN ("Location", "Country")) のような IQL クエリは

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".

connectedTickets() 関数の使用

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.

名前説明
connectedTickets()チケットが接続されているすべてのオブジェクトが返されます。
connectedTickets(JQL query)Object having tickets connected to them that match given JQL query are returned.


This query runs a JQL query (labels IS empty) on all connected tickets, and then returns objects based on the results.

objectTypeAndChildren() 関数を使用する

この関数は、特定のオブジェクト タイプのオブジェクト (およびその子) を返すために使用されます。

名前説明
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)ID とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。

An IQL query that returns all objects and child objects from the "Asset Details" object type.


関数、参照、IQL は、さまざまな優れた方法で組み合わせられます。たとえば、あるオブジェクトに添付されている 1 つのカスタム フィールドに複数のオブジェクト参照を追加して、これらの参照を次のような特定のキー:

object HAVING inboundReferences(Key IN (${MyCustomField${0}}))

または、ドット表記を使用して次のような特定のラベルで検索できます。

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.



















発注

任意の 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. 
  • 見つからない値はリストの上部に表示されます。これは、クエリ内の順序が昇順である場合に true になります: "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.
  • 結果に「order by」句で指定された属性が含まれていない場合、返されるオブジェクトの順序は任意になります。 
  • 属性名の代わりにプレースホルダー ラベルを使用して、設定されたラベルでオブジェクトを並べ替えられます。 


これらの検索結果は、キーの降順に並べられます。





  • ラベルなし