Overview
GraphQL is a query language that enables you to query your APIs and fetch specific data that you need. Using one endpoint, you can query just the data you want to retrieve and receive a JSON response containing that specific data. To learn more about GraphQL, the query language, type system, how the GraphQL service works, as well as best practices for using GraphQL see GraphQL documentation.
Using GraphQL to Query Metadata
Authentication
Using GraphQL to query metadata provides a simple way to fetch packages data stored in the metadata microservice. Since GraphQL enables you to query objects in a hierarchical structure, and allows you to choose which fields to include in a response, it will be simpler to find the exact data you are looking for.
To use the metadata server GraphQL, you will need a scoped token for Artifactory.
cURL Example
curl -H "Authorization: Bearer <Your Token>" -XPOST http://<server:port>/metadata/api/v1/query -d '{"query":"..." }'
GraphiQL
JFrog offers a version of a simple GraphiQL, a UI tool for your GraphQL queries. You can use the GraphiQL to learn about the GraphQL metadata schema and as a playground to test your queries. To access it, <your server url>/metadata/api/v1/query/graphiql
.
Building a Metadata GraphQL Query
In this section, you will learn about the structure of a query, how to construct a query, and the available Metadata queries.
Pagination
The Metadata GraphQL implementation utilizies GraphQL's pagination convention using the GraphQL connection model. This means that every entity queried is embedded within a wrapper containing the pagination information. To learn more, see GraphQL Pagination.
GraphQL query enables you to sort and order your queries by using a set of predefined arguments. Available sort arguments are First
(limit), After
(Offset) and OrderBy
.
For example, for Package pagination you can use: (first:5 after:$PackageCursor). The Package cursor is retrieved from the last Package queried. Additionally, you can get the last Package cursor and know if there are additional Packages to query by adding the pageInfo
to your query.
Pagination Example
query { packages ( # filter argument filter: {name: "*" }, first: 5, after: "UGFja2FnZTo1" ) { pageInfo { hasNextPage endCursor } # Connection Model edges { cursor node { #Object fields to be returned by the query name packageType description } } } }
Available Queries
The following are the queries available for the Metadata GraphQL.
Packages
packages( filter: PackageFilter! first: Int after: ID orderBy: PackageOrder ): PackageConnection!
Versions
versions( filter: VersionFilter! first: Int after: ID orderBy: VersionOrder ): VersionConnection!
Files
files( filter: FileFilter! first: Int after: ID orderBy: FileOrder ): FileConnection!
Filter Types
The following describes the available filter names you can use to construct a filter for each of the query types.
PackageFilter!
Filter Name | Type | Description | Example |
---|---|---|---|
| Case sensitive pattern | Match package names against a pattern. |
|
| [PackageType!] | Match packages of one of the given types. |
|
| Time | Match packages with a "created date" equal or after provided date. |
|
| Time | Match packages with a "created date" equal or before provided date. |
|
| Time | Match packages with a "modified date" equal or after provided date. |
|
| Time | Match packages with a "modified date" equal or before provided date. |
|
| Case sensitive pattern | Match packages with the latest version matching the provided pattern. |
|
| Int | Match packages with at least a certain amount of versions. |
|
| Int | Match packages with at most a certain amount of versions. |
|
VersionFilter!
Filter Name | Type | Description | Example |
---|---|---|---|
| Case sensitive pattern | Match version names against a pattern |
|
| Time | Match versions with a "created date" equal or after provided date. |
|
| Time | Match versions with a "created date" equal or before provided date. |
|
| String | Match versions with size greater than or equal to provided size. |
|
| String | Match versions with size less than or equal to provided size. |
|
| List Filter | Match versions with licenses. |
|
| List Filter | Match versions with tags. |
|
| [NameValuePattern!] | Match versions with a specific set of properties. |
|
| [VulnerabilitiesFilter!] | Match versions with vulnerabilities. |
|
FileFilter!
Filter Name | Type | Description | Example |
---|---|---|---|
| Case sensitive pattern | Match file names |
|
| String | Match files with size greater than or equal to provided size. |
|
| String | Match files with size less than or equal to provided size |
|
| Case sensitive pattern | Match MD5 hashes against a pattern |
|
| Case sensitive pattern | Match SHA-1 hashes against a pattern |
|
| Case sensitive pattern | Match SHA-256 hashes against a pattern |
|
Entities and Fields
Packages
Field | Type |
---|---|
| String! |
| String! |
| Time! |
| Time! |
| Int! |
| String! |
| String! |
| String! |
| String! |
| [License!] |
| [Property!] |
| [Qualifier!] |
| [Version] |
| [Source!] |
| [String!] |
| PackageStats |
| Vulnerabilities |
Licenses
Field | Type |
---|---|
| String! |
| String! |
| String! |
| Time! |
| String! |
Properties
Field | Type |
---|---|
| String! |
| String! |
Qualifiers
Field | Type |
---|---|
| String! |
| String! |
Versions
Field | Type |
---|---|
| String! |
| String! |
| Time! |
| Time! |
| Entity |
Entity | |
VersionRepository | |
| Entity |
| VersionsStats |
| Entity |
| Entity |
VersionContributors | |
VersionVulnerabilties |
Sources
Field | Type |
---|---|
| String! |
| String! |
| Time! |
PackageStats
Field | Type |
---|---|
| Int! |
| Int! |
VersionVulnerabilities
Field | Type |
---|---|
| Int! |
| Int! |
| Int! |
| Int! |
| Int! |
| Int! |
Files
Field | Type |
---|---|
| String! |
| String! |
| String! |
| String! |
| Bolean |
| String! |
| String! |
| String! |
| String! |
| String! |
| String! |
| Entity |
VersionRepository
Field | Type |
---|---|
| String! |
| String! |
| String! |
| String! |
VersionStats
Field | Type |
---|---|
| Int! |
VersionContributor
Field | Type |
---|---|
| String! |
| String! |
| String! |
| String! |
Query Examples
Example 1 - Package by name and type
Query
# Query package name and description, filtered by name pattern, ordered by name descending query { packages( filter: { name: "*ello*", packageTypeIn: [NPM, DOCKER] }, first: 3, orderBy: { field: NAME, direction: DESC } ) { edges { node { name description } } } }
Sample Result
{ "data": { "packages": { "edges": [ { "node": { "name": "p2Hello", "description": "Sample Package 2" } }, { "node": { "name": "p1Hello", "description": "Sample Package 1" } }, { "node": { "name": "library/hello-world", "description": null } } ] } } }
Example 2 - Package with its Versions and Licenses by creation date
Query
# Query Package name description and creation date, with its version names and sizes, and associated licenses name and source for each version. # filtered by package creation date, limited to first 3 results. query { packages( filter: { createdMin: "2020-01-01T01:59:00.000Z" }, first: 3 ) { edges { node { name description created versions{ name size licenses{ name source } } } } } }
Sample Result
{ "data": { "packages": { "edges": [ { "node": { "name": "sample_rpm-1", "description": "Sample RPM Package for data generation", "created": "2020-01-05T09:53:21.588Z", "versions": [ { "name": "0:2.0.0-2.0.0", "size": "2080", "licenses": [ { "name": "MIT", "source": "Local File" } ] }, { "name": "0:8.0.0-8.0.0", "size": "2080", "licenses": [ { "name": "MIT", "source": "Local File" } ] } ] } }, { "node": { "name": "example package 7", "description": null, "created": "2020-01-09T18:02:48.604Z", "versions": [ { "name": "0.4.6", "size": "", "licenses": [ { "name": "Apache-2.0", "source": "Local File" } ] } ] } }, { "node": { "name": "another example", "description": "a nice package for web apps", "created": "2020-01-05T17:43:13.979Z", "versions": [ { "name": "1.2.32", "size": "", "licenses": [ { "name": "MIT", "source": "Local File" } ] }, { "name": "1.7.9", "size": "623646", "licenses": [ { "name": "MIT", "source": "Local File" } ] } ] } } ] } } }
Watch the Tutorial
Here is a video demonstrating how to use the GraphQL playground to retrieve packages metadata: