AQL Syntax

Artifactory Query Language (AQL) is a flexible query language that lets you search for artifacts, builds, and other entities in Artifactory. Use AQL when you need to:

Perform complex searches that go beyond the capabilities of the standard search UI
Automate artifact discovery in CI/CD pipelines
Generate reports on repository contents
Find artifacts based on properties, checksums, or build information

AQL provides powerful filtering, sorting, and pagination capabilities, making it ideal for managing large repositories with thousands of artifacts.

Command Syntax

<domain_query>.find(<criteria>).include(<fields>).sort(<sort_order>).offset(<offset_value>).limit(<limit_value>).distinct(<distinct_value>)

Placeholder Descriptions

Placeholder	Required	Description
<domain_query>	Yes	The primary domain to query. Valid values: `items`, `builds`, `artifacts`, or `entries`.
<fields>	No	Comma-separated list of fields to include in the output. If omitted, default fields for the domain are returned.
<sort_order>	No	JSON object specifying sort direction and fields. Use `$asc` for ascending or `$desc` for descending, followed by an array of field names.
<offset_value>	No	Integer specifying how many results to skip. Used for pagination.
<limit_value>	No	Integer specifying the maximum number of records to return. If omitted, all matching records are returned.
<distinct_value>	No	Boolean (`true` or `false`) to enable or disable unique results. Default: true.

Methods Reference

Method	Required	Description
.find(<criteria>)	Yes	Defines the search criteria.
.include(<fields>)	No	Specifies which fields to return in the output.
.sort(<sort_order>)	No	Orders the results by specified fields.
.offset(<offset_value>)	No	Skips the specified number of results (pagination).
.limit(<limit_value>)	No	Limits the number of returned results.
.distinct(<distinct_value>)	No	Controls whether duplicate results are removed.

Examples

Basic Search

items.find({"repo": "libs-release-local"})

Search with Pattern Matching

items.find({"name": {"$match": "*.jar"}})

Search with Multiple Criteria

items.find({
  "$and": [
    {
      "$or": [
        {"repo": "libs-release-local"},
        {"repo": "ext-release-local"}
      ]
    },
    {"name": {"$match": "*.jar"}},
    {"size": {"$gt": 1048576}}
  ]
})

Include Specific Fields

items.find({"repo": "libs-release-local"}).include("name", "path", "size")

Sort Results

items.find({"repo": "libs-release-local"}).sort({"$asc": ["name"]})

items.find({"repo": "libs-release-local"}).sort({"$desc": ["created"]})

Pagination

items.find({"repo": "libs-release-local"}).offset(50).limit(25)

Disable Unique Results

items.find({"name": {"$match": "*.jar"}}).include("name").distinct(false)

Combined Example

items.find({
  "repo": "libs-release-local",
  "name": {"$match": "*.jar"}
})
.include("name", "path", "size", "created")
.sort({"$desc": ["created"]})
.offset(0)
.limit(100)

Limitations

Note

The sort, limit, and offset methods only work when:

Your query does not include an include method
Your include method only specifies fields from the primary domain

Example where sorting is ignored due to sub-domain fields in include:

items.find()
  .include("artifact", "artifact.module", "artifact.module.build")
  .sort({"$asc": ["name"]})
  .limit(100)

Working alternative:

items.find()
  .include("name", "path", "repo")
  .sort({"$asc": ["name"]})
  .limit(100)