gremlin-go

README

NOTE that versions suffixed with "-rc" are considered release candidates (i.e. pre-alpha, alpha, beta, etc.) and thus for early testing purposes only.

Go Gremlin Language Variant

Apache TinkerPop™ is a graph computing framework for both graph databases (OLTP) and graph analytic systems (OLAP). Gremlin is the graph traversal language of TinkerPop. It can be described as a functional, data-flow language that enables users to succinctly express complex traversals on (or queries of) their application's property graph.

Gremlin-Go implements Gremlin within the Go language and can be used on any Go runtime greater than v1.21. One important difference between Go and Java is that the functions are capitalized, as is required to export functions is Go.

Gremlin-Go is designed to connect to a "server" that is hosting a TinkerPop-enabled graph system. That "server" could be Gremlin Server or a remote Gremlin provider that exposes protocols by which Gremlin-Go can connect.

Once "g" has been created using a connection, it is then possible to start writing Gremlin traversals to query the remote graph:

package main

import (
	"fmt"
	"github.com/apache/tinkerpop/gremlin-go/v3/driver"
)

func main() {
	// Creating the connection to the server with default settings.
	driverRemoteConnection, err := gremlingo.NewDriverRemoteConnection("ws://localhost:8182/gremlin")
	// Handle error
	if err != nil {
		fmt.Println(err)
		return
	}
	// Cleanup
	defer driverRemoteConnection.Close()

	// Create an anonymous traversal source with remote
	g := gremlingo.Traversal_().WithRemote(driverRemoteConnection)

	// Add a vertex with properties to the graph with the terminal step Iterate()
	promise := g.AddV("gremlin").Property("language", "go").Iterate()

	// The returned promised is a go channel to wait for all submitted steps to finish execution and return error.
	err = <-promise
	if err != nil {
		fmt.Println(err)
		return
	}

	// Get the value of the property
	result, err := g.V().HasLabel("gremlin").Values("language").ToList()
	if err != nil {
		fmt.Println(err)
		return
	}
	// Print the result
	for _, r := range result {
		fmt.Println(r.GetString())
	}
}

Sample Traversals

The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that cover a wide body of features. Traversal in Go is very similar to other GLV, with the exception that all step functions are capitalized.

Anonymous traversal __ replaced with T__ due to Go limitations.

Anything in the package when referenced needs the prefix gremlingo like gremlingo.Desc.

Create Vertex

Adding a vertex with properties.

promise := g.AddV("gremlin").Property("language", "go").Iterate()
// Wait for all steps to finish execution and check for error.
err := <-promise
if err != nil {
    fmt.Println(err)
    return
}

Find Vertices

Getting the property value associated with the added vertex. We currently only support ToList() for submitting the remote traversal. Support for Next() will be implemented in the subsequent milestones.

result, err := g.V().HasLabel("gremlin").Values("language").ToList()
// Handle error
if err != nil {
    fmt.Println(err)
    return
}
// Print result
for _, r := range result {
    fmt.Println(r.GetString())
}

Update Vertex

Updating vertex by adding another property to it.

promise := g.AddV("gremlin").Property("language", "go").Iterate()
// Wait for all steps to finish execution and check for error.
err := <-promise
if err != nil {
    fmt.Println(err)
    return
}

Filtering and sorting

results, err := g.V().HasLabel("person").Has("age", gremlingo.T__.Is(gremlingo.P.Gt(30))).Order().By("age", gremlingo.Order.Desc).ToList()

Or with aliases

results, err := g.V().HasLabel("person").Has("age", __.Is(gt(30))).Order().By("age", order.Desc).ToList()

List of all exports can be found at pkg.go.dev

Supported Data Types

The Go driver supports all of the core GraphBinary data types.

More

For information on Installation, Connection Usage, Developer Documentation and more, visit the driver docs