数据插入

本节介绍用于插入点、边的方法。

示例图

本节中的示例演示如何向图中插入点和边，图中包含如下的Schema和属性定义：

参考此示例创建这个图。

插入请求配置

所有的插入方法都接受一个可选的InsertRequestConfig参数，而不是标准的RequestConfig参数。

InsertRequestConfig包括RequestConfig的所有字段，另外包括：

简单插入

insertNodes()和insertEdges()方法适用于插入少量点或边。这些方法将用户请求转换为UQL语句并发送给数据库。它们易于使用，但由于查询处理的开销，对于大批量数据插入的效率较低。

insertNodes()

向图中某个Schema插入点。

参数

• schemaName: string：Schema名称。
• nodes: Node[]：待插入的点列表。
• config?: InsertRequestConfig：请求配置。

返回值

• Response：请求结果。

// Inserts two 'user' nodes into the graph 'social'

const insertRequestConfig: InsertRequestConfig = {
  graph: "social",
  insertType: InsertType.NORMAL,
  silent: true
};

const node1: Node = {
  id: "U1",
  values: {
    name: "Alice",
    age: 18,
    score: 65.32,
    birthday: "1993-05-04",
    active: 0,
    location: "POINT(132.1 -1.5)",
    interests: ["tennis", "violin"],
    permissionCodes: [2004, 3025, 1025]
  },
};
const node2 = { 
  id: "U2", 
  values: { name: "Bob" } 
};
const nodeList = [node1,node2]

const response = await driver.insertNodes("user", nodeList, insertRequestConfig);
console.log(response.status?.message);

SUCCESS

insertEdges()

向图中某个Schema插入边。

参数

• schemaName: string：Schema名称。
• edges: Edge[]：待插入的边列表；每个Edge的from和to属性必填。
• config?: InsertRequestConfig：请求配置。

返回值

• Response：请求结果。

// Inserts two 'follows' edges to the graph 'social'

const insertRequestConfig: InsertRequestConfig = {
  graph: "social",
  insertType: InsertType.NORMAL,
  silent: true
};

const edge1 = {
  from: "U1",
  to: "U2",
  values: {
    createdOn: "2024-05-06 12:10:05",
    weight: 3.2
  },
};
const edge2 = {
  from: "U2",
  to: "U1",
  values: { createdOn: 1715169600 }
};
const edgeList = [edge1, edge2];

const response = await driver.insertEdges("follows", edgeList, insertRequestConfig);
console.log(response.status?.message);

SUCCESS

批量插入

insertNodesBatchBySchema()、insertEdgesBatchBySchema()、insertNodesBatchAuto()和insertEdgesBatchAuto()方法适用于插入大批量点或边。这些方法使用gRPC协议将数据包直接发送到服务器，从而显著提高了吞吐量。

重要提示：使用批量插入方法时，请使用对应的Node.js数据类型给各类型的属性赋值（参考下表）。

^[1] 支持的日期格式包括YYYY-MM-DD和YYYYMMDD，支持的时间格式包括HH:MM:SS[.fraction]和HHMMSS[.fraction]。日期和时间用空格或字母T连接。支持的时区格式包括±HH:MM和±HHMM。

insertNodesBatchBySchema()

通过gRPC向图中某个Schema插入点。此方法针对批量插入进行了优化。

参数

• schema: Schema：目标Schema；字段name必填，properties包含图中对应Schema关联的部分或所有属性。
• nodes: Node[]：待插入的点列表。
• config?: InsertRequestConfig：请求配置。

返回值

• InsertResponse：插入请求结果。

// Inserts two 'user' nodes into the graph 'social'

const insertRequestConfig: InsertRequestConfig = {
  graph: "social",
  insertType: InsertType.NORMAL,
  silent: true
};

const user: Schema = {
  name: "user",
  dbType: DBType.DBNODE,
  properties: [
    { name: "name", type: ULTIPA.UltipaPropertyType.STRING, schema: "user" },
    { name: "age", type: ULTIPA.UltipaPropertyType.INT32, schema: "user" },
    { name: "score", type: ULTIPA.UltipaPropertyType.DECIMAL, decimalExtra: { precision: 25, scale: 10 }, schema: "user" },
    { name: "birthday", type: ULTIPA.UltipaPropertyType.DATE, schema: "user" },
    { name: "active", type: ULTIPA.UltipaPropertyType.BOOL, schema: "user" },
    { name: "location", type: ULTIPA.UltipaPropertyType.POINT, schema: "user" },
    { name: "interests", type: ULTIPA.UltipaPropertyType.LIST, subType: [UltipaPropertyType.STRING], schema: "user" },
    { name: "permissionCodes", type: ULTIPA.UltipaPropertyType.SET, subType: [UltipaPropertyType.INT32], schema: "user" }
  ]
};

