数据模型¶

在使用GraphScope Interactive时，若使用自定义图数据则必须定义数据模型。该数据模型包含两个主要组成部分：图数据和实体数据。

图数据¶

图数据包含两个基本要素：

顶点(Vertices): 顶点表示图中的实体。在属性图模型的上下文中，顶点通常被称为节点。每个顶点都有一个唯一标识符，并且可以关联零个或多个属性。例如，在社交网络图中，一个顶点可以表示一个人，具有姓名、年龄和位置等属性。
边（Edges）: 边定义了顶点之间的关系。每条有向边都包含一个源顶点、一个目标顶点以及描述关系性质的类型。此外，边也可以拥有属性。例如，在社交网络图中，一条边可能表示两个人之间的友谊关系，并可能包含诸如"since_date"（友谊开始日期）这样的属性。

注：此图模型与属性图模型一致，详细说明请参见此处。但需特别注意我们的术语规范：我们使用"顶点"(vertex)而非"节点"(node)，使用"边"(edge)而非"关系"(relationship)，且仅支持有向边，不支持无向边。

在graph.yaml文件中，顶点类型定义在vertex_types部分。每个顶点类型必须包含以下字段：type_name、properties和primary_keys。例如：

- type_name: person
  description: all persons
  properties:
    - property_name: id
      property_type:
        primitive_type: DT_SIGNED_INT64
    - property_name: name
      property_type:
        string:
          long_text:
  primary_keys: # these must also be listed in the properties
    - id  

注意：

在当前版本中，只能指定一个单一的主键，但我们计划在未来支持多个主键。
主键列的数据类型必须是以下之一：DT_SIGNED_INT32、DT_UNSIGNED_INT32、DT_SIGNED_INT64、DT_UNSIGNED_INT64，或字符串类型var_char、long_text（目前不支持fixed_char）。

边的关系定义在edge_types部分，由以下必填字段描述：type_name、vertex_type_pair_relations和properties。其中type_name和properties字段的功能与顶点中的对应字段类似。而vertex_type_pair_relations字段是边特有的，用于指定允许的源顶点和目标顶点类型，以及描述该边可以连接多少源顶点和目标顶点的关系规则。下面是一个示例说明：

type_name: knows
description: The relationship between persons.
vertex_type_pair_relations:
  - source_vertex: person
    destination_vertex: person
    # the "knows" edge can link multiple source and destination vertices
    relation: MANY_TO_MANY  

注意：

单一类型的边可以拥有多个vertex_type_pair_relations。例如，"knows"边可以连接两个人，表示他们的朋友关系；也可以关联一个人与一项技能，表示其在该技能上的熟练程度。
允许的关系类型包括：ONE_TO_ONE、ONE_TO_MANY、MANY_TO_ONE和MANY_TO_MANY。优化器可以利用这些关系生成更高效的执行计划。
支持多边属性。
目前我们仅支持在所有字符串类型中将var_char和long_text作为边属性。
所有与实现相关的配置都放在x_csr_params下。
- max_vertex_num 限制该类型的顶点数量：
  - 限制数量用于mmap内存映射，因此在实际插入顶点前仅占用虚拟内存。
  - 如果未设置max_vertex_num，将使用默认的大数值（例如：2^48）。
- edge_storage_strategy 指定了该类型边的入边或出边的存储策略，共有3种策略
  - ONLY_IN: 仅存储入边。
  - ONLY_OUT: 仅存储出边。
  - BOTH_OUT_IN(默认): 边的双向都会被存储。

实体数据¶

实体数据涉及与顶点和边相关联的属性。在GraphScope Interactive中，我们支持多种数据类型用于这些属性：

基本类型¶

DT_SIGNED_INT32
DT_UNSIGNED_INT32
DT_SIGNED_INT64
DT_UNSIGNED_INT64
DT_BOOL
DT_FLOAT
DT_DOUBLE

