アセット クエリ言語 (AQL) 構文を使用する

Assets Query Language (AQL) is a language format used in Assets to create search queries for one or more objects. Using AQL, you can return any object or group of objects in a search, filter objects, modify objects, create custom fields, automate processes, and more.

AQL can be used in the Advanced AQL search or within an object custom field. It is one of Assets' most powerful and dynamic features.


基本的な構文

The basic syntax of an AQL query is <attribute> <operator> <value/function>. When the attributes of the objects match the operator and value specified, one or more objects will be returned by the query.

Example: Owner = "Ted Anderson"

This AQL query would return all objects where the Owner is Ted Anderson. Note the quotations around "Ted Anderson" because there is a space in the value.

特殊文字の構文

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

  • AQL では、大文字と小文字が区別されません

  • 値または属性にスペースが含まれている式を使用する場合は、上記の "Ted Anderson" の例のように、値を囲む引用符を含める必要があります。

  • If you are using an expression where the value or attribute contain quotation marks, you must escape the quotes by preceding them with backslashes. For example, if you have an object name such as 15" Screen, to search for it enter: 15\” Screen

  • AQL で指定する属性名は、アセット スキーマに存在する必要があります。そうでない場合、AQL は無効とみなされます。

AQL has a defined syntax that must be entered exactly. Here are some key guidelines:

  • AQL is not case-sensitive.

  • If the value or attribute contains spaces, enclose it in quotations. For example: "Ted Anderson".

  • If the value or attribute contains quotation marks, escape them using backslashes. For example, for an object name like 15" Screen, use: 15\” Screen.

  • The attribute name you specify in the AQL must exist in your Assets schema. If not, the AQL will be invalid.

AQL は次のタスクを実行する際に役立ちます。


ドット表記

Dot notation in AQL is used to traverse a reference chain of objects. The format <attribute>.<attribute> <operator> <value/function> allows you to return information based on objects referenced by a parent object.

For example: “Belongs to Department”.Name = HR

Here, the Employee object type has a referenced attribute called "Belongs to Department". This query will return all employees who belong to the HR department.

Since the referenced attribute contains spaces, it is enclosed in double quotes for proper formatting.


キーワード

In AQL, you can use keywords to return objects based on their properties rather than specific attributes. The syntax is as follows: <keyword> <operator> <value/function>

For instance, to return all objects of a specific object type, you can use the objectType keyword.

Example: objectType = “Employee”

The table below lists supported keywords and examples:

キーワード

説明

objectSchema

検索結果を次のように特定のオブジェクト スキーマ名に制限できます。objectSchema = "ITSM Schema".

objectSchemaId

検索結果はオブジェクト スキーマ ID に制限できます。例:objectSchemaId in (1, 2).

objectType

検索結果は次のように特定のオブジェクト タイプ名に制限できます。objectType = "Employment Start Date".

objectTypeId

検索結果はオブジェクト タイプ ID に制限できます。例:objectTypeId in (1, 2).

object

オブジェクトの検索は次のように制限できます。"object having inboundReferences()" では、インバウンド参照を持つすべてのオブジェクトを検索します。

objectId

次のように、オブジェクト ID でオブジェクトを検索できます。"objectId = 114".オブジェクト ID はオブジェクトのキーにある番号ですが、プレフィックスがありません。たとえば、オブジェクトのキーが ITSM-1111 の場合、プレフィックスは ITSM でありオブジェクト IDは 1111 です。

"Host" オブジェクト タイプを持つすべてのオブジェクトを返す AQL クエリは次のとおりです。

objectType = "Host"

If you're in the User role, you won’t have access to the object type ID or schema ID. You can request these values from your Administrator or Manager to perform your queries.

Alternatively, instead of using the objectId, you can search using the Key attribute for any object type to find a specific object.

For example: Key = "ITSM-1111"

This query will return the unique object whose key is ITSM-1111.


演算子

Operators in AQL help you create more detailed and logical expressions for querying objects. Here’s a table that describes the operators supported:

演算子

説明

AQL クエリの例

=

大文字と小文字を区別しない値の等価テスト。

Office = Stockholm

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

==

大文字と小文字を区別する値の等価テスト。

Office==Stockholm

Office 属性に、入力した大文字/小文字を考慮して Stockholm と等しい値があるかどうかを確認します。

!=

不等式テスト

objecttype=Employee と Office!=Stockholm

Employee オブジェクトに、値が Stockholm と等しくない属性 Office があるかどうかを確認します。

<

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

Price < 2000

Price2000 ドル未満かどうかを確認します。

>

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

Price > 2000

Price2000 ドルを超えているかどうかを確認します。

<=

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

Price <= 2000

Price2000 ドル以下かどうかを確認します。

>=

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

Price >= 2000

Price が 2000 ドル以上かどうかを確認します。

like

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

objecttype=Employees と 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").

StockholmOslo、または San Jose のいずれかの値を持つ Office タイプのすべてのオブジェクトを返します。

not in()

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

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

StockholmOslo、または San Jose のいずれかの値を持たない Office タイプのすべてのオブジェクトを返します。

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.

Office タイプの値が存在するかどうかをチェックして、それに応じて結果を返します。

"Office is not EMPTY"

Office タイプの値が空ではないかどうかを確認します。

dot operator(.)

オブジェクトの Referenced タイプ属性にナビゲートできます。

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

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

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

order by 句。

Country.Office = Stockholm

ここで、ドット演算子は属性 Country で参照されるオブジェクト Office に移動して、Office を値 Stockholm と比較します。

having

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

object having inboundReferences()

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

not having

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

object not having inboundReferences()

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


組み合わせ演算子

You can use operators like AND and OR to combine multiple conditions and create more complex AQL queries. Here’s an example:

objectType = "Host" AND "Operating System" = "Ubuntu (64-bit"

関数 

You can use different functions to supply dynamic values to AQL queries.

タイプ

関数名

説明

日時

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

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

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

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

(例: 次のものを含むクエリ: objectType = Employees and "Employment End Date" < endOfMonth(-90d)

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

(例: また、将来の日付を確認できます。たとえば、ソフトウェアのライセンスの有効期限が年末のいつまでに期限切れになるかを確認します。クエリは次のようにできます。licenseEndDate = endOfYear()

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

ユーザー

 

currentUser()

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

例: objecttype = Computer and User = currentUser()

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

currentReporter()

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

例: User = currentReporter()

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

user(user1, user2, ..)

関数の引数リストで指定したユーザーへの参照を持つオブジェクトをフィルタリングできます。フィルタリングに使用する属性は、User タイプである必要があります。 

この関数は、フィルタリングする User タイプ属性が複数の値を許可する場合、つまりこのカーディナリティが複数の場合のみ、複数の引数で機能します。

(例: オブジェクト タイプ Team には属性 Member があります。この属性は User タイプです。さらに、この属性のカーディナリティは 3 と設定されています。ユーザー adminmanager がメンバーである一連の Team オブジェクトを検索する場合は、以下のクエリを記述できます。

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

グループ

group(group1, group2,...)

特定のグループ内のユーザーに接続されている任意のオブジェクトをフィルタリングできます。フィルタリングに使用する属性は、User タイプである必要があります。

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

 

user(user1, user2, ...)

特定のグループ内のユーザーに接続されている任意のオブジェクトをフィルタリングします。フィルターに使用する属性は、Group タイプである必要があります。

Group having user("currentReporter()")

Project

currentProject()

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

例: Project = currentProject()


参照関数

Reference functions in AQL allow you to run a query on a subset of objects, typically of a specific reference type. They take two arguments: an AQL query and an optional reference-type argument.

  • AQL argument: This is the query you want to run, which could include other reference functions.

  • Reference type argument: This is optional and allows you to limit the query to a particular reference type.

シリアル番号

名前

説明

a

  • inboundReferences(AQL)

  • inR(AQL)

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

e.g. An AQL query like: object having inboundReferences() will return all objects having inbound references since the empty AQL argument to the function will match all inbound referenced objects.

ただし、object having inboundReferences(Name="John") のようなクエリの例では、属性 Name があり Name の値が「John」のようなインバウンド参照オブジェクトのあるすべてのオブジェクトを返します。

B

  • inboundReferences(AQL, referenceTypes)

  • inR(AQL, refTypes)

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

これを使用すると、参照タイプを 1 つ以上の値として指定することによって、インバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。

参照タイプは、オブジェクト タイプの参照オブジェクトを定義するときに属性に指定する [追加値 (Additional Value)] フィールドです。

e.g. An AQL query like this: object having inR(objectType = "File System", refType IN ("Depends"))

「File System」というインバウンド参照オブジェクトがあり、その File System オブジェクトの参照タイプが 「Depends」であるオブジェクトを返します。

Similarly, an AQL query like: object having inR(objectType = "File System", refType IN ("Depends", "Installed", "Using"))

File System というインバウンド参照オブジェクトがあり、その File System オブジェクトの参照タイプが Depends、Installed、Using のいずれかであるオブジェクトを返します。

c

  • outboundReferences(AQL)

  • outR(AQL)

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

e.g. An AQL query like: object having outboundReferences() will return all objects having outbound references since the empty AQL argument to the function will match all outbound referenced objects.

ただし、bject having outboundReferences(Name="John") のようなクエリの例では、属性 Name があり、Name の値が "John" のようなアウトバウンド参照オブジェクトのあるすべてのオブジェクトを返します。

d

  • outboundReferences(AQL, referenceTypes)

  • outR(AQL, refTypes)

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

これを使用すると、参照タイプを 1 つ以上の値として指定することによって、アウトバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。

参照タイプは、オブジェクト タイプの参照オブジェクトを定義するときに属性に指定する [追加値 (Additional Value)] フィールドです。

e.g. An AQL query like this: object having outR(objectType = "Employees", refType IN ("Location"))

アウトバウンド参照オブジェクト Employees があり、その Employees オブジェクトの参照タイプが "Location" であるオブジェクトを返します。

Similarly, an AQL query like: object having outR(objectType = "Employees", refType IN ("Location", "Country"))

アウトバウンド参照オブジェクト Employees があり、その Employees オブジェクトの参照タイプが Location, Country のいずれかであるオブジェクトを返します。

connectedTickets() 関数の使用

The connectedTickets() function in AQL is used to filter objects that have Jira work items connected to them. You can specify a JQL query to filter the specific Jira work you want to include in your search. If no JQL query is provided, the function will return all objects that have connected Jira issues.

You must provide a JQL as an argument to that AQL function (e.g. object having connectedTickets(Project = VK)).

The connectedTickets() function does not work with the Assets macro in Confluence. Learn more about displaying Assets data in Confluence

名前

説明

connectedTickets(JQL query)

指定の JQL クエリに一致するチケットが接続されているオブジェクトが返されます。

たとえば、クエリ: object HAVING connectedTickets(labels is empty)

は JQL クエリ (labels is empty) を接続されているすべてのチケットで実行して、その結果に基づいてオブジェクトを返します。

objectTypeAndChildren() 関数を使用する

The objectTypeAndChildren() function in AQL is used to return objects of a specific object type along with their associated child objects. This function is useful when you want to retrieve not just a parent object but also its related child objects within the same query.

名前

説明

objectTypeAndChildren(Name)

Name とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。名前にスペースが含まれている場合は、必ず二重引用符で囲んでください。

objectTypeAndChildren(ID)

ID とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。

This AQL query returns all objects and child objects from the "Asset Details" object type:

objectType in objectTypeAndChildren("Asset Details")

参照、関数、AQL を組み合わせる

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

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

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

object HAVING inboundReferences(Label IN (${Portfolios.label${0}}))

These above two queries make use of Assets placeholders. Learn more about Assets placeholders.

This powerful function can produce results that may not be immediately obvious, especially when dealing with complex queries that involve operations like negation. To interpret the results accurately, it’s helpful to think of the query process as a two-step action:

  1. JQL execution: The first step filters the relevant Jira work items using JQL.

  2. AQL execution: The second step applies the AQL logic to the results returned by the JQL query, operating on the filtered set of work items.

By breaking it down into these steps, you can better understand and refine the query results, especially when dealing with more intricate or negated conditions.

By default, the Assets object detail view presents Unresolved connected tickets.


発注

You can order the results of your AQL query by appending the following suffix:

pgsqlCopyEditorder by [AttributeName|label] [asc|desc]

  • If no order by clause is specified, the default order is ascending by the object type's label attribute.

  • If the attribute in the order by clause is a reference type, you can use dot notation to order by an attribute of the referenced object.

    • For example, to order by the referenced Department of an Employee object, use: order by Employee.Department. This can be done in unlimited depth, but each additional dot will impact query performance.

  • Missing values will appear at the top of the list when using ascending order (asc).

  • The attribute used in the order by clause must exist in the Assets schema. If it does not, the AQL will be invalid.

  • You can use the label placeholder to order objects by their configured label.

  • 複数の属性による順序づけはサポートされていません。

If the attribute specified in the order by clause is not found in the results, the order will be arbitrary.

 

さらにヘルプが必要ですか?

アトラシアン コミュニティをご利用ください。