const node1 = {
  id: "U1",
  values: {
    name: "Alice",
    age: 18,
    score: 65.32,
    birthday: "1993-05-04",
    active: 0,
    location: "POINT(132.1 -1.5)",
    interests: ["tennis", "violin"],
    permissionCodes: [2004, 3025, 1025],
  },
};
const node2 = { id: "U2", values: { name: "Bob" } };
const nodeList = [node1, node2];

const insertResponse = await driver.insertNodesBatchBySchema(user, nodeList, insertRequestConfig);
if (insertResponse.errorItems?.size === 0) {
  console.log("All nodes inserted successfully");
} else {
  console.log("Error items:", insertResponse.errorItems);
}

All nodes inserted successfully

insertEdgesBatchBySchema()

通过gRPC向图中某个Schema插入边。此方法针对批量插入进行了优化。

参数

• schema: Schema：目标Schema；字段name必填，properties包含图中对应Schema关联的部分或所有属性。
• edges: Edge[]：待插入的边列表；每个Edge的from和to字段必填。
• config?: InsertRequestConfig：请求配置。

返回值

• config: InsertResponse：插入请求结果。

// Inserts two 'follows' edges into the graph 'social'

const insertRequestConfig: InsertRequestConfig = {
  graph: "social",
  insertType: InsertType.NORMAL,
  silent: true
};

const follows: Schema = {
  name: "follows",
  dbType: DBType.DBEDGE,
  properties: [
    { name: "createdOn", type: UltipaPropertyType.TIMESTAMP, schema: "follows" },
    { name: "weight", type: UltipaPropertyType.FLOAT, schema: "follows" }
  ]
};

const edge1 = {
  from: "U1",
  to: "U2",
  values: {
    createdOn: "2024-05-06 12:10:05",
    weight: 3.2,
  },
};
const edge2 = { 
  from: "U2", 
  to: "U1", 
  values: { 
    createdOn: 1715169600 
  } 
};
const edgeList = [edge1, edge2];

const insertResponse = await driver.insertEdgesBatchBySchema(follows, edgeList, insertRequestConfig);
if (insertResponse.errorItems?.size === 0) {
  console.log("All edges inserted successfully");
} else {
  console.log("Error items:", insertResponse.errorItems);
}

All edges inserted successfully

insertNodesBatchAuto()

通过gRPC向图中一个或多个Schema插入点。此方法针对批量插入进行了优化。

参数

• nodes: Node[]：待插入的点列表；每个Node的schema字段必填，values包含图中对应Schema关联的部分或所有属性。
• config?: InsertRequestConfig：请求配置。

返回值

• Map<string, InsertResponse>：Schema名称，插入请求结果。

// Inserts two 'user' nodes and a 'product' node into the graph 'social'

const insertRequestConfig: InsertRequestConfig = {
  graph: "social",
  insertType: InsertType.NORMAL,
  silent: true
};

const node1 = {
  id: "U1",
  schema: "user",
  values: {
    name: "Alice",
    age: 18,
    score: 65.32,
    birthday: "1993-05-04",
    active: false,
    location: "POINT(132.1 -1.5)",
    interests: ["tennis", "violin"],
    permissionCodes: [2004, 3025, 1025]
  },
};
const node2 = { id: "U2", schema: "user", values: { name: "Bob" } };
const node3 = {
  id: "P1",
  schema: "product",
  values: { name: "Wireless Earbud", price: "93.2" }
};

const nodeList = [node1, node2, node3];

const result = await driver.insertNodesBatchAuto(nodeList, insertRequestConfig);
for (let [schemaName, insertResponse] of result.entries()) {
  if (insertResponse.errorItems && insertResponse.errorItems.size > 0) {
    console.log("Error items of", schemaName, "nodes:");
    for (const [rowIndex, errorCode] of insertResponse.errorItems.entries()) {
      const errorMessage = InsertErrorCode[errorCode];
      console.log(`Row ${rowIndex} failed: ${errorMessage} (Code: ${errorCode})`);
    }
  } else {
    console.log("All " + schemaName + " nodes inserted successfully");
  }
}

All user nodes inserted successfully
All product nodes inserted successfully

insertEdgesBatchAuto()

通过gRPC向图中一个或多个Schema插入边。此方法针对批量插入进行了优化。

参数

• edges: Edge[]：待插入的边列表；每个Edge的schema、from和to字段必填，values包含图中对应Schema关联的部分或所有属性。
• config?: InsertRequestConfig：请求配置。

