Data Insertion

This section introduces methods for the insertion of nodes and edges.

Property Type Mapping

The mappings between Ultipa property types and Node.js data types are as follows:

^[1] Supported date string formats include [YY]YY-MM-DD HH:MM:SS, [YY]YY-MM-DD HH:MM:SSZ, [YY]YY-MM-DDTHH:MM:SSZ, [YY]YY-MM-DDTHH:MM:SSXX, [YY]YY-MM-DDTHH:MM:SSXXX, [YY]YY-MM-DD HH:MM:SS.SSS and their variations.

Example Graph Structure

The examples in this section demonstrate the insertion and deletion of nodes and edges in a graph based on the following schema and property definitions:

To create this graph structure, see the example provided here.

insertNodes()

Inserts nodes to a schema in the graph.

Parameters

• schemaName: string: Schema name.
• nodes: Node[]: The list of nodes to be inserted.
• config: InsertRequestConfig (Optional): Request configuration.

Returns

• Response: Response of the request.

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

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

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

const nodes : ULTIPA.Node[] = nodeList.map(entity => {
  const node = new ULTIPA.Node();
  node.id = entity.id;
  node.values = new Map(Object.entries(entity.values));
  return node
})
const response = await conn.insertNodes("user",nodes,insertRequestConfig)
console.log(response.status?.message)

SUCCESS

insertEdges()

Inserts edges to a schema in the graph.

Parameters

• schemaName: string: Schema name.
• edges: Edge[]: The list of edges to be inserted; the attributes from and to of each Edge are mandatory.
• config: InsertRequestConfig (Optional): Request configuration.

Returns

• Response: Response of the request.

// 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-5-6",
    weight: "3.2",
  },
};
const edge2 = {
  from: "U2",
  to: "U1",
  values: { createdOn: "2024-5-8" },
};
const edgeList = [edge1, edge2];

const edges: ULTIPA.Edge[] = edgeList.map((entity) => {
  const edge = new ULTIPA.Edge();
  edge.from = entity.from;
  edge.to = entity.to;
  edge.values = new Map(Object.entries(entity.values));
  return edge;
});
const response = await conn.insertEdges("follows", edges, insertRequestConfig);
console.log(response.status?.message);

SUCCESS

insertNodesBatchBySchema()

Inserts nodes to a schema in the graph through gRPC. This method is optimized for bulk insertion.

Parameters

• schema: Schema: The target schema; the attribute name is mandatory, properties includes partial or all properties defined for the corresponding schema in the graph.
• nodes: Node[]: The list of nodes to be inserted; the attribute values of each Node must have the same structure with Schema.properties.
• config: InsertRequestConfig (Optional): Request configuration.

Returns

• InsertResponse: Response of the insertion request.

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

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

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

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

const nodes: ULTIPA.Node[] = nodeList.map((entity) => {
  const node = new ULTIPA.Node();
  node.id = entity.id;
  node.values = new Map(Object.entries(entity.values));
  return node;
});

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

All nodes inserted successfully

insertEdgesBatchBySchema()

Inserts edges to a schema in the graph through gRPC. This method is optimized for bulk insertion.

Parameters

• schema: Schema: The target schema; the attribute name is mandatory, properties includes partial or all properties defined for the corresponding schema in the graph.
• edges: Edge[]: The list of edges to be inserted; the attributes from and to of each Edge are mandatory, values must have the same structure with Schema.properties.
• config: InsertRequestConfig (Optional): Request configuration.

Returns

• config: InsertResponse: Response of the insertion request.

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

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

const schema: 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: 1714953600,
    weight: "3.2",
  },
};
const edge2 = { from: "U2", to: "U1", values: { createdOn: 1715169600 } };
const edgeList = [edge1, edge2];

const edges: ULTIPA.Edge[] = edgeList.map((entity) => {
  const edge = new ULTIPA.Edge();
  edge.from = entity.from;
  edge.to = entity.to;
  edge.values = new Map(Object.entries(entity.values));
  return edge;
});

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

All edges inserted successfully

insertNodesBatchAuto()

Inserts nodes to one or multipe schemas in the graph through gRPC. This method is optimized for bulk insertion.

Parameters

• nodes: Node[]: The list of nodes to be inserted; the attribute schema of each Node are mandatory, the values of all nodes must have the same structure and include partial or all properties defined for the corresponding schema in the graph.
• config: InsertRequestConfig (Optional): Request configuration.

Returns

• Map<string, InsertResponse>: The schema name, and response of the insertion request.

// 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-5-4",
    active: false,
    location: `POINT(132.1 -1.5)`,
    profile: "abc",
    interests: ["tennis", "violin"],
    permissionCodes: [2004, 3025, 1025],
  },
};
const node2 = { id: "U2", schema: "user", values: { name: "Bob" } };
const node3 = {
  schema: "product",
  values: { name: "Wireless Earbud", price: "93.2" },
};

const nodeList = [node1, node2,node3];
const nodes: ULTIPA.Node[] = nodeList.map((entity) => {
  const node = new ULTIPA.Node();
  if('id' in entity){
    node.id = entity.id;
  }
  node.schema = entity.schema;
  node.values = new Map(Object.entries(entity.values));
  return node;
});

const result = await conn.insertNodesBatchAuto(nodes, insertRequestConfig);
for (let [schemaName, insertResponse] of result.entries()) {
  if (!isEmpty(insertResponse.errorItems)) {
    console.log(
      "Error items of " +
        schemaName +
        " nodes: " +
        JSON.stringify(insertResponse.errorItems)
    );
  } else {
    console.log("All " + schemaName + " nodes inserted successfully");
  }
}

All user nodes inserted successfully
All product nodes inserted successfully

insertEdgesBatchAuto()

Inserts edges to one or multipe schemas in the graph through gRPC. This method is optimized for bulk insertion.

Parameters

• edges: Edge[]: The list of edges to be inserted; the attributes schema, from, and to are mandatory, the values of all edges must have the same structure and include partial or all properties defined for the corresponding schema in the graph.
• config: InsertRequestConfig (Optional): Request configuration.

Returns

• Map<string, InsertResponse>: The schema name, and response of the insertion request.

// Inserts two 'follows' edges and a 'purchased' edge 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",
    weight: "3.2"
  },
};
const edge2 = { 
  from: "U2",
  to: "U1",
  schema: "follows", 
  values: { 
    createdOn: 1714953600,
  } };
const edge3 = {
  from:"U2",
  to: "68382e950000010021000000",
  schema: "purchased"
};

const edgeList = [edge1, edge2,edge3];
const edges: ULTIPA.Edge[] = edgeList.map((entity) => {
  const edge = new ULTIPA.Edge();
  if('values' in entity && entity.values instanceof Object){
    edge.values = new Map(Object.entries(entity.values));
  }
  edge.from = entity.from;
  edge.to = entity.to;
  edge.schema = entity.schema;
  return edge;
});

const result = await conn.insertEdgesBatchAuto(edges, insertRequestConfig);
for (let [schemaName, insertResponse] of result.entries()) {
  if (!isEmpty(insertResponse.errorItems)) {
    console.log(
      "Error items of " +
        schemaName +
        " edges: " +
        JSON.stringify(insertResponse.errorItems)
    );
  } else {
    console.log("All " + schemaName + " edges inserted successfully");
  }
}

All follows edges inserted successfully
All purchased edges inserted successfully

Full Example

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types";
import { InsertRequestConfig } from "@ultipa-graph/ultipa-driver/dist/types/types";
import { InsertType } from "@ultipa-graph/ultipa-driver/src/proto/ultipa_pb";
import { isEmpty } from "lodash";

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

  const conn = new UltipaDriver(ultipaConfig);
  const isSuccess = await conn.test();
  console.log(`Connection succeeds: ${isSuccess}`);

  // 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-5-4",
      active: 0,
      location: `POINT(132.1 -1.5)`,
      profile: "abc",
      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 nodes: ULTIPA.Node[] = nodeList.map((entity) => {
    const node = new ULTIPA.Node();
    node.id = entity.id;
    node.schema = entity.schema;
    node.values = new Map(Object.entries(entity.values));
    return node;
  });

  const edge1 = {
    from: "U1",
    to: "U2",
    schema: "follows",
    values: {
      createdOn: "2024-05-06",
      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 edges: ULTIPA.Edge[] = edgeList.map((entity) => {
    const edge = new ULTIPA.Edge();
    if ("values" in entity && entity.values instanceof Object) {
      edge.values = new Map(Object.entries(entity.values));
    }
    edge.from = entity.from;
    edge.to = entity.to;
    edge.schema = entity.schema;
    return edge;
  });

  const result_n = await conn.insertNodesBatchAuto(nodes, insertRequestConfig);
  for (let [schemaName, insertResponse] of result_n.entries()) {
    if (!isEmpty(insertResponse.errorItems)) {
      console.log(
        "Error items of " +
          schemaName +
          " nodes: " +
          JSON.stringify(insertResponse.errorItems)
      );
    } else {
      console.log("All " + schemaName + " nodes inserted successfully");
    }
  }

  const result_e = await conn.insertEdgesBatchAuto(edges, insertRequestConfig);
  for (let [schemaName, insertResponse] of result_e.entries()) {
    if (!isEmpty(insertResponse.errorItems)) {
      console.log(
        "Error items of " +
          schemaName +
          " edges: " +
          JSON.stringify(insertResponse.errorItems)
      );
    } else {
      console.log("All " + schemaName + " edges inserted successfully");
    }
  }
};

sdkUsage().catch(console.error);