Query Execution and Permissions

This page covers how to run AQL queries, supported authentication methods, and the permission model that controls what results users can see.

How Do I Execute an AQL Query?

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

Description: Flexible and high performance search using Artifactory Query Language.

Since: 3.5.0

Security: Requires an authenticated user. Certain domains/queries may require Admin access.

Usage:POST /artifactory/api/search/aql

Consumes: text/plain

📘

Note

For information on limiting the maximum number of AQL search results, see Limiting AQL Search Results.

Sample Usage:

POST https://<JFrogPlatformURL>/artifactory/api/search/aql  
items.find(
        {
                "repo":{"$eq":"libs-release-local"}
        }
)

Produces: application/json

Sample Output:

{
        "results" : [
        {
                "repo" : "libs-release-local",
                "path" : "org/jfrog/artifactory",
                "name" : "artifactory.war",
                "type" : "item type",
                "size" : "75500000",
                "created" : "2015-01-01T10:10;10",
                "created_by" : "Jfrog",
                "modified" : "2015-01-01T10:10;10",
                "modified_by" : "Jfrog",
                "updated" : "2015-01-01T10:10;10"
        }
        ],
        "range" : {
        "start_pos" : 0,
        "end_pos" : 1,
        "total" : 1,
        "limit": 5,
        "notification": "AQL query reached the search hard limit, results are trimmed."
        }
}

cURL Examples

Basic Authentication

curl -X POST \
  -u username:password \
  -H "Content-Type: text/plain" \
  -d 'items.find({"repo": "libs-release-local"})' \
  "https://artifactory.example.com/artifactory/api/search/aql"

Query from File

echo 'items.find({"repo": "libs-release-local"}).limit(10)' > query.aql

curl -X POST \
  -u username:password \
  -H "Content-Type: text/plain" \
  -d @query.aql \
  "https://artifactory.example.com/artifactory/api/search/aql"

API Key Authentication

curl -X POST \
  -H "X-JFrog-Art-Api: your-api-key" \
  -H "Content-Type: text/plain" \
  -d 'items.find({"repo": "libs-release-local"})' \
  "https://artifactory.example.com/artifactory/api/search/aql"

Access Token Authentication

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: text/plain" \
  -d 'items.find({"repo": "libs-release-local"})' \
  "https://artifactory.example.com/artifactory/api/search/aql"

JFrog CLI Integration

You can use AQL with JFrog CLI through file specs. Create a file spec (search.json):

{
  "files": [
    {
      "aql": {
        "items.find": {
          "repo": "libs-release-local",
          "type": "file"
        }
      }
    }
  ]
}

Execute:

jf rt search --spec=search.json

Response Formats

Add ?compact=true to the endpoint URL to reduce response size:

What HTTP Error Codes Can AQL Return?

AQL can return the following HTTP status codes:

For information on configuring timeouts and rate limiting, see Performance and Operational Controls.

How Do I Stream Large Result Sets?

For queries that return large result sets, you can enable streaming mode by adding a stream: true HTTP header to the request. Streaming uses a cursor-based approach that reduces memory consumption on the server.

curl -X POST \
  -u username:password \
  -H "Content-Type: text/plain" \
  -H "stream: true" \
  -d 'items.find({"repo": "libs-release-local"})' \
  "https://<JFrogPlatformURL>/artifactory/api/search/aql"

When streaming is enabled, results are fetched from the database in batches (default batch size: 50,000 rows) rather than loading the entire result set into memory.

What Permissions Are Required for AQL?

Users Without Admin Privileges

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

Regular Users (Without Scoped Tokens)

• The following fields must be included in theinclude directive:repo,path, andname
• The primary domain in the query may only beitem

These fields are required for permission filtering. Omitting them can cause queries to fail or generate repeated warnings in logs.

However, once these restrictions are met, you may include any other accessible field from any domain in theinclude directive.

🚧

Troubleshooting: "AQL minimal field expectation error"

If you see log messages such as "AQL minimal field expectation error: repo, path and name" or "AQL minimal field expectation error: name, number and repo", the query result set is missing fields required for permission checks. Ensure your .include() specifies:

• Items domain: repo, path, and name
• Builds domain: name, number, and repo

Example for items:

JavaScript

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

Users with Scoped Tokens

Users authenticating with scoped tokens have expanded capabilities based on their token scope:

📘

Note

Scoped tokens with build permissions can execute builds.find() queries without requiring admin privileges. This is the recommended approach for CI/CD integrations and third-party tools like ServiceNow.

Creating a Scoped Token for AQL

To create a scoped token that allows both items and builds queries:

curl -X POST "https://<JFrogPlatformURL>/access/api/v1/tokens" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "scope=artifact:*/**:r build:artifactory-build-info/**:r" \
  -u admin:password

This token can then be used with the AQL API:

curl -X POST "https://<JFrogPlatformURL>/artifactory/api/search/aql" \
  -H "Authorization: Bearer <scoped-token>" \
  -H "Content-Type: text/plain" \
  -d 'builds.find({"name": "my-build"})'

Quick Reference: Scoped Token Permissions for AQL

Frequently Asked Questions

What authentication methods does AQL support?

AQL supports basic authentication (username:password), API key (X-JFrog-Art-Api header), and access token (Authorization: Bearer header). Anonymous access isn't allowed.

Why do I get a 429 Too Many Requests error?

The rate limiter has been reached. By default, self-managed instances allow three concurrent AQL queries. Wait briefly and retry, or increase the limit via artifactory.aql.queries.limit. See Performance and Operational Controls.

Can I query the builds domain without admin privileges?

Yes. Create a scoped access token with build:artifactory-build-info/**:r scope. This allows builds.find() queries without requiring admin privileges. See Users with Scoped Tokens.

What fields must non-admin users include?

For item queries, you must include repo, path, and name in the output. For build queries, you must include name, number, and repo. These fields are required for permission filtering.

Related Topics

• Query Structure and Syntax
• Query Output and Modifiers
• Performance and Operational Controls
• AQL Entities and Fields Reference
• AQL Examples and Common Patterns