gogm

README

Neo4j-go-ogm - A Neo4j Object Graph Mapping Library for Golang runtime

The main goal of Neo4j-go-ogm is to get developers up and running quickly without writing unnecessary boiler plate code. Using Go Tags, Go runtime structs can be annotated and mapped to Neo4j domain entities. This project was hugely inspired by the Java version of Neo4j OGM.

Quick start

go get -u github.com/codingfinest/neo4j-go-ogm

Set up domain entities

The setup below declares 3 node entities (Actor, Movie, Director) and 1 relelationship entity (Character) which relates an Actor to a Movie.

type Movie struct {
	gogm.Node `gogm:"label:FILM,label:PICTURE"`

	Title    string
	Released int64
	Tagline  string

	Characters []*Character `gogm:"direction:<-"`
	Directors  *Director  `gogm:"direction:<-"`
}

type Director struct {
	gogm.Node
	Name   string
	Movies []*Movie
}

type Actor struct {
	gogm.Node
	Name       string
	Characters []*Character
}

type Character struct {
	gogm.Relationship `gogm:"reltype:ACTED_IN"`

	Roles          []string
	Name           string
	NumberOfScenes int64
	Actor          *Actor `gogm:"startNode"`
	Movie          *Movie `gogm:"endNode"`
}

Relationships must be a pointer to a struct as can be seen in the Movie-Director relationship or a slice of pointer to struct as can be seen in Characters within Actor or Movie

Persist/Load entities

	var ogm = gogm.New("bolt://localhost:7687", "USERNAME", "PASSWORD", gogm.NONE)
	var session, err = ogm.NewSession(true)
	if err != nil {
		panic(err)
	}

	theMatrix := &Movie{}
	theMatrix.Title = "The Matrix"
	theMatrix.Released = 1999

	carrieAnne := &Actor{}
	carrieAnne.Name = "Carrie-Anne Moss"

	keanu := &Actor{}
	keanu.Name = "Keanu Reeves"

	carrieAnneMatrixCharacter := &Character{Movie: theMatrix, Actor: carrieAnne, Roles: []string{"Trinity"}}
	keanuReevesMatrixCharacter := &Character{Movie: theMatrix, Actor: keanu, Roles: []string{"Neo"}}

	theMatrix.Characters = append(theMatrix.Characters, carrieAnneMatrixCharacter, keanuReevesMatrixCharacter)

	//Persist the movie. This persists the actors as well and creates the relationships with their associated properties
	if err := session.Save(&theMatrix, nil); err != nil {
		panic(err)
	}

	var loadedMatrix *Movie
	if err := session.Load(&loadedMatrix, *theMatrix.ID, nil); err != nil {
		panic(err)
	}

	for _, character := range loadedMatrix.Characters {
		fmt.Println("Actor: " + character.Actor.Name)
	}

Features

• Save only deltas: Persist only modified changes.
• Node label inheritance: Labels can be inherited from embedded node struct
• Customizable node labels and relationship type: Don't like the default node label or relationship type ? Easily customize them with the label and reltype struct tags respectively.
• Runtime managed labels: Dynamically manage your node labels at runtime
• Transactions: Commit or Rollback changes made to runtime objects
• Rich Relationships: Add properties to relationships
• Persistence event: Intercept events during the lifecyle of a runtime object.
• Custom queries: Create custom queries to polulate runtime objects

Struct Tags

• id: Entity identifier. Only primitive types are supported. Unique constraint is created on this field.
• unique: Creates a unique constraint on this field.
• index: Creates an index on this field.
• label: Used to customize the node labels when tagged on the embedded gogm.Node struct or any embedded annonymous struct embedding gogm.Node. When used on a field with type []string, it identifies that field as the source of runtime manage labels.
• reltype: Used to customize relationship type. It should be tagged on gogm.Relationship for relationship entities or fields within nodes that relate to other nodes.
• name: Denotes the name to use in the database for the property associated with this field.
• direction: Indicates the direction of relationship. Possible values are <- for incoming, -- for undirected and -> for outgoing. When a direction isn't specified, default is ->.
• startNode: Denotes the start node of a relationship
• endNode: Denotes the end node of a relationship
• -: Ignore field

Reporting bugs

