GraphQL

Fluree supports queries and transactions using GraphQL. GraphQL supports a more limited set of query capability than FlureeQL. Fluree's version of GraphQL supports a wide-range of GraphQL features, but not all of them.

If you don't already know and want to use GraphQL, we definitely recommend using FlureeQL. This section is an overview of GraphQL, and highlights key differences between FlureeQL and GraphQL. Throughout the rest of the documentation, you can toggle the left sidebar to see all applicable examples in GraphQL.

Because FlureeQL is a JSON format, this allows queries to be more easily composed within your programming code and is built to support Fluree's advanced capabilities like graph recursion.

All GraphQL queries and transactions should be run through the /graphql endpoint.

Queries

Using GraphQL, you can only retrieve predicates from within the namespace that you specify. In the below example, we indicate that we are looking in the chat collection.

Therefore, we can only retrieve predicates like _id, message, person, or comments, which are in the chat namespace.

{ graph {
  chat {
    _id
    message
  }
}
}

Fluree allows any reference predicate to point to any subject, regardless of collection type.

However, in order to retrieve references using GraphQL, the restrictCollection property of that predicate has to be set to a valid collection. This second example retrieves not only the _id and message for each chat, but the _id and handle predicates for the person associated with each chat.

{ graph {
  chat {
    _id
    message
    person {
        _id
        handle
    }
  }
}
}

Wildcards

GraphQL does not usually support the use of wildcards ( *), so most GraphQL interfaces will show an error when you attempt to use a wildcard. However, if you submit, the following query, the expected results will be returned.

# Note this may show an error in your GraphQL tool, but it will return the expected result. 

{ graph {
  person {
    *
  }
}
}

Reverse References

In addition to retrieving information in a forward-direction, we can also traverse the graph backwards.

The syntax for doing so differs from FlureeQL to GraphQL. While FlureeQL uses the format chat/_person, GraphQL performs the same query with chat_Via_person.

Using GraphQL:

{ graph {
  person {
    chat_Via_person {
      _id
      instant
      message
    }
  }
}
}

Using FlureeQL

{
  "select": [
    "*",
    {"chat/_person": ["*"]}
  ],
  "from": "person"
}

Block Queries

In order to query a specific block or range of blocks in GraphQL, you need to use a specific type of block query and specify the range of blocks you would like to see.

Querying a single block

query  {
  block(from: 3, to: 3)
}

Querying a range of blocks

query  {
  block(from: 3, to: 5)
}

Querying a range of blocks starting from a lower limit

query  {
  block(from: 3)
}

Search by Id or Ident

To query a specific subject id, you can use the _id option, as seen below.

{ graph {
  chat(_id: 369435906932737) {
    _id
    comments
    instant
    message
    person
  }
}
}

To query a unique two-tuple, you can use the ident option, as seen below.

# Note this may show an error in your GraphQL tool, but it will return the expected result. 

{ graph {
  person1(ident: ["person/handle", "jdoe"]){
    _id
    handle
    fullName
  }
    person2(ident: ["person/handle", "zsmith"]){
    _id
    handle
    fullName
  }
}
}

Sort By

GraphQL queries allow you to sort any field at any level in the graph. In order to perform a sort, you need to specify both the attribute name and whether you would like to sort the values by ascending or descending values.

In the below example, we are sorting chat messages in alphabetical order.

{ graph {
  chat (sort: {attribute: "message", order: ASC}) {
    _id
    instant 
    message
  }
}
}

The below query sorts every person alphabetically by their full name, and then sorts all of their comments by message.

{ graph {
   person (sort: {attribute: "fullName", order: ASC}) {
    fullName
    comment_Via_person (sort:{attribute: "message", order: DESC}) {
      message
      instant
    }
  }
}
}

Query with sort. Get all chat messages sorted alphabetically by message.

{ graph {
  chat (sort: {attribute: "message", order: ASC}) {
    _id
    instant 
    message
  }
}
}

Query with sort. Get all people, sorted alphabetically by full name, and get each person's chat messages sorted from oldest to newest.

{ graph {
   person (sort: {attribute: "fullName", order: ASC}) {
    fullName
    comment_Via_person (sort:{attribute: "instant", order: ASC}) {
      message
      instant
    }
  }
}
}

Transactions

We can perform transactions in GraphQL by passing a variable to a GraphQL mutation. This variable should contain a JSON-formatted parcel of data without line breaks.

As you can see in the below example, in order to add people, we store the JSON-formatted data in a variable called myPeopleTx and use the variable myPeopleTx in the mutation statement.

We also need to ensure that all " are escaped, like so \". If you use $ anywhere in your transaction, that also needs to be escaped. If using GraphQL for transactions, we recommend using # as the delimiting characters in tempids (i.e. person#1 rather than person$1), as # does not need to be escaped.

mutation addPeople ($myPeopleTx: JSON) {
  transact(tx: $myPeopleTx)
}

{
  "myPeopleTx": "[{ \"_id\": \"person\", \"handle\": \"aSmith\", \"fullName\": \"Alice Smith\" }, { \"_id\": \"person\", \"handle\": \"aVargas\", \"fullName\": \"Alex Vargas\" }]"
}

If you are using the UI, you can place your variable in the "Query Variables" section on the lower left hand side of the GraphQL interface. If you are using the API, you should add a new key, "variables" to your request body and include your variables (more information in the /graphql reference section on GraphQL endpoints.

Other Features

Fluree's version of GraphQL supports both variables (as evident in Transactions) and fragments.

We support introspection and type queries, as well.

Sub-Select Queries

Simply list the options inside of parentheses immediately after the chosen predicate. For example, we can limit the chat_Via_person predicates to only show 10 chats (in GraphQL, reverse references use Via rather than /_).

Note that in GraphQL, the options do not have a leading underscore. In GraphQL, the options that you can include are:

Key	Description
limit	Limit (integer) of results to include. Only for multi and ref predicates.
recur	Number of times (integer) to follow a relationship. Only for ref predicates.
as	Alternate name for a predicate. Only for ref predicates.

{ graph {
  person {
    _id
    handle
    chat_Via_person (limit: 10) {
      instant
      message
      comments {
        message
      }
    }
  }
}}