How to Use Voyager

Modified on Fri, 18 Nov 2022 at 11:19 AM

Voyager is a visualization of our data model and how you can interact with the API. You can think of it as a tree or a flowchart of where the API is looking to get the information. You can use it to help yourself form queries for the data you need.

When you first go on onto the Voyager page you're going to be fully zoomed out looking at the full query tree. There are two main sides to it - "Query" and "Mutation". Use the drop down to select which one you'd like. I'm going to use the "Query" side for the example.

To start, have a look at the left most table as this is where all queries or mutations start.

The text on the left hand side of each table are the fields that you can type in to your query, the text on the right hand side is where the API now goes to look for the information/data. If the text on the right is just plain black text it's an endpoint or sometimes called a leaf.

For instance:

-"id" is an endpoint and it returns an ID.

-"children" takes you to back around to "SupCategory" to further query.

Take for example "supSearchMpn", when you click on the link, voyager will move your view to the next table. Now you've got a whole new list of fields you can use nested within your "supSearchMpn" query.

Most likely you would want to see the results set so you then use the "results" field next. However if you wanted to you could use some of the other fields alongside, I'm going to add "hits" to mine.

So far you should have something looking like this:

query voyager_guide{
  supSearchMpn {
    hits
    results{
      
    }
  }
}

If you tried to run this query as it is, you would get an error back as "results" is not a leaf nor does it have any further leaves nested inside of it.

Following the "results" link you should get to the "SupPartResult" table.

From here I'd like to see some information on parts so I'm going to use the "part" field. This now takes us to the "SupPart" table.

For each of these parts, I would like to see their; id, name, a description of what each one is and how much each one would cost me. So for this I'm going to use "id", "name", "shortDescription" and "medianPrice1000". The only one that isn't an endpoint is "medianPrice1000" so following the link I get to one final table. From here I'd like to see the price, what the price is in my currency and what the exchange rate that is in so I'm going to use "price", "convertedPrice" and "conversionRate".

As well as this I've added filters to search for the Mpn "2000", changed my country/currency to GB/GBP and added a condition that the parts must be in stock using "inStockOnly".

query voyager_guide{
  supSearchMpn(
    q: "2000",
    country: "GB",
    currency: "GBP",
    inStockOnly: true
  ){
    hits
    results{
      part {
        id
        mpn
        name
        shortDescription
        medianPrice1000 {
          price
          convertedPrice
          conversionRate
        }
      }
    }
  }
}

Skip Relay

Alongside the "Query"/"Mutation" option there's a check box for "Skip Relay". If this isn't checked you will notice there are more boxes on the page. For queries that will potentially return large amounts of data, we use paging to make things efficient such that we return smaller chunks of data, and only the data we are interested in. The boxes that are hidden when the "Skip Relay" box is checked relate to controlling what pages are shown of a large set of raw data rather than any changes to the data itself.

For example in "desProjects" if the box is unticked then the next table is:

The path is:

"desProjects" then "nodes" to get to the "DesProject" box. If you had many pages of projects then you could use these fields to control the size of the chunks of data that will be returned.

However if it is ticked then you go straight to the "DesProject" box - skipping the boxes about manipulating pages.

Mutations

Using the drop down at the bottom, select "Mutation". This will be a whole new graph:

The layout and process is the same for mutations. You can make comments, new projects and more from here. For the design side of these mutations you will need a Altium workspace.

Type List

If you click on a box in voyager the "Type List" on the left will show a list of the fields in that box and show how they work.

You can search for the field you want at the top. Then if you click into one of these fields it will expand, e.g. "supSearchMpn" shown below:

These are all the inputs that the field takes. For example you might add "limit: 10" or "inStockOnly: true".