dga

README

dgraph-access

This is a helper package to work with github.com/dgraph-io/dgo (v2), a Go client for accessing a DGraph cluster. See the example folder for a complete program.

status

This package is under heavy development; the API and scope may change before a v1.0.0 release.

usage

import (
    dga "github.com/emicklei/dgraph-access"
)

example

See documented code examples

See example

© 2019, ernestmicklei.com. MIT License. Contributions welcome.

Documentation

Overview

Package dga is a helper package to work with `github.com/dgraph-io/dgo` (v2), a Go client for accessing a DGraph cluster.

Index

• Constants
• Variables
• type DGraphAccess
  • func NewDGraphAccess(client *dgo.Dgraph) *DGraphAccess
  • func (d *DGraphAccess) AlterSchema(source string) error
  • func (d *DGraphAccess) CommitTransaction() error
  • func (d *DGraphAccess) CreateEdge(subject HasUID, predicate string, object interface{}) error
  • func (d *DGraphAccess) CreateEdgeWithFacets(subject HasUID, predicate string, object interface{}, ...) error
  • func (d *DGraphAccess) CreateNode(node HasUID) error
  • func (d *DGraphAccess) DiscardTransaction() error
  • func (d *DGraphAccess) FindEquals(result interface{}, predicateName, value string, literalPredicates ...string) error
  • func (d *DGraphAccess) ForReadOnly(ctx context.Context) *DGraphAccess
  • func (d *DGraphAccess) ForReadWrite(ctx context.Context) *DGraphAccess
  • func (d *DGraphAccess) InTransactionDo(ctx context.Context, do func(da *DGraphAccess) error) error
  • func (d *DGraphAccess) Upsert(query string, nQuads []NQuad) error
  • func (d *DGraphAccess) UpsertRequest(query string, nQuads []NQuad) *api.Request
  • func (d *DGraphAccess) WithTraceLogging() *DGraphAccess
• type DGraphTransaction
• type HasUID
• type Mutation
  • func (m Mutation) RDF() string
• type NQuad
  • func BlankNQuad(subjectName string, predicate string, object interface{}) NQuad
  • func (n NQuad) Bytes() []byte
  • func (n NQuad) RDF() string
  • func (n NQuad) WithFacet(key string, value interface{}) NQuad
  • func (n NQuad) WithStorageType(t RDFDatatype) NQuad
• type RDFDatatype
• type UID
  • func BlankUID(name string) UID
  • func FunctionUID(s string) UID
  • func IntegerUID(i int) UID
  • func NewUID(s string) UID
  • func StringUID(id string) UID
  • func (u UID) IsZero() bool
  • func (u UID) MarshalJSON() ([]byte, error)
  • func (u UID) RDF() string
  • func (u UID) String() string
  • func (u *UID) UnmarshalJSON(data []byte) error

Examples

• BlankNQuad
• BlankUID
• FunctionUID
• IntegerUID
• StringUID

Constants

const (
	// Star is used to model any predicate or any object in an NQuad.
	Star = "*"

	// DateTimeFormat is the format used by Dgraph for facet values of type dateTime.
	DateTimeFormat = "2006-01-02T15:04:05"

	// DgraphType is a reserved predicate name to refer to a type definition.
	DgraphType = "dgraph.type"
)

const (
	// RDFString is a RDF type
	RDFString   = RDFDatatype("<xs:string>")
	RDFDateTime = RDFDatatype("<xs:dateTime>")
	RDFDate     = RDFDatatype("<xs:date>")
	RDFInteger  = RDFDatatype("<xs:int>")
	RDFBoolean  = RDFDatatype("<xs:boolean>")
	RDFDouble   = RDFDatatype("<xs:double>")
	RDFFloat    = RDFDatatype("<xs:float>")
)

see https://docs.dgraph.io/mutations/#language-and-rdf-types

Variables

