文档

Graph Database(GDB)数据源

更新时间:

Graph Database数据源为您提供读取和写入Graph Database双向通道的功能,本文为您介绍DataWorks的Graph Database数据同步的能力支持情况。

使用限制

离线读

离线写

  • 导出GDB需要配置点任务和边任务,分别导出点数据和边数据。

  • 导出任务根据点或边的类型名称遍历数据,您需要确保待导出数据的类型名称。

  • GDB中点和边的主键ID字段是字符串类型,请配置导出为STRING类型。如果配置LONG等数值类型,GDB Reader会转换为配置的目标类型,但转换失败时会丢失该记录。

  • 您需要配置GDB导出的属性值为存储类型。如果存储类型和配置类型不一致,GDB Reader会转换为目标类型,但可能会转换失败导致该记录丢失。

  • 导出点SET属性的一个值时,不能保证多次导出都是同一个值。

  • 导出所有属性使用JSON格式输出时,仅包含一个属性值的SET属性会被作为普通属性输出。

  • 如果未对示例的字段名或枚举值进行特别说明,请注意大小写敏感。

  • GDB服务端仅支持UTF-8编码格式,导出的数据均为UTF-8编码格式。

  • GDB需要升级至1.0.20或更高版本才支持SET属性。使用SET属性时,请确认实例的版本。

  • 必须先运行点的同步任务,运行成功后,才可以运行边的同步任务。

  • 点有以下约束规则:

    • 点必须具备类型名(即点名称,对应label)。

    • 点的主键ID为必选,必须保证在点范围内唯一,且类型必须是STRING(如果不是STRING类型,GDB Writer插件会强制转换)。

    • 请谨慎选择点的主键映射规则idTransRule。如果选择none,需要保证点的ID在全局点的范围内唯一。

  • 边有以下约束规则:

    • 边必须具备类型名(即边名称,对应label)。

    • 边的主键ID为可选。

      • 如果填写,则需要保证在全局边范围内唯一。

      • 如果不填写,则GDB服务端默认生成一个UUID,类型必须是STRING(如果不是STRING类型,GDB Writer插件会强制转换)。

    • 请谨慎选择边的主键映射规则idTransRule。如果选择none,需要保证边的ID在全局点边的范围内唯一。

    • 边必须选择srcIdTransRuledstIdTransRule,且必须和导入点时选择的idTransRule一致。

  • 示例的字段名或枚举值,如果没有特殊说明,均为大小写敏感。

  • 目前GDB服务端仅支持UTF-8编码格式,要求来源数据均为UTF-8编码格式。

  • 由于网络限制,运行数据集成任务时,只能使用独享数据集成资源组,请您提前购买并绑定GDB实例所在的专有网络(VPC)。

数据同步任务开发

GDB数据同步任务的配置入口和通用配置流程指导可参见下文的配置指导,详细的配置参数解释可在配置界面查看对应参数的文案提示。

创建数据源

在进行数据同步任务开发时,您需要在DataWorks上创建一个对应的数据源,操作流程请参见创建与管理数据源

单表离线同步任务配置指导

附录:脚本Demo与参数说明

附录:离线任务脚本配置方式

如果您配置离线任务时使用脚本模式的方式进行配置,您需要在任务脚本中按照脚本的统一格式要求编写脚本中的reader参数和writer参数,脚本模式的统一要求请参见通过脚本模式配置离线同步任务,以下为您介绍脚本模式下的数据源的Reader参数和Writer参数的指导详情。

Reader脚本Demo