Thanks for trying out the package! Any bug found should be documented with specific reproducible conditions on the githib issue page.

Coming soon

• Load options Filters, Sort, Pagination etc

LICENSE

MIT

Documentation

Overview

Package gogm is a package for mapping go runtime objects to neo4j entities. MIT License

Copyright (c) 2020 codingfinest

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Index

• Constants
• type Config
• type DeleteOptions
• type Event
• type EventListener
• type Gogm
  • func New(config *Config) *Gogm
  • func (g *Gogm) NewSession(isWriteMode bool) (Session, error)
• type LoadOptions
  • func NewLoadOptions() *LoadOptions
• type LogLevel
• type Node
• type Object
• type Relationship
• type SaveOptions
  • func NewSaveOptions() *SaveOptions
• type Session

Constants

const (
	//CREATE is an event life cycle indicating creation of an object
	CREATE lifeCycle = iota

	//LOAD is an event life cycle indicating the load of an object
	LOAD

	//UPDATE is an event life cycle indicating the update of an object
	UPDATE

	//DELETE is an event life cycle indicating the delete of an object
	DELETE
)

const (
	NONE    LogLevel = 0
	ERROR            = 1
	WARNING          = 2
	INFO             = 3
	DEBUG            = 4
)

Types

type Config

type Config struct {
	URI            string
	Username       string
	Password       string
	LogLevel       LogLevel
	AllowCyclicRef bool
}

Config holds the OGM configuration

type DeleteOptions

type DeleteOptions struct {
}

DeleteOptions represents options used for saving database objects. Currently, not applicatble to this version of the OGM

type Event

type Event interface {
	GetObject() interface{}
	GetLifeCycle() lifeCycle
}

Event is fired on an object during one of the following life cycle CREATE, LOAD, UPDATE or DELETE

type EventListener

type EventListener interface {
	OnPreSave(event Event)
	OnPostSave(event Event)
	OnPostLoad(event Event)
	OnPreDelete(event Event)
	OnPostDelete(event Event)
}

EventListener listens for Events

type Gogm

type Gogm struct {
	// contains filtered or unexported fields
}

Gogm is an instance of the OGM

func New

func New(config *Config) *Gogm

New creates a new instance of the OGM

func (*Gogm) NewSession

func (g *Gogm) NewSession(isWriteMode bool) (Session, error)

NewSession creates a new session on an OGM instance

type LoadOptions

type LoadOptions struct {
	Depth int
}

LoadOptions represents options used for loading database objects

func NewLoadOptions

func NewLoadOptions() *LoadOptions

NewLoadOptions creates LoadOptions with defaults

type LogLevel

type LogLevel int

type Node

type Node struct {
	Object
}

Node is the base object for all domain Nodes

type Object

type Object struct {
	ID *int64 `json:"id"`
}

Object is the base object for all domain Nodes and Relationships

type Relationship

type Relationship struct {
	Object
}

Relationship is the base object for all domain Relationships

type SaveOptions

type SaveOptions struct {
	Depth int
}

SaveOptions represents options used for saving database objects

func NewSaveOptions

func NewSaveOptions() *SaveOptions

NewSaveOptions creates SaveOptions with defaults

type Session

type Session interface {
	Load(object interface{}, ID interface{}, loadOptions *LoadOptions) error
	LoadAll(objects interface{}, IDs interface{}, loadOptions *LoadOptions) error
	Reload(objects ...interface{}) error
	Save(objects interface{}, saveOptions *SaveOptions) error
	Delete(object interface{}) error
	DeleteAll(object interface{}, deleteOptions *DeleteOptions) error
	PurgeDatabase() error
	Clear() error
	BeginTransaction() (*transaction, error)
	GetTransaction() *transaction
	QueryForObject(object interface{}, cypher string, parameters map[string]interface{}) error
	QueryForObjects(objects interface{}, cypher string, parameters map[string]interface{}) error
	Query(cypher string, parameters map[string]interface{}, objects ...interface{}) ([]map[string]interface{}, error)
	CountEntitiesOfType(object interface{}) (int64, error)
	Count(cypher string, parameters map[string]interface{}) (int64, error)
	RegisterEventListener(EventListener) error
	DisposeEventListener(EventListener) error
}

Session provides access to the database