Repository-Specific Queries

This page covers how to run AQL queries against remote and virtual repositories, including the .transitive() modifier, rules, limitations, and examples.

Using AQL With Remote Repositories

Searching Remote Repositories

From Artifactory version 7.17.4, you can search directly within Smart Remote repositories (pointing to a local repository on a different remote instance of Artifactory). This requires providing credentials to the remote Artifactory on the remote repository configuration under the Basic tab.

To enable a search within a remote repository, add the transitive tag to the search query.

items.find(“repo”: “remote-repo”).transitive()

Rules and Guidelines for Using AQL in Remote Repositories

The following rules and guidelines apply when searching remote and virtual repositories:

The remote repository MUST be an Artifactory instance.

The query MUST include a single repository and a$eq clause.

Example

items.find(“repo”: “remote-repo”).transitive()

You cannot useSort andOffset flags within the AQL Query.

The primary domain can only containItems.

Include may only have the following domains:Items andItemProperties.

The search will run on the first five remote repositories within the virtual repository.

Examples of Searching in Remote Repositories with AQL

Example 1: Input

The following example searches for all the fields of thedomain item.

items.find(
    {
            "repo" : "docker-remote-repo"
    }
).transitive()

Example 1: Output

{
    "results": [
        {
            "repo": "docker-remote-repo-cache",
            "path": "alpine/latest",
            "name": "manifest.json",
            "type": "file",
            "size": 528,
            "created": "2021-03-21T13:54:52.383+02:00",
            "created_by": "admin",
            "modified": "2021-03-21T13:54:32.000+02:00",
            "modified_by": "admin",
            "updated": "2021-03-21T13:54:52.384+02:00"
        },
    ...
    ],
    "range": {
        "start_pos": 0,
        "end_pos": 12,
        "total": 12
    }
}

Example 2: Input

The following example limits the searches to results listed in theinclude section. For non-admin users, you must includerepo,path, andname for permission filtering.

items.find( { "repo" : "docker-remote-repo" } ).include("repo", "path", "name").transitive()

Example 2: Output

{
    "results": [
        {
            "name": "manifest.json"
        },
        {
            "name": "sha256__4c0d98bf9879488e0407f897d9dd4bf758555a78e39675e72b5124ccf12c2580"
        },
        {
            "name": "sha256__e50c909a8df2b7c8b92a6e8730e210ebe98e5082871e66edd8ef4d90838cbd25.marker"
        },
        {
            "repo": "docker-remote-repo",
            "name": "manifest.json"
        },
        {
            "repo": "docker-remote-repo",
            "name": "repository.catalog"
        },
        {
            "repo": "docker-remote-repo",
            "name": "sha256__4c0d98bf9879488e0407f897d9dd4bf758555a78e39675e72b5124ccf12c2580"
        },
        {
            "repo": "docker-remote-repo",
            "name": "sha256__e50c909a8df2b7c8b92a6e8730e210ebe98e5082871e66edd8ef4d90838cbd25"
        }
    ],
    "range": {
        "start_pos": 0,
        "end_pos": 7,
        "total": 7
    }
}

Using AQL With Virtual Repositories

AQL supports virtual repositories. Since virtual repositories only contain items indirectly through the local repositories they include, several conventions have been laid down as described in the following sections.

Searching for Items in a Virtual Repository

You may limit queries to search in a specified virtual repository. Since virtual repositories can indirectly contain both local and remote repositories, this means the query will be applied to local repositories and remote repository caches included in the specified virtual repository.

For example, to find all the items within any repository contained in a virtual repository calledmy-virtual, you would run the following query:

items.find({"repo" : "my-virtual"})

Running this query returns the items from local repositories and remote-cache repositories associated with the remote repositories assigned to the specified virtual repository.

If the virtual repository contains a Smart Remote repository, you can use the.transitive() tag, so that the results will also list items residing on a remote Artifactory instance. For example:

items.find({"repo" : "my-virtual"}).transitive()

Output Fields

The item domain has a virtual_repos field which includes the virtual repositories in which a found item is contained. In general, to display this field, you need to expressly specify it in your query as an output field. However, if your query specifies a virtual repository as its search target, the virtual_repos field is implicitly included in the search results as an output field.

Include and Exclude Patterns in AQL

AQL search results respect repository include and exclude patterns. For local, remote, and virtual repositories, items that do not match the repository's include/exclude patterns are filtered out of AQL results.

Admin users: See all matching items regardless of include/exclude patterns.
Non-admin users: See only items whose paths match the repository's include/exclude patterns.

Example: If a local repository has an exclude pattern**/excluded-folder/**, a non-admin user runningitems.find({"repo":"my-repo"}) will not see artifacts in paths matching that pattern. Admin users will see all artifacts.

✅

An item must be accessible to be found

A search query will only find an item in a virtual repository if it is accessible by that virtual repository. For example, the local repository that contains an item may specify an include or exclude pattern which prevents access to the item by the encapsulating virtual repository. In this case the search query will not find the item. [This behavior is consistent with Include and Exclude Patterns in AQL above.]

Transitive Query Limitations

The following limitations apply when using .transitive() queries:

Limitation	Detail
No sorting	`.sort()` is not supported; sort results client-side after retrieval
No offset	`.offset()` is not supported; use `.limit()` and client-side filtering
Subdomain restrictions	`.include()` may only specify `Items` and `ItemProperties` domains
Single repository	The query must target a single repository with a `$eq` clause
Remote repository limit	Searches run on the first five remote repositories within a virtual repository
Performance	More underlying repos and larger result sets increase query time

Frequently Asked Questions

Does `.transitive()` work with all repository types?

No. The remote repository must be an Artifactory instance (Smart Remote). The query must target a single repository using a $eq clause.

Can I sort transitive query results?

No. .sort() and .offset() aren't supported with .transitive(). Sort results client-side after retrieval. .limit() is supported.

How many remote repositories does a transitive search cover?

By default, transitive queries search up to five remote repositories within a virtual repository. You can change this with the artifactory.aql.transitive.remote.repos.limit system property. See Performance and Operational Controls.

Does AQL respect repository include/exclude patterns?

Yes. Non-admin users only see items whose paths match the repository's include/exclude patterns. Admin users see all items regardless of patterns.