Performance and Operational Controls

This page covers result set limits, query string size limits, rate limiting configuration, and best practices for writing performant AQL queries.

What Are the AQL Result Set Limits?

The maximum number of AQL search results is limited as follows:

• For Artifactory SaaS platforms starting from version 7.100.2, a fixed value of 500,000 is set as the default maximal result set size to limit the search/AQL API call response. When this limit is reached, no further results are displayed and the user receives the following message: "AQL query reached the search hard limit, results are trimmed."
• For Artifactory SaaS version 7.107.0 and above, aql.search.query.max.limit is set to 500,000 results. This limit optimizes search result integrity and protects database performance.
• For Artifactory self-managed, there is no default maximum result limit. However, from self-managed version 7.90.6 and later users can limit search results with the system property aql.search.query.max.limit.

What Is the Maximum AQL Query String Size?

Artifactory limits the length of the AQL query string that you send to POST /artifactory/api/search/aql. The default maximum is 6,000 characters. This protects the instance when a large query body is posted, for example a large aql.spec file with jf rt curl or curl -d @aql.spec.

The limit applies from Artifactory 7.111.4 (self-managed) and later, and from Artifactory 7.107.1 (SaaS) and later. Queries that ran successfully on earlier versions can start failing after you upgrade if the query text is longer than 6,000 characters.

When the query exceeds the limit, Artifactory does not run the search. It returns HTTP 400 (Bad Request) with this message:

{
  "errors": [
    {
      "status": 400,
      "message": "AQL query is too long; please reduce the query length to less than 6000 chars"
    }
  ]
}

The number in the message matches the configured limit.

Reduce Query Size

Keep each AQL request at or under 6,000 characters. Practical ways to stay under the limit:

• Split a large $or list or long property list into several smaller queries, then combine the results in your script.
• Avoid posting a large spec file as the AQL body. Send only the AQL statement, with no extra comments or unused criteria.
• Narrow the query with repo, path, and name instead of enumerating thousands of artifact names.

Configure the Limit (Self-Managed)

On self-managed Artifactory, you can change the limit with artifactory.aql.search.query.size.limit in $JFROG_HOME/artifactory/var/etc/artifactory/artifactory.system.properties. Restart Artifactory after you change the file.

artifactory.aql.search.query.size.limit=6000

How Do I Configure AQL Rate Limiting?

From Artifactory version 7.84, self-managed instances limit the number of search/AQL requests that can run in parallel. This protects the instance from overload when many concurrent AQL queries are executed. When the limit is reached, additional requests receive an HTTP 429 (Too Many Requests) response until capacity becomes available.

Configuration Properties

Configure AQL query rate limiting using the following properties in the$JFROG_HOME/artifactory/var/etc/artifactory/artifactory.system.properties file. Restart Artifactory after making changes.

Disabling Rate Limiting

If you experience unexpected 429 errors and need to disable rate limiting, add the following line toartifactory.system.properties:

artifactory.aql.queries.limit.enabled=false

Tuning Rate Limiting

To allow more concurrent AQL queries, increaseartifactory.aql.queries.limit. To exempt additional clients (for example, CI agents), add their user agent toartifactory.aql.queries.unlimited.agents.

What Are the Query Timeout Defaults?

AQL queries are subject to timeout limits to protect database resources. If a query exceeds its timeout, the database cancels it and Artifactory returns an HTTP 408 (Request Timeout) response.

Configure query timeouts using the following properties in$JFROG_HOME/artifactory/var/etc/artifactory/artifactory.system.properties. Restart Artifactory after making changes.

Transitive Search Configuration

The number of remote repositories searched during a .transitive() query on a virtual repository is configurable:

To increase the limit, add the following line to artifactory.system.properties:

artifactory.aql.transitive.remote.repos.limit=10

How Do I Optimize AQL Query Performance?

Index-Friendly Criteria

Use indexed fields first to narrow results efficiently:

Pattern:

items.find({
    "repo": "libs-release-local",
    "type": "file",
    "@custom-prop": "value"
})

Limiting Result Sets

Always specify limits to avoid unbounded queries:

// Good
items.find({"repo": "my-repo"}).limit(1000)

// Risky for large repos
items.find({"repo": "my-repo"})

Avoiding Expensive Patterns

Include Optimization

Only include what you need:

// Expensive: all fields plus cross-domain
.include("*", "property.*", "stat.*", "artifact.module.build.*")

// Efficient: specific fields
.include("repo", "path", "name", "size")

Batch vs. Single Queries

For multiple lookups, combine into one query:

// Instead of N separate queries
// Use one query with $or
items.find({
    "$or": [
        {"name": "item1"},
        {"name": "item2"},
        {"name": "item3"}
    ]
})

Frequently Asked Questions

What is the default AQL query timeout?

REST API queries time out after 900 seconds (15 minutes). UI-triggered queries time out after 120 seconds (two minutes). Streamed queries time out after 7,200 seconds (two hours). You can configure all of these via system properties. See What Are the Query Timeout Defaults?.

How do I disable AQL rate limiting?

Set artifactory.aql.queries.limit.enabled=false in your artifactory.system.properties file and restart Artifactory. See Disabling Rate Limiting.

What is the maximum AQL query size?

By default, AQL queries can't exceed 6,000 characters. Queries that exceed this limit receive an HTTP 400 response with the message AQL query is too long; please reduce the query length to less than 6000 chars. See What Is the Maximum AQL Query String Size?.

Why did a previously working AQL query fail after an upgrade?

If you upgraded to Artifactory 7.111.4 or later (self-managed) or to Artifactory 7.107.1 or later (SaaS), Artifactory now rejects AQL request bodies longer than 6,000 characters. Shorten or split the query. Don't raise artifactory.aql.search.query.size.limit above 6,000 unless JFrog Support asks you to.

How do I increase the transitive search remote repository limit?

Set artifactory.aql.transitive.remote.repos.limit to a higher value in your artifactory.system.properties file. The default is five. See Transitive Search Configuration.

Related Topics

• Query Output and Modifiers
• Query Execution and Permissions
• Repository-Specific Queries
• AQL Examples and Common Patterns