配置写入GDB的数据同步作业时,请分别配置点和边:

  • 点配置示例

    {
        "order":{
            "hops":[
                {
                    "from":"Reader",
                    "to":"Writer"
                }
            ]
        },
        "setting":{
            "errorLimit":{
                "record":"100"  //错误记录数,表示脏数据的最大容忍条数。
            },
            "jvmOption":"",
            "speed":{
                "concurrent":3,
                "throttle":true,///当throttle值为false时,mbps参数不生效,表示不限流;当throttle值为true时,表示限流。
                "mbps":"12"//限流,此处1mbps = 1MB/s。
            }
        },
        "steps":[
            {
                "category":"reader",
                "name":"Reader",
                "parameter":{
                    "host": "gdb-xxxxxx.aliyuncs.com", //GDB实例的连接地址。
                    "port": 8182, //GDB实例的连接端口。
                    "username": "gdb", //GDB实例的用户名。
                    "password": "gdb", //GDB实例用户名对应的密码。
                    "labelType": "VERTEX", // Label类型,使用VERTEX表示点。
                    "labels": ["label1", "label2"],  // Label名的列表,为空表示导出所有的点。
                    "column": [
                        {
                            "name": "id",               // 字段名。
                            "type": "string",           // 字段类型。
                            "columnType": "primaryKey"  // 字段分类,表示点的主键ID,GDB中是STRING类型。
                        },
                        {
                            "name": "label",              // 字段名。
                            "type": "string",             // 字段类型。
                            "columnType": "primaryLabel"  // 字段分类,表示点的Label名,GDB中是STRING类型。
                        },
                        {
                            "name": "age",                   // 属性字段名。
                            "type": "int",                   // 属性字段类型。
                            "columnType": "vertexProperty"   // 字段分类,表示点的属性,GDB中基础类型属性。
                        }
                    ]
                },
                "stepType":"gdb"
            },
            {
                "category":"writer",
                "name":"Writer",
                "parameter":{
                    "print": true
                },
                "stepType":"stream"
            }
        ]
    }
  • 边配置示例

    {
        "order":{
            "hops":[
                {
                    "from":"Reader",
                    "to":"Writer"
                }
            ]
        },
        "setting":{
            "errorLimit":{
                "record":"100"  //错误记录数,表示脏数据的最大容忍条数。
            },
            "jvmOption":"",
            "speed":{
                "concurrent":3,
                "throttle":true,//当throttle值为false时,mbps参数不生效,表示不限流;当throttle值为true时,表示限流。
                "mbps":"12"//限流,此处1mbps = 1MB/s。
            }
        },
        "steps":[
            {
                "category":"reader",
                "name":"Reader",
                "parameter":{
                    "host": "gdb-xxxxxx.aliyuncs.com", //GDB实例的连接地址。
                    "port": 8182, //GDB实例的连接端口。
                    "username": "gdb", //GDB实例用户名。
                    "password": "gdb", //GDB实例用户名对应的密码。
                    "labelType": "EDGE", // Label类型,VERTEX表示点。
                    "labels": ["label1", "label2"],  // Label名列表,为空表示导出所有的边。
                    "column": [
                        {
                            "name": "id",               // 字段名。
                            "type": "string",           // 字段类型。
                            "columnType": "primaryKey"  // 字段分类,表示边的主键ID,GDB中是STRING类型。
                        },
                        {
                            "name": "label",              // 字段名。
                            "type": "string",             // 字段类型。
                            "columnType": "primaryLabel"  // 字段分类,表示边的Label名,GDB中是STRING类型。
                        },
                        {
                            "name": "srcId",               // 字段名。
                            "type": "string",              // 字段类型。
                            "columnType": "srcPrimaryKey"  // 字段分类,表示边关联点中起点的ID,GDB中是STRING类型。
                        },
                        {
                            "name": "srcLabel",               // 字段名。
                            "type": "string",                 // 字段类型。
                            "columnType": "srcPrimaryLabel"   // 字段分类,表示边关联点中起点的Label名,GDB中是STRING类型。
                        },
                        {
                            "name": "dstId",                    // 字段名。
                            "type": "string",                   // 字段类型。
                            "columnType": "dstPrimaryKey"       // 字段分类,表示边关联点中终点的ID,GDB中是STRING类型。
                        },
                        {
                            "name": "dstLabel",                 // 字段名。
                            "type": "string",                   // 字段类型。
                            "columnType": "dstPrimaryLabel"     // 字段分类,表示边关联点中终点的Label名,GDB中是STRING类型。
                        },
                        {
                            "name": "weight",               // 属性字段名。
                            "type": "double",               // 属性字段类型。
                            "columnType": "edgeProperty"    // 字段分类,表示边的属性。
                        }
                    ]
                },
                "stepType":"gdb"
            },
            {
                "category":"writer",
                "name":"Writer",
                "parameter":{
                    "print": true
                },
                "stepType":"stream"
            }
        ]
    }

