浏览一下 - https://tour.dgraph.io

Dgraph的 GraphQL+- 基于Facebook的GraphQL。GraphQL不是为Graph数据库开发的，但它的图形式查询语法，模式验证和子图形状响应使其成为一种很好的语言选择。我们修改了语言以更好地支持图形操作，添加和删除功能以最适合图形数据库。我们称这种简化的，功能丰富的语言为“GraphQL+- ”。

GraphQL+-正在开发中。我们正在添加更多功能，我们可能会进一步简化现有功能。

浏览一下 - https://tour.dgraph.io

本文档是Dgraph查询参考资料。这不是一个教程。它被设计为已经知道如何在GraphQL+-中编写查询的用户的参考，但需要检查语法，索引或函数等。

注意 如果您是Dgraph的新手并想学习如何使用Dgraph和GraphQL+-，请浏览一下 - https://tour.dgraph.io

运行示例

该参考文献中的示例使用了关于电影和演员的2100万三倍的数据库。示例查询运行并返回结果。查询由运行在 https://play.dgraph.io/ 的Dgraph实例执行。要在本地运行查询或进行更多实验，请参阅入门 指南，该指南还说明如何加载此处示例中使用的数据集。

GraphQL+-基本原理

GraphQL+- 查询根据搜索条件查找节点，匹配图中的模式并返回图形作为结果。

查询由嵌套块组成，从查询根开始。根找到初始节点集，应用以下图形匹配和过滤。

返回结果

每个查询都有一个名称，在查询根目录中指定，并且相同的名称标识结果。

如果边是值类型，则可以通过给出边名来返回该值。

查询示例：在示例数据集中，将电影链接到导演和演员的边，电影具有许多众所周知的电影数据库的名称，发布日期和标识符。这个名为bladerunner的查询，以及与电影名称匹配的根，返回80年代早期科幻经典“Blade Runner”的值。

{
  bladerunner(func: eq(name@en, "Blade Runner")) {
    uid
    name@en
    initial_release_date
    netflix_id
  }
}

对于所有“name”边缘等于“Blade Runner”的节点，查询首先使用索引搜索图形，以使搜索更有效。对于找到的节点，查询然后返回列出的传出边。

每个节点都有一个唯一的64位标识符。上面查询中的uid边缘返回该标识符。如果已知所需节点，则函数“uid”找到该节点。

查询示例：通过UID找到的“Blade Runner”电影数据。

{
  bladerunner(func: uid(0x107b2c)) {
    uid
    name@en
    initial_release_date
    netflix_id
  }
}

查询可以匹配许多节点并返回每个节点的值。

查询示例：名称中包含“Blade”或“Runner”的所有节点。

{
  bladerunner(func: anyofterms(name@en, "Blade Runner")) {
    uid
    name@en
    initial_release_date
    netflix_id
  }
}

可以在列表中为uid函数指定多个ID。

查询示例：

{
  movies(func: uid(0x107b2c, 0x85f961)) {
    uid
    name@en
    initial_release_date
    netflix_id
    ~director.film {
      uid
      name@en
    }
  }
}

注意 如果你的谓词有特殊字符，那么你应该在查询中询问它时用尖括号包装它。 例如 <first:name>

扩展图形边缘

查询通过使用 { } 嵌套查询块来扩展节点之间的边缘。

Query Example: 查询在“Blade Runner”中扮演的演员和角色。 查询首先找到名为“Blade Runner”的节点, 然后将传出的“starring”边缘跟随表示actor作为角色的表现的节点。 从那里扩展performance.actor 和 performance,character 的边，以找到电影中每个演员的演员姓名和角色。

{
  brCharacters(func: eq(name@en, "Blade Runner")) {
    name@en
    initial_release_date
    starring {
      performance.actor {
        name@en  # actor name
      }
      performance.character {
        name@en  # character name
      }
    }
  }
}

注释

# 后面的任何内容都是注释。

应用过滤器

查询根找到一组初始节点，查询通过返回值和后续边缘继续进一步节点继续进行 - 查询中到达的任何节点都是在根搜索后通过遍历找到的。 找到的节点可以通过在根之后或任何边缘应用 @ filter 进行过滤。

查询示例: 查询导演雷德利斯科特在2000年之前发布的电影“Blade Runner”。

{
  scott(func: eq(name@en, "Ridley Scott")) {
    name@en
    initial_release_date
    director.film @filter(le(initial_release_date, "2000")) {
      name@en
      initial_release_date
    }
  }
}

查询示例：查询标题中带有“Blade”或“Runner”，并在2000年之前发行的电影。

{
  bladerunner(func: anyofterms(name@en, "Blade Runner")) @filter(le(initial_release_date, "2000")) {
    uid
    name@en
    initial_release_date
    netflix_id
  }
}

语言支持

注意 这 @lang 指令 必须明确指定对应schema 的 query 或者 mutate 的谓语后面跟随的特定的语言标记.

Dgraph 支持 UTF-8 字符.

在一个查询中, 对于一个字符类型的 edge, 语法如下

edge@lang1:...:langN

按照如下规则，依据指定的顺序与语言返回

• 最多一个返回.
• 列表返回顺序，优先级从左到右: 一个没找到就往下找，找到就返回.
• 这个列表都没匹配到，就不返回.
• 最后一个 .意味着没有指定语言或者对应的值没有匹配到特定的语言, 某个被匹配到的语言会返回.

举例如下:

• name => 查找标识值为空的语言; 如果标识值不存在，什么都不返回.
• name@. => 查找标识值为空的语言,然后查找任意一种语言.
• name@en => 查找标识值为 en的语言; 如果标识值 en 没匹配到，什么都不返回.
• name@en:. => 查找标识值为 en的语言, 然后是未标识的语言, 最后是任意一种语言.
• name@en:pl => 查找标识值为 en的语言, 然后是 pl, 没有匹配到,什么都不返回.
• name@en:pl:. => 查找标识值为en的语言, 然后是pl的语言, 接着找未标识的语言, 最后是任意一种语言.

注意 在函数中,不支持多种语言.只能查找一种语言, . 符号 和 属性名也不支持多语言

注意 在全文搜索函数中(alloftext, anyoftext), 没有指定特定语言的标识值，默认使用英文标识器tokenizer

查询案例: 查找演员 Farhan Akhtar’s 导演的电影 按照下面三种语言分类 俄语 印度语 英语 显示,其他语言不显示.

{
  q(func: allofterms(name@en, "Farhan Akhtar")) {
    name@hi
    name@en
    director.film {
      name@ru:hi:en
      name@en
      name@hi
      name@ru
    }
  }
}

函数

注意 函数只能被应用在已经建立索引的谓词上

函数允许基于节点或变量的属性进行筛选。函数可以应用于查询根或过滤器中。

对于字符串值谓词上的函数，如果没有提供语言首选项，则将该函数应用于所有没有语言标记的语言和字符串;如果给定了语言首选项，则该函数仅应用于给定语言的字符串.

词匹配

所有的词 allofterms

语法: allofterms(predicate, "space-separated term list")

Schema 类型: string

索引 要求: term

匹配以任何顺序包含所有指定项的字符串;不区分大小写.

在根节点使用 Usage at root

