While Hygraph works well for many types of content, sometimes, for a variety of reasons, not all your content will live in Hygraph. No worries, that’s why we have Content Federation and Remote Sources.

In this demo, we’ll explore how to take the basic e-commerce starter and combine Hygraph product information with a third-party database for product reviews. The same principles at play in this example will work with any other GraphQL API and Hygraph data.

#Requirements

• A Hygraph project (ideally from the Hygraph Commerce starter)
• A FaunaDB account

#Setting up FaunaDB

To begin, we’ll set up a new database and collection in Fauna. To do this, sign up or log into your Fauna account and create a new database. We’ll call the database “reviews.” Inside this new database, create a Collection. The Collection can also be called reviews.

Once we have a database and Collection, we can add our first piece of data. Since Fauna is a NoSQL document store, we can create an object in the document.

We’ll add four data points for each review: reviewer name, rating, content, and product ID (which will match a Hygraph slug or ID or any unique identifier on the product data in Hygraph).

{
  "rating": 4,
  "productId": "unisex-long-sleeve-tee",
  "name": "Bryan Robinson",
  "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris ac cursus massa. Nam sit amet ornare justo. Proin faucibus mi et tellus finibus sodales. Phasellus consequat pulvinar neque ac tristique. Pellentesque nulla velit, scelerisque id ante quis, ultricies viverra arcu. Integer ac risus dictum, tempus urna non, eleifend sapien. Cras rhoncus lacus at ligula auctor aliquam. Nunc fringilla facilisis lorem quis rhoncus. Quisque convallis venenatis urna, a tincidunt urna convallis non. Suspendisse vitae cursus lorem. Integer tempor sed felis quis condimentum. Etiam vel ex lacinia, consequat sapien quis, dapibus lacus. In maximus dapibus mauris, id euismod ante tincidunt non. Donec in nunc pulvinar lacus faucibus pellentesque."
}

Fauna will automatically generate a custom ID and a time stamp for every object entered. Note the productId property. This lines up with the demo content in the e-commerce starter, but whatever identifier makes the most sense for your project can be used here. The rating is an integer, and the name and content are both strings.

From here, we have a Fauna database ready for querying. In order to use it most efficiently, we need to set up a GraphQL end point for our Collection.

Setting up a Fauna GraphQL endpoint

To set up a GraphQL endpoint, navigate in your Fauna dashboard to the GraphQL section. Nothing will be waiting for you. We need to add a schema for our data and a specific query to get our reviews. To do this, we upload a GraphQL schema file.

type Review @collection(name: "reviews") {
    name: String!
    productId: String!
    content: String
    rating: Int!
}

type Query {
    reviewsByHygraphSlug(productId: String!): [Review]
}

This is a fairly simple schema and query but note the @collection directive. This directive lets us keep associating a specific type with a collection name. If they were named exactly the same, we wouldn’t need this, but it can help to keep best practices from both GraphQL and Fauna in place and associate the two.

Now that we have a schema set up, we can run a quick query in the GraphQL playground inside Fauna to give it a try.

query Reviews($slug: String!) {
  reviewsByHygraphSlug(productId:$slug){
    data{
      name
      rating
      content
      productId      
    }
  }
}

With this query and the productId slug from the created document above, we can get a list of reviews with that productId. This means we can get it by the Hygraph slug from within Hygraph.

Add an Fauna API key

In order to use this data in Hygraph, we need an API. Head over to the “Security” page in Fauna and click “New key.”

Tell it which database to use (if you’re following along, there should only be one), and select a role. This key is fine to set up as a Server key, but you can also go into Roles and set up a custom role to keep permissions as granular as you need.

Once this is saved in, Fauna will display your key. This is the only time to copy it, so make sure to grab it before moving on. We’ll use that in our Remote Source in Hygraph.

#Setting up a remote source

While we could set up a separate API call to Fauna to get all the reviews at build or request time, it would be a much strong developer experience to only make one API call to Hygraph and get all the data we need for a given product. To do that, we can use Hygraph’s Remote Sources and Remote Source Fields.

To set this up, head over to your Hygraph project (ideally one created from this starter), and open up the Schema view.

Click “Add” under Remote Sources and fill out the following information:

• Name the remote source “Fauna Reviews”
• Select GraphQL for the remote source type
• The Base URL is the GraphQL URL from your Fauna database (typically something like https://graphql.us.fauna.com/graphql )
• Add an Authorization header set to Bearer <your-api-key>
• Add this same header to the Introspection Headers
• Click save

This creates a connection between Fauna’s GraphQL API and Hygraph. Once this is set up, we need to set up a GraphQL Remote Source Field for our products.

#Add a remote source field

Navigate to the Product Schema. In the available Fields, there is now a “GraphQL Field.” Click this, and it’s time to set up the field to pull the correct data for each product.

Give the field a name and an API ID and in the “Query” builder, select “ReviewsByHygraphSlug” — the query we built in our schema for Fauna. Choose productId as the query argument. In the input below that checkbox select {{doc.slug}} which will pull the current document’s slug as the value to pass to that argument.

Once we have that, we could go ahead and query. However, our query would always require we get the data object off the response. This is an extra bit that we don’t have to deal with. Click the checkbox by “Data” in the “Fields” list. This will put the data in the root of the response from the query. Now the data will be available one level up — a small but pleasant improvement.

#Craft a query to get Hygraph data and Fauna data

Now that we have this field saved, we can navigate to any product, and we can see the new “Fauna Reviews” field. The only thing it will display is a “Preview in Playground” link. If you’re using the default e-commerce starter data, you should have a product with a slug “unisex-long-sleeve-tee”. Navigate to that product and click the Preview button for the Fauna Reviews field.

This will take us to the API playground with the basic query to this item. We can expand the faunaReviews array with the data we require right next to additional information on the product itself.

query content_product_faunaReviews($id: ID!) {
  values: product(where: {id: $id}) {
    slug
    name
    faunaReviews {
      name
      rating
      content
      _ts
    }
  }
}

We don’t have to do any normalization, extra queries, or even pass in arguments in this call. It’s all combined for us by the GraphQL API in Hygraph. This data can now be used in the frontend to show reviews alongside all the product information.

#Next steps

Once you have this setup, you can add additional databases or data from Fauna. You could also pull product information in the same way from something like BigCommerce or Shopify — including using the new Shopify extension to help. The same could go for any third-party review application that has an API. As long as you have a unique identifier that can be entered into Hygraph, you can pull any additional information you need.