Facets and Edge Attributes

We’re overhauling Dgraph’s docs to make them clearer and more approachable. If you notice any issues during this transition or have suggestions, please let us know.

Dgraph supports facets --- key value pairs on edges --- as an extension to RDF triples. That is, facets add properties to edges, rather than to nodes. For example, a friend edge between two nodes may have a Boolean property of close friendship. Facets can also be used as weights for edges.

Though you may find yourself leaning towards facets many times, they should not be misused. It wouldn’t be correct modeling to give the friend edge a facet date_of_birth. That should be an edge for the friend. However, a facet like start_of_friendship might be appropriate. Facets are however not first class citizen in Dgraph like predicates.

Facet keys are strings and values can be string, bool, int, float and dateTime. For int and float, only 32-bit signed integers and 64-bit floats are accepted.

The following mutation is used throughout this section on facets. The mutation adds data for some peoples and, for example, records a since facet in mobile and car to record when Alice bought the car and started using the mobile number.

First we add some schema.

curl localhost:8080/alter -XPOST -d $'
    name: string @index(exact, term) .
    rated: [uid] @reverse @count .
' | python -m json.tool | less

curl -H "Content-Type: application/rdf" localhost:8080/mutate?commitNow=true -XPOST -d $'
{
  set {

    # -- Facets on scalar predicates
    _:alice <name> "Alice" .
    _:alice <dgraph.type> "Person" .
    _:alice <mobile> "040123456" (since=2006-01-02T15:04:05) .
    _:alice <car> "MA0123" (since=2006-02-02T13:01:09, first=true) .

    _:bob <name> "Bob" .
    _:bob <dgraph.type> "Person" .
    _:bob <car> "MA0134" (since=2006-02-02T13:01:09) .

    _:charlie <name> "Charlie" .
    _:charlie <dgraph.type> "Person" .
    _:dave <name> "Dave" .
    _:dave <dgraph.type> "Person" .


    # -- Facets on UID predicates
    _:alice <friend> _:bob (close=true, relative=false) .
    _:alice <friend> _:charlie (close=false, relative=true) .
    _:alice <friend> _:dave (close=true, relative=true) .


    # -- Facets for variable propagation
    _:movie1 <name> "Movie 1" .
    _:movie1 <dgraph.type> "Movie" .
    _:movie2 <name> "Movie 2" .
    _:movie2 <dgraph.type> "Movie" .
    _:movie3 <name> "Movie 3" .
    _:movie3 <dgraph.type> "Movie" .

    _:alice <rated> _:movie1 (rating=3) .
    _:alice <rated> _:movie2 (rating=2) .
    _:alice <rated> _:movie3 (rating=5) .

    _:bob <rated> _:movie1 (rating=5) .
    _:bob <rated> _:movie2 (rating=5) .
    _:bob <rated> _:movie3 (rating=5) .

    _:charlie <rated> _:movie1 (rating=2) .
    _:charlie <rated> _:movie2 (rating=5) .
    _:charlie <rated> _:movie3 (rating=1) .
  }
}' | python -m json.tool | less

Facets on scalar predicates

Querying name, mobile and car of Alice gives the same result as without facets.

{
  data(func: eq(name, "Alice")) {
    name mobile car
  }
}

The syntax @facets(facet-name) is used to query facet data. For Alice the since facet for mobile and car are queried as follows.

{
  data(func: eq(name, "Alice")) {
    name mobile @facets(since) car @facets(since)
  }
}

Facets are returned at the same level as the corresponding edge and have keys like edge|facet.

All facets on an edge are queried with @facets.

{
  data(func: eq(name, "Alice")) {
    name mobile @facets car @facets
  }
}

Facets i18n

Facets keys and values can use language-specific characters directly when mutating. But facet keys need to be enclosed in angle brackets <> when querying. This is similar to predicates. See Predicates i18n for more info.

Dgraph supports Internationalized Resource Identifiers (IRIs) for facet keys when querying.

Example:

{
  set {
    _:person1 <name> "Daniel" (वंश="स्पेनी", ancestry="Español") .
_:person1 <dgraph.type> "Person" . _:person2 <name> "Raj" (वंश="हिंदी",
ancestry="हिंदी") . _:person2 <dgraph.type> "Person" . _:person3 <name> "Zhang
Wei" (वंश="चीनी", ancestry="中文") . _:person3 <dgraph.type> "Person" . } }
. _:person2 <dgraph.type> "Person" . _:person3 <name> "Zhang Wei" (वंश="चीनी",
ancestry="中文") . _:person3 <dgraph.type> "Person" .
  }
}

