Chapter 5. Schema and Data Modeling

每个janusgraph的图有自己的schema，由边labels、属性keys和顶点labels组成。一个graph的schema可以显示或隐式定义。鼓励用户在应用开发阶段显示定义graph的schema。一个显示定义的schema是一个健壮的图应用的重要组件，并很助于提供合作开发。注意，janusgraph的schema可以不中断常规数据库操作的情况下实时改动，扩展schema不会减慢查询，也不需要数据库下线。

schema的type，例如边label，属性key或顶点label，在第一次创建时（edge、properties、vertices）被分配给图的元素。每一个元素指定的type不能被改变，确保系统的type是稳定的。

这节之外的schema定义参数声明等，在Chapter 30, Advanced Schema讨论了schema tpye性能优化等。

5.1 定义Edge label

每个连接两个顶点的边都有一个label，定义了顶点之间关系的语义，例如顶点A和B之间label为friend的edge，说明了两个个体的朋友关系。
在一个open的graph或者管理的事务里，用makeEdgeLabel(String)方法+提供边的label名作为参数，来定义一个边的label。在图中每个边的label必须是唯一的。这个方法返回一个边label的builder，通过builder允许定义边的多样性。一个边label的多样性定义了所有用这个label的边的多样性限制。就是顶点对之间最大的变数量。janusgraph约定了下面的多样性设置。

5.1.1 边label的多样性

多样性限制

MULTI

在顶点对之间允许同名label的边有多个。对于这个边label是一个multi graph。边的多样性没有限制。
SIMPLE

在顶点对之间同名label最多允许一条边，对于这个label是一个simple graph。确保了指定顶点s和lable，边是唯一的。
MANY2ONE

顶点上允许最多一个出边（outgoing edge），但是入边（incoming edge）没有限制。mother是一个边label例子，因为每个人最多有一个mother，但是mother可以有多个children。
ONE2MANY

顶点上允许最多一个入边，出边没有限制。例子是winnerOf
ONE2ONE

顶点上允许最多一个入边，允许最多一个出边。例子married。

默认label多样性是MULTI。在builder上用make()完成边label的定义。下面是例子：

mgmt = graph.openManagement()
follow = mgmt.makeEdgeLabel('follow').multiplicity(MULTI).make()
mother = mgmt.makeEdgeLabel('mother').multiplicity(MANY2ONE).make()
mgmt.commit()

5.2 定义属性keys

顶点和边的属性是kv对。例如，属性name='Daniel'的key是name，value是'Daniel'。属性key是janusgraph schema的一部分，能够限制允许的数据类型和value种类。

用makePropertyKey(String)定义一个属性key，提供属性key的名称作为参数。在图中属性key的名称必须时唯一的，并且建议避免空格和特殊字符。这个方法返回属性key的builder。

5.2.1 属性key的数据格式

用dataType(Class)定义属性key的数据格式。janusgraph强制要求所有key的value有指定的数据类型，因此确保图中的数据是有效的。例如个命名为name的key要求String的数据类型。

janusgraph原生支持以下数据类型。

5.2.2 属性key种类

用cardinality(Cardinality)定义顶点的key的value的种类。
种类设置：

SINGLE

这个key允许每个元素一个value。例如birthDate
LIST

这个key允许每个元素有任意个value。例如sensorReading
SET

这个key允许每个元素有多个value（不重复）。如policeid

默认种类是SINGAL。注意边的属性key只能是SINGAL。

mgmt = graph.openManagement()
birthDate = mgmt.makePropertyKey('birthDate').dataType(Long.class).cardinality(Cardinality.SINGLE).make()
name = mgmt.makePropertyKey('name').dataType(String.class).cardinality(Cardinality.SET).make()
sensorReading = mgmt.makePropertyKey('sensorReading').dataType(Double.class).cardinality(Cardinality.LIST).make()
mgmt.commit()

5.3 关系类型

边的lable和属性key合起来作为关系的类型。关系类型的名称必须时唯一的，意味着属性key和边label不能有相同的名称。以下方法是通过压缩属性key和边label来query已存或取回的关系类型。

mgmt = graph.openManagement()
if (mgmt.containsRelationType('name'))
    name = mgmt.getPropertyKey('name')
mgmt.getRelationTypes(EdgeLabel.class)
mgmt.commit()

5.4 定义顶点label

和边类似，顶点也有label。不同于边，顶点的label是可选的。顶点label用于区分顶点不同的类型。例如user顶点和product顶点。

