Project: GraphScope (App Definition and Development / Database)
File: data_model.md

When working with GraphScope Interactive, the data model must be defined while . This data model consists of two primary components: graph data and entity data. The graph data encompasses two fundamental elements: Vertex (Vertices): A vertex represents an entity in the graph. In the context of the property graph model, vertices are often referred to as nodes. Each vertex has a unique identifier and can have zero or more properties associated with it. For example, in a social network graph, a vertex could represent a person, with properties like name, age, and location. Edge (Edges): Edges define the relationships between vertices. Each directed edge has a source vertex, a destination vertex, and a type that describes the nature of the relationship. Additionally, edges can also have properties. For instance, in a social network graph, an edge might represent a friendship between two people and could have properties like "since_date" indicating when the friendship started. Note: This graph model aligns with the property graph model, which offers a detailed explanation . However, it's essential to note our terminology: we use "vertex" instead of "node" and "edge" instead of "relationship", and we only support directed edge instead of both directed and undirected edge. Within the `graph.yaml` file, vertices are delineated under the `vertextypes` section. Each vertex type is structured with mandatory fields: `typename`, `properties`, and `primary_keys`. For instance: ```yaml type_name: person description: all persons properties: property_name: id property_type: primitivetype: DTSIGNED_INT64 property_name: name property_type: string: long_text: primary_keys: # these must also be listed in the properties id ``` Note: In the current version, only one single primary key can be specified, but we plan to support multiple primary keys in the future. The data type of primary key column must be one of `DTSIGNEDINT32`, `DTUNSIGNEDINT32`, `DTSIGNEDINT64` or `DTUNSIGNEDINT64`. Edges are defined within the `edgetypes` section, characterized by the mandatory fields: `typename`, `vertextypepairrelations`, and `properties`. The typename and properties fields function similarly to those in vertices. However, the vertextypepair_relations field is exclusive to edges, specifying the permissible source and destination vertex types, as well as the relationship detailing how many source and destination vertices can be linked by this edge. Here's an illustrative example: ```yaml type_name: knows description: The relationship between persons. vertextypepair_relations: source_vertex: person destination_vertex: person relation: MANYTOMANY ``` Note: A single edge type can have multiple `vertextypepair_relations`. For instance, a "knows" edge might connect one person to another, symbolizing their friendship. Alternatively, it could associate a person with a skill, indicating their proficiency in that skill. The permissible relations include: `ONETOONE`, `ONETOMANY`, `MANYTOONE`, and `MANYTOMANY`. These relations can be utilized by the optimizer to generate more efficient execution plans. Currently we only support at most one property for each edge triplet. All implementation related configuration are put under `xcsrparams`. `maxvertexnum` limit the number of vertices of this type: The limit number is used to `mmap` memory, so it only takes virtual memory before vertices are actually inserted. If `maxvertexnum` is not set, a default large number (e.g.: 2^48) will be used. `edgestoragestrategy` specifies the storing strategy of the incoming or outgoing edges of this type, there are 3 kinds of strategies `ONLY_IN`: Only incoming edges are stored. `ONLY_OUT`: Only outgoing edges are stored. `BOTHOUTIN`(default): Both direction of edges are stored. Entity data pertains to the properties associated with vertices and edges. In GraphScope Interactive, we support a diverse range of data types for these properties: DTSIGNEDINT32 DTUNSIGNEDINT32 DTSIGNEDINT64 DTUNSIGNEDINT64 DT_BOOL DT_FLOAT DT_DOUBLE In the

a primitive type, such as `DT_DOUBLE`, can be written as: ```yaml property_type: primitivetype: DTDOUBLE ``` We categorize string type into three subtypes: `long_text`: A string type with no length limitation, allowing for unlimited text content. `char`: A string type with a fixed length. The field defines an attribute fixed_length, which specifies the desired length of the string. The string will be restricted to the specified length. `varchar`: A string type with variable length, bounded by a maximum length. The field defines an attribute maxlength, which sets the maximum length of the string. The string will be limited to the specified maximum length. These three string type can be written in yaml as: ```yaml string: long_text: # string with unlimited length char: # string with fixed length fixed_length: <uint32> varchar: # string with variable length, bounded by maxlength max_length: <uint32> ``` Users can choose the appropriate string type based on their requirements. The longtext type is suitable for handling text with unlimited length. The char type is useful for scenarios that require fixed-length strings. The varchar type is ideal for situations where the string length needs to be restricted and a maximum length is specified. Note: fixed-length char is currently not supported. Temporal types can be defined in the following ways: ```yaml temporal: date: date_format: <string> time: time_format: <string> timezoneformat: <string> date_time: datetimeformat: <string> timezoneformat: <string> # optional value: TZFUTC, TZFOFFSET date32: # int32 days since 1970-01-01 time32: # int32 milliseconds past midnight timestamp: # int64 milliseconds since 1970-01-01 00:00:00.000000 ``` Here is an explanation of each temporal type: `date`: Denotes a date value. Optionally, the field dateformat can be specified to define the format of the date. The dateformat attribute could take a value like DFYYYYMM_DD, indicating the ISO format: "2019-01-01". `time`: Represents a time value. Optionally, the field timeformat can be used to specify the format of the time. The timeformat attribute could take a value like TFHHMMSSSSS, indicating the ISO format: "00:00:00.000". The timezoneformat attribute can also be included to define the format of the time zone, with optional values of TZFUTC or TZFOFFSET. `datetime`: Signifies a combination of date and time. The field datetimeformat is optional and can be used to specify the format of the date and time. For example, a datetimeformat value of DTFYYYYMMDDHHMMSSSSS would indicate the ISO format: "2019-01-01 00:00:00.000". The timezoneformat attribute can additionally be specified to define the format of the time zone, with optional values of TZFUTC or TZFOFFSET. `date32`: Represents the date as an integer, with the value being the number of days since January 1, 1970. `time32`: Represents the time as an integer, representing the number of milliseconds past midnight. `timestamp`: Denotes a timestamp as an integer, representing the number of milliseconds since January 1, 1970 at 00:00:00.000. This YAML structure allows users to select the appropriate data type and format for handling temporal data, such as dates, times, and timestamps. The optional attributes provide flexibility to define the desired format or timezone representation. Note: Currently we only support `date` and `timestamp`. The other types will be supported in the near future. Array types are currently not supported, but are planned to be supported in the near future. Once supported, albeit requiring that every element within the array adheres to one of the previously mentioned primitive types. It's crucial that all elements within a single array share the same type. In `graph.yaml`, user can describe designating a property as an array of the `DTUNSIGNEDINT64` type as: ```yaml property_type: array: component_type: primitivetype: DTUNSIGNED_INT64 max_length: 10 # overflowed elements will be truncated ```