Query, notice the <>’s:

{ q(func: has(name)) { name @facets(<वंश>) } }

Alias with facets

Alias can be specified while requesting specific predicates. Syntax is similar to how would request alias for other predicates. orderasc and orderdesc are not allowed as alias as they have special meaning. Apart from that anything else can be set as alias.

Here we set car_since, close_friend alias for since, close facets respectively.

{
  data(func: eq(name, "Alice")) { name mobile car @facets(car_since: since)
    friend @facets(close_friend: close) { name }
  }
}

Facets on UID predicates

Facets on UID edges work similarly to facets on value edges.

For example, friend is an edge with facet close. It was set to true for friendship between Alice and Bob and false for friendship between Alice and Charlie.

A query for friends of Alice.

{
  data(func: eq(name, "Alice")) {
    name friend { name }
  }
}

A query for friends and the facet close with @facets(close).

{
  data(func: eq(name, "Alice")) {
    name friend @facets(close) { name }
  }
}

For uid edges like friend, facets go to the corresponding child under the key edge|facet. In the above example you can see that the close facet on the edge between Alice and Bob appears with the key friend|close along with Bob’s results.

{
  data(func: eq(name, "Alice")) {
    name friend @facets { name car @facets }
  }
}

Bob has a car and it has a facet since, which, in the results, is part of the same object as Bob under the key car|since. Also, the close relationship between Bob and Alice is part of Bob’s output object. Charlie does not have car edge and thus only UID facets.

Filtering on facets

Dgraph supports filtering edges based on facets. Filtering works similarly to how it works on edges without facets and has the same available functions.

Find Alice’s close friends

{
  data(func: eq(name, "Alice")) { friend @facets(eq(close, true)) { name }
  }
}

To return facets as well as filter, add another @facets(<facetname>) to the query.

{
  data(func: eq(name, "Alice")) {
    friend @facets(eq(close, true)) @facets(relative) { # filter close
      friends and give relative status name
    }
  }
}

Facet queries can be composed with AND, OR and NOT.

{
  data(func: eq(name, "Alice")) {
    friend @facets(eq(close, true) AND eq(relative, true)) @facets(relative) {
      # filter close friends in my relation name
    }
  }
}

Sorting using facets

Sorting is possible for a facet on a uid edge. Here we sort the movies rated by Alice, Bob and Charlie by their rating which is a facet.

{
  me(func: anyofterms(name, "Alice Bob Charlie")) { name rated
@facets(orderdesc: rating) { name } }
}

Assigning Facet values to a variable

Facets on UID edges can be stored in value variables. The variable is a map from the edge target to the facet value.

Alice’s friends reported by variables for close and relative.

{
  var(func: eq(name, "Alice")) { friend @facets(a as close, b as relative) }

  friend(func: uid(a)) { name val(a) }

  relative(func: uid(b)) { name val(b) }
}

Facets and Variable Propagation

Facet values of int and float can be assigned to variables and thus the values propagate.

Alice, Bob and Charlie each rated every movie. A value variable on facet rating maps movies to ratings. A query that reaches a movie through multiple paths sums the ratings on each path. The following sums Alice, Bob and Charlie’s ratings for the three movies.

{
  var(func: anyofterms(name, "Alice Bob Charlie")) {
    num_raters as math(1) rated @facets(r as rating) {
      total_rating as math(r) # sum of the 3 ratings average_rating as math(total_rating / num_raters)
    }
  }
  data(func: uid(total_rating)) { name val(total_rating) val(average_rating) }
}

Facets and Aggregation

Facet values assigned to value variables can be aggregated.

{
  data(func: eq(name, "Alice")) { name rated @facets(r as rating) { name }
    avg(val(r))
  }
}

Note though that r is a map from movies to the sum of ratings on edges in the query reaching the movie. Hence, the following does not correctly calculate the average ratings for Alice and Bob individually --- it calculates 2 times the average of both Alice and Bob’s ratings.

{
  data(func: anyofterms(name, "Alice Bob")) { name rated @facets(r as rating) {
    name
  }
  avg(val(r))
}
}

Calculating the average ratings of users requires a variable that maps users to the sum of their ratings.

{
  var(func: has(rated)) {
    num_rated as math(1) rated @facets(r as rating) {
      avg_rating as math(r / num_rated)
    }
  }

  data(func: uid(avg_rating)) { name val(avg_rating) }
}