How to query using nodes

In this example we take you through how to query using nodes using the Seller API

4 minute read

What you’ll learn

In this article you’ll learn:

How to use node and nodes to query with GraphQL
Why you would do this

“Node” in the context of this article refers to the “node” concept in graph theory, not the popular JavaScript framework!

Why query with Node?

The Marketplacer GraphQL API provides a number of predefined queries that address the most common use-cases when attempting to build an integration into Marketplacer, for example:

Query	What does it do
`allAdverts`	Gives us the ability to search for published, unpublished and deleted adverts
`invoices`	Allows the user to query invoices based on a wide-ranging set of criteria
`allSellers`	Allows the user to query all the sellers participating on the marketplace, irrespective of their status

The full list of queries is available in our full documentation.

However, there may be instances where you need to retrieve objects, (e.g. country, prototype, shipment etc.), where there isn’t a predefined query, in this case you may be able to use the node or nodes construct.

This type of query is suitable when:

The object (e.g. invoice, lineItem etc.) “implements” node
You want to query based on the object ID(s)

What is a node?

The concepts of “nodes” and “edges” are common to graph theory, essentially providing an elegant way to represent hierarchical data. Our Getting Started docs provide a further overview of how this works, including the fact that we implement nodes and edges via the Relay Specification.

Which objects implement node?

To see which objects implement node, and are therefore available query using “node”, we need to perform an introspection query. An introspection query, as the name suggests, allows us to “query ourself” to return some kind of meta-information – in this case a list of objects that implement node.

The query is as follows:

query nodeImplementations{
  __type(name: "Node") {
    possibleTypes {
      name
      description
    }
  }
}

This should yield results similar to the following:

{
  "data": {
    "__type": {
      "possibleTypes": [
        {
          "name": "Address",
          "description": "All information necessary for a complete address."
        },
        {
          "name": "Adjustment",
          "description": "Adjustments to a line item or invoice, e.g. promotion discounts, fees, etc."
        },
        {
          "name": "Admin",
          "description": "Properties of an admin"
        },
        {
          "name": "AdminRole",
          "description": "Admin role"
        },
        {
          "name": "Advert",
          "description": "An advert"
        },
        
        ... and many more ...
      ]
    }
  }
}

Query using node

Armed with:

The list of objects that implement node
The IDs of the objects we want to search for

We can query for either individual objects (node) or multiple objects (nodes) as shown in the examples below:

Node example (Query an Invoice)

query
{
  node(id: "SW52b2ljZS0xMDAzMA=="){
    ... on Invoice{
      __typename
      id
      statusFlags
    }
  }
}

Examining the query further, you’ll note:

Use a fragment (... on Invoice) to specify that we want to query on an Invoice
We specify the __typename as a return attribute in our query, this is somewhat redundant but helps illustrate the point, as shown in the query results below:

{
  "data": {
    "node": {
      "__typename": "Invoice",
      "id": "SW52b2ljZS0xMDAzMA==",
      "statusFlags": [
        "PAID",
        "SENT",
        "REMITTED"
      ]
    }
  }
}

Nodes example (Query Invoices)

This is a slight expansion on the node query in that it allows you to pass an array of object Ids on which to query.

Note that the IDs must relate to the same type of node object, (e.g. Invoice).

query
{
  nodes(ids: [
    "SW52b2ljZS0xMDAzMA==",
    "SW52b2ljZS0xMDAzMQ==",
    "SW52b2ljZS0xMDAyOQ=="
  ])
  {
    ... on Invoice{
      __typename
      id
      statusFlags
      shipments{
        carrier
      }
    }
  } 
}

An example response is shown below:

{
  "data": {
    "nodes": [
      {
        "__typename": "Invoice",
        "id": "SW52b2ljZS0xMDAzMA==",
        "statusFlags": [
          "PAID",
          "SENT",
          "REMITTED"
        ],
        "shipments": [
          {
            "carrier": "Allied Express"
          }
        ]
      },
      {
        "__typename": "Invoice",
        "id": "SW52b2ljZS0xMDAzMQ==",
        "statusFlags": [
          "PAID",
          "SENT",
          "REMITTED"
        ],
        "shipments": [
          {
            "carrier": "Allied Express"
          }
        ]
      },
      {
        "__typename": "Invoice",
        "id": "SW52b2ljZS0xMDAyOQ==",
        "statusFlags": [
          "PAID",
          "SENT",
          "REMITTED"
        ],
        "shipments": [
          {
            "carrier": "Allied Express"
          }
        ]
      }
    ]
  }
}