var (
	// ErrNoClient is a DGraphAccess state error
	ErrNoClient = errors.New("dgo client not initialized")

	// ErrNoTransaction is a DGraphAccess state error
	ErrNoTransaction = errors.New("dgo transaction not created")

	// ErrNoContext is a DGraphAccess state error
	ErrNoContext = errors.New("dgo transaction context not created")
)

var NoFacets map[string]interface{} = nil

NoFacets can be used in CreateEdge for passing no facets.

Types

type DGraphAccess

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

DGraphAccess is a decorator for a dgo.Client that holds a Context and Transaction to perform queries and mutations.

func NewDGraphAccess

func NewDGraphAccess(client *dgo.Dgraph) *DGraphAccess

NewDGraphAccess returns a new DGraphAccess using a client.

func (*DGraphAccess) AlterSchema

func (d *DGraphAccess) AlterSchema(source string) error

AlterSchema uses a schema definition to change the current DGraph schema. This operation is idempotent. Requires a DGraphAccess with a Write transaction.

func (*DGraphAccess) CommitTransaction

func (d *DGraphAccess) CommitTransaction() error

CommitTransaction completes the current transaction. Return an error if the DGraphAccess is in the wrong state or if the Commit fails. Requires a DGraphAccess with a Write transaction.

func (*DGraphAccess) CreateEdge

func (d *DGraphAccess) CreateEdge(subject HasUID, predicate string, object interface{}) error

CreateEdge creates a new Edge (using an NQuad). Return an error if the mutation fails. Requires a DGraphAccess with a Write transaction.

func (*DGraphAccess) CreateEdgeWithFacets

func (d *DGraphAccess) CreateEdgeWithFacets(subject HasUID, predicate string, object interface{}, facetsOrNil map[string]interface{}) error

CreateEdgeWithFacets creates a new Edge (using an NQuad) that has facets (can be nil or empty) Return an error if the mutation fails. Requires a DGraphAccess with a Write transaction.

func (*DGraphAccess) CreateNode

func (d *DGraphAccess) CreateNode(node HasUID) error

CreateNode creates a new Node . Return an error if the mutation fails. Requires a DGraphAccess with a Write transaction.

func (*DGraphAccess) DiscardTransaction

func (d *DGraphAccess) DiscardTransaction() error

DiscardTransaction aborts the current transaction (unless absent).

func (*DGraphAccess) FindEquals

func (d *DGraphAccess) FindEquals(result interface{}, predicateName, value string, literalPredicates ...string) error

FindEquals populates the result with the result of matching a predicate with a value and optionally fetching other literal predicates.

func (*DGraphAccess) ForReadOnly

func (d *DGraphAccess) ForReadOnly(ctx context.Context) *DGraphAccess

ForReadOnly returns a copy of DGraphAccess ready to perform read operations only.

func (*DGraphAccess) ForReadWrite

func (d *DGraphAccess) ForReadWrite(ctx context.Context) *DGraphAccess

ForReadWrite returns a copy of DGraphAccess ready to perform mutations.

func (*DGraphAccess) InTransactionDo

func (d *DGraphAccess) InTransactionDo(ctx context.Context, do func(da *DGraphAccess) error) error

InTransactionDo calls a function with a prepared DGraphAccess with a Write transaction. Return an error if the Commit fails.

func (*DGraphAccess) Upsert

func (d *DGraphAccess) Upsert(query string, nQuads []NQuad) error

Upsert runs a mutation if the query has no results. Requires a DGraphAccess with a Write transaction.

func (*DGraphAccess) UpsertRequest

func (d *DGraphAccess) UpsertRequest(query string, nQuads []NQuad) *api.Request

func (*DGraphAccess) WithTraceLogging

func (d *DGraphAccess) WithTraceLogging() *DGraphAccess

WithTraceLogging returns a copy of DGraphAccess that will trace parts of its internals.

type DGraphTransaction

type DGraphTransaction interface {
	Mutate(ctx context.Context, mu *api.Mutation) (*api.Response, error)
	Commit(ctx context.Context) error
	Discard(ctx context.Context) error
	Do(ctx context.Context, req *api.Request) (*api.Response, error)
	Query(ctx context.Context, q string) (*api.Response, error)
}

