Query Structure and Syntax

This page explains how AQL queries are structured, what methods are available, and how to reference fields from primary and related domains.

Query Structure

AQL queries follow this pattern:

<domain_query>.find(<criteria>).include(<fields>).sort(<sort_order>).offset(<offset_value>).limit(<limit_value>).distinct(<distinct_value>)

Placeholder	Required	Description
`<domain_query>`	Yes	The primary domain to query. Valid values: `items`, `builds`, `build.promotions`, `releases`, or `release_artifacts`.
`<criteria>`	Yes	JSON object defining filter conditions. Can be empty `{}`.
`<fields>`	No	Comma-separated list of fields to include in the output. If omitted, default fields for the domain are returned.
`<sort_order>`	No	JSON object specifying sort direction and fields. Use `$asc` for ascending or `$desc` for descending, followed by an array of field names.
`<offset_value>`	No	Integer specifying how many results to skip. Used for pagination.
`<limit_value>`	No	Integer specifying the maximum number of records to return. If omitted, all matching records are returned.
`<distinct_value>`	No	Boolean (`true` or `false`) to enable or disable unique results. Default: `true`.

Query Methods

Method	Required	Description
`.find(<criteria>)`	Yes	Defines the search criteria.
`.include(<fields>)`	No	Specifies which fields to return in the output.
`.sort(<sort_order>)`	No	Orders the results by specified fields.
`.offset(<offset_value>)`	No	Skips the specified number of results (pagination).
`.limit(<limit_value>)`	No	Limits the number of returned results.
`.distinct(<distinct_value>)`	No	Controls whether duplicate results are removed.

For details on .include(), .sort(), .offset(), .limit(), and .distinct(), see Query Output and Modifiers.

Field References

Primary Domain Fields

Any fields from your primary domain can be used directly anywhere in your query. For example, to find all items in a repository called "myrepo":

items.find({"repo": "myrepo"})

Cross-Domain Field Paths

If you use fields from other domains, they must be specified using a complete relation path from the primary domain.

To find all items created by modules named "mymodule":

items.find({"artifact.module.name" : "mymodule"})

Since you may also issue a query from the build domain, to find all builds that generated an item called "artifactory.war":

builds.find({"module.artifact.item.name": "artifactory.war"})

For the complete list of fields available in each domain, see AQL Entities and Fields Reference.

Syntax Rules

JSON-like Syntax

AQL uses a JSON-like syntax with these rules:

// String values use double quotes
{"repo": "libs-release-local"}

// Numbers can be quoted or unquoted
{"size": 1048576}
{"size": "1048576"}

// Arrays for multiple values
{"$or": [{"repo": "repo1"}, {"repo": "repo2"}]}

// Nested objects for comparators
{"size": {"$gt": "1000000"}}

Key rules:

Field names are always quoted: "repo", "name", "path"
String values are quoted: "libs-release-local"
Comparators start with $: $eq, $gt, $match
Logical operators start with $: $and, $or

Quoting and Escaping

// Path separators use forward slash
{"path": "org/example/module"}

// Property keys use the @ prefix
{"@license": "Apache-2.0"}

// Wildcard property key
{"@*": "value"}

Case Sensitivity

Field names are case-sensitive:

// Correct
{"repo": "my-repo"}

// Incorrect (will not match)
{"Repo": "my-repo"}
{"REPO": "my-repo"}

AQL Actions

In addition to .find(), AQL supports .delete() and .update() actions that operate on the result set. Both actions support a .dryRun() modifier for safe testing.

Delete Action

The .delete() action removes items matching the query criteria. It is only available on the items domain.

items.delete(<criteria>).dryRun("<true|false>")

Element	Description
`<criteria>`	JSON filter conditions (same syntax as `.find()`).
`.dryRun("true")`	Simulates the deletion without actually removing items. Use this to preview which items would be affected.
`.dryRun("false")`	Executes the deletion.

Limitations: .limit(), .offset(), and .sort() are not supported with .delete().

Example:

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

Update Action

The .update() action modifies property values for items matching the query criteria. It is only available on the properties domain (item properties only; build.properties and module.properties do not support .update()).

properties.update(<criteria>).keys("<key1>","<key2>",...).newValue("<value>").dryRun("<true|false>")

Element	Description
`<criteria>`	JSON filter conditions. Use `item.*` field paths to filter by item attributes.
`.keys("<key>")`	The property key(s) to update. Required.
`.newValue("<value>")`	The new value to assign to the matched properties. Required.
`.dryRun("true")`	Simulates the update without making changes.
`.dryRun("false")`	Executes the update.