Reader脚本参数

参数

描述

是否必选

默认值

host

GDB实例的连接域名。您可以在图数据库GDB控制台,单击相应实例后的管理,查看内网地址(即host)。

port

GDB实例的连接端口。

8182

username

GDB实例的账号名。

password

GDB实例账号的密码。

labels

类型名,即点或边的名称。支持读取多个名称的数据,使用数组表示,例如["label1", "label2"]。

labelType

数据的Label类型:

  • 枚举值VERTEX表示点。

  • 枚举值EDGE表示边。

column

点或边的字段映射关系配置。

column -> name

点或边的映射关系的字段名。读取属性时必选,请提供属性名。

column -> type

点或边的映射关系的字段值类型:

  • 主键ID、类型名Label在GDB中均为STRING类型。如果您配置为STRING类型,会转换失败。

  • 普通属性支持INT、LONG、FLOAT、DOUBLE、BOOLEAN和STRING等类型。

  • GDB Reader会尽量转换读取的数据为配置要求的类型,但转换失败会导致该条记录错误。

column -> columnType

GDB点或边数据对应到的点或边的映射关系字段,包括以下枚举值:

  • 公共枚举值:

    • primaryKey:表示该字段为主键ID。

    • primaryLabel:表示该字段为名称Label。

  • 点枚举值:

    • vertexProperty:当labelType为点时,表示该字段为点的属性。

    • vertexJsonProperty:当labelType为点时,表示该字段为点的属性的集合,使用JSON格式封装。当配置该类型时,所有属性会打包至该列,column中不能再包含其它属性的类型。

      vertexJsonProperty格式如下。

      {
          "properties":[
              {"k":"name","t":"string","v":"tom","c":"set"},
              {"k":"name","t":"string","v":"jack","c":"set"},
              {"k":"sex","t":"string","v":"male","c":"single"}
          ]
      }
                                                          

      上述导出的属性包含多值属性name,有两个属性值和一个单值属性。如果GDB中的多值属性仅包含一个属性值,导出会被当作单值属性。

  • labelType为边时的边枚举值:

    • srcPrimaryKey:表示该字段为起点主键ID。

    • dstPrimaryKey:表示该字段为终点主键ID。

    • srcPrimaryLabel:表示该字段为起点名称Label。

    • dstPrimaryLabel:表示该字段为终点名称Label。

    • edgeProperty:表示该字段为边的属性。

    • edgeJsonProperty:表示该字段为边的属性集合,使用JSON格式封装。配置该类型时,所有属性均会打包至该列,column中不能再包含其它属性的类型。

      edgeJsonProperty格式如下。

      {
          "properties":[
              {"k":"name","t":"string","v":"tom"},
              {"k":"sex","t":"string","v":"male"}
      ]
      }
                                                          

      边不支持多值属性,无c字段。

