Skip to content
A Go package built to communicate with Apache TinkerPop™ Graph computing framework using Gremlin; a graph traversal language used by graph databases such as JanusGraph®, MS Cosmos DB, AWS Neptune, and DataStax® Enterprise Graph.
Go Shell
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets Last minute touches to clean up Grammes Jan 17, 2019
docs Exported diagrams as PNG files in docs/ Mar 28, 2019
examples updated examples to work with new changes Mar 28, 2019
gremconnect Linting through Grammes Feb 4, 2019
gremerror Added descriptions of every package in the grammes repository Jan 18, 2019
logging Named interface parameters and returns for easy clarification Jan 25, 2019
manager Switched from []byte res to [][]byte for batching fix Mar 28, 2019
model Switched from []byte res to [][]byte for batching fix Mar 28, 2019
query Fixed tests to pass with new go version Mar 28, 2019
quick Switched from []byte res to [][]byte for batching fix Mar 28, 2019
scripts Adding baseline of Grammes to new repo. Jan 13, 2019
testing Added descriptions of every package in the grammes repository Jan 18, 2019
.gitignore Added gitignore and removed dupe contribute Jan 13, 2019
.travis.yml Updated tests to run in parallel and CI pipeline to test for data races Jan 25, 2019
CONTRIBUTING.md Updated examples Jan 25, 2019
LICENSE Initial commit Jan 11, 2019
README.md Updated README to include testing instructions and new go version Mar 28, 2019
client.go Removed response Mutex and now relying on sync Map fully Mar 28, 2019
client_test.go Updated tests to run in parallel and CI pipeline to test for data races Jan 25, 2019
configuration.go Updated dialer to use time.Duration rather than ints for seconds Jan 18, 2019
configuration_test.go Updated tests to run in parallel and CI pipeline to test for data races Jan 25, 2019
connection.go Adding baseline of Grammes to new repo. Jan 13, 2019
connection_test.go Updated tests to run in parallel and CI pipeline to test for data races Jan 25, 2019
go.mod Updated versions used in Grammes for dependencies Mar 28, 2019
go.sum Updated versions used in Grammes for dependencies Mar 28, 2019
grammes.go Updated grammes main package documentation Mar 28, 2019
grammes_test.go Updated examples Jan 25, 2019
model.go Removed Localhost global variable due to security threats relating it Mar 28, 2019
request.go Switched from []byte res to [][]byte for batching fix Mar 28, 2019
request_test.go Updated tests to run in parallel and CI pipeline to test for data races Jan 25, 2019
response.go Switched from []byte res to [][]byte for batching fix Mar 28, 2019
response_test.go Added Chris' tests Jan 25, 2019
testing.go Added Chris' tests Jan 25, 2019
traversal.go Updated how traversal objects append strings to be thread safe Feb 5, 2019
traversal_test.go Updated traversal test to pass Feb 5, 2019

README.md

Grammes

Grammes

Build Status Coverage Status GoDoc Go Report Card

Grammes is an API/Wrapper for Gremlin and Janusgraph. It's written purely in Golang and allows for easy use of Gremlin without touching the Gremlin terminal.

Table of Contents

Local Setup

You need to setup all of the following tools to run the service locally

  • Go 1.12
  • Git
  • Elastic Search
  • Cassandra
    • Java 8

Cloning Grammes

Begin by opening up a terminal or command prompt and clone the grammes repository.

go get -u github.com/northwesternmutual/grammes

Setting up JanusGraph

if you have decided to use another graph database then you may move on to project setup

First off, direct your terminal to the Grammes' scripts directory.

cd $GOPATH/src/github.com/northwesternmutual/grammes/scripts

In here you can find the gremlin.sh and janusgraph.sh scripts. To set up JanusGraph just run the janusgraph.sh script.

./janusgraph.sh

This should download and/or begin the graph and TinkerPop server.

To make sure that everything is running try running gremlin.sh.