虽然label是可选的，内部实现时janusgraph会给所有顶点分配一个label。通过addVertex创建的顶点使用默认的label。

用makeVertexLabel(String).make()创建一个label，用顶点label的名字作为参数，顶点label名称必须唯一。

mgmt = graph.openManagement()
person = mgmt.makeVertexLabel('person').make()
mgmt.commit()
// Create a labeled vertex
person = graph.addVertex(label, 'person')
// Create an unlabeled vertex
v = graph.addVertex()
graph.tx().commit()

5.5自动schema制作器

如果一个边label、属性key或者顶点label没有被明确定义，将在第一次使用时（边、顶点、属性的增加或设置）隐式定义。janusgraph的DefaultSchemaMaker配置默认类型。

默认，隐式创建的边是MULTI，属性key是SINGAL和Object.class。用户可以通过实现他们自己的DefaultSchemaMaker控制自动创建的元素类型。

鼓励明确定义所有schema元素，并且禁用schema自动创建（schema.default=none）

5.6 改变schema元素

边label、属性key或顶点label一旦commit不能被改变。然后，schmea元素的名称可以通过JanusGraphManagement.changeName(JanusGraphSchemaElement, String)改变，下面是个属性key-place改为location的例子：

mgmt = graph.openManagement()
place = mgmt.getPropertyKey('place')
mgmt.changeName(place, 'location')
mgmt.commit()

注意，schema名称改变可能不会即时生效。schema名称的改变通过存储后端通知给所有janusgraph实例，可能需要一会儿来使schema变更生效，也可能在确定错误场景下需要重启实例（如同时改名冲突）。因而，用户必须确保下面几点：

改名的label或key当前不是激活在用的（如读或写过程中），并且直到所有实例感知不要使用。
在变更期间运行的图遍历，旧的和新的名称都是可能可用的，例如遍历时同时query两个名称。

需要重新定义一个已有的schema类型，建议不要改当前在用的。完成后，一个新定义的label或key替换了旧的。然后，注意不会生效于已有类型之前写入的顶点、边或属性。不支持在线重新定义图元素，而是必须通过一个图转换批处理完成。

5.7 schema约束

schema的定义允许用户配置详细的属性和连接的约束。属性可以绑定到指定的顶点label和/或边label。进一步，连接约束允许用户明确定义哪两个顶点label能被一个边label连接。那些约束能被用来确保一个图匹配给定的领域模型。例如上帝图，一个god可是另一个god的brother，但是不能和一个mostor。一个god可以有age属性，但是location不能有age属性。这种约束默认是disable的。

激活schema约束通过配置schema.constraints=true（默认false，可选true或false），约束不符合会抛出IllegalArgumentException异常。是否异常的判断依赖schema.default配置，如果schema.default=none（默认是default，可选none、logging、第三方插件实现），那么所有connection和property的约束需要手动创建，如果schema.default没有设置为default，schema约束可以被自动创建，但是默认是MULTI edge labels 和SINGLE property keys。激活schema约束不会影响已有数据，因为约束只应用在插入过程，读数据不受约束影响。

用JanusGraphManagement.addProperties(VertexLabel, PropertyKey...)可以将多个参数绑定到一个顶点，例如

mgmt = graph.openManagement()
person = mgmt.makeVertexLabel('person').make()
name = mgmt.makePropertyKey('name').dataType(String.class).cardinality(Cardinality.SET).make()
birthDate = mgmt.makePropertyKey('birthDate').dataType(Long.class).cardinality(Cardinality.SINGLE).make()
mgmt.addProperties(person, name, birthDate)
mgmt.commit()

用JanusGraphManagement.addProperties(EdgeLabel, PropertyKey...)可以将多个参数绑定到一个边，例如：

mgmt = graph.openManagement()
follow = mgmt.makeEdgeLabel('follow').multiplicity(MULTI).make()
name = mgmt.makePropertyKey('name').dataType(String.class).cardinality(Cardinality.SET).make()
mgmt.addProperties(follow, name)
mgmt.commit()

用JanusGraphManagement.addConnection(EdgeLabel, VertexLabel out, VertexLabel in)可以定义一个出顶点，一个入顶点和一个边的连接关系，例如：

mgmt = graph.openManagement()
person = mgmt.makeVertexLabel('person').make()
company = mgmt.makeVertexLabel('company').make()
works = mgmt.makeEdgeLabel('works').multiplicity(MULTI).make()
mgmt.addConnection(works, person, company)
mgmt.commit()