Searching for Components
Notable Search Functionality Differences Between Environments
Due to ongoing work for improving component search in Sonatype Nexus Repository, some functionality differences currently exist between deployments using OrientDB, H2, PostgreSQL, and/or High Availability (HA). Take note of the specific differences and considerations in the sections below before you begin searching for components.
Searching for Components in an OrientDB Environment
Most of the documentation in this section focuses on how search works in an OrientDB environment. However, searching by Conan Package Id and Conan Package or Recipe Revisions is not available for those using OrientDB.
Searching for Components in an H2 or Non-HA PostgreSQL Environment
- Searching by Conan Package Id and Conan Package or Recipe Revisions is supported in an H2 environment.
- When searching for raw components, you must use a leading slash (i.e., "/").
Search functionality is otherwise the same as that of an OrientDB environment.
Searching for Components in an HA Environment
As noted in High Availability Deployment Options, the search feature implemented for HA differs a great deal from the search currently used in a non-HA environment.
HA search has the following requirements:
- At least one search criterion is required when searching through the UI
- At least one additional search criterion is required beyond format when searching through the UI
- Each search criteria must be at least three characters long
- Leading wildcard search is not supported; however, you may use a trailing wildcard (i.e., prefix search)
- Searches cannot begin with special characters followed by a wildcard
- All keyword searches automatically append a wildcard (*) at the end of each criterion
Searching for an Exact Match
In keyword search, search criteria are split by default by any commas, spaces, dashes, or forward slashes.
Searching for an exact match can be done in one of two ways depending on if you need to include a wildcard:
- Search for an exact match of a full phrase with no wildcards by enclosing it in quotation marks
"nexus-core"will search for only that exact match
- Include a wildcard in your search by escaping with a backslash; do not use quotation marks
nexus\-cor*will return anything that begins with "
nexus-cor" such as
Example Invalid Search Patterns in an HA Environment
The following search patterns are some that may work in non-HA environments but will not work in an HA environment
|"*"||Less than three characters long; leading wildcard not supported|
|"he*"||Less than three characters long|
|"he*@_"||User criteria ("@_") contains only an underscore|
|"he*@/"||User criteria ("@/") contains only a forward slash|
|"he*@*"||User criteria ("@*") contains only a wildcard|
|"hel*/1.*"||The version criteria (1.*) contains only two characters|
|"/*/hel"||Search begins with a special character followed by a wildcard|
|"$%*hel"||Search begins with two special characters followed by a wildcard|
Searching for components allows you to quickly identify and access information about specific components (e.g., available versions, security and license data, etc.). This can be especially helpful for activities such as build tool migrations, downloading deployment packages, and other component-related development, QA, and operations acitivities.
Component search is available in a few places: through the search input in the top navigation, through the main Search button in the left-hand navigation, or through one of the specific format buttons nested under Search in the left-hand navigation.
Beneath the search title is the search criteria input area that displays the current criteria input (e.g., Keyword). Beside the current criteria is a More criteria drop-down menu that allows you to add additional criteria to your search. Each criteria can be removed by selecting the minus/dash icon within the criteria input box. The cross/x in the input box resets the value.
Each criteria can be used together to allow for broad or fine search results. For example, searching on name foo might return a large number of Maven, NuGet, and other components but adding a version could limit it to what you’re searching for. The Keyword field also supports the * (star, asterisk) character for wildcard matching. For example, a keyword search for
org.sonatype.nexus* would return components containing
org.sonatype.nexus.plugins, and any other matches. If nothing is specified in a criteria, the results have no reductions based around that criteria.
Search Criteria and Component Attributes
Search Criterial for All Formats
You can use a number of different criteria with any repository format to retrieve results from all components in all repositories:
Use a keyword search to search for a string and see matches found in Format, Group, Name, Version, and all other component metadata values.
The format of the repository in which to look for a component.
group is an identifier that groups components in some way, such as by organization. It can also be used to simply to create a specific namespace for a project. Not all repository formats use the notion of a
group. Some tools simply use a different name for the concept e.g.,
org for Apache Ivy or
groupId for Apache Maven and the maven2 repository format. In the case of a maven2 repository,
group is a required attribute. Other formats, like the nuget repository format, do not use
group at all.
name of a component constitutes its main identifier. Different repository formats use a different name for the concept such as
artifactId for Apache Maven and the maven2 repository format.
The name of a repository in which to look for a component.
A component's version identifies the specific point in time at which that component was released. Various tools such as Maven or NuGet use the term
version. Other build systems call this something else (e.g., Apache Ivy uses
rev(short for revision)). In most repository formats, version numbers do not need to follow a specific standard and are simply a string. This affects the sort order and can produce unexpected results.
Checksum - MD5, SHA-1, SHA-256 or SHA-512
A checksum value of a component file generated by an MD5, SHA-1, SHA-256 or SHA-512 algorithm.
Format-Specific Search Criteria
Some formats also have format-specific criteria that you can use.
Project or library version (e.g.,"1.0.0").
Channel represents an alternative variant of packages for the same library and usually describes the maturity of the package (e.g., "stable" or "testing"). Also can show package revisions.
Common Version criteria for Conan format is combination of Base Version and Channel, for instance "1.0.0-stable"
Package Id (PostgreSQL or H2 databases only)
A Conan Package Id is a unique identifier that encodes information about settings, options, and requirements of each package.
Package and Recipe Revisions (PostgreSQL or H2 databases only)
In simplest terms, revisions are versions of versions. The Conan revisions feature allows you to make changes to your artifacts while maintaining a single Conan reference. Every Conan recipe export is associated with a unique ID (i.e., a revision); every recipe change results in a new recipe revision (RREV). Whenever you create a new package, Conan calculates a new package revision (PREV) using the package contents' hash. Package revisions belong to recipe revisions; the same package ID may have multiple package revisions belonging to a single recipe revision. See Conan's documentation on package revisions.
The name for the Docker image. It is equivalent to the Name of the component in the repository manager that represents the Docker image.
The tag for the Docker image. It is equivalent to the Version of the component in the repository manager that represents the Docker image.
The unique identifier for a Docker image layer.
The Maven groupId for a component. Other build systems supporting the Maven repository format call this differently e.g. org for Apache Ivy and group for Gradle and Groovy Grape. Group Id is equivalent to Group.
The Maven artifactId for a component. Other build systems call this differently e.g. name for Apache Ivy and Gradle, and module for Groovy Grape. Artifact Id is equivalent to Name.
The Maven classifier for a component. Common values are
The base version of the component/asset. Typically this is the same value as the version for release components. SNAPSHOT development components use a time-stamped version but the base version uses the SNAPSHOT version e.g. version of 1.0.0-20151001.193253-1 and base version of 1.0.0-SNAPSHOT.
The extension used for a specific asset of a component.
The NuGet component identifier is known as Package ID to NuGet users.
Additional information about a component formatted as space-delimited keywords, chosen by the package author.
The name of a p2 plugin stored
Denote the maturity, intended audience, license and supported versions the creator wished associated with their component.
Creator provided long description of the component.
Associated component keywords. Generally used as identifiers to search.
Creator provided description of the component.
The Platform the gem runs on defined via the gemspec.
A short summary of the gem's description definied via the gemspec.
A long description of the gem defined via the gemspec. This field is optional when creating a gem so may be blank.
The name of the package, this field is the equivalent of Name for Yum.
The architecture the package is designed to be run on.
Keyword search query string handling
The query you enter is passed into the indexes made against every component in the system. These indexes contain the component coordinates as well as any metadata attached to the component. Some of these indexes contain data that has been tokenized (for example, strings split on a hyphen, so
aether-util would match 2 search terms,
util), while other indexes do not (imagine wanting to search for
"aether-util" (see below for more details on double quotes), this would require the full name to match against, rather than a tokenized version). Without wildcards, your query string must match a field in one of these indexes exactly, wildcards can save you when you just can't remember the exact name, but have some partial idea.
About wildcards, how do they change my queries?
Let's suppose you did a query for
aeth, and it returned no results, as the component you are trying to match needs the full term
aether to make a match. So you can then use
aeth* and this would now match the
aether-util component you were initially searching for. Keep in mind that you can use wildcards anywhere in the query string, but placed anywhere except for the last character position has potential to cause the query to run slow.
Using a hyhpen in my query generates a lot of results, how can I make this more manageable?
Along with tokenizing strings for search terms in some of the indexes, we also do the same to the query string you type, so if you type
aether-util we will show all results that would match
util. Suppose you know you want exactly
aether-util and want to filter out all the other results that were brought in, you can use double quotes in your search term,
"aether-util" for example, this would then no longer tokenize your query string, but require the full string for a match.
Once you have provided your search terms in one or multiple criteria input fields, like the Keyword criteria in the Search feature view, the first 300 results become visible in the component list.
The components are listed with their Name, Group, Version, Format and Repository information and by default are sorted alphabetically by Name. Columns and sort order can be adjusted like in all other lists.
Selecting a component in the list changes to a display of the component information documented in Viewing Component Information.
The main toolbar includes a Search components text input field. Type your search term and press enter/return and the repository manager performs a search by Keyword.
The same search can be accessed by selecting the Search item in the Browse main menu. The search term can be provided in the Keyword input field in the Search feature view.
A configurable search using the criteria you select is available via the Custom menu item in the Search section of the Browse main menu. Initially it has no criteria and it allows you to create a search with criteria you add with the More Criteria dropdown.
The Apt search is a predefined search available via the Apt menu item in the Search section of the Browse main menu. It defaults to inputs for Package Name and Version and supports adding further criteria. The format is configured to apt.
The Bower search is a predefined search available via the Bower menu item in the Search section of the Browse menu. It defaults to inputs for Name and Version and supports adding further criteria. The format is configured to bower.
The CocoaPods search is a predefined search available via the CocoaPods menu item in the Search section of the Browse main menu. It defaults to inputs for Package Name and Version and supports adding further criteria. The format is configured to cocoapods.
The Conan search is a predefined search available via the Conan menu item in the Search section of the Browse main menu. It defaults to inputs for Package Name, Base Version and Channel and supports adding further criteria. The format is configured to conan.
The Conda search is a predefined search available via the Conda menu item in the Search section of the Browse main menu. It defaults to inputs for Package Name and Version and supports adding further criteria. The format is configured to conda.
The Docker search is a predefined search available via the Docker menu item in the Search section of the Browse main menu. It defaults to inputs for Image Name, Image Tag and Layer Id and supports adding further criteria. The format is configured to docker.
Git LFS Search
The Git LFS search is a predefined search available via the Git LFS menu item in the Search section of the Browse main menu. It defaults to an input for Name and supports adding further criteria. The format is configured to gitlfs. Note that since Git LFS is not provided with the original filename for a tracked file, the Name field actually contains the generated OID which can be found in the corresponding pointer file’s contents.
The Go search is a predefined search available via the Go menu item in the Search section of the Browse main menu. It defaults to an input for Name and Version and supports adding further criteria. The format is configured to go.
The Helm search is a predefined search available via the Helm menu item in the Search section of the Browse main menu. It defaults to inputs for Name and Version and supports adding further criteria. The format is configured to helm.
The Maven search is a predefined search available via the Maven menu item in the Search section of the Browse main menu. It defaults to inputs for Group Id, Artifact Id, Version, Base Version, Classifier and Extension and supports adding further criteria. The format is configured to maven2.
The NuGet search is a predefined search available via the NuGet menu item in the Search section of the Browse main menu. It defaults to inputs for ID and Tags and supports adding further criteria. The format is configured to nuget.
The npm search is a predefined search available via the npm menu item in the Search section of the Browse main menu. It defaults to inputs for Scope, Name, and Version and supports adding further criteria. The format is configured to npm.
The p2 search is a predefined search available via the p2 menu item in the Search section of the Browse main menu. It defaults to inputs for Package Name and Plugin Name and supports adding further criteria. The format is configured to p2.
The PyPI search is a predefined search available via the PyPI menu item in the Search section of the Browse main menu. It defaults to inputs for Classifiers, Description, PyPI Keywords, and Summary and supports adding further criteria. The format is configured to pypi.
The R search is a predefined search available via the R menu item in the Search section of the Browse main menu. It defaults to inputs for Package Name and Version and supports adding further criteria. The format is configured to r.
The Raw search is a predefined search available via the Raw menu item in the Search section of the Browse main menu. It defaults to an input for Name and supports adding further criteria. The format is configured to raw.
The RubyGems search is a predefined search available via the RubyGems menu item in the Search section of the Browse main menu. It defaults to inputs for Name, Version, Platform, Summary and Description and supports adding further criteria. The format is configured to rubygems.
The Yum search is a predefined search available via the Yum menu item in the Search section of the Browse main menu. It defaults to inputs for Package Name, Version and Architecture and supports adding further criteria. The format is configured to yum.
Example Use Case - SHA-1 Search
Sometimes it is necessary to determine the version of a component, where you only have access to the binary file without any detailed component information. When attempting this identification and neither the filename nor the contents of the file contain any useful information about the exact version of the component, you can use SHA-1 search to identify the component.
Create a sha1 checksum, e.g., with the
sha1sum command available on Linux or OSX or
fciv on Windows, and use the created string in a Custom search by adding the SHA-1 criteria from the Checksum section of the More criteria control.
The search will return a result, which will provide you with the detailed information about the file allowing you to replace the file with a dependency declaration. E.g. you can derive the Maven coordinates of a jar file and use them in a dependency declaration.
A SHA-1 or similar checksum search can be a huge timesaver when migrating from a legacy build system, where the used libraries are checked into the version control system as binary components with no version information available.
Viewing Component Information
Once you located a component via a search and selected it in the list, you see the component information. An example is displayed in Figure: “Example for Component Information and List of Associated Assets”.
The information displayed includes the name and format of the repository that contains the component as well as the component identifiers Group, Name, and Version. Most popular version contains the version number of the same component that is most popular in its usage within a specific group and name. Popularity shows a relative percentage of popularity between the displayed component against all other versions of this component. A value of 100% signals this version to be the most popular. 50% means that the specific version is half as popular as the most popular version. Popularity data is provided by the Sonatype Data Services based on requests from the Central Repository and other data and not available for all components. Age shows the age of the component.
None of the popularity or age data is viewable without Repository Health Check enabled, as lightly touched on in Managing Repositories and Repository Groups.
A list of one or more assets associated with the component is shown below the component information. Click on the row with the Name of the asset you want to inspect to view the asset information documented in Viewing Asset Information.
To delete a component press the Delete component button. A modal will pop up to confirm the deletion. You can only delete components from hosted and proxy repositories. A deletion of a components triggers the deletion of all its associated assets, in most repository formats.
In some repository formats assets are shared across components. They remain after a component deletion. For example, while a Docker image is a component and can be deleted, the layers that make it up remain after its deletion as these assets are potentially shared with other Docker images.
To analyze an application, press the Analyze application button. A form will pop up to request further information from you: email address, report password, a list of proprietary packages for the application, and a name for the report. Once you provide this information, press the Analyze button as shown in Figure: “Analyze Application Form”. Your report link will be emailed to you as soon as it is finished.
Viewing Asset Information
Asset information can be accessed from a component information view. The Delete button allows you to remove an asset. The information itself is broken up into sections, accessible by tabs below the Delete Asset button. The Summary section contains a number of attributes about the specific asset. An example for search is displayed in Figure: “Asset Info Example”.
the path to the asset in the repository. This is a link, either downloadable or loading in browser dependent on the contents of the asset.
the MIME type of the asset
the size of the file
the date and time when the asset was created in the Sonatype Nexus Repository blob store
the date and time when the asset was updated last in the Sonatype Nexus Repository blob store. This will initially match Blob created.
Last 30 days:
the number of times the asset was downloaded in the last thirty days
the date when the asset was last downloaded (or updated). It will be updated when the asset is first downloaded and then on subseqent 200 and 304 responses. By default, this is prevented from updating too often for performance reasons and will only update once in any given 12 hour period. It is possible to override this setting by adding a Storage Settings capability (shown below) and configuring the 'Last Downloaded' Update Interval value.
value of true means the asset can be found in the repository manager storage while false indicates that the metadata about the asset is available, though the asset itself has not been downloaded
a unique identifier pointing at the the binary blob representing the asset in the repository manager storage
user who uploaded the asset
Uploader's IP Address:
the IP address of the indiviual who uploaded or requested the asset
The Attributes section contains further metadata about the asset related to Cache, Checksum, and Content attributes. Assets can include format specific attributes displayed in additional sections. For example an asset in a Maven2 repository has a Maven2 section with attributes for extension, baseVersion, groupId, artifactId, version, and asset_kind.
In Sonatype Nexus Repository Pro, two additional tabs named Component Tags and Component IQ are available. The Component Tags tab contains a list of tag names (firstCreated and lastUpdated dates) associated with the selected component. When a row in this table is clicked the user will be presented with the tag deatails.
If Repository Health Check is enabled (on a Professional licensed system) or Nexus IQ Server is connected, the Component IQ tab shows security information and license details about a component, if available to that format and from Sonatype.
The nx-search-read Privilege gives access to this left nav item as well as the sub-item Search - Custom. In order to get access to format specific searches, you must have the associated format repository-view privileges. For example, if you want to see the Maven sub-item you need to have repository-view privilege for at least one Maven repository.