Querying Data
Faros provides a flexible GraphQL API to query data across all connected sources. GraphQL is one of the standard query languages for querying information on the web. To learn more about GraphQL please visit the GraphQL website.
Trying out GraphQL
You can try out the Faros GraphQL API by selecting GraphQL
from the Inspect
menu in the navigation panel. This opens up the GraphQL explorer where you can see the entities that Faros is aware of in the Explorer
panel. You can formulate a GraphQL query either by selecting entities and fields from the Explorer
panel, or by directly typing in your query.

Query Explorer
Here is an example query to try out. Copy-paste it into the query window, and hit the play
button to execute the query and see the results on your data. This assumes you have already connected a source-control system such as GitHub to Faros.
query PRs {
vcs {
repositories {
nodes {
name
pullRequests {
nodes {
title
state {
category
}
author {
uid
}
}
}
}
}
}
}
This query returns all your repositories, along with their pull requests, as well as information about the PR authors. This is the power of Farosβ GraphQL API: you can accomplish with a single query, what would ordinarily require multiple API calls (with potentially multiple credentials) to multiple remote APIs.
Querying data across sources
In addition to querying data from within a source, the Faros GraphQL API also enables querying data from across sources. For instance, if you've connected up both your CI/CD systems and source control systems to Faros, you can query all the builds associated with your 10 most recent commits with the following query:
query CommitsAndBuilds {
vcs {
commits(last: 10) {
nodes {
sha
message
repository {
name
createdAt
}
buildAssociations {
nodes {
build {
startedAt
endedAt
status {
category
detail
}
}
}
}
}
}
}
}
Here the commits may come from a source control system such as GitHub and the builds from a CI/CD system such as Jenkins. But you can retrieve information from across both these systems with a single query: Faros automatically resolves the joins.
Filtering your data
The (last: 10)
in the example above is an example of a filter. The Faros schema comes with certain default filters that allow you to paginate (before
/after
) and filter by time (first
/last
), but Faros also lets you add the ability to filter entities by additional columns in the schema.
Navigate to the Filters
in the Inspect
menu on the left. Select the entity you wish to make filterable, and you will get a drop-down list of fields that you can ask Faros to index the data on. In the example below we would like to make the vcs_Repository
entity filterable on the name
column.

Filters
With this change, we can now try a query like the one below to only retrieve pull requests from a specific repo my-repo
:
query FilteredPRs {
vcs {
repositories(filter: {name: {equalTo: "my-repo"}}) {
nodes {
name
pullRequests {
nodes {
title
state {
category
}
author {
uid
}
}
}
}
}
}
}
Updated 4 months ago