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.

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.

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
            }
          }
        }
      }
    }
  }
}