Artifactory Query Language

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 items.find( { "name":{"$match":"multi2*.jar"}, "$or":[ { "$and":[ {"artifact.module.build.name":{"$eq":"maven+example"}}, {"artifact.module.build.number":{"$eq":"317"}} ] }, { "$and":[ {"artifact.module.build.name":{"$eq":"maven+example"}}, {"artifact.module.build.number":{"$eq":"318"}} ] } ] }).include("archive.entry")

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

Architecture

AQL构造为一组相互关联的《婚姻保护法》ins as displayed in the diagram below. You may run queries only on one domain at a time, and this is referred to as thePrimarydomain of the query.

目前,以下是支持为主domains:Item,Build,Entry,PromotionandRelease.i.e., your queries may be of the form:items.find(...), builds.find(...),archive.entries.find(...), build.promotions.find(...) or releases.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 inUsing Fields.

Supported Domains

AQL was introduced in Artifactory V3.5.0 with support forItemas a primary domain with its attachedProperty, as well asStatisticas 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
Item
Item.Property
Statistic
Archive
Archive.Entry
Artifact
Dependency
Module
Module.Property
Build
Build.Property
Promotion
Release
Release_artifact

Usage

Syntax

.find().include().sort().offset().limit()

where:

items.find()其中包括(“工件”、“artifact.module”,"artifact.module.build")

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.

为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 thebuilddomain, to find all builds that generated an item called "artifactory.war", you could also use:

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

Execution

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

Output Fields

Output result will return a JSON response, with 2 fields:

1. results——结果数组,根据查询请求ed domain and inclusions, with fields corresponding to the request parameter.
2. range-Describes the number ofresultsreturned by the query, and consists of:
   1. start_pos:is the first index of the first result. should be equal to the offset. (if none provided, should be 0)
   2. end_pos:is the index+1 of the last result.
   3. total:the total number of results returned.
      
   4. limit: optional, if limit was provided

Sample output:

{ "results" : [ { "repo" : "artifactory-local", "path" : "com/jfrog/artifactory/artifactory-oss", "name" : "maven-metadata.xml", "type" : "file", "size" : 383, "created" : "2018-11-06T11:15:01.265Z", "created_by" : "admin", "modified" : "2018-11-06T11:15:01.000Z", "modified_by" : "admin", "updated" : "2018-11-06T11:15:01.267Z" } ], "range" : { "start_pos" : 0, "end_pos" : 1, "total" : 1, "limit" : 1 } }

Entities and Fields

You may issue afindrequest according to thesyntaxabove, and configure your request to display fields from any of the domains.

Constructing Search Criteria

Thecriteriaelement 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 totrueare 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 ofComparison Operators. While each criterion may be expressed in complete general format, AQL defines shortened forms for readabilityas described below.

Field Criteria

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

{"" : {"" : ""}}

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

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

Properties Criteria

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

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

{"@":{"operator":""}}

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

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

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

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

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 regularfindand using the$mspoperator is:

• findwill return an item ifANYof its properties answerALLof the criteria in the search term.
• $mspwill only return an item if at leastONEof its properties answersALLof the criteria in the$mspterm.

Here is an example.

Consider two items A and B.

A has a license property with valueAGPL-V3

B has two license properties . One isLGPL-2.1, and the otherLGPL-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 bothItems Aand Breturned sinceAhasAGPL-V3andBhasLGPL-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 returnsitem 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$mspoperator as follows:

"items.find({ "$msp": [ "@license":{"$match": "*GPL*"}, "@license":{"$nmatch": "LGPL-2.1*"} ]}).

Then bothItem Aand Item Bare returned.

Item A is returned because it has the @license propertyAGPL-V3which meetsboththe {"@license":{"$match": "*GPL*"}} criterion and the "@license":{"$nmatch": "LGPL-2.1*"} criterion.

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

Comparison Operators

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

为time-based operations, please also refer toRelative Time Operators.

Using Wildcards

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

Using Wildcards with$matchand$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 matchanykey oranyvalue 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

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

Examples

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

Date and Time Format

AQL supports Date and Time formats according to aW3C profileof 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.)

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

为full details, please refer to theW3C 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:

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

为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 optionalincludeelement in your query.

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

Displaying All Fields

Use:.include("*")

为example:

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

Displaying Specific Fields

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

Use:.include("", ""...)

为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 theitemdomain, then this will override the default output setting, and only theitemfields you expressly specified will be displayed.

If you only specify fields from thepropertyorstatdomains, then the output will display the default fields from theitemdomain, and in addition, the other fields you expressly specified from thepropertyorstatdomains.

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

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 beitem.
2. The following three fields must be included in theincludedirective:name, repo, andpath.

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

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 .includeelement can be used to filter out unwanted properties from the result, and only display (i.e. "include") those you are interested in.

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

Sorting

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.sortelement to the end of your query as follows:

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

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.limitelements, 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.offsetelement.

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

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.

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

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

Output Fields

Theitemdomain has avirtual_reposfield 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 anoutput field. However, if your query specifies a virtual repository as its search target, thevirtual_reposfield is implicitly included in the search results as an output field.