Searching for Components
Available in Nexus Repository OSS and Nexus Repository Pro
Searching components in the repository manager is an important use case for being able to access information about specific components including different versions that are available, security and license data and other information as well as for build tool migrations, download of deployment packages and other component related development, QA and operations activities.
The different search modes can be accessed with the Browse button in the main toolbar and selecting Search or one of the nested options like Custom or Maven. The common feature view with the criteria drop-down selector for the search without results is displayed in Figure 3.6, “Keyword Search with More criteria Input”.
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 button that allows you to add further criteria to your search. Each criteria can be removed by clicking on 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
A number of criteria can be used with any repository format and returns results from all components in all repositories:
A keyword is a string used for a search, where matches in Format, Group, Name, Version and all other component metadata values are returned.
The format of the repository in which to look for a component.
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.
The 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.
The version of a component allows you to have different points in time of a component released. Various tools such as Maven or NuGet use the term version. Other build systems call this differently e.g. rev, short for revision, in the case of Apache Ivy. In most repository formats version numbers are not enforced 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.
In addition there are criteria that can be used to search for components in repositories with specific formats only:
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 Maven packaging for a component, which is jar by default. Other values as used in Maven and other build tools are ear, war, maven-plugin, pom, ejb, zip, tar.gz, aar and many others.
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.
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 1000 results become visible in the component list, with an example displayed in Figure 3.7, “Results of a Component Search for format maven2”. If more than 1000 results exist, notation will appear under the filters relaying how many items were found in total.
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.
Figure 3.7. Results of a Component Search for format maven2
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 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 button.
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 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 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 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 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 3.8, “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.
Figure 3.8. Example for Component Information and List of Associated Assets
To delete a component press the Delete component button as shown in Figure 3.8, “Example for Component Information and List of Associated Assets”. 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.
Figure 3.9. Analyze Application Form
To analyze an application, press the Analyze application button as shown in Figure 3.8, “Example for Component Information and List of Associated Assets”. 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 3.9, “Analyze Application Form”. Your report link will be emailed to you as soon as it is finished.
Viewing Asset Information
Available in Nexus Repository OSS and Nexus Repository Pro
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 3.10, “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 Nexus Repository Manager blob store
the date and time when the asset was updated last in the Nexus Repository Manager 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 and time 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
Figure 3.10. Asset Info Example
The Attributes section contains further metadata about the asset related to Cache, Checksum, and Content attributes. An example is displayed in Figure 3.11, “Asset Attributes Example”. 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.
Figure 3.11. Asset Attributes Example
In Nexus Repository Manager 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. An example is displayed in Figure 3.12, "Component Tags Example".
Figure 3.12. Component Tags Example
If Repository Health Check is enabled 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.