DGraphTransaction exists for testing. It has only the methods this package needs from a *dgo.Txn

type HasUID

type HasUID interface {
	SetUID(uid UID)
	GetUID() UID
}

HasUID is used in CreateNode to set the assigned UID to a typed value.

type Mutation

type Mutation struct {
	// set, delete
	Operation string
	//
	NQuads []NQuad
}

Mutation represents an action with multiple RDF Triples represented by NQuad values.

func (Mutation) RDF

func (m Mutation) RDF() string

RDF returns the string representation of the Mutation.

type NQuad

type NQuad struct {
	// Subject is the node for which the predicate must be created/modified.
	Subject UID

	// Predicate is a known schema predicate or a Star
	Predicate string

	// Object can be a primitive value or a UID or a Star (constant)
	Object interface{}

	// StorageType is used to optionally specify the type when storing the object
	// see https://docs.dgraph.io/mutations/#language-and-rdf-types
	// Example: dga.RDFString
	StorageType RDFDatatype

	// Maps to string, bool, int, float and dateTime.
	// For int and float, only 32-bit signed integers and 64-bit floats are accepted.
	Facets map[string]interface{}
}

NQuad represents an RDF S P O pair.

func BlankNQuad

func BlankNQuad(subjectName string, predicate string, object interface{}) NQuad

BlankNQuad returns an NQuad value with a Blank UID subject. Use BlankUID if you want the object also to be a Blank UID from a name.

Example

fmt.Println(BlankNQuad("subject", "predicate", 42).RDF())

Output:

_:subject <predicate> "42" .

func (NQuad) Bytes

func (n NQuad) Bytes() []byte

Bytes returns the mutation line.

func (NQuad) RDF

func (n NQuad) RDF() string

RDF returns the string version of its Bytes representation.

func (NQuad) WithFacet

func (n NQuad) WithFacet(key string, value interface{}) NQuad

WithFacet returns a copy with an additional facet (key=value).

func (NQuad) WithStorageType

func (n NQuad) WithStorageType(t RDFDatatype) NQuad

WithStorageType returns a copy with its StorageType set. Use DetectStorageType(any interface{})

type RDFDatatype

type RDFDatatype string

RDFDatatype is to set the StorageType of an NQuad.

type UID

type UID struct {
	// Str is exposed for JSON marshalling. Do not use it to read/write it directly.
	Str string
	// contains filtered or unexported fields
}

UID represents a DGraph uid which can be expressed using an integer,string or undefined value.

func BlankUID

func BlankUID(name string) UID

BlankUID returns an UID with an undefined uid and a local name only valid for one write transaction. .RDF() => _:name

Example

fmt.Println(BlankUID("canada").RDF())

Output:

_:canada

func FunctionUID

func FunctionUID(s string) UID

FunctionUID returns an UID calling the uid function on the argument. .RDF() => uid(s)

Example

fmt.Println(FunctionUID("v").RDF())

Output:

uid(v)

func IntegerUID

func IntegerUID(i int) UID

IntegerUID returns an UID using the integer value. .RDF() => <0x...>

Example

fmt.Println(IntegerUID(42).RDF())

Output:

<0x2a>

func NewUID

func NewUID(s string) UID

NewUID returns an UID that is printed as is. .RDF() => s

func StringUID

func StringUID(id string) UID

StringUID returns an UID using a string value for uid. .RDF() => <id>

Example

fmt.Println(StringUID("name").RDF())

Output:

<name>

func (UID) IsZero

func (u UID) IsZero() bool

IsZero returns whether this UID is a zero value

func (UID) MarshalJSON

func (u UID) MarshalJSON() ([]byte, error)

MarshalJSON is part of JSON

func (UID) RDF

func (u UID) RDF() string

RDF returns a string presentation for use in an NQuad.

func (UID) String

func (u UID) String() string

String is for debugging only

func (*UID) UnmarshalJSON

func (u *UID) UnmarshalJSON(data []byte) error

UnmarshalJSON is part of JSON