$ ./gremlin.sh
SLF4J: Class path contains multiple SLF4J bindings.
SLF4J: Found binding in [jar:file:/Users/<username>/projects/nm/gocode/src/github.com/northwesternmutual/grammes/bin/janusgraph-0.3.1-hadoop2/lib/slf4j-log4j12-1.7.12.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: Found binding in [jar:file:/Users/<username>/projects/nm/gocode/src/github.com/northwesternmutual/grammes/bin/janusgraph-0.3.1-hadoop2/lib/logback-classic-1.1.2.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
SLF4J: Actual binding is of type [org.slf4j.impl.Log4jLoggerFactory]
15:05:59 WARN  org.apache.hadoop.util.NativeCodeLoader  - Unable to load native-hadoop library for your platform... using builtin-java classes where applicable
gremlin>

Once Gremlin starts then you may begin by running this command.

gremlin> :remote connect tinkerpop.server conf/remote.yaml
===>Configured localhost/127.0.0.1:8182

If you see the message that Gremlin was configured to the localhost then quit Gremlin.

gremlin> :exit

Finally, run the janusgraph.sh script again, but this time with the status flag.

./janusgraph.sh status

Using Grammes

Once you have cloned the repository then you may begin implementing it into a project. Let's begin with creating a place for your code in the $GOPATH, i.e.,

$GOPATH/src/github.com/<username-here>/<project-name-here>

Next, you'll want to create a main.go file. For this example I will be using MS Code, but you may use any editor you prefer.

code main.go

In this file we can begin by making it a typical empty main.go file like this:

package main

func main() {
}

Next, import the grammes package and begin using it by connecting your client to a gremlin server.

package main

import (
    "log"

    "github.com/northwesternmutual/grammes"
)

func main() {
    // Creates a new client with the localhost IP.
    client, err := grammes.DialWithWebSocket("ws://127.0.0.1:8182")
    if err != nil {
        log.Fatalf("Error while creating client: %s\n", err.Error())
    }

    // Executing a basic query to assure that the client is working.
    res, err := client.ExecuteStringQuery("1+3")
    if err != nil {
        log.Fatalf("Querying error: %s\n", err.Error())
    }

    // Print out the result as a string
    log.Println(string(res))
}

Once the client is created then you can begin querying the gremlin server via the .ExecuteQuery method in the client. To use this function you must put in a Query which is an interface for any kind of Query-able type in the package. These include: graph.String and traversal.String. For an example of querying the gremlin server for all of the Vertex labels:

package main

import (
    "log"

    "github.com/northwesternmutual/grammes"
)

func main() {
    // Creates a new client with the localhost IP.
    client, err := grammes.DialWithWebSocket("ws://127.0.0.1:8182")
    if err != nil {
        log.Fatalf("Error while creating client: %s\n", err.Error())
    }

    // Executing a query to add a vertex to the graph.
    client.AddVertex("testingvertex")

    // Create a new traversal string to build your traverser.
    g := grammes.Traversal()

    // Executing a query to fetch all of the labels from the vertices.
    data, err := client.ExecuteQuery(g.V().Label())
    if err != nil {
        log.Fatalf("Querying error: %s\n", err.Error())
    }

    // Log out the response.
    log.Println(string(data))
}

After this is all written you may run this file by saving it and hopping back on to your terminal. After starting your Gremlin Server and graph database in the terminal let's run this command to run the file:

go run main.go

For more examples look in the examples/ directory of the project. In there you'll find multiple examples on how to use the Grammes package.

Testing Grammes

Grammes uses goconvey by smartystreets for its tests. Before trying to run the unit tests in Grammes you should update your version of this repository using this command.

go get -u github.com/smartystreets/goconvey/convey

Once you have this downloaded you may run the tests in Grammes how you normally would in Golang.

go test ./...

Additional Resources

Documentation on Gremlin

To learn more about how to use Gremlin I highly recommend looking through their Tinkerpop3 documentation. It's full of examples and documentation on every traversal step available.

Examples

To find examples look in the examples/ directory of Grammes. In there you'll find plenty of examples related to how to use this package. Make sure you're running Janusgraph before you begin running the examples.

Troubleshooting

Fixing time outs when starting Janusgraph

If Nodetool times out or any other part of the setup times out then the most common issue is that Cassandra is already running on your machine. To fix this run this command.

# only for Unix at the moment.
launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.cassandra.plist
You can’t perform that action at this time.