{"id":13397029,"url":"https://github.com/northwesternmutual/grammes","last_synced_at":"2026-02-25T09:05:36.966Z","repository":{"id":35002956,"uuid":"165282008","full_name":"northwesternmutual/grammes","owner":"northwesternmutual","description":"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.","archived":false,"fork":false,"pushed_at":"2024-05-27T04:36:27.000Z","size":23749,"stargazers_count":129,"open_issues_count":25,"forks_count":44,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-08-14T01:04:27.504Z","etag":null,"topics":["client","database","go","golang","graph","graph-database","gremlin","package","tinkerpop"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/northwesternmutual.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-11T17:22:58.000Z","updated_at":"2025-03-25T03:22:12.000Z","dependencies_parsed_at":"2024-01-15T22:42:51.311Z","dependency_job_id":"f466f44a-83f2-40d3-af9b-620f2d8474c1","html_url":"https://github.com/northwesternmutual/grammes","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/northwesternmutual/grammes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northwesternmutual%2Fgrammes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northwesternmutual%2Fgrammes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northwesternmutual%2Fgrammes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northwesternmutual%2Fgrammes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/northwesternmutual","download_url":"https://codeload.github.com/northwesternmutual/grammes/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northwesternmutual%2Fgrammes/sbom","scorecard":{"id":694565,"data":{"date":"2025-08-11","repo":{"name":"github.com/northwesternmutual/grammes","commit":"a0883ed30fe8f10f3c58ed9ff80849c029cf92c9"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.8,"checks":[{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":4,"reason":"Found 5/11 approved changesets -- score normalized to 4","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/build.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Pinned-Dependencies","score":1,"reason":"dependency not pinned by hash detected -- score normalized to 1","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/northwesternmutual/grammes/build.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/northwesternmutual/grammes/build.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/northwesternmutual/grammes/build.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/northwesternmutual/grammes/build.yml/master?enable=pin","Warn: downloadThenRun not pinned by hash: .github/workflows/build.yml:45","Info:   0 out of   4 GitHub-owned GitHubAction dependencies pinned","Info:   1 out of   1 goCommand dependencies pinned","Info:   0 out of   1 downloadThenRun dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Vulnerabilities","score":9,"reason":"1 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2020-0019 / GHSA-3xh2-74w9-5vxm"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 25 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-22T03:17:22.619Z","repository_id":35002956,"created_at":"2025-08-22T03:17:22.619Z","updated_at":"2025-08-22T03:17:22.619Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29815300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T05:36:42.804Z","status":"ssl_error","status_checked_at":"2026-02-25T05:36:31.934Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","database","go","golang","graph","graph-database","gremlin","package","tinkerpop"],"created_at":"2024-07-30T18:01:09.744Z","updated_at":"2026-02-25T09:05:36.933Z","avatar_url":"https://github.com/northwesternmutual.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/img/grammes-gopher-v4.png\" alt=\"Grammes\" title=\"Grammes\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n# Grammes\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://godoc.org/github.com/northwesternmutual/grammes\"\u003e\u003cimg src=\"https://godoc.org/github.com/northwesternmutual/grammes?status.svg\" alt=\"GoDoc\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/northwesternmutual/grammes/releases\"\u003e\u003cimg src=\"https://badgen.net/github/release/northwesternmutual/grammes\"\u003e\u003c/a\u003e\n\u003ca href=\"https://goreportcard.com/report/github.com/northwesternmutual/grammes\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/northwesternmutual/grammes\" alt=\"Go Report Card\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/northwesternmutual/grammes/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/northwesternmutual/grammes.svg\" alt=\"License\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/northwesternmutual/grammes/actions\"\u003e\u003cimg src=\"https://github.com/northwesternmutual/grammes/workflows/Build/badge.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nGrammes 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.\n\n## Table of Contents\n\n- [Grammes](#grammes)\n  - [Table of Contents](#table-of-contents)\n  - [Local Setup](#local-setup)\n    - [Cloning Grammes](#cloning-grammes)\n    - [Setting up JanusGraph](#setting-up-janusgraph)\n    - [Using Grammes](#using-grammes)\n  - [Testing Grammes](#testing-grammes)\n  - [Additional Resources](#additional-resources)\n    - [Documentation on Gremlin](#documentation-on-gremlin)\n    - [Examples](#examples)\n  - [Troubleshooting](#troubleshooting)\n    - [Fixing time outs when starting Janusgraph](#fixing-time-outs-when-starting-janusgraph)\n\n## Local Setup\n\nYou need to setup all of the following tools to run the service locally\n\n- Go 1.12\n- Git\n- Elastic Search\n- Cassandra\n  - Java 8\n\n---\n\n### Cloning Grammes\n\nBegin by opening up a terminal or command prompt and clone the grammes repository.\n\n```sh\ngo get -u github.com/northwesternmutual/grammes\n```\n\n---\n\n### Setting up JanusGraph\n\n*if you have decided to use another graph database then you may move on to [project setup](#using-grammes)*\n\nFirst off, direct your terminal to the Grammes' `scripts` directory.\n\n```sh\ncd $GOPATH/src/github.com/northwesternmutual/grammes/scripts\n```\n\nIn here you can find the `gremlin.sh` and `janusgraph.sh` scripts. To set up JanusGraph just run the `janusgraph.sh` script.\n\n```sh\n./janusgraph.sh\n```\n\nThis should download and/or begin the graph and TinkerPop server.\n\nTo make sure that everything is running try running `gremlin.sh`.\n\n```sh\n$ ./gremlin.sh\nSLF4J: Class path contains multiple SLF4J bindings.\nSLF4J: Found binding in [jar:file:/Users/\u003cusername\u003e/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]\nSLF4J: Found binding in [jar:file:/Users/\u003cusername\u003e/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]\nSLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.\nSLF4J: Actual binding is of type [org.slf4j.impl.Log4jLoggerFactory]\n15:05:59 WARN  org.apache.hadoop.util.NativeCodeLoader  - Unable to load native-hadoop library for your platform... using builtin-java classes where applicable\ngremlin\u003e\n```\n\nOnce Gremlin starts then you may begin by running this command.\n\n```sh\ngremlin\u003e :remote connect tinkerpop.server conf/remote.yaml\n===\u003eConfigured localhost/127.0.0.1:8182\n```\n\nIf you see the message that Gremlin was configured to the localhost then quit Gremlin.\n\n```sh\ngremlin\u003e :exit\n```\n\nFinally, run the `janusgraph.sh` script again, but this time with the `status` flag.\n\n```sh\n./janusgraph.sh status\n```\n\n---\n\n### Using Grammes\n\nOnce 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.,\n\n```sh\n$GOPATH/src/github.com/\u003cusername-here\u003e/\u003cproject-name-here\u003e\n```\n\nNext, you'll want to create a `main.go` file. For this example I will be using [MS Code](https://code.visualstudio.com/download), but you may use any editor you prefer.\n\n```sh\ncode main.go\n```\n\nIn this file we can begin by making it a typical empty `main.go` file like this:\n\n``` go\npackage main\n\nfunc main() {\n}\n```\n\nNext, import the grammes package and begin using it by connecting your client to a gremlin server.\n\n``` go\npackage main\n\nimport (\n    \"log\"\n\n    \"github.com/northwesternmutual/grammes\"\n)\n\nfunc main() {\n    // Creates a new client with the localhost IP.\n    client, err := grammes.DialWithWebSocket(\"ws://127.0.0.1:8182\")\n    if err != nil {\n        log.Fatalf(\"Error while creating client: %s\\n\", err.Error())\n    }\n\n    // Executing a basic query to assure that the client is working.\n    res, err := client.ExecuteStringQuery(\"1+3\")\n    if err != nil {\n        log.Fatalf(\"Querying error: %s\\n\", err.Error())\n    }\n\n    // Print out the result as a string\n    for _, r := range res {\n        log.Println(string(r))\n    }\n}\n```\n\nOnce 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:\n\n``` go\npackage main\n\nimport (\n    \"log\"\n\n    \"github.com/northwesternmutual/grammes\"\n)\n\nfunc main() {\n    // Creates a new client with the localhost IP.\n    client, err := grammes.DialWithWebSocket(\"ws://127.0.0.1:8182\")\n    if err != nil {\n        log.Fatalf(\"Error while creating client: %s\\n\", err.Error())\n    }\n\n    // Executing a query to add a vertex to the graph.\n    client.AddVertex(\"testingvertex\")\n\n    // Create a new traversal string to build your traverser.\n    g := grammes.Traversal()\n\n    // Executing a query to fetch all of the labels from the vertices.\n    res, err := client.ExecuteQuery(g.V().Label())\n    if err != nil {\n        log.Fatalf(\"Querying error: %s\\n\", err.Error())\n    }\n\n    // Log out the response.\n    for _, r := range res {\n        log.Println(string(r))\n    }\n}\n```\n\nAfter 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:\n\n```sh\ngo run main.go\n```\n\nFor more examples look in the `examples/` directory of the project. In there you'll find multiple examples on how to use the Grammes package.\n\n## Testing Grammes\n\nGrammes uses [goconvey](https://www.github.com/smartystreets/goconvey/) by [smartystreets](https://www.github.com/smartystreets/) for its tests. Before trying to run the unit tests in Grammes you should update your version of this repository using this command.\n\n```sh\ngo get -u github.com/smartystreets/goconvey/convey\n```\n\nOnce you have this downloaded you may run the tests in Grammes how you normally would in Golang.\n\n```sh\ngo test ./...\n```\n\n## Additional Resources\n\n### Documentation on Gremlin\n\nTo learn more about how to use Gremlin I highly recommend looking through their [Tinkerpop3 documentation](http://tinkerpop.apache.org/docs/current/reference/). It's full of examples and documentation on every traversal step available.\n\n### Examples\n\nTo 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.\n\n## Troubleshooting\n\n### Fixing time outs when starting Janusgraph\n\nIf 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.\n\n``` bash\n# only for Unix at the moment.\nlaunchctl unload ~/Library/LaunchAgents/homebrew.mxcl.cassandra.plist\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorthwesternmutual%2Fgrammes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnorthwesternmutual%2Fgrammes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorthwesternmutual%2Fgrammes/lists"}