在graph.yaml文件中，基本类型如DT_DOUBLE可以表示为：

property_type:
  primitive_type: DT_DOUBLE

字符串类型¶

我们将字符串类型分为三种子类型：

long_text: 不限长度的字符串类型，允许存储无限文本内容。
char: 一种固定长度的字符串类型。该字段定义了一个fixed_length属性，用于指定字符串的期望长度。字符串将被限制为指定的长度。
var_char: 一种可变长度的字符串类型，受最大长度限制。该字段定义了max_length属性，用于设置字符串的最大长度。字符串将被限制在指定的最大长度内。

这三种字符串类型可以用yaml表示为：

string:
  long_text: # string with unlimited length
  char:  # string with fixed length
    fixed_length: <uint32>
  var_char:  # string with variable length, bounded by max_length
    max_length: <uint32>

用户可以根据需求选择合适的字符串类型。long_text类型适合处理长度不受限的文本。char类型适用于需要固定长度字符串的场景。var_char类型则非常适合需要限制字符串长度并指定最大长度的场合。

注意：目前不支持固定长度的字符。

时间类型¶

时间类型可以通过以下方式定义：

temporal:
  date:
    # optional value: DF_YYYY_MM_DD, means ISO fomat: 2019-01-01
    date_format: <string> 
  time:
    # optional value: TF_HH_MM_SS_SSS, means ISO format: 00:00:00.000
    time_format: <string>
    # optional value: TZF_UTC, TZF_OFFSET
    time_zone_format: <string>
  date_time:
    # optional value: DTF_YYYY_MM_DD_HH_MM_SS_SSS,
    # means ISO format: 2019-01-01 00:00:00.000
    date_time_format: <string>
    time_zone_format: <string> # optional value: TZF_UTC, TZF_OFFSET
  date32: # int32 days since 1970-01-01
  time32: # int32 milliseconds past midnight
  timestamp:  # int64 milliseconds since 1970-01-01 00:00:00.000000

以下是每种时间类型的说明：

date: 表示日期值。可选地，可以指定date_format字段来定义日期的格式。date_format属性可以取值如DF_YYYY_MM_DD，表示ISO格式："2019-01-01"。
time: 表示时间值。可选地，可以使用字段time_format来指定时间的格式。time_format属性可以取值如TF_HH_MM_SS_SSS，表示ISO格式："00:00:00.000"。也可以包含time_zone_format属性来定义时区的格式，可选值为TZF_UTC或TZF_OFFSET。
date_time: 表示日期和时间的组合。字段date_time_format是可选的，可用于指定日期和时间的格式。例如，date_time_format值为DTF_YYYY_MM_DD_HH_MM_SS_SSS将表示ISO格式："2019-01-01 00:00:00.000"。还可以指定time_zone_format属性来定义时区格式，可选值为TZF_UTC或TZF_OFFSET。
date32: 将日期表示为整数，其值为自1970年1月1日以来的天数。
time32: 表示时间作为一个整数，代表从午夜开始的毫秒数。
timestamp: 表示时间戳的整数值，代表自1970年1月1日00:00:00.000以来的毫秒数。

该YAML结构允许用户选择合适的数据类型和格式来处理时间数据，例如日期、时间和时间戳。可选属性提供了灵活性，可以定义所需的格式或时区表示形式。

注意：

目前我们仅支持date和timestamp类型，其他类型将在不久的将来得到支持。

数组类型¶

目前暂不支持数组类型，但计划在不久的将来提供支持。一旦支持后，虽然要求数组中的每个元素都必须符合前面提到的基本类型之一。关键的是，单个数组内的所有元素必须共享相同类型。在graph.yaml中，用户可以通过以下方式指定某个属性为DT_UNSIGNED_INT64类型的数组：

property_type:
  array:
    component_type: 
      primitive_type: DT_UNSIGNED_INT64
      max_length: 10  # overflowed elements will be truncated