Artifactory Query Language

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.

	3.5.0	4.2.0	4.7.0	6.0.0/ 7.0.0
Item
Item.Property
Statistic
Archive
Archive.Entry
Artifact
Dependency
Module
Module.Property
Build
Build.Property
Promotion
Release
Release_artifact

// Find all unique jars's names in artifactory 
items.find({"name" : {"$match":"*.jar"}}).include("name")

// Find all jars's names in artifactory includes repeated values across different repositories.
items.find({"name" : {"$match":"*.jar"}}).include("name").distinct(false)

// Find all jar items in a repository called "my_local".
// Property "path" already unique inside single repository and unique results can be disabled for performance reason.
items.find(
        {"repo" : "my_local"},
        {"name" : {"$match":"*.jar"}}
)
.include("path")
.distinct(false)

<domain_query>.find(<criteria>).include(<fields>).sort(<order_and_fields>).offset(<offset_records>).limit(<num_records>).distinct(<true|false>)

where:

items.find().include("artifact","artifact.module","artifact.module.build")

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

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

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

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

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.
items.find({"stat.downloads":{"$gt":"5"}})
 
//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.
items.find({"stat.downloads":{"$eq":null}})

//Find builds that use a dependency that is a snapshot
builds.find({"module.dependency.item.name":{"$match":"*SNAPSHOT*"}})

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

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

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

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*"}})

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

<criterion>={<"$and"|"$or">:[{<criterion>},{<criterion>}]

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 were created in a build called "my_debian_build" and whose name ends with ".deb" or all items created in a build called "my_yum_build" and whose name ends with ".rpm".
items.find(
        {
                "$or":
                [
                        {
                                "$and":
                                [
                                        {"artifact.module.build.name" : "my_debian_build"} ,
                                        {"name" : {"$match" : "*.deb"}}
                                ]
                        }, 
                        {
                                "$and":
                                [
                                        {"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

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:

items.find({
            "@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:

"items.find({
                        "$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.

Tip

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

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

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

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

items.find({"@artifactory.licenses":"*"})

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.

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:

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

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"}})

Use: .include("*")

For example:

//Find all items, and display all the item fields
items.find().include("*")

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
items.find().include("stat")

//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
builds.find({
                "module.artifact.item.@license":{"$match":"Apache*"}
            }
).include("module.artifact.item.name")

{

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

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

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

//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.*")

//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")

The following rules and guidelines apply when searching remote and virtual repositories:

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"})

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.