返回值

• Map<string, InsertResponse>：Schema名称，插入请求结果。

// Inserts two 'user' nodes and a 'product' node into the graph 'social'

const insertRequestConfig: InsertRequestConfig = {
  graph: "social",
  insertType: InsertType.NORMAL,
  silent: true
};

const edge1 = {
  from: "U1",
  to: "U2",
  schema: "follows",
  values: {
    createdOn: "2024-05-06 12:10:05",
    weight: 3.2
  }
};
const edge2 = {
  from: "U2",
  to: "U1",
  schema: "follows",
  values: {
    createdOn: 1714953600
  }
};
const edge3 = { from: "U2", to: "P1", schema: "purchased" };

const edgeList = [edge1, edge2, edge3];

const result = await driver.insertEdgesBatchAuto(edgeList, insertRequestConfig);
for (let [schemaName, insertResponse] of result.entries()) {
  if (insertResponse.errorItems && insertResponse.errorItems.size > 0) {
    console.log("Error items of", schemaName, "edges:");
    for (const [rowIndex, errorCode] of insertResponse.errorItems.entries()) {
      const errorMessage = InsertErrorCode[errorCode];
      console.log(`Row ${rowIndex} failed: ${errorMessage} (Code: ${errorCode})`);
    }
  } else {
    console.log("All " + schemaName + " edges inserted successfully");
  }
}

All follows edges inserted successfully
All purchased edges inserted successfully

完整示例

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";
import { DBType, GraphSet, RequestConfig, Schema, Node, Edge, UltipaPropertyType, InsertRequestConfig, InsertType, InsertErrorCode } from "@ultipa-graph/ultipa-driver/dist/types/types.js";

let sdkUsage = async () => {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    // URI example: hosts: ["xxxx.us-east-1.cloud.ultipa.com:60010"]
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>"
  };

  const driver = new UltipaDriver(ultipaConfig);

  // Inserts two 'user' nodes, a 'product' node, two 'follows' edges, and a 'purchased' edge into the graph 'social'

  const insertRequestConfig: InsertRequestConfig = {
    graph: "social",
    insertType: InsertType.NORMAL,
    silent: true
  };

  const node1 = {
    id: "U1",
    schema: "user",
    values: {
      name: "Alice",
      age: 18,
      score: 65.32,
      birthday: "1993-05-04",
      active: false,
      location: "POINT(132.1 -1.5)",
      interests: ["tennis", "violin"],
      permissionCodes: [2004, 3025, 1025]
    },
  };
  const node2 = { id: "U2", schema: "user", values: { name: "Bob" } };
  const node3 = {
    id: "P1",
    schema: "product",
    values: { name: "Wireless Earbud", price: "93.2" }
  };

  const nodeList = [node1, node2, node3];

  const edge1 = {
    from: "U1",
    to: "U2",
    schema: "follows",
    values: {
      createdOn: "2024-05-06 12:10:05",
      weight: 3.2,
    },
  };
  const edge2 = {
    from: "U2",
    to: "U1",
    schema: "follows",
    values: {
      createdOn: 1714953600
    },
  };
  const edge3 = { from: "U2", to: "P1", schema: "purchased" };

  const edgeList = [edge1, edge2, edge3];

  const result_n = await driver.insertNodesBatchAuto(nodeList, insertRequestConfig);
  for (let [schemaName, insertResponse] of result_n.entries()) {
    if (insertResponse.errorItems && insertResponse.errorItems.size > 0) {
      console.log("Error items of", schemaName, "nodes:");
      for (const [rowIndex, errorCode] of insertResponse.errorItems.entries()) {
        const errorMessage = InsertErrorCode[errorCode];
        console.log(`Row ${rowIndex} failed: ${errorMessage} (Code: ${errorCode})`);
      }
    } else {
      console.log("All " + schemaName + " nodes inserted successfully");
    }
  }

  const result_e = await driver.insertEdgesBatchAuto(edgeList, insertRequestConfig);
  for (let [schemaName, insertResponse] of result_e.entries()) {
    if (insertResponse.errorItems && insertResponse.errorItems.size > 0) {
      console.log("Error items of", schemaName, "edges:");
      for (const [rowIndex, errorCode] of insertResponse.errorItems.entries()) {
        const errorMessage = InsertErrorCode[errorCode];
        console.log(`Row ${rowIndex} failed: ${errorMessage} (Code: ${errorCode})`);
      }
    } else {
      console.log("All " + schemaName + " edges inserted successfully");
    }
  }
};

sdkUsage().catch(console.error);