Writer脚本Demo

  • 点配置示例

    {
        "order":{
            "hops":[
                {
                    "from":"Reader",
                    "to":"Writer"
                }
            ]
        },
        "setting":{
            "errorLimit":{
                "record":"100"  //错误记录数,表示脏数据最大容忍条数。
            },
            "speed":{
                 "throttle":true,//当throttle值为false时,mbps参数不生效,表示不限流;当throttle值为true时,表示限流。
                "concurrent":3, //作业并发数。
                "mbps":"12"//限流,此处1mbps = 1MB/s。
            }
        },
        "steps":[
            {
                "category":"reader",
                "name":"Reader",
                "parameter":{
                    "column":[
                        "*"
                    ],
                    "datasource":"_ODPS",
                    "emptyAsNull":true,
                    "guid":"",
                    "isCompress":false,
                    "partition":[],
                    "table":""
                },
                "stepType":"odps"
            },
            {
                "category":"writer",
                "name":"Writer",
                "parameter": {
                    "datasource": "testGDB", // 数据源名称。
                    "label": "person", //label名,即点名称。
                    "srcLabel": "", // 点类型时此字段无需关注。
                    "dstLabel": "", // 点类型时此字段无需关注。
                    "labelType": "VERTEX", //label类型,"VERTEX"表示点。
                    "writeMode": "INSERT", //导入ID重复时处理方式。
                    "idTransRule": "labelPrefix", //点的主键转换规则。
                    "srcIdTransRule": "none", // 点类型时此字段无需关注。
                    "dstIdTransRule": "none", // 点类型时此字段无需关注。
                    "column": [
                        {
                            "name": "id", //字段名。
                            "value": "#{0}", //#{0}表示取源端第1个字段值,支持拼接,0是源端column索引号。
                            "type": "string", //字段类型。
                            "columnType": "primaryKey" //字段分类,primaryKey表示是主键。
                        }, //点的主键,字段名必须是ID且类型是STRING,该记录必须存在。
                        {
                            "name": "person_age",
                            "value": "#{1}", //#{1}表示取源端第2个字段值,同上支持拼接。
                            "type": "int",
                            "columnType": "vertexProperty" //字段分类,vertexProperty表示是点的属性。
                        }, //点的属性,支持INT、LONG、FLOAT、DOUBLE、BOOLEAN和STRING类型。
                        {
                            "name": "person_credit",
                            "value": "#{2}", //#{2}表示取源端第3个字段值,同上支持拼接。
                            "type": "string",
                            "columnType": "vertexProperty"
                        }, //点的属性。
                    ]
                }
                "stepType":"gdb"
            }
        ],
        "type":"job",
        "version":"2.0"
    }
  • 边配置示例

    {
        "order":{
            "hops":[
                {
                    "from":"Reader",
                    "to":"Writer"
                }
            ]
        },
        "setting":{
            "errorLimit":{
                "record":"100" //错误记录数,表示脏数据的最大容忍条数。
            },
            "jvmOption":"",
            "speed":{
                "throttle":true,//当throttle值为false时,mbps参数不生效,表示不限流;当throttle值为true时,表示限流。
                "concurrent":3, //作业并发数。
                "mbps":"12"//限流,此处1mbps = 1MB/s。
            }
        },
        "steps":[
            {
                "category":"reader",
                "name":"Reader",
                "parameter":{
                    "column":[
                        "*"
                    ],
                    "datasource":"_ODPS",
                    "emptyAsNull":true,
                    "guid":"",
                    "isCompress":false,
                    "partition":[],
                    "table":""
                },
                "stepType":"odps"
            },
            {
                "category":"writer",
                "name":"Writer",
                "parameter": {
                    "datasource": "testGDB", // 数据源名称。
                    "label": "use", //label名,即边名称。
                    "labelType": "EDGE", //label类型,EDGE表示边。
                    "srcLabel": "person", //起点的点名称。
                    "dstLabel": "software", //终点的点名称。
                    "writeMode": "INSERT", //导入ID重复时的处理方式。
                    "idTransRule": "labelPrefix", //边的主键转换规则。
                    "srcIdTransRule": "labelPrefix", //起点的主键转换规则。
                    "dstIdTransRule": "labelPrefix", //终点的主键转换规则。
                    "column": [
                        {
                            "name": "id", //字段名。
                            "value": "#{0}", //#{0}表示取源端第1个字段值,支持拼接。
                            "type": "string", //字段类型。
                            "columnType": "primaryKey" //字段分类,primaryKey表示该字段是主键。
                        }, //边的主键,字段名必须是ID且类型是STRING,该记录选填。
                        {
                            "name": "id",
                            "value": "#{1}", //支持拼接,注意映射规则要与录入点时一致。
                            "type": "string",
                            "columnType": "srcPrimaryKey" //字段分类,srcPrimaryKey表示是起点主键。
                        }, //起点的主键,字段名必须是ID且类型是STRING,该记录必须存在。
                        {
                            "name": "id",
                            "value": "#{2}", //支持拼接,注意映射规则要与录入点时一致。
                            "type": "string",
                            "columnType": "dstPrimaryKey" //字段分类,dstPrimaryKey表示是终点主键。
                        }, //终点的主键,字段名必须是ID且类型是STRING,该记录必须存在。
                        {
                            "name": "person_use_software_time",
                            "value": "#{3}", //支持拼接。
                            "type": "long",
                            "columnType": "edgeProperty" //字段分类,edgeProperty表示边的属性。
                        }, //边的属性,支持INT、LONG、FLOAT、DOUBLE、BOOLEAN和STRING类型。
                        {
                            "name": "person_regist_software_name",
                            "value": "#{4}", //支持拼接。
                            "type": "string",
                            "columnType": "edgeProperty"
                        }, //边属性
                        {
                            "name": "id",
                            "value": "#{5}", //支持拼接。
                            "type": "long",
                            "columnType": "edgeProperty"
                        }, //边的属性,字段名是ID。与主键ID不同,该字段为普通属性,可选。
                    ]
                }
                "stepType":"gdb"
            }
        ],
        "type":"job",
        "version":"2.0"
    }

