AQL Examples and Common Patterns

This page provides ready-to-use AQL query examples organized by use case. Each example can be executed directly via the AQL REST API endpoint.

Basic Queries

Find Items in a Repository

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

Find Items by Name Pattern

Find all JAR files across all repositories:

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

Find Items by Multiple Criteria

Find all JAR files in specific repositories larger than 1MB:

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

Find All Artifacts of a Build

items.find({"@build.name":{"$eq":"artifactory"}})

Find Builds by Dependency License

builds.find({"module.dependency.item.@license":{"$nmatch":"Apache-*"}})

Output Shaping Examples

Include Specific Fields

Return only the name, path, and size fields:

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

Sort Results

Sort results by name in ascending order:

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

Sort results by created date in descending order:

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

Pagination

Skip the first 50 results and return the next 25:

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

Disable Unique Results

From Artifactory 7.37.x, you can disable unique results for improved performance when duplicates are acceptable:

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

Combined Query Examples

Filtering + Sorting + Pagination

A complete query with filtering, field selection, sorting, and pagination:

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

Cross-Build Artifact Comparison

Compare the artifacts in two 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("name", "repo", "path", "size")

Property-Based Query Examples

Find items 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 created in a build run on linux:

items.find({"artifact.module.build.@os" : {"$match" : "linux*"}})

Find items with a specific license:

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

Find items with any property matching a value:

items.find({"@*":"GPL"})

Build-Related Query Examples

Find all artifacts from a specific build and build number:

items.find({
    "artifact.module.build.name":{"$eq":"Artifactory"},
    "artifact.module.build.number":{"$eq":"521"}
})

Find all items in a repository with a specific license:

items.find({"repo" : "my_local"},{"@artifactory.licenses" : {"$match" : "*LGPL*"}})

Date and Time Query Examples

Find all items modified during the last three days:

items.find({"modified" : {"$last" : "3d"}})

Find all builds created up to two weeks ago:

builds.find({"created" : {"$before" : "2w"}})

Find items modified after a specific date:

items.find({"modified" : {"$gt" : "2012-07-16T19:20:30.45+01:00"}})

Common Mistakes

Mistake	Correct Usage
Missing quotes on field names	`{"repo": ...}` not `{repo: ...}`
Using single quotes	`"value"` not `'value'`
Wrong property syntax	`"@key": "value"` not `"key": "value"` for properties
Forgetting comparator for ranges	`{"size": {"$gt": "1000"}}` not `{"size": ">1000"}`
Using backslash in paths	`"path": "org/example"` not `"path": "org\\example"`
Searching zero downloads with 0	Use `null` not `0` for zero-value stat fields

Action Examples

Delete Items (Dry Run)

Preview which temporary files would be deleted without actually removing them:

items.delete({"name" : {"$match" : "*.tmp"}}).dryRun("true")

Delete Items

Delete all items matching the criteria:

items.delete({"name" : {"$match" : "*.tmp"}, "repo" : "temp-local"}).dryRun("false")

Update Property Values (Dry Run)

Preview a property value change:

properties.update({"item.name" : {"$match" : "*.jar"}}).keys("status").newValue("approved").dryRun("true")

Update Property Values

Update the status property to approved for all matching items:

properties.update({"item.repo" : "libs-release-local", "item.name" : {"$match" : "*.jar"}}).keys("status").newValue("approved").dryRun("false")