查询案例: 在全部节点中查找 名字name 包含词indiana 和 jones, 返回 英语名字 和英语电影类型.

{
  me(func: allofterms(name@en, "jones indiana")) {
    name@en
    genre {
      name@en
    }
  }
}

使用过滤器

查询案例: 所有史蒂文·斯皮尔伯格的电影中 indiana and jones这两个词. 这个过滤器@filter(has(director.film)) 删除不是Steven Spielberg导演的节点 —- 这些数据还包括一部名为史蒂文·斯皮尔伯格(Steven Spielberg)的电影中的一个角色.

{
  me(func: eq(name@en, "Steven Spielberg")) @filter(has(director.film)) {
    name@en
    director.film @filter(allofterms(name@en, "jones indiana"))  {
      name@en
    }
  }
}

任意一个词 anyofterms

语法: anyofterms(predicate, "space-separated term list")

Schema 类型: string

索引 要求: term

匹配具有任意顺序指定项的字符串;不区分大小写.

在根节点使用 Usage at root

查询案例: 所有节点名字name包含 poison 或者 peacock. 返回的许多节点是影片, 但是像琼·皮科克(Joan Peacock)这样的人也符合搜索条件,因为级联指令没有指定查询需要类型。

{
  me(func:anyofterms(name@en, "poison peacock")) {
    name@en
    genre {
      name@en
    }
  }
}

Usage as filter

查询案例: 所有史蒂文·斯皮尔伯格的电影都包含战争或间谍 war or spies。过滤器 @filter(has(director.film))过滤掉名为Steven Spielberg的节点，但这些这些节点不是导演———这些数据包含一个名为Steven Spielberg的电影中的角色。

{
  me(func: eq(name@en, "Steven Spielberg")) @filter(has(director.film)) {
    name@en
    director.film @filter(anyofterms(name@en, "war spies"))  {
      name@en
    }
  }
}

正则表达式

语法: regexp(predicate, /regular-expression/) 或不区分大小写 regexp(predicate, /regular-expression/i)

Schema 类型: string

索引 要求: trigram

通过正则表达式匹配字符串。正则表达式语言是go语言的正则表达式.

查询案例: 从根节点开始，将节点与名称开头为 Steven Sp匹配，后面跟着任何字符。对于每个匹配的uid，匹配包含 ryan的影片。注意与 allofterms函数的不同, allofterms函数 只匹配ryan但是正则表达式会所有包含ryan, 例如 bryan.

{
  directors(func: regexp(name@en, /^Steven Sp.*$/)) {
    name@en
    director.film @filter(regexp(name@en, /ryan/i)) {
      name@en
    }
  }
}

技术细节

一个三元组是三个连续符文的子串。例如 Dgraph 的三元组有 Dgr, gra, rap, aph。

为保证正则表达式匹配的效率, Dgraph使用三元组索引trigram indexing.也就是说，Dgraph将正则表达式转换为三元组查询，使用三元组索引和三元组查询查找可能的匹配项，并仅对可能的项应用完整的正则表达式搜索。

编写有效的正则表达式和限制条件

当你设计正则表达式查询语句是把如下建议记在脑中

• 至少一个三元组必须与正则表达式匹配 (不支持正则模式少于三个字符的)。也就是说, Dgraph 要求查询的正则表达式要能被转换为一个三元组.
• 正则表达式匹配的备选三元组的数量应该尽可能少([a-zA-Z][a-zA-Z][0-9] 这样的正则不是一个好选择)。许多可能的匹配意味着对要对许多字符串检查完整的正则表达式; 然而,如果正则表达式强制匹配更多的三元组，Dgraph 最好地使用索引，并根据更小的可能匹配集代替检查完整的正则表达式。
• 因此，正则表达式应该尽可能精确。匹配较长的字符串意味着需要更多的三元组，这有助于有效地使用索引。
• 如果使用重复的正则符号(*, +, ?, {n,m}), 整个正则表达式必须不匹配空字符串或任意字符串，例如, * 可以这样使用[Aa]bcd* 但不能这样 (abcd)* 或者这样 (abcd)|((defg)*)
• 重复的正则符号在括号表达式后面(例如. [fgh]{7}, [0-9]+ or [a-z]{3,5}) 通常被认为匹配任意字符串因为他们匹配太多元组。
• 如果部分结果(对于三元组的子集) 超过 1000000 uids 在索引扫描时,这条查询由于过于查询代价过于昂贵阻止被禁止。

全文检索

语法: alloftext(predicate, "space-separated text") 和 anyoftext(predicate, "space-separated text")

Schema 类型: string

索引 要求: fulltext

应用词干分析和停止词的全文检索来查找匹配所有或任何给定文本的字符串。

在索引生成和处理全文搜索参数时，应用以下步骤:

1. 标记化(根据Unicode单词边界)。
2. 转换为小写的。
3. 单点标准化(以KC形式标准化)(to Normalization Form KC).
4. 使用特定于语言的词干分析器进行词干分析(如果有语言支持)。
5. 停止词删除(如果有语言支持)。

Dgraph使用bleve作为全文搜索索引。参见bleve语言特定的停止单词列表。

下表包含所有支持的语言，对应的国家代码，词干提取和停止过滤支持。

查询案例: 所有名字有run, running, 等词 和 man。消除停止字 the 和 maybe

{
  movie(func:alloftext(name@en, "the man maybe runs")) {
     name@en
  }
}

不等式

等于

语法例子:

• eq(predicate, value)
• eq(val(varName), value)
• eq(predicate, val(varName))
• eq(count(predicate), value)
• eq(predicate, [val1, val2, ..., valN])

Schema 类型: int, float, bool, string, dateTime

索引 要求: eq(predicate, ...) 需要一个索引 (请参阅下面的表)。 对于在查询根 count(predicate),需要@count上有索引.对于变量，值是作为查询的一部分计算的，因此不需要索引。

测试谓词或变量的值是否相等或能否与列表中的值对应。

布尔常量是 true and false, 因此对于 eq , 就变成了, eq(boolPred, true).

查询示例: 恰好属于有13种类型的电影.

{
  me(func: eq(count(genre), 13)) {
    name@en
    genre {
        name@en
    }
  }
}

查询示例: 名字叫史蒂文且执导过1部、2部或3部电影。

{
  steve as var(func: allofterms(name@en, "Steven")) {
    films as count(director.film)
  }
  stevens(func: uid(steve)) @filter(eq(val(films), [1,2,3])) {
    name@en
    numFilms : val(films)
  }
}

小于，小于或等于，大于，大于或等于

语法示例:不等式 IE

• IE(predicate, value)
• IE(val(varName), value)
• IE(predicate, val(varName))
• IE(count(predicate), value)

IE 可以替换成下面这些

• le 小于或等于
• lt 小于
• ge 大于或等于
• gt 大于

Schema 类型: int, float, string, dateTime

索引 要求: IE(predicate, ...) 需要一个索引 (请参阅下面的表)。 对于在查询根 count(predicate),需要@count上有索引.对于变量，值是作为查询的一部分计算的，因此不需要索引。

查询示例: 1980年以前上映的雷德利·斯科特电影。

{
  me(func: eq(name@en, "Ridley Scott")) {
    name@en
    director.film @filter(lt(initial_release_date, "1980-01-01"))  {
      initial_release_date
      name@en
    }
  }
}