Writer脚本参数

参数

描述

是否必选

默认值

datasource

数据源名称,脚本模式支持添加数据源,此配置项填写的内容必须与添加的数据源名称保持一致。

label

类型名,即点/边名称。

label支持从源列中读取,例如#{0},表示取第1列字段作为label名,源列索引从0开始。

labelType

label的类型:

  • 枚举值VERTEX表示点。

  • 枚举值EDGE表示边。

srcLabel

  • 当label为边时,表示起点的点名称。

    label为边、srcIdTransRulenone时,可以不填写,否则为必填项。

  • label为点时,则不填。

dstLabel

  • 当label为边时,表示终点的点名称。

    label为边、dstIdTransRulenone时,可以不填写,否则为必填项。

  • label为点时,则不填。

writeMode

导入ID重复时的处理模式。

  • 枚举值INSERT表示会报错,错误记录数加1。

  • 枚举值MERGE表示用新值覆盖旧值。

INSERT

idTransRule

主键ID的转换规则。

  • 枚举值labelPrefix表示将映射的值转换为{label名}-{源字段}

  • 枚举值none表示映射的值不进行转换。

none

srcIdTransRule

label为边时,表示起点的主键ID转换规则。

  • 枚举值labelPrefix表示将映射的值转换为{label名}-{源字段}

  • 枚举值none表示映射的值不进行转换,此时可以不填写srcLabel

label为边时必选

none

dstIdTransRule

label为边时,表示终点的主键ID转换规则。

  • 枚举值labelPrefix表示将映射的值转换为{label名}-{源字段}

  • 枚举值none表示映射的值不进行转换,此时可以不填写dstLabel

label为边时必选

none

column

点/边字段映射关系配置。

  • name:点/边的字段名。

  • value:点/边字段映射的值,仅脚本模式支持字符串自定义拼接。

    • #{N}表示直接映射源端值,N为源端column索引,从0开始。

    • #{0}表示映射源端column第1个字段。

    • test-#{0}表示源端值进行拼接转换,#{0}值前/后可以添加固定字符串。

    • #{0}-#{1}表示进行多字段拼接,也可以在任意位置添加固定字符串,例如test-#{0}-test1-#{1}-test2

  • type:点/边字段映射值的类型。

    主键ID仅支持STRING类型,GDB Writer会进行强制转换,源ID必须保证可以转换为STRING类型。

    普通属性支持类型:INT、LONG、FLOAT、DOUBLE、BOOLEAN和STRING。

  • columnType:点/边映射字段的分类,支持的枚举值如下所示。

    • 公共枚举值

      primaryKey:label为点/边时,表示该字段是主键ID。

    • 点枚举值

      • vertexProperty:label为点时,表示该字段是点的普通属性。

      • vertexJsonProperty:label为点时,表示是点JSON属性,value结构请参见properties示例。

    • 边枚举值

      • srcPrimaryKey:label为边时,表示该字段是起点主键ID。

      • dstPrimaryKey:label为边时,表示该字段是终点主键ID。

      • edgeProperty:label为边时,表示该字段是边的普通属性。

      • edgeJsonProperty:label为边时,表示是边JSON属性,value结构请参见properties示例。

properties示例

{"properties":[
    {"k":"name","t":"string","v":"tom"},
    {"k":"age","t":"int","v":"20"},
    {"k":"sex","t":"string","v":"male"}
]}