Data Insertion

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

Property Type Mapping

The mappings between Ultipa property types and Go 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: []*structs.Node: The list of nodes to be inserted.
• config: *configuration.InsertRequestConfig (Optional): Request configuration.

Returns

• Response: Response of the request.
• error: An error object that contains details about any issues encountered during the operation. If the operation succeeds, nil is returned.

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

requestConfig := &configuration.RequestConfig{
    Graph: "social",
}

insertRequestConfig := &configuration.InsertRequestConfig{
    RequestConfig: requestConfig,
}

nodes := []*structs.Node{
    {
    	ID: "U1",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"name":            "Alice",
        		"age":             18,
        		"score":           65.32,
        		"birthday":        "1993-5-4",
        		"active":          0,
        		"location":        "point({latitude: 132.1, longitude: -1.5})",
        		"interests":       []string{"tennis", "violin"},
        		"permissionCodes": []int32{2004, 3025, 1025},
      		},
    	},
    },
    {
    	ID: "U2",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"name": "Bob",
      		},
    	},
  	},
}

response, _ := driver.InsertNodes("user", nodes, insertRequestConfig)
if response.Status.Code.String() == "SUCCESS" {
    fmt.Println(response.Status.Code)
} else {
    fmt.Println(response.Status.Message)
}

SUCCESS

InsertEdges()

Inserts edges to a schema in the graph.

Parameters

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

Returns

• Response: Response of the request.
• error: An error object that contains details about any issues encountered during the operation. If the operation succeeds, nil is returned.

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

requestConfig := &configuration.RequestConfig{
    Graph: "social",
}

insertRequestConfig := &configuration.InsertRequestConfig{
    RequestConfig: requestConfig,
}

edges := []*structs.Edge{
    {
    	From: "U1",
    	To:   "U2",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"createdOn": "2024-5-6",
        		"weight":    3.2,
      		},
    	},
  	},
  	{
    	From: "U2",
    	To:   "U1",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"createdOn": 1715169600,
      		},
    	},
  	},
}

response, _ := driver.InsertEdges("follows", edges, insertRequestConfig)
if response.Status.Code.String() == "SUCCESS" {
    fmt.Println(response.Status.Code)
} else {
    fmt.Println(response.Status.Message)
}

SUCCESS

InsertNodesBatchBySchema()

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

Parameters

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

Returns

• InsertResponse: Result of the request.
• error: An error object that contains details about any issues encountered during the operation. If the operation succeeds, nil is returned.

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

requestConfig := &configuration.RequestConfig{
    Graph: "social",
}

insertRequestConfig := &configuration.InsertRequestConfig{
    RequestConfig: requestConfig,
}

schema := &structs.Schema{
    Name: "user",
    Properties: []*structs.Property{
    	{Name: "name", Type: ultipa.PropertyType_STRING},
    	// {Name: "age", Type: ultipa.PropertyType_INT32},
    	{Name: "score", Type: ultipa.PropertyType_DECIMAL, DecimalExtra: &structs.DecimalExtra{Precision: 25, Scale: 10}},
    	{Name: "birthday", Type: ultipa.PropertyType_DATETIME},
    	{Name: "active", Type: ultipa.PropertyType_BOOL},
    	{Name: "location", Type: ultipa.PropertyType_POINT},
    	{Name: "interests", Type: ultipa.PropertyType_LIST, SubTypes: []ultipa.PropertyType{ultipa.PropertyType_STRING}},
    	{Name: "permissionCodes", Type: ultipa.PropertyType_SET, SubTypes: []ultipa.PropertyType{ultipa.PropertyType_INT32}},
    },
}

nodes := []*structs.Node{
    {
    	ID: "U1",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"name": "Alice",
        		// "age":             18,
        		"score":           65.32,
        		"birthday":        "1993-5-4",
        		"active":          false,
        		"location":        types.NewPoint(132.1, -1.5),
        		"interests":       []string{"tennis", "violin"},
        		"permissionCodes": []int32{2004, 3025, 1025},
      		},
    	},
    },
    {
    	ID: "U2",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"name": "Bob",
        		// "age":             nil,
        		"score":           nil,
        		"birthday":        nil,
        		"active":          nil,
        		"location":        nil,
        		"interests":       nil,
        		"permissionCodes": nil,
      		},
    	},
    },
}

insertResponse, err := driver.InsertNodesBatchBySchema(schema, nodes, insertRequestConfig)
if err != nil {
    log.Fatalf("Insert failed: %v", err)
}

if insertResponse != nil && len(insertResponse.ErrorItem) > 0 {
    fmt.Println("Error items:", insertResponse.ErrorItem)
} else {
    fmt.Println("All nodes inserted successfully")
}

All nodes inserted successfully

InsertEdgesBatchBySchema()

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

Parameters

• schema: *structs.Schema: The target schema; the fields Name is mandatory, Properties includes partial or all properties defined for the corresponding schema in the graph.
• edges: []*structs.Edge: The list of edges to be inserted; the fields From and To of each Edge are mandatory; the fields Values of each Edge must have the same structure with Schema.Properties.
• config: *configuration.InsertRequestConfig (Optional): Request configuration.

Returns

• InsertResponse: Result of the request.
• error: An error object that contains details about any issues encountered during the operation. If the operation succeeds, nil is returned.

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

requestConfig := &configuration.RequestConfig{
    Graph: "social",
}

insertRequestConfig := &configuration.InsertRequestConfig{
    RequestConfig: requestConfig,
}

schema := &structs.Schema{
    Name: "follows",
    Properties: []*structs.Property{
    	// {Name: "createdOn", Type: ultipa.PropertyType_TIMESTAMP},
    	{Name: "weight", Type: ultipa.PropertyType_FLOAT},
    },
}

edges := []*structs.Edge{
    {
    	From: "U1",
    	To:   "U2",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		// "createdOn": "2024-5-6",
                "weight": float32(3.2),
      		},
    	},
  	},
  	{
    	From: "U2",
    	To:   "U1",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		// "createdOn": 1715169600,
        		"weight": nil,
      		},
    	},
  	},
}

insertResponse, err := driver.InsertEdgesBatchBySchema(schema, edges, insertRequestConfig)
if err != nil {
  	log.Fatalf("Insert failed: %v", err)
}

if insertResponse != nil && len(insertResponse.ErrorItem) > 0 {
  	fmt.Println("Error items:", insertResponse.ErrorItem)
} else {
  	fmt.Println("All edges inserted successfully")
}

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: []*structs.Node: The list of nodes to be inserted; the field Schema of each Node are mandatory, the Values of all nodes must have the same structure and include all properties defined for the corresponding schema in the graph.
• config: *configuration.InsertRequestConfig (Optional): Request configuration.

Returns

• map[string]*http.InsertResponse: The schema name, and response of the insertion request.
• error: An error object that contains details about any issues encountered during the operation. If the operation succeeds, nil is returned.

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

requestConfig := &configuration.RequestConfig{
    Graph: "social",
}

insertRequestConfig := &configuration.InsertRequestConfig{
    RequestConfig: requestConfig,
}

nodes := []*structs.Node{
    {
    	Schema: "user",
    	ID:     "U1",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"name":            "Alice",
        		"age":             18,
        		"score":           65.32,
        		"birthday":        "1993-5-4",
        		"active":          false,
        		"location":        types.NewPoint(132.1, -1.5),
        		"interests":       []string{"tennis", "violin"},
        		"permissionCodes": []int32{2004, 3025, 1025},
      		},
    	},
  	},
  	{
    	Schema: "user",
    	ID:     "U2",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"name":            "Bob",
        		"age":             nil,
        		"score":           nil,
        		"birthday":        nil,
        		"active":          nil,
        		"location":        nil,
        		"interests":       nil,
        		"permissionCodes": nil,
      		},
    	},
  	},
  	{
    	Schema: "product",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"name":  "Wireless Earbud",
        		"price": float32(93.2),
      		},
    	},
  	},
}

result, err := driver.InsertNodesBatchAuto(nodes, insertRequestConfig)
if err != nil {
  	log.Fatalf("Insert failed: %v", err)
}

for schemaName, insertResponse := range result {
  	if len(insertResponse.ErrorItem) > 0 {
    	fmt.Println("Error items of", schemaName, "nodes:", insertResponse.ErrorItem)
  	} else {
    	fmt.Println("All", schemaName, "nodes inserted successfully")
  	}
}

All product nodes inserted successfully
All user 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: []*structs.Edge: The list of edges to be inserted; the fields Schema, From, and To of each Edge are mandatory, the Values of all edges must have the same structure and include all properties defined for the corresponding schema in the graph.
• config: *configuration.InsertRequestConfig (Optional): Request configuration.

Returns

• map[string]*http.InsertResponse: The schema name, and response of the insertion request.
• error: An error object that contains details about any issues encountered during the operation. If the operation succeeds, nil is returned.

// Inserts two 'follows' edges and a 'purchased' edge into the graph 'social'

requestConfig := &configuration.RequestConfig{
    Graph: "social",
}

insertRequestConfig := &configuration.InsertRequestConfig{
  	RequestConfig: requestConfig,
}

edges := []*structs.Edge{
  	{
    	Schema: "follows",
    	From:   "U1",
    	To:     "U2",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"createdOn": "2024-5-6",
        		"weight":    float32(3.2),
      		},
    	},
  	},
  	{
    	Schema: "follows",
    	From:   "U2",
    	To:     "U1",
    	Values: &structs.Values{
      		Data: map[string]interface{}{
        		"createdOn": 1715169600,
        		"weight":    nil,
      		},
    	},
  	},
  	{
    	Schema: "purchased",
    	From:   "U2",
    	To:     "684bd6a70000020020000001",
  	},
}

result, err := driver.InsertEdgesBatchAuto(edges, insertRequestConfig)
if err != nil {
  	log.Fatalf("Insert failed: %v", err)
}

for schemaName, insertResponse := range result {
  	if len(insertResponse.ErrorItem) > 0 {
    	fmt.Println("Error items of", schemaName, "edges:", insertResponse.ErrorItem)
  	} else {
    	fmt.Println("All", schemaName, "edges inserted successfully")
  	}
}

All follows edges inserted successfully
All purchased edges inserted successfully

Full Example

package main

import (
	"fmt"
	"log"

	"github.com/ultipa/ultipa-go-sdk/sdk"
	"github.com/ultipa/ultipa-go-sdk/sdk/configuration"
	"github.com/ultipa/ultipa-go-sdk/sdk/structs"
	"github.com/ultipa/ultipa-go-sdk/sdk/types"
)

func main() {
	config := &configuration.UltipaConfig{
		// URI example:	Hosts: []string{"mqj4zouys.us-east-1.cloud.ultipa.com:60010"},
		Hosts:    []string{"192.168.1.85:60061", "192.168.1.87:60061", "192.168.1.88:60061"},
		Username: "<usernmae>",
		Password: "<password>",
	}

	driver, err := sdk.NewUltipaDriver(config)
	if err != nil {
		log.Fatalln("Failed to connect to Ultipa:", err)
	}

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

	requestConfig := &configuration.RequestConfig{
		Graph: "social",
	}

	insertRequestConfig := &configuration.InsertRequestConfig{
		RequestConfig: requestConfig,
	}

	nodes := []*structs.Node{
		{
			Schema: "user",
			ID:     "U1",
			Values: &structs.Values{
				Data: map[string]interface{}{
					"name":            "Alice",
					"age":             18,
					"score":           65.32,
					"birthday":        "1993-5-4",
					"active":          false,
					"location":        types.NewPoint(132.1, -1.5),
					"interests":       []string{"tennis", "violin"},
					"permissionCodes": []int32{2004, 3025, 1025},
				},
			},
		},
		{
			Schema: "user",
			ID:     "U2",
			Values: &structs.Values{
				Data: map[string]interface{}{
					"name":            "Bob",
					"age":             nil,
					"score":           nil,
					"birthday":        nil,
					"active":          nil,
					"location":        nil,
					"interests":       nil,
					"permissionCodes": nil,
				},
			},
		},
		{
			Schema: "product",
			ID:     "P1",
			Values: &structs.Values{
				Data: map[string]interface{}{
					"name":  "Wireless Earbud",
					"price": float32(93.2),
				},
			},
		},
	}

	edges := []*structs.Edge{
		{
			Schema: "follows",
			From:   "U1",
			To:     "U2",
			Values: &structs.Values{
				Data: map[string]interface{}{
					"createdOn": "2024-5-6",
					"weight":    float32(3.2),
				},
			},
		},
		{
			Schema: "follows",
			From:   "U2",
			To:     "U1",
			Values: &structs.Values{
				Data: map[string]interface{}{
					"createdOn": 1715169600,
					"weight":    nil,
				},
			},
		},
		{
			Schema: "purchased",
			From:   "U2",
			To:     "P1",
		},
	}

	result_n, err := driver.InsertNodesBatchAuto(nodes, insertRequestConfig)
	if err != nil {
		log.Fatalf("Insert failed: %v", err)
	}

	for schemaName, insertResponse := range result_n {
		if len(insertResponse.ErrorItem) > 0 {
			fmt.Println("Error items of", schemaName, "nodes:", insertResponse.ErrorItem)
		} else {
			fmt.Println("All", schemaName, "nodes inserted successfully")
		}
	}

	result_e, err := driver.InsertEdgesBatchAuto(edges, insertRequestConfig)
	if err != nil {
		log.Fatalf("Insert failed: %v", err)
	}

	for schemaName, insertResponse := range result_e {
		if len(insertResponse.ErrorItem) > 0 {
			fmt.Println("Error items of", schemaName, "edges:", insertResponse.ErrorItem)
		} else {
			fmt.Println("All", schemaName, "edges inserted successfully")
		}
	}
}