查询示例:电影导演名字含有 Steven 同时指导超过100名演员。

{
  ID as var(func: allofterms(name@en, "Steven")) {
    director.film {
      num_actors as count(starring)
    }
    total as sum(val(num_actors))
  }
  dirs(func: uid(ID)) @filter(gt(val(total), 100)) {
    name@en
    total_actors : val(total)
  }
}

查询示例:每类电影超过30000部。因为这边没有指定电影种类返回按照什么顺序排序 将使用UID排序。count 索引记录节点外的边数，并进行更多的查询。

{
  genre(func: gt(count(~genre), 30000)){
    name@en
    ~genre (first:1) {
      name@en
    }
  }
}

查询示例:查找名字为斯蒂芬·斯皮尔伯格导演的电影，同时要求initial_release_date大于（大于就是晚于）电影《少数派报告》的initial_release_date(首次发布日期)。

{
  var(func: eq(name@en,"Minority Report")) {
    d as initial_release_date
  }
  me(func: eq(name@en, "Steven Spielberg")) {
    name@en
    director.film @filter(ge(initial_release_date, val(d))) {
      initial_release_date
      name@en
    }
  }
}

uid

语法示例:

• q(func: uid(<uid>))
• predicate @filter(uid(<uid1>, ..., <uidn>))
• predicate @filter(uid(a)) 使用变量 a
• q(func: uid(a,b)) 使用变量 a 和 b

将当前查询级别的节点过滤到给定uid集中的节点。

对于查询变量 a, uid(a)表示存储在 a 其中的一组uid。 对于值变量 b, uid(b) 表示从UID到值映射的UID. 有两个或两个以上的变量, uid(a,b,...)表示所有变量的并集。

uid(<uid>), 像标识函数一样, 即使节点没有任何边, 也会返回请求的 UID。

查询示例: 如果已知节点的UID，则可以直接读取该节点的值。如已知电影普里扬卡·乔普的UID 为 0x878110，可以通过UID直接查

{
  films(func: uid(0x878110)) {
    name@hi
    actor.film {
      performance.film {
        name@hi
      }
    }
  }
}

查询示例: 塔拉吉·汉森的电影按类型划分

{
  var(func: allofterms(name@en, "Taraji Henson")) {
    actor.film {
      F as performance.film {
        G as genre
      }
    }
  }
  Taraji_films_by_genre(func: uid(G)) {
    genre_name : name@en
    films : ~genre @filter(uid(F)) {
      film_name : name@en
    }
  }
}

查询示例: 塔拉吉·汉森的电影按类型划分然后排序，最后统计每种类型电影的。

{
  var(func: allofterms(name@en, "Taraji Henson")) {
    actor.film {
      F as performance.film {
        G as count(genre)
        genre {
          C as count(~genre @filter(uid(F)))
        }
      }
    }
  }
  Taraji_films_by_genre_count(func: uid(G), orderdesc: val(G)) {
    film_name : name@en
    genres : genre (orderdesc: val(C)) {
      genre_name : name@en
    }
  }
}

uid_in

语法 例子:

• q(func: ...) @filter(uid_in(predicate, <uid>)
• predicate1 @filter(uid_in(predicate2, <uid>)

Schema 类型: UID

索引 要求: 无

uid 函数则根据uid过滤当前级别的节点,函数 uid_in 允许沿着边缘向前查看，以检查它是否指向特定的UID。这通常可以保存一个额外的查询块，并避免返回边缘。

uid_in 不能在根节点下使用，它接受一个UID常量作为参数(而不是变量)。

查询示例: Marc Caro和Jean-PierreJeunet(UID 0x6777ba)的合作。如果Jean-Pierre Jeunet的UID是已知的, 通过这种~director.film方式进行查询，就不需要一个块将其UID提取到变量中，也不需要额外的边缘遍历和过滤器 .

{
  caro(func: eq(name@en, "Marc Caro")) {
    name@en
    director.film @filter(uid_in(~director.film, 0x6777ba)){
      name@en
    }
  }
}

has

语法 例子: has(predicate)

Schema 类型: all

确定节点是否具有特定谓词。

查询示例: 前五位导演和他们所有的电影都有上映日期的记录。导演至少导演过一部电影——相当于 gt(count(director.film), 0).

{
  me(func: has(director.film), first: 5) {
    name@en
    director.film @filter(has(initial_release_date))  {
      initial_release_date
      name@en
    }
  }
}

定位

注意 到目前为止，我们只支持索引点、多边形和多边形集合类型。

注意，对于定位查询，任何带有孔的多边形都将被替换为外部循环，忽略孔洞。另外，对于0.7.7版本，多边形包含检查是近似的。

Mutations（变化）

要使用geo函数，谓词上需要一个索引。

loc: geo @index(geo) .

下面是如何添加一个点

{
  set {
    <_:0xeb1dde9c> <loc> "{'type':'Point','coordinates':[-122.4220186,37.772318]}"^^<geo:geojson> .
    <_:0xeb1dde9c> <name> "Hamon Tower" .
  }
}

下面是如何将“多边形”与节点关联。添加一个“多边形集合”也是类似的。

{
  set {
    <_:0xf76c276b> <loc> "{'type':'Polygon','coordinates':[[[-122.409869,37.7785442],[-122.4097444,37.7786443],[-122.4097544,37.7786521],[-122.4096334,37.7787494],[-122.4096233,37.7787416],[-122.4094004,37.7789207],[-122.4095818,37.7790617],[-122.4097883,37.7792189],[-122.4102599,37.7788413],[-122.409869,37.7785442]],[[-122.4097357,37.7787848],[-122.4098499,37.778693],[-122.4099025,37.7787339],[-122.4097882,37.7788257],[-122.4097357,37.7787848]]]}"^^<geo:geojson> .
    <_:0xf76c276b> <name> "Best Western Americana Hotel" .
  }
}

上面的例子是从我们的SF旅游数据集中挑选出来的。

查询

接近

语法 例子: near(predicate, [long, lat], distance)

Schema 类型: geo

索引 要求: geo

匹配’谓词’所给出的位置在distance米的geojson[long,lat]坐标的所有实体。

查询示例: 旅游景点在1公里内的一个点在旧金山的金门公园。

{
  tourist(func: near(loc, [-122.469829, 37.771935], 1000) ) {
    name
  }
}

在…之内

语法 例子: within(predicate, [[[long1, lat1], ..., [longN, latN]]])

Schema 类型: geo

索引 要求: geo

匹配“谓词”给出的位置位于geojson坐标数组指定的多边形中的所有实体。

查询示例: 旧金山金门公园指定区域内的旅游景点。

{
  tourist(func: within(loc, [[[-122.47266769409178, 37.769018558337926 ], [ -122.47266769409178, 37.773699921075135 ], [ -122.4651575088501, 37.773699921075135 ], [ -122.4651575088501, 37.769018558337926 ], [ -122.47266769409178, 37.769018558337926]]] )) {
    name
  }
}

包含

语法 例子: contains(predicate, [long, lat]) or contains(predicate, [[long1, lat1], ..., [longN, latN]])

Schema 类型: geo

索引 要求: geo

匹配“谓词”给出的坐标的多边形[long, lat]或给定的geojson多边形的所有实体

查询示例 :所有实体中包含一个点在火烈鸟围场的旧金山动物园。

{
  tourist(func: contains(loc, [ -122.50326097011566, 37.73353615592843 ] )) {
    name
  }
}

交叉

语法 例子: intersects(predicate, [[[long1, lat1], ..., [longN, latN]]])

Schema 类型: geo

索引 要求: geo

匹配”谓词”给定位置的多边形与给定geojson多边形相交的所有实体。

{
  tourist(func: intersects(loc, [[[-122.503325343132, 37.73345766902749 ], [ -122.503325343132, 37.733903134117966 ], [ -122.50271648168564, 37.733903134117966 ], [ -122.50271648168564, 37.73345766902749 ], [ -122.503325343132, 37.73345766902749]]] )) {
    name
  }
}

连接过滤器

在@filter中，多个函数可以与布尔连接词一起使用。

AND, OR and NOT

连接词 AND, OR 和 NOT 连接过滤器，可以构建到任意复杂的过滤器中, 比如 (NOT A OR B) AND (C AND NOT (D OR E))。 注意, NOT与 AND 绑定比 NOT 与 OR 更紧密。

查询示例 :所有史蒂文斯皮尔伯格电影包含’印第安纳’和’琼斯’或“侏罗纪”和“公园”。

{
  me(func: eq(name@en, "Steven Spielberg")) @filter(has(director.film)) {
    name@en
    director.film @filter(allofterms(name@en, "jones indiana") OR allofterms(name@en, "jurassic park"))  {
      uid
      name@en
    }
  }
}

别名

语法 例子:

• aliasName : predicate
• aliasName : predicate { ... }
• aliasName : varName as ...
• aliasName : count(predicate)
• aliasName : max(val(varName))

别名可以结果中提供另一个名称。谓词，变量和聚合可以通过添加:来添加别名。别名不必与原始谓词名不同，但是，在一个作用域内， 别名必须与同一作用域中返回的谓词名和其他别名不同。别名可用于在一个作用域内多次返回相同的谓词。

查询示例 : 名称与“Steven”相匹配的导演，他们的UID，英文名，每部电影的平均演员人数，每部电影的总数量以及每部电影的英文和法文名称。

{
  ID as var(func: allofterms(name@en, "Steven")) @filter(has(director.film)) {
    director.film {
      num_actors as count(starring)
    }
    average as avg(val(num_actors))
  }
  films(func: uid(ID)) {
    director_id : uid
    english_name : name@en
    average_actors : val(average)
    num_films : count(director.film)
    films : director.film {
      name : name@en
      english_name : name@en
      french_name : name@fr
    }
  }
}

分页

分页允许只返回部分结果集，而不是返回整个结果集。这对于top-k风格的查询非常有用同时也减小结果集的大小对于 客户端处理或允许分页访问结果。for client side processing or to allow paged access to results.

分页通常用于排序。

注意 在没有指定排序顺序的情况下，结果按“uid”进行排序，uid是随机分配的。因此，虽然顺序是确定的，但可能不是您所期望的。

First

语法 例子:

• q(func: ..., first: N)
• predicate (first: N) { ... }
• predicate @filter(...) (first: N) { ... }

对于正数N， ‘first: N根据排序或UID顺序检索第一个N结果。

对于负数 N, first: N 根据排序或UID顺序检索最后一个N结果,目前,负数只有在排序后才支持。要通过排序实现负数查找的效果，请颠倒排序的顺序后使用正数N

查询示例 : 史蒂文斯皮尔伯格的导演和的前三种电影类型的最后两部电影，通过UID排序，按英文名称的字母顺序排序。

{
  me(func: allofterms(name@en, "Steven Spielberg")) {
    director.film (first: -2) {
      name@en
      initial_release_date
      genre (orderasc: name@en) (first: 3) {
          name@en
      }
    }
  }
}

查询示例 : 所有名字含有叫史蒂文的导演中执导过最多演员的前三位导演

{
  ID as var(func: allofterms(name@en, "Steven")) @filter(has(director.film)) {
    director.film {
      stars as count(starring)
    }
    totalActors as sum(val(stars))
  }
  mostStars(func: uid(ID), orderdesc: val(totalActors), first: 3) {
    name@en
    stars : val(totalActors)
    director.film {
      name@en
    }
  }
}

Offset 偏移量

语法 例子:

• q(func: ..., offset: N)
• predicate (offset: N) { ... }
• predicate (first: M, offset: N) { ... }
• predicate @filter(...) (offset: N) { ... }

使用offset: N时，不会返回第一个 N 结果。组合使用first: M, offset: N ，从第N项后开始，返回M项数据,第N会被跳过。

查询示例 : 徐克的电影所有按英文名排序,跳过前4条数据返回后续的6条数据。

{
  me(func: allofterms(name@en, "Hark Tsui")) {
    name@zh
    name@en
    director.film (orderasc: name@en) (first:6, offset:4)  {
      genre {
        name@en
      }
      name@zh
      name@en
      initial_release_date
    }
  }
}

在…之后 After

语法 例子:

• q(func: ..., after: UID)
• predicate (first: N, after: UID) { ... }
• predicate @filter(...) (first: N, after: UID) { ... }

另一种方法得到跳过某些结果的返回结果后可以使用默认的UID排序，并直接跳过由UID指定的节点。例如，第一个查询可以是这种形式predicate (after: 0x0, first: N),或者 predicate (first: N), 使用表单的后续查询 predicate(after: <uid of last entity in last result>, first: N).

查询示例 :巴兹·鲁曼电影的前五部，按UID顺序排列。

{
  me(func: allofterms(name@en, "Baz Luhrmann")) {
    name@en
    director.film (first:5) {
      uid
      name@en
    }
  }
}

第五部电影是澳大利亚经典电影《舞动奇迹》。它的UID是0x8116e4。 在《舞动奇迹》的后一项可以使用after获得。

{
  me(func: allofterms(name@en, "Baz Luhrmann")) {
    name@en
    director.film (first:5, after: 0x264ce8) {
      uid
      name@en
    }
  }
}

计算

语法 例子:

• count(predicate)
• count(uid)

这个方式 count(predicate) 可以计算有多少 predicate 边从节点引出。

这个方式 count(uid) 可以计算有多少 UIDs 匹配在封闭块中。

查询示例 : 以“奥兰多”Orlando为名字的演员出演的电影数量。

{
  me(func: allofterms(name@en, "Orlando")) @filter(has(actor.film)) {
    name@en
    count(actor.film)
  }
}

计算可以在根目录下使用并别名。

查询示例 : 计算已执导五部以上影片的导演人数。在查询根上使用时，count需要索引。

{
  directors(func: gt(count(director.film), 5)) {
    totalDirectors : count(uid)
  }
}

Count可以赋值给值变量。

查询示例 : 李安的《吃喝男女》的演员们按出演电影的数量排序。

{
    var(func: allofterms(name@en, "eat drink man woman")) {
    starring {
      actors as performance.actor {
        totalRoles as count(actor.film)
      }
    }
  }
  edmw(func: uid(actors), orderdesc: val(totalRoles)) {
    name@en
    name@zh
    totalRoles : val(totalRoles)
  }
}

排序

语法 例子:

• q(func: ..., orderasc: predicate)
• q(func: ..., orderdesc: val(varName))
• predicate (orderdesc: predicate) { ... }
• predicate @filter(...) (orderasc: N) { ... }
• q(func: ..., orderasc: predicate1, orderdesc: predicate2)

可排序的类型: int, float, String, dateTime, id, default

结果可以通过谓词或变量按升序(orderasc)或降序(orderdesc)排序。

对于使用可排序索引对谓词排序，Dgraph对值和索引并行排序，并返回最先计算的结果。

默认情况下，排序查询最多检索1000个结果。这可以使用first改变。

查询示例 : 法国导演让-皮埃尔·让内的电影按上映日期排序。

{
  me(func: allofterms(name@en, "Jean-Pierre Jeunet")) {
    name@fr
    director.film(orderasc: initial_release_date) {
      name@fr
      name@en
      initial_release_date
    }
  }
}

排序可以在根变量和值变量上执行。

查询示例 : 所有电影类型按字母顺序排列，返回每类中属于最多类型的前5部电影。

{
  genres as var(func: has(~genre)) {
    ~genre {
      numGenres as count(genre)
    }
  }
  genres(func: uid(genres), orderasc: name@en) {
    name@en
    ~genre (orderdesc: val(numGenres), first: 5) {
      name@en
        genres : val(numGenres)
    }
  }
}

排序还可以由多个谓词执行，如下所示，第一个谓词的值相等，然后根据第二个谓词排序，依此类推。

找到所有具有Person类型的节点，按它们的firstname对它们排序，在具有相同firstname的节点中按lastname降序对它们排序。

{
  me(func: eq(type, "Person", orderasc: first_name, orderdesc: last_name)) {
    first_name
    last_name
  }
}

多个查询块

在单个查询中，允许使用多个查询块。返回结果是具有一致块名称的所有块。

多个查询块会并行执行。

这些块不需要以任何方式关联。

查询示例 :所有安吉丽娜·朱莉(Angelina Jolie)的各种类型的电影, 彼得杰克逊导演的电影自2008年以后的电影。

{
 AngelinaInfo(func:allofterms(name@en, "angelina jolie")) {
  name@en
   actor.film {
    performance.film {
      genre {
        name@en
      }
    }
   }
  }
 DirectorInfo(func: eq(name@en, "Peter Jackson")) {
    name@en
    director.film @filter(ge(initial_release_date, "2008"))  {
        Release_date: initial_release_date
        Name: name@en
    }
  }
}

如果查询在答案中包含一些重叠，则结果集仍然是独立的。

查询示例 : 麦肯齐·克鲁克演过的电影，杰克·达文波特演过的电影。结果集重叠，因为它们都在《加勒比海盗》电影中扮演过角色，但查询返回结果是独立的，并且都包含完整的答案集。

{
  Mackenzie(func:allofterms(name@en, "Mackenzie Crook")) {
    name@en
    actor.film {
      performance.film {
        uid
        name@en
      }
      performance.character {
        name@en
      }
    }
  }
  Jack(func:allofterms(name@en, "Jack Davenport")) {
    name@en
    actor.film {
      performance.film {
        uid
        name@en
      }
      performance.character {
        name@en
      }
    }
  }
}

声明作用域 Var Blocks

声明作用域以关键字 var 开头不会在查询结果中返回。

查询示例 : 安吉丽娜·朱莉的电影按类型排序。

{
  var(func:allofterms(name@en, "angelina jolie")) {
    name@en
    actor.film {
      A AS performance.film {
        B AS genre
      }
    }
  }
  films(func: uid(B), orderasc: name@en) {
    name@en
    ~genre @filter(uid(A)) {
      name@en
    }
  }
}

查询变量

语法 例子:

• varName as q(func: ...) { ... }
• varName as var(func: ...) { ... }
• varName as predicate { ... }
• varName as predicate @filter(...) { ... }

类型 : uid

在查询的某个位置匹配的节点(UID)可以存储在变量中，并在其他地方使用。查询变量可用于其他查询块或定义块的子节点。

查询变量在定义时不影响查询的语义。查询变量被计算到定义块匹配的所有节点。

通常，查询块是并行执行的，但是变量对某些块施加了一个计算顺序。不允许由变量依赖引起的循环。

如果定义了一个变量，那么它必须在查询的其他地方使用。

一个查询变量通过使用uid(var-name)提取其中的uid。

语法func: uid(A,B) 或者 @filter(uid(A,B)) 是对A 和 B 的变量UIDs的联合.

查询示例 : 安吉丽娜·朱莉和布拉德·皮特的电影，他们都曾出演过同一类型的电影。 注意，“B”和“D”匹配所有电影的所有类型，而不是每部电影的类型。

{
 var(func:allofterms(name@en, "angelina jolie")) {
   actor.film {
    A AS performance.film {  # All films acted in by Angelina Jolie
     B As genre  # Genres of all the films acted in by Angelina Jolie
    }
   }
  }
 var(func:allofterms(name@en, "brad pitt")) {
   actor.film {
    C AS performance.film {  # All films acted in by Brad Pitt
     D as genre  # Genres of all the films acted in by Brad Pitt
    }
   }
  }
 films(func: uid(D)) @filter(uid(B)) {   # Genres from both Angelina and Brad
  name@en
   ~genre @filter(uid(A, C)) {  # Movies in either A or C.
     name@en
   }
 }
}

值变量

Syntax Examples:

• varName as scalarPredicate
• varName as count(predicate)
• varName as avg(...)
• varName as math(...)

Types : int, float, String, dateTime, id, default, geo, bool

Value variables store scalar values. Value variables are a map from the UIDs of the enclosing block to the corresponding values.

It therefore only makes sense to use the values from a value variable in a context that matches the same UIDs - if used in a block matching different UIDs the value variable is undefined.

It is an error to define a value variable but not use it elsewhere in the query.

Value variables are used by extracting the values with val(var-name), or by extracting the UIDs with uid(var-name).

Facet values can be stored in value variables.

Query Example: The number of movie roles played by the actors of the 80’s classic “The Princess Bride”. Query variable pbActors matches the UIDs of all actors from the movie. Value variable roles is thus a map from actor UID to number of roles. Value variable roles can be used in the the totalRoles query block because that query block also matches the pbActors UIDs, so the actor to number of roles map is available.

{
  var(func:allofterms(name@en, "The Princess Bride")) {
    starring {
      pbActors as performance.actor {
        roles as count(actor.film)
      }
    }
  }
  totalRoles(func: uid(pbActors), orderasc: val(roles)) {
    name@en
    numRoles : val(roles)
  }
}

Value variables can be used in place of UID variables by extracting the UID list from the map.

Query Example: The same query as the previous example, but using value variable roles for matching UIDs in the totalRoles query block.

{
  var(func:allofterms(name@en, "The Princess Bride")) {
    starring {
      performance.actor {
        roles as count(actor.film)
      }
    }
  }
  totalRoles(func: uid(roles), orderasc: val(roles)) {
    name@en
    numRoles : val(roles)
  }
}

Variable Propagation

Like query variables, value variables can be used in other query blocks and in blocks nested within the defining block. When used in a block nested within the block that defines the variable, the value is computed as a sum of the variable for parent nodes along all paths to the point of use. This is called variable propagation.

For example:

{
  q(func: uid(0x01)) {
    myscore as math(1)          # A
    friends {                   # B
      friends {                 # C
        ...myscore...
      }
    }
  }
}

At line A, a value variable myscore is defined as mapping node with UID 0x01 to value 1. At B, the value for each friend is still 1: there is only one path to each friend. Traversing the friend edge twice reaches the friends of friends. The variable myscore gets propagated such that each friend of friend will receive the sum of its parents values: if a friend of a friend is reachable from only one friend, the value is still 1, if they are reachable from two friends, the value is two and so on. That is, the value of myscore for each friend of friends inside the block marked C will be the number of paths to them.

The value that a node receives for a propagated variable is the sum of the values of all its parent nodes.

This propagation is useful, for example, in normalizing a sum across users, finding the number of paths between nodes and accumulating a sum through a graph.

Query Example: For each Harry Potter movie, the number of roles played by actor Warwick Davis.

{
    num_roles(func: eq(name@en, "Warwick Davis")) @cascade @normalize {
    paths as math(1)  # records number of paths to each character
    actor : name@en
    actor.film {
      performance.film @filter(allofterms(name@en, "Harry Potter")) {
        film_name : name@en
        characters : math(paths)  # how many paths (i.e. characters) reach this film
      }
    }
  }
}

Query Example: Each actor who has been in a Peter Jackson movie and the fraction of Peter Jackson movies they have appeared in.

{
    movie_fraction(func:eq(name@en, "Peter Jackson")) @normalize {
    paths as math(1)
    total_films : num_films as count(director.film)
    director : name@en
    director.film {
      starring {
        performance.actor {
          fraction : math(paths / (num_films/paths))
          actor : name@en
        }
      }
    }
  }
}

More examples can be found in two Dgraph blog posts about using variable propagation for recommendation engines (post 1, post 2).

Aggregation

Syntax Example: AG(val(varName))

For AG replaced with

• min : select the minimum value in the value variable varName
• max : select the maximum value
• sum : sum all values in value variable varName
• avg : calculate the average of values in varName

Schema Types:

Aggregation can only be applied to value variables. An index is not required (the values have already been found and stored in the value variable mapping).

An aggregation is applied at the query block enclosing the variable definition. As opposed to query variables and value variables, which are global, aggregation is computed locally. For example:

A as predicateA {
  ...
  B as predicateB {
    x as ...some value...
  }
  min(val(x))
}

Here, A and B are the lists of all UIDs that match these blocks. Value variable x is a mapping from UIDs in B to values. The aggregation min(val(x)), however, is computed for each UID in A. That is, it has a semantics of: for each UID in A, take the slice of x that corresponds to A‘s outgoing predicateB edges and compute the aggregation for those values.

Aggregations can themselves be assigned to value variables, making a UID to aggregation map.

Min

Usage at Root

Query Example: Get the min initial release date for any Harry Potter movie.

The release date is assigned to a variable, then it is aggregated and fetched in an empty block.

{
  var(func: allofterms(name@en, "Harry Potter")) {
    d as initial_release_date
  }
  me() {
    min(val(d))
  }
}

Usage at other levels.

Query Example: Directors called Steven and the date of release of their first movie, in ascending order of first movie.

{
  stevens as var(func: allofterms(name@en, "steven")) {
    director.film {
      ird as initial_release_date
      # ird is a value variable mapping a film UID to its release date
    }
    minIRD as min(val(ird))
    # minIRD is a value variable mapping a director UID to their first release date
  }
  byIRD(func: uid(stevens), orderasc: val(minIRD)) {
    name@en
    firstRelease: val(minIRD)
  }
}

Max

Usage at Root

Query Example: Get the max initial release date for any Harry Potter movie.

The release date is assigned to a variable, then it is aggregated and fetched in an empty block.

{
  var(func: allofterms(name@en, "Harry Potter")) {
    d as initial_release_date
  }
  me() {
    max(val(d))
  }
}

Usage at other levels.

Query Example: Quentin Tarantino’s movies and date of release of the most recent movie.

{
  director(func: allofterms(name@en, "Quentin Tarantino")) {
    director.film {
      name@en
      x as initial_release_date
    }
    max(val(x))
  }
}

Sum and Avg

Usage at Root

Query Example: Get the sum and average of number of count of movies directed by people who have Steven or Tom in their name.

{
  var(func: anyofterms(name@en, "Steven Tom")) {
    a as count(director.film)
  }
  me() {
    avg(val(a))
    sum(val(a))
  }
}

Usage at other levels.

Query Example: Steven Spielberg’s movies, with the number of recorded genres per movie, and the total number of genres and average genres per movie.

{
  director(func: eq(name@en, "Steven Spielberg")) {
    name@en
    director.film {
      name@en
      numGenres : g as count(genre)
    }
    totalGenres : sum(val(g))
    genresPerMovie : avg(val(g))
  }
}

Aggregating Aggregates

Aggregations can be assigned to value variables, and so these variables can in turn be aggregated.

Query Example: For each actor in a Peter Jackson film, find the number of roles played in any movie. Sum these to find the total number of roles ever played by all actors in the movie. Then sum the lot to find the total number of roles ever played by actors who have appeared in Peter Jackson movies. Note that this demonstrates how to aggregate aggregates; the answer in this case isn’t quite precise though, because actors that have appeared in multiple Peter Jackson movies are counted more than once.

{
  PJ as var(func:allofterms(name@en, "Peter Jackson")) {
    director.film {
      starring {  # starring an actor
        performance.actor {
          movies as count(actor.film)
          # number of roles for this actor
        }
        perf_total as sum(val(movies))
      }
      movie_total as sum(val(perf_total))
      # total roles for all actors in this movie
    }
    gt as sum(val(movie_total))
  }
  PJmovies(func: uid(PJ)) {
    name@en
      director.film (orderdesc: val(movie_total), first: 5) {
        name@en
        totalRoles : val(movie_total)
      }
    grandTotal : val(gt)
  }
}

Math on value variables

Value variables can be combined using mathematical functions. For example, this could be used to associate a score which is then be used to order or perform other operations, such as might be used in building newsfeeds, simple recommendation systems and the likes.

Math statements must be enclosed within math( <exp> ) and must be stored to a value variable.

The supported operators are as follows:

Query Example: Form a score for each of Steven Spielberg’s movies as the sum of number of actors, number of genres and number of countries. List the top five such movies in order of decreasing score.

{
    var(func:allofterms(name@en, "steven spielberg")) {
        films as director.film {
            p as count(starring)
            q as count(genre)
            r as count(country)
            score as math(p + q + r)
        }
    }
    TopMovies(func: uid(films), orderdesc: val(score), first: 5){
        name@en
        val(score)
    }
}

Value variables and aggregations of them can be used in filters.

Query Example: Calculate a score for each Steven Spielberg movie with a condition on release date to penalize movies that are more than 10 years old, filtering on the resulting score.

{
  var(func:allofterms(name@en, "steven spielberg")) {
    films as director.film {
      p as count(starring)
      q as count(genre)
      date as initial_release_date
      years as math(since(date)/(365*24*60*60))
      score as math(cond(years > 10, 0, ln(p)+q-ln(years)))
    }
  }
  TopMovies(func: uid(films), orderdesc: val(score)) @filter(gt(val(score), 2)){
    name@en
    val(score)
    val(date)
  }
}

Values calculated with math operations are stored to value variables and so can be aggreated.

Query Example: Compute a score for each Steven Spielberg movie and then aggregate the score.

{
    steven as var(func:eq(name@en, "Steven Spielberg")) @filter(has(director.film)) {
        director.film {
            p as count(starring)
            q as count(genre)
            r as count(country)
            score as math(p + q + r)
        }
        directorScore as sum(val(score))
    }
    score(func: uid(steven)){
        name@en
        val(directorScore)
    }
}

GroupBy

Syntax Examples:

• q(func: ...) @groupby(predicate) { min(...) }
• `predicate @groupby(pred) { count(uid) }``

A groupby query aggregates query results given a set of properties on which to group elements. For example, a query containing the block friend @groupby(age) { count(uid) }, finds all nodes reachable along the friend edge, partitions these into groups based on age, then counts how many nodes are in each group. The returned result is the grouped edges and the aggregations.

Inside a groupby block, only aggregations are allowed and count may only be applied to uid.

If the groupby is applied to a uid predicate, the resulting aggregations can be saved in a variable (mapping the grouped UIDs to aggregate values) and used elsewhere in the query to extract information other than the grouped or aggregated edges.

Query Example: For Steven Spielberg movies, count the number of movies in each genre and for each of those genres return the genre name and the count. The name can’t be extracted in the groupby because it is not an aggregate, but uid(a) can be used to extract the UIDs from the UID to value map and thus organize the byGenre query by genre UID.

{
  var(func:allofterms(name@en, "steven spielberg")) {
    director.film @groupby(genre) {
      a as count(uid)
      # a is a genre UID to count value variable
    }
  }
  byGenre(func: uid(a), orderdesc: val(a)) {
    name@en
    total_movies : val(a)
  }
}

Query Example: Actors from Tim Burton movies and how many roles they have played in Tim Burton movies.

{
  var(func:allofterms(name@en, "Tim Burton")) {
    director.film {
      starring @groupby(performance.actor) {
        a as count(uid)
        # a is an actor UID to count value variable
      }
    }
  }
  byActor(func: uid(a), orderdesc: val(a)) {
    name@en
    val(a)
  }
}

Expand Predicates

Keyword _predicate_ retrieves all predicates out of nodes at the level used.

Query Example: All predicates from actor Geoffrey Rush.

{
  director(func: eq(name@en, "Geoffrey Rush")) {
    _predicate_
  }
}

The number of predicates from a node can be counted and be aliased.

Query Example: All predicates from actor Geoffrey Rush and the count of such predicates.

{
  director(func: eq(name@en, "Geoffrey Rush")) {
    num_predicates: count(_predicate_)
    my_predicates: _predicate_
  }
}

Predicates can be stored in a variable and passed to expand() to expand all the predicates in the variable.

If _all_ is passed as an argument to expand(), all the predicates at that level are retrieved. More levels can be specfied in a nested fashion under expand(). If _forward_ is passed as an argument to expand(), all predicates at that level (minus any reverse predicates) are retrieved. If _reverse_ is passed as an argument to expand(), only the reverse predicates are retrieved.

Query Example: Predicates saved to a variable and queried with expand().

{
  var(func: eq(name@en, "Lost in Translation")) {
    pred as _predicate_
    # expand(_all_) { expand(_all_)}
  }
  director(func: eq(name@en, "Lost in Translation")) {
    name@.
    expand(val(pred)) {
      expand(_all_)
    }
  }
}

_predicate_ returns string valued predicates as a name without language tag. If the predicate has no string without a language tag, expand() won’t expand it (see language preference). For example, above name generally doesn’t have strings without tags in the dataset, so name@. is required.

Cascade Directive

With the @cascade directive, nodes that don’t have all predicates specified in the query are removed. This can be useful in cases where some filter was applied or if nodes might not have all listed predicates.

Query Example: Harry Potter movies, with each actor and characters played. With @cascade, any character not played by an actor called Warwick is removed, as is any Harry Potter movie without any actors called Warwick. Without @cascade, every character is returned, but only those played by actors called Warwick also have the actor name.

{
  HP(func: allofterms(name@en, "Harry Potter")) @cascade {
    name@en
    starring{
        performance.character {
          name@en
        }
        performance.actor @filter(allofterms(name@en, "Warwick")){
            name@en
         }
    }
  }
}

Normalize directive

With the @normalize directive, only aliased predicates are returned and the result is flattened to remove nesting.

Query Example: Film name, country and first two actors (by UID order) of every Steven Spielberg movie, without initial_release_date because no alias is given and flattened by @normalize

{
  director(func:allofterms(name@en, "steven spielberg")) @normalize {
    director: name@en
    director.film {
      film: name@en
      initial_release_date
      starring(first: 2) {
        performance.actor {
          actor: name@en
        }
        performance.character {
          character: name@en
        }
      }
      country {
        country: name@en
      }
    }
  }
}

Ignorereflex directive

The @ignorereflex directive forces the removal of child nodes that are reachable from themselves as a parent, through any path in the query result

Query Example: All the coactors of Rutger Hauer. Without @ignorereflex, the result would also include Rutger Hauer for every movie.

{
  coactors(func: eq(name@en, "Rutger Hauer")) @ignorereflex {
    actor.film {
      performance.film {
        starring {
          performance.actor {
            name@en
          }
        }
      }
    }
  }
}

Debug

For the purposes of debugging, you can attach a query parameter debug=true to a query. Attaching this parameter lets you retrieve the uid attribute for all the entities along with the server_latency information.

Query with debug as a query parameter

curl "http://localhost:8080/query?debug=true" -XPOST -d $'{
  tbl(func: allofterms(name@en, "The Big Lebowski")) {
    name@en
  }
}' | python -m json.tool | less

Returns uid and server_latency

{
  "data": {
    "tbl": [
      {
        "uid": "0x41434",
        "name@en": "The Big Lebowski"
      },
      {
        "uid": "0x145834",
        "name@en": "The Big Lebowski 2"
      },
      {
        "uid": "0x2c8a40",
        "name@en": "Jeffrey \"The Big\" Lebowski"
      },
      {
        "uid": "0x3454c4",
        "name@en": "The Big Lebowski"
      }
    ],
    "server_latency": {
      "parsing": "101µs",
      "processing": "802ms",
      "json": "115µs",
      "total": "802ms"
    }
  }
}

Schema

For each predicate, the schema specifies the target’s type. If a predicate p has type T, then for all subject-predicate-object triples s p o the object o is of schema type T.

• On mutations, scalar types are checked and an error thrown if the value cannot be converted to the schema type.

• On query, value results are returned according to the schema type of the predicate.

If a schema type isn’t specified before a mutation adds triples for a predicate, then the type is inferred from the first mutation. This type is either:

• type uid, if the first mutation for the predicate has nodes for the subject and object, or

• derived from the rdf type, if the object is a literal and an rdf type is present in the first mutation, or

• default type, otherwise.

Schema Types

Dgraph supports scalar types and the UID type.

Scalar Types

For all triples with a predicate of scalar types the object is a literal.

{{% notice “note” %}}Dgraph supports date and time formats for dateTime scalar type only if they are RFC 3339 compatible which is different from ISO 8601(as defined in the RDF spec). You should convert your values to RFC 3339 format before sending them to Dgraph.{{% /notice %}}

UID Type

The uid type denotes a node-node edge; internally each node is represented as a uint64 id.

Adding or Modifying Schema

Schema mutations add or modify schema.

Multiple scalar values can also be added for a S P by specifying the schema to be of list type. Occupations in the example below can store a list of strings for each S P.

An index is specified with @index, with arguments to specify the tokenizer. When specifying an index for a predicate it is mandatory to specify the type of the index. For example:

name: string @index(exact, fulltext) @count .
multiname: string @lang .
age: int @index(int) .
friend: uid @count .
dob: dateTime .
location: geo @index(geo) .
occupations: [string] @index(term) .

If no data has been stored for the predicates, a schema mutation sets up an empty schema ready to receive triples.

If data is already stored before the mutation, existing values are not checked to conform to the new schema. On query, Dgraph tries to convert existing values to the new schema types, ignoring any that fail conversion.

If data exists and new indices are specified in a schema mutation, any index not in the updated list is dropped and a new index is created for every new tokenizer specified.

Reverse edges are also computed if specified by a schema mutation.

{{% notice “note” %}} If your predicate is a URI or has special characters, then you should wrap it with angular brackets while doing the schema mutation. E.g. <first:name>{{% /notice %}}

Upsert directive

Predicates can specify the @upsert directive if you want to do upsert operations against it. If the @upsert directive is specified then the index key for the predicate would be checked for conflict while committing a transaction, which would allow upserts.

This is how you specify the upsert directive for a predicate. This replaces the IgnoreIndexConflict field which was part of the mutation object in previous releases.

email: string @index(exact) @upsert .

RDF Types

Dgraph supports a number of RDF types in mutations.

As well as implying a schema type for a first mutation, an RDF type can override a schema type for storage.

If a predicate has a schema type and a mutation has an RDF type with a different underlying Dgraph type, the convertibility to schema type is checked, and an error is thrown if they are incompatible, but the value is stored in the RDF type’s corresponding Dgraph type. Query results are always returned in schema type.

For example, if no schema is set for the age predicate. Given the mutation

{
 set {
  _:a <age> "15"^^<xs:int> .
  _:b <age> "13" .
  _:c <age> "14"^^<xs:string> .
  _:d <age> "14.5"^^<xs:string> .
  _:e <age> "14.5" .
 }
}

Dgraph:

• sets the schema type to int, as implied by the first triple,
• converts "13" to int on storage,
• checks "14" can be converted to int, but stores as string,
• throws an error for the remaining two triples, because "14.5" can’t be converted to int.

Extended Types

The following types are also accepted.

Password type

A password for an entity is set with setting the schema for the attribute to be of type password. Passwords cannot be queried directly, only checked for a match using the checkpwd function.

For example: to set a password, first set schema, then the password:

pass: password .

{
  set {
    <0x123> <name> "Password Example"
    <0x123> <pass> "ThePassword" .
  }
}

to check a password:

{
  check(func: uid(0x123)) {
    name
    checkpwd(pass, "ThePassword")
  }
}

output:

{
  "check": [
    {
      "name": "Password Example",
      "pass": [
        {
          "checkpwd": true
        }
      ]
    }
  ]
}

Indexing

{{% notice “note” %}}Filtering on a predicate by applying a function requires an index.{{% /notice %}}

When filtering by applying a function, Dgraph uses the index to make the search through a potentially large dataset efficient.

All scalar types can be indexed.

Types int, float, bool and geo have only a default index each: with tokenizers named int, float, bool and geo.

Types string and dateTime have a number of indices.

String Indices

The indices available for strings are as follows.

{{% notice “warning” %}} Incorrect index choice can impose performance penalties and an increased transaction conflict rate. Use only the minimum number of and simplest indexes that your application needs. {{% /notice %}}

DateTime Indices

The indices available for dateTime are as follows.

The choices of dateTime index allow selecting the precision of the index. Applications, such as the movies examples in these docs, that require searching over dates but have relatively few nodes per year may prefer the year tokenizer; applications that are dependent on fine grained date searches, such as real-time sensor readings, may prefer the hour index.

All the dateTime indices are sortable.

Sortable Indices

Not all the indices establish a total order among the values that they index. Sortable indices allow inequality functions and sorting.

• Indexes int and float are sortable.
• string index exact is sortable.
• All dateTime indices are sortable.

For example, given an edge name of string type, to sort by name or perform inequality filtering on names, the exact index must have been specified. In which case a schema query would return at least the following tokenizers.

{
  "predicate": "name",
  "type": "string",
  "index": true,
  "tokenizer": [
    "exact"
  ]
}

Count index

For predicates with the @count Dgraph indexes the number of edges out of each node. This enables fast queries of the form:

{
  q(func: gt(count(pred), threshold)) {
    ...
  }
}

List Type

Predicate with scalar types can also store a list of values if specified in the schema. The scalar type needs to be enclosed within [] to indicate that its a list type. These lists are like an unordered set.

occupations: [string] .
score: [int] .

• A set operation adds to the list of values. The order of the stored values is non-deterministic.
• A delete operation deletes the value from the list.
• Querying for these predicates would return the list in an array.
• Indexes can be applied on predicates which have a list type and you can use Functions on them.
• Sorting is not allowed using these predicates.

Reverse Edges

A graph edge is unidirectional. For node-node edges, sometimes modeling requires reverse edges. If only some subject-predicate-object triples have a reverse, these must be manually added. But if a predicate always has a reverse, Dgraph computes the reverse edges if @reverse is specified in the schema.

The reverse edge of anEdge is ~anEdge.

For existing data, Dgraph computes all reverse edges. For data added after the schema mutation, Dgraph computes and stores the reverse edge for each added triple.

Querying Schema

A schema query queries for the whole schema:

schema {}

{{% notice “note” %}} Unlike regular queries, the schema query is not surrounded by curly braces. {{% /notice %}}

You can query for particular schema fields in the query body.

schema {
  type
  index
  reverse
  tokenizer
  list
  count
  upsert
  lang
}

You can also query for particular predicates:

schema(pred: [name, friend]) {
  type
  index
  reverse
  tokenizer
  list
  count
  upsert
  lang
}

Facets : Edge attributes

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 decimal integers upto 32 signed bits, and 64 bit float values are accepted respectively.

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 localhost:8080/mutate -H "X-Dgraph-CommitNow: true" -XPOST -d $'
{
  set {
    # -- Facets on scalar predicates
    _:alice <name> "Alice" .
    _:alice <mobile> "040123456" (since=2006-01-02T15:04:05) .
    _:alice <car> "MA0123" (since=2006-02-02T13:01:09, first=true) .
    _:bob <name> "Bob" .
    _:bob <car> "MA0134" (since=2006-02-02T13:01:09) .
    _:charlie <name> "Charlie" .
    _:dave <name> "Dave" .
    # -- 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" .
    _:movie2 <name> "Movie 2" .
    _:movie3 <name> "Movie 3" .
    _: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