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

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.

Users with Scoped Tokens

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

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

Limit and Repository Permissions

Artifactory checks what you can read after it searches the items for .limit(N). You can get fewer than N items, or none, when those first items are in repositories you can't read. From Artifactory 7.133.0, you can send the scan-factor header to search further and still receive at most N results. You can also limit the query to repositories you can read. For more information, see Return the Results You Can Read.

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 AQL query is too long?

The AQL request body is longer than the 6,000-character default. Split or shorten the query. For details, including why you shouldn't raise the limit much above 6,000 characters, see What Is the Maximum AQL Query String Size?.

Why do I get a 429 Too Many Requests error?

You get HTTP 429 when rate limiting is on and Artifactory reaches the global concurrency limit or the per-user limit. The global limit defaults to 3 concurrent AQL queries. With the default per-user percentage of 100, each user can use that full limit. Wait and retry. On a self-managed installation, you can raise artifactory.aql.queries.limit or lower artifactory.aql.queries.user.limit.percent. For more information, see How Do I Configure AQL Rate Limiting?.

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.

Why does .limit() return an empty result when the same query without it doesn't?

.limit(N) stops the search before Artifactory checks repository permissions. If you can't read those items, the response is empty even when later items are ones you can read. Send scan-factor with an integer greater than 1, or limit the query to repositories you can read. For more information, see Return the Results You Can Read.

Related Topics

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