Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata


Artifactory Query Language (AQL) is specially designed to let you uncover any data related to the artifacts and builds stored within Artifactory. Its syntax offers a simple way to formulate complex queries that specify any number of search criteria, filters, sorting options, and output parameters. AQL is exposed as a RESTful API which uses data streaming to provide output data resulting in extremely fast response times and low memory consumption. Currently, AQL can only extract data that resides in your instance of Artifactory, so it runs on local repositories, remote repository caches and virtual repositories.

Here are a few simple examples:

// Return all artifacts of the "artifactory" build.
// Return all builds that have a dependency with a license that is not Apache.
// Return all archives containing a file called "org/artifactory/Main.class".
items.find({"archive.entry.name":{"$eq":"Main.class"} , "archive.entry.path":{"$eq":"org/artifactory"}})

Here is a slightly more complex example.

// Return all entries of any archive named "Artifactory.jar" from any build named "Artifactory" with 
// build number 521.
archive.entries.find( {

Page Contents

Here is an another example that shows the full power of AQL to mine information from your repositories in a way that no other tool can match.

// Compare the contents of artifacts in 2 "maven+example" builds  
 Click to view the output of this query...

  "results" : [ {
  "repo" : "ext-snapshot-local",
   "path" : "org/jfrog/test/multi2/3.0.0-SNAPSHOT",
    "name" : "multi2-3.0.0-20151012.205507-1.jar",
    "type" : "file",
    "size" : 1015,
    "created" : "2015-10-12T22:55:23.022+02:00",
    "created_by" : "admin",
    "modified" : "2015-10-12T22:55:23.013+02:00",
    "modified_by" : "admin",
    "updated" : "2015-10-12T22:55:23.013+02:00",
    "archives" : [ {
        "entries" : [ {
            "entry.name" : "App.class",
            "entry.path" : "artifactory/test"
    }, {
           "entry.name" : "MANIFEST.MF",
          "entry.path" : "META-INF"
        } ]
    } ]
  "repo" : "ext-snapshot-local",
  "path" : "org/jfrog/test/multi2/3.0.0-SNAPSHOT",
   "name" : "multi2-3.0.0-20151013.074226-2.jar",
   "type" : "file",
   "size" : 1015,
   "created" : "2015-10-13T09:42:39.389+02:00",
   "created_by" : "admin",
   "modified" : "2015-10-13T09:42:39.383+02:00",
   "modified_by" : "admin",
   "updated" : "2015-10-13T09:42:39.383+02:00",
   "archives" : [ {
      "entries" : [ {
         "entry.name" : "App.class",
         "entry.path" : "artifactory/test"
      }, {
         "entry.name" : "MANIFEST.MF",
         "entry.path" : "META-INF"
   } ]
} ]
} ],
"range" : {
"start_pos" : 0,
"end_pos" : 2,
"total" : 2


AQL is constructed as a set of interconnected domains as displayed in the diagram below. You may run queries only one of the domains at a time, and this is referred to as the Primary domain of the query. 

Currently, the following are supported as primary domains: ItemBuild, Entry, and Promotion. i.e., your queries may be of the form: items.find(...), builds.find(...)archive.entries.find(...), or build.promotions.find(...).

You may use fields from other domains as part of your search criteria or to specify fields to display in the output, but in that case, you need to follow the conventions described in Using Fields.

AQL Domains

Supported Domains

AQL was introduced in Artifactory V3.5.0 with support for Item as a primary domain with its attached Property, as well as Statistic as a secondary domain. Later versions of Artifactory introduced additional domains that can be included in queries. The following table summarizes from which version each domain is accessible.









The query corresponding to the primary domain. Must be one of items, builds or entries.
The search criteria in valid JSON format
(Optional) There is a default set of fields for query output. This parameter lets you specify a different set of fields that should be included in the output
(Optional) The fields on which the output should be sorted, and the sort order. A default set of fields and sort order is defined for each domain.
(Optional) The maximum number of records that should be extracted. If omitted, all records answering the query criteria will be extracted.
(Optional) The offset from the first record from which to display results (i.e. how many results should be skipped for display)


Sort, limit and offset elements only works in the following cases:

  • Your query does not have an include element
  • If you do have an include element, you only specify fields from the primary domain in it.

For example, in the following query, sort, limit and offset will not work because the primary domain is item, but the include element specifies that fields from the the artifact, module and build domains should be displayed:


Using Fields

Any fields from your primary domain can be used directly anywhere in your query. If you use fields from other domains, they must be specified using a complete relation path from the primary domain.

For example, to find all items in a repository called "myrepo" you would use:

items.find({"repo": "myrepo"})


But to find all items created by modules named "mymodule" you would use:

items.find({"artifact.module.name" : "mymodule"})


And since you may also issue a query from the build domain, to find all builds that generated an item called "artifactory.war", you could also use:

builds.find({"module.artifact.item.name": "artifactory.war"})


To execute an AQL query, use the Artifactory Query Language REST API.

Entities and Fields

You may issue a find request according to the syntax above, and configure your request to display fields from any of the domains.

DomainField NameTypeDescription
itemrepoStringThe name of the repository in which this item is stored
pathStringThe full path associated with this item
nameStringThe name of the item
createdDateWhen the item was created
modifiedDateFile system timestamp indicating when the item was last modified
updatedDateWhen the item was last uploaded to a repository.
created_byStringThe name of the item owner
modified_byStringThe name of the last user that modified the item

The item type (file/folder/any).

If type is not specified in the query, the default type searched for is file

depthintThe depth of the item in the path from the root folder
original_md5StringThe item's md5 hash code when it was originally uploaded
actual_md5StringThe item's current md5 hash code
original_sha1StringThe item's sha1 hash code when it was originally uploaded
actual_sha1StringThe item's current sha1 hash code
sizelongThe item's size on disk
virtual_reposStringThe virtual repositories which contain the repository in which this item is stored.

The archive domain currently contains no fields

entrynameStringThe entry's name
pathStringThe path of the entry within the repository

createdDateWhen the build was promoted
created_byStringThe Artifactory user that promoted the build
statusStringThe status of the promotion
repoStringThe name of the repository to which the build was promoted
commentStringA free text comment about the promotion
userStringThe CI server user that promoted the build
buildurlStringThe URL of the build
nameStringThe build name
numberStringThe build number
createdDateFile system timestamp indicating when the item was last modified
created_byStringThe name of the user who created the build
modifiedDateFile system timestamp indicating when the build was last modified
modified_byStringThe name of the last user that modified the build
property keyStringThe property key
valueStringThe property value
downloadeddateThe last time an item was downloaded
downloadsintThe total number of downloads for an item
downloaded_byStringThe name of the last user to download this item
remote_downloadsintThe total number of downloads for an item from a smart remote repository proxying the local repository in which the item resides
remote_downloadeddateThe last time an item was downloaded from a smart remote repository proxying the local repository in which the item resides
remote_downloaded_byStringThe name of the last user to download this item from a smart remote repository proxying the local repository in which the item resides
remote_originStringThe address of the remote Artifactory instance along a smart remote proxy chain from which the download request originated.
remote_pathStringThe full path along a smart remote proxy chain through which the download request went from the origin instance to the current instance.
artifact   nameStringThe name of the artifact
typeStringThe type of the artifact
sha1StringThe SHA1 hash code of the artifact
md5StringThe MD5 hash code of the artifact
modulenameStringThe name of the module
dependency    nameStringThe name of the dependency
scopeStringThe scope of the dependency
typeStringThe type of the dependency
sha1StringThe SHA1 hash code of the dependency
md5StringThe MD5 hash code of the dependency

Constructing Search Criteria

The criteria element must be a valid JSON format statement composed of the criteria that specify the items that should be returned. It is essentially a compound boolean statement, and only elements for which the statement evaluates to true are returned by the query. 

Each criterion is essentially a comparison statement that is applied either to a field or a property. Please see the full list of Comparison Operators. While each criterion may be expressed in complete general format, AQL defines shortened forms for readability as described below. 

Field Criteria

The general way to specify a criterion on a field is as follows:

{"<field>" : {"<comparison operator>" : "<value>"}}

If the query applied is to a different domain, then field names must be pre-pended by a relation path to the primary domain.

For example:

//Find items whose "name" field matches the expression "*test.*"
items.find({"name": {"$match" : "*test.*"}})
//Find items that have been downloaded over 5 times. 
//We need to include the "stat" specifier in "stat.downloads" since downloads is a field of the stat domain and not of the item domain.
//Find items that have never been downloaded. Note that when specifying zero downloads we use "null" instead of 0.
//We need to include the "stat" specifier in "stat.downloads" since downloads is a field of the stat domain and not of the item domain.

//Find builds that use a dependency that is a snapshot

Fields with "Zero" value in the stat domain

Note that when searching for items that have a "zero" value in the stat domain, you should search for null, not 0. For example, as shown above, when searching for items with zero downloads you specify "null" instead of 0.

Short notation for Field criteria

AQL supports a short notation for search criteria on fields.

 An "equals" ("$eq") criterion on a field may be specified as follows:

{"<field>" : "<value>"}

Find items whose "name" field equals "ant-1.9.4.jar"
Regular notation


Short notation


Properties Criteria

Artifactory lets you attach, and search on properties in three domains: itemsmodules and builds.

The general way to specify a criterion on a property is as follows:


Accessing the right properties

If you are specifying properties from the primary domain of your query, you may simply enter the property key and value as described above. If you are specifying properties from one of the other domains, you need to specify the full relational path to the property.

In the example below, the primary domain is the build domain, but we want to find builds based a property in the item domain, so we must specify the full path to the property:

builds.find({"module.artifact.item.@qa_approved" : {"$ne" : "true"}})

Here are some examples:

//Find items that have been approved by QA"
items.find({"@qa_approved" : {"$eq" : "true"}})
//Find builds that were run on a linux machine"
builds.find({"@os" : {"$match" : "linux*"}})

//Find items that were created in a build that was run on a linux machine.
items.find({"artifact.module.build.@os" : {"$match" : "linux*"}})

Short notation for properties criteria

AQL supports a short notation for search criteria on properties.

An "equals" ("$eq") criterion on a property may be specified as follows:

{"@<property_key>" : "<property_value>"}


Find items with associated properties named "license" with a value that equals "GPL"

Regular notation

items.find({"@artifactory.licenses" : {"$eq" : "GPL"}})

Short notation
items.find({"@artifactory.licenses" : "GPL"})

Compounding Criteria

Search criteria on both fields and properties may be nested and compounded into logical expressions using "$and" or "$or" operators.  If no operator is specified, the default is $and 


Criteria may be nested to any degree

Note that since search criteria can be nested to any degree, you may construct logical search criteria with any degree of complexity required.

Here are some examples:   

//This example shows both an implicit "$and" operator (since this is the default, you don't have to expressly specify it, but rather separate the criteria by a comma), and an explicit "$or" operator. 
//Find all items that are files and are in either the jcenter or my-local repositories. 
items.find({"type" : "file","$or":[{"repo" : "jcenter", "repo" : "my-local" }]})

//Find all the items that are either in a repository called "debian" and whose name ends with ".deb" or are in a repository called "yum" and whose name ends with ".rpm".
					{"artifact.module.build.name" : "my_debian_build"} ,
					{"name" : {"$match" : "*.deb"}}
					{"artifact.module.build.name" : "my_yum_build"} ,
					{"name" : {"$match" : "*.rpm"}}
//Find all items in a repository called "my_local" that have a property with a key called "license" and value that is any variant of "LGPL".
items.find({"repo" : "my_local"},{"@artifactory.licenses" : {"$match" : "*LGPL*"}})

Matching Criteria on a Single Property ($msp)

A search that specifies several criteria on properties may sometimes yield unexpected results. 

This is because items are frequently annotated with several properties, and as long as any criterion is true for any property, the item will be returned in a regular find

But sometimes, we need to find items in which a single specific property answers several criteria. For this purpose we use the $msp (match on single property) operator.

The fundamental difference between a regular find and using the $msp operator is:

  • find will return an item if ANY of its properties answer ALL of the criteria in the search term. 
  • $msp will only return an item if at least ONE of its properties answers ALL of the criteria in the $msp term. 

Here is an example.

Consider two items A and B.

A has a license property with value AGPL-V3

B has two license properties . One is LGPL-2.1, and the other LGPL-2.2

Items with properties

Now let's assume we want to find items that use any variety of GPL license as long as it's NOT LGPL-2.1.

In our example we would expect to get both Items A and B returned since A has AGPL-V3 and B has LGPL-2.2.

As a first thought, we might write our query as follows:

            "@license":{"$match": "*GPL*"},
        	"@license":{"$nmatch": "LGPL-2.1*"}

But this query only returns item A.

Item A is returned because it clearly answers both criteria: "@license":{"$match": "*GPL*"} and "@license":{"$nmatch": "LGPL-2.1*"}

Item B is not returned because it has the property license=LGPL-2.1 which does not meet the criterion of  "@license":{"$nmatch": "LGPL-2.1*"}.

If we use the $msp operator as follows:

			"$msp": [
           		"@license":{"$match": "*GPL*"},
        		"@license":{"$nmatch": "LGPL-2.1*"}

Then both Item A and Item B are returned. 

Item A is returned because it has the @license property AGPL-V3 which meets both the {"@license":{"$match": "*GPL*"}} criterion and the "@license":{"$nmatch": "LGPL-2.1*"} criterion.

Item B is returned because it has the @license property LGPL-2.2 which also meets both the{"@license":{"$match": "*GPL*"}} criterion and the "@license":{"$nmatch": "LGPL-2.1*"} criterion.

Note that the $msp operator works equally well on all domains that have properties: item, module and build.

Comparison Operators

The following table lists the full set of comparison operators allowed:

$nestring, date, int, longNot equal to
$eqstring, date, int, longEquals
$gtstring, date, int, longGreater than
$gtestring, date, int, longGreater than or equal to
$ltstring, date, int, longLess than
$ltestring, date, int, longLess than or equal to
$nmatchstringDoes not match

For time-based operations, please also refer to Relative Time Operators.

Using Wildcards

To enable search using non-specific criteria, AQL supports wildcards in common search functions.

Using Wildcards with $match and $nmatch

When using the "$match" and "$nmatch" operators, the "*" wildcard replaces any string and the "?" wildcard replaces a single character.

"Catch all" Notation on Properties

In addition to supporting "$match"  and "$nmatch", AQL supports a notation that uses wildcards to match any key or any value on properties.

If you specify "@*" as the property key, then it means a match on any key.

If you specify "*" as the property value, then it means a match on any value


Find items that have any property with a value of "GPL"

Regular notation

items.find({"$and" : [{"property.key" : {"$eq" : "*"}}, {"property.value" : {"$eq" : "GPL"}}]})

Short notation



Find any items annotated with any property whose key is "license" (i.e. find any items with a "license" property)

Regular notation

items.find({"$and" : [{"property.key" : {"$eq" : "license"}}, {"property.value" : {"$eq" : "*"}}]})

Short notation

Be careful not to misuse widlcards

Wildcard characters ("*" and "?") used in queries that do not conform to the above rules are interpreted as literals.


To avoid confusion, here are some examples that use the "*" and "?" characters explaining why they are interpreted as wildcards or literals.

QueryWildcard or LiteralExplanationWhat the query returns

Wildcards on fields are allowed with the $match operator. 

All items whose name matches the expression "ant-1.9.4.*"

Wildcards on fields are only allowed with the $match and $nmatch operators.

Only find items whose name is literally "ant-1.9.4.*"



For properties, this short notation is allowed and denotes any value

All items with a property whose key is "license"



This is the short notation replacing the $eq operator for properties, but it does not use the "catch all" notation for properties.

All items with a license whose value is literally "*GPL"


WildcardWildcards on properties are allowed with the $match operator. All items with a license matches the expression "*GPL*"

Date and Time Format

AQL supports Date and Time formats according to a W3C profile of the ISO 8601 Standard for Date and Time Formats.

The complete date and time notation is specified as: 

YYYY-MM-DDThh:mm:ss.sTZD (e.g., 2012-07-16T19:20:30.45+01:00)

Date/Time specified in partial precision is also supported: (i.e. specify just the year, or year and month, year, month and day etc.)

For example, the following query will return all items that were modified after July 16, 2012 at 30.45 seconds after 7:20pm at GMT+1 time zone:

 //Find all the items that have been modified after 2012-07-16T19:20:30.45+01:00
items.find({"modified" : {"$gt" : "2012-07-16T19:20:30.45+01:00"}})

//Find all the builds that have were created after 2012-07-01
builds.find({"created" : {"$gt" : "2012-07-01"}})

For full details, please refer to the W3C documentation.

Relative Time Operators

AQL supports specifying time intervals for queries using relative time. In other words, the time interval for the query will always be relative to the time that the query is run, so you don't have to change or formulate the time period, in some other way, each time the query is run. For example, you may want to run a query over the last day, or for the time period up to two weeks ago. 

Relative time is specified using the following two operators: 

The query is run over complete period up to specified time.
The query is run over period from the specified time until the query is run

Time periods are specified with a number and one of the following suffixes:

 "mills", "ms"
"seconds", "s" 
"days", "d" 
"weeks", "w" 
"months", "mo" 
"years", "y" 

For example, to specify five days, you could use "5d". To specify two weeks, you could use  "2w".

Below are some examples using relative time operators:

//Find all the items that were modified during the last three days
items.find({"modified" : {"$last" : "3d"}})

 //Find all the builds that were created up to two weeks ago (i.e. no later than two weeks ago)
builds.find({"created" : {"$before" : "2w"}})

Specifying Output Fields

Each query displays a default set of fields in the result set, however you have complete control this and may specify which fields to display using an optional include element in your query.

You can even specify to display fields from other entities related to your result set.

Displaying All Fields

Use: .include("*")

For example:

//Find all items, and display all the item fields

Displaying Specific Fields

Each query displays a default set of fields in the output. Using the .include element you can override this default setting and specify any particular set of fields you want to receive in the output.

Use: .include("<field1>", "<field2>"...)

For example:

//Find all items, only display the "name" and "repo" fields
items.find().include("name", "repo")


You can also display specific fields from other entities associated with those returned by the query.

If you specify any field from the item domain, then this will override the default output setting, and only the item fields you expressly specified will be displayed.

If you only specify fields from the property or stat domains, then the output will display the default fields from the item domain, and in addition, the other fields you expressly specified from the property or stat domains.

For example:

//Find all items, and display the "name" and "repo" fields as well as the number of "downloads" from the corresponding "stat" entity
items.find().include("name", "repo", "stat.downloads")

//Find all items, and display the default item fields fields as well as the stat fields

//Find all items, and display the default item fields as well as the stat and the property fields
items.find().include("stat", "property")

//Find all items, and display the "name" and "repo" fields as well as the stat fields
items.find().include("name", "repo", "stat")
//Find all builds that generated items with an Apache license, and display the build fields as well as the item "name" fields. Click below to view the output of this query
 Click to view the output of the last query

Note that the output displays the default fields of the "build" domain, and the "name" field from the item domain. Fields from the module and artifact domains are not displayed since they were not specified in the include element.


"results" : [ {
  "build.created" : "2015-09-06T15:49:01.156+03:00",
  "build.created_by" : "admin",
  "build.name" : "maven+example",
  "build.number" : "313",
  "build.url" : "http://localhost:9595/jenkins/job/maven+example/313/",
  "modules" : [ {
    "artifacts" : [ {
      "items" : [ {
        "name" : "multi-3.0.0-20150906.124843-1.pom"
      } ]
    } ]
  } ]
  "build.created" : "2015-09-06T15:54:40.726+03:00",
  "build.created_by" : "admin",
  "build.name" : "maven+example",
  "build.number" : "314",
  "build.url" : "http://localhost:9595/jenkins/job/maven+example/314/",
  "modules" : [ {
    "artifacts" : [ {
      "items" : [ {
        "name" : "multi-3.0.0-20150906.124843-1.pom"

      } ]
    } ]
  } ]
} ],
"range" : {
  "start_pos" : 0,
  "end_pos" : 2,
  "total" : 2

Users Without Admin Privileges

To ensure that non-privileged users do not gain access to information without the right permissions, users without admin privileges have the following restrictions:

  1. The primary domain in the query may only be item.
  2. The following three fields must be included in the include directive: name, repo, and path.

Note, however, that once these restrictions are met, you may include any other accessible field from any domain in the include directive. 


Filtering Properties by Key

As described above, the primary use of the .include element is to specify output fields to display in the result set.

This notion is applied in a similar way in regard to properties. Each item may be annotated with several (even many) properties. In many cases you may only be interested in a specific subset of the properties, and only want to display those.

So the .include element can be used to filter out unwanted properties from the result, and only display (i.e. "include") those you are interested in.

For example, to display all the properties annotating an item found :

//Find all items, and display the "name" and "repo" fields, as well as all properties associated with each item
items.find().include("name", "repo", "property.*")

However, if you are only interested in a specific property (e.g. you just want to know the version of each item returned), you can filter out all other properties and only include the property with the key you are interested in:

//Find all items, and display the "name" and "repo" fields, as well as the key and value of the "version" property of each item
items.find().include("name", "repo", "@version")


AQL implements a default sort order, however, you can override the default and specify any other sort order using fields in your output by adding the .sort element to the end of your query as follows: 

.sort({"<$asc | $desc>" : ["<field1>", "<field2>",... ]})

You can only specify sorting on fields that are displayed in the output (whether they are those displayed by default or due to a .include element.

Here are some examples:

 // Find all the jars in artifactory and sort them by repo and name
items.find({"name" : {"$match":"*.jar"}).sort({"$asc" : ["repo","name"]})

 // Find all the jars in artifactory and their properties, then sort them by repo and name
items.find({"name" : {"$match":"*.jar"})include("@").sort({"$asc" : ["repo","name"]})

Display Limits and Pagination

Using the .limit elements, you can limit the number of records that will be displayed by your query.

// Find all the jars in artifactory and sort them by repo and name, but only display the first 100 results
items.find({"name" : {"$match":"*.jar"}).sort({"$asc" : ["repo","name"]}).limit(100)


You can also implement pagination when you want to focus on a subset of your results using the .offset element.


//Run the same example, but this time, display up to 50 items but skipping the first 100
items.find({"name" : {"$match":"*.jar"}).sort({"$asc" : ["repo","name"]}).offset(100).limit(50)


Note the limitation on sort, limit and offset described above.

Working With Virtual Repositories

From version 4.8.1, AQL supports virtual repositories. Since virtual repositories only contain items indirectly through the local repositories they include, several conventions have been laid down as described in the following sections.

Filtering on a Virtual Repository

You may limit queries to search in a specified virtual repository. In practice this means that the query will be applied to local repositories and remote repository caches included in the specified virtual repository.

For example, find all the items within any repository contained in a virtual repository called "my-virtual":

items.find({"repo" : "my-virtual"})

Output Fields

The item domain has a virtual_repos field which includes the virtual repositories in which a found item is contained. In general, to display this field, you need to expressly specify it in your query as an output field. However, if your query specifies a virtual repository as its search target, the virtual_repos field is implicitly included in the search results as an output field.

An item must be accessible in order to be found

A search query will only find an item in a virtual repository if it is accessible by that virtual repository. For example, the local repository that contains an item may specify and include or exclude pattern which prevents access to the item by the encapsulating virtual repository. In this case the search query will not find the item.