Introduction
JFrog Artifactory offers a powerful query language known as AQL (Artifactory Query Language), which enables users to perform complex searches to retrieve artifact information based on various criteria, such as download counts within a specific time period. This guide provides detailed examples and instructions for using AQL to obtain the count of downloaded artifacts over defined time frames.
Important Disclaimer Regarding AQL Performance
When using AQL commands to search within repositories containing a large number of artifacts (e.g., millions of artifacts), these operations can significantly impact the performance of other database queries/processes. For repositories with a smaller number of artifacts, AQL queries should perform as expected, depending on concurrent database operations. It is crucial to consider the scale of your repository when executing extensive AQL searches.
Fetch Artifact Downloads Based on Time Period
To count the number of artifacts downloaded within a specified period, you can use relative time operators in your AQL queries. This approach is dynamic, as it adapts based on when the query is run.
Fetching Artifact Statistics
View statistics for all artifacts in a repository:
curl -u <username>:<password> -s -k -XPOST "https://<JPD_URL>/artifactory/api/search/aql" -d 'items.find({"repo":"<REPO_NAME>"}).include("stat")' -H "Content-Type: text/plain"
Expected output:
{
"results" : [ {
"repo" : "nuget-local",
"path" : ".",
"name" : "MySampleLibrary.1.0.0.nupkg",
"type" : "file",
"size" : 3651,
"created" : "2025-04-30T06:12:24.348Z",
"created_by" : "<username>",
"modified" : "2025-04-30T06:12:24.348Z",
"modified_by" : "<username>",
"updated" : "2025-04-30T06:12:24.351Z",
"stats" : [ {
"downloaded" : "2025-04-30T06:12:25.049Z",
"downloaded_by" : "<username>",
"downloads" : 1,
"remote_downloads" : 0
} ]
} ],
"range" : {
"start_pos" : 0,
"end_pos" : 1,
"total" : 1
}
}
To get the Count of Downloaded Artifacts in a specific time period:
1. Stats for artifacts downloaded in the past week in a repository:
curl -u <username>:<password> -s -k -XPOST "https://< JPD_URL>/artifactory/api/search/aql" -d 'items.find({"repo":"<REPO-NAME>", "stat.downloaded": {"$last":"1w"}}).include("stat")' -H "Content-Type: text/plain"
Expected Output:
{
"results" : [ {
"repo" : "target-docker-repo",
"path" : "nginx/latest",
"name" : "manifest.json",
"type" : "file",
"size" : 1778,
"created" : "2025-04-17T09:01:06.086Z",
"created_by" : "<username>",
"modified" : "2025-04-17T09:01:06.086Z",
"modified_by" : "<username>",
"updated" : "2025-04-17T09:01:06.091Z",
"stats" : [ {
"downloaded" : "2025-06-02T14:18:19.463Z",
"downloaded_by" : "<username>",
"downloads" : 1,
"remote_downloads" : 0
} ]
} ],
"range" : {
"start_pos" : 0,
"end_pos" : 1,
"total" : 1
}
}
2. Stats for artifacts in a repository downloaded in the past 6 months:
curl -s -k -XPOST "https://<JPD_URL>/artifactory/api/search/aql" -d 'items.find({"repo":"<REPO-NAME>", "stat.downloaded": {"$last":"6mo"}}).include("stat")' -H "Content-Type: text/plain" -u <username>:<password>
Expected Output:
{
"results" : [ {
"repo" : "nuget-local",
"path" : ".",
"name" : "MySampleLibrary.1.0.0.nupkg",
"type" : "file",
"size" : 3651,
"created" : "2025-04-30T06:12:24.348Z",
"created_by" : "<username>",
"modified" : "2025-04-30T06:12:24.348Z",
"modified_by" : "<username>",
"updated" : "2025-04-30T06:12:24.351Z",
"stats" : [ {
"downloaded" : "2025-04-30T06:12:25.049Z",
"downloaded_by" : "<username>",
"downloads" : 1,
"remote_downloads" : 0
} ]
}],
"range" : {
"start_pos" : 0,
"end_pos" : 1,
"total" : 1
}
}
Relative Time Operators for Queries
AQL supports relative time operators, allowing you to specify time intervals that dynamically adjust based on when the query is run.
Sorting Download Results Using `jq`
You can sort download results in ascending or descending order to analyze your data better using `jq`:
| jq '[.results[] | {repo: .repo, path: .path, name: .name, type: .type, size: .size, created: .created, created_by: .created_by, modified: .modified, modified_by: .modified_by, updated: .updated, stats: .stats}] | sort_by(.stats[].downloads)| reverse'
Additional Resources
For more detailed documentation and examples, check out the official JFrog resources:
- Relative Time Operators in AQL
Conclusion
Using JFrog Artifactory’s AQL, you can effectively query and retrieve download counts for artifacts within specified time frames. This capability enhances your repository management and facilitates better tracking of usage patterns.