README
¶
ndgo 
ndgo provides dgraph dgo txn abstractions and helpers.
Why
- Reduce txn related boilerplate, thus making code more readable,
- Make using ratel like queries easier,
- Get query execution times the easy way, even for multi-query txns,
- Be low level - don't do magic, keep dgo things exposed for them to be usable, if necessary,
- No performance overhead compared to dgo, if possible.
Install
go get -u github.com/ppp225/ndgo
import (
"github.com/ppp225/ndgo/v5"
)
Common uses
Run transactions the same way one would do in ratel:
q := QueryDQL(fmt.Sprintf(`
{
%s(func: eq(%s, "%s")) {
uid
name
}
}
`, "favActor", "name", "Keanu Reeves"))
resp, err := q.Run(txn)
Or marshal structs:
jsonBytes, err := json.Marshal(myObj)
if err != nil {
return nil, err
}
resp, err := txn.Setb(jsonBytes, nil)
Or don't:
resp, err := txn.Seti(myObj, myObj2, myObj3)
Do Upserts:
q := `{ a as var(func: eq(name, "Keanu")) }`
myObj := personStruct{
UID: "uid(a)",
Type: "Person",
Name: "Keanu",
}
resp, err := txn.DoSeti(q, myObj)
See TestBasic and TestComplex and TestTxnUpsert in ndgo_test.go for a complete example.
ndgo.Txn
Create a transaction:
dg := NewDgraphClient()
txn := ndgo.NewTxn(ctx, dg.NewTxn()) // or dg.NewReadOnlyTxn(), you can use any available dgo.txn options. You can also use ndgo.NewTxnWithoutContext(txn)
defer txn.Discard()
...
err = txn.Commit()
Do mutations and queries:
resp, err := txn.Mutate(*api.Mutation)
resp, err := txn.Setb(jsonBytes, rdfBytes)
resp, err := txn.Seti(myObjs...)
resp, err := txn.Setnq(nquads)
resp, err := txn.Deleteb(jsonBytes, deleteRdfBytes)
resp, err := txn.Deletei(myObjs...)
resp, err := txn.Deletenq(nquads)
resp, err := txn.Query(queryString)
resp, err := txn.QueryWithVars(queryWithVarsString, vars...)
resp, err := txn.Do(req *api.Request)
resp, err := txn.DoSetb(queryString, jsonBytes)
resp, err := txn.DoSeti(queryString, myObjs...)
resp, err := txn.DoSetnq(queryString, nquads)
Get diagnostics:
dbms := txn.GetDatabaseTime()
nwms := txn.GetNetworkTime()
ndgo.Set/Delete JSON/RDF
Define and run txns through json, rdf or predefined helpers
Set:
set := ndgo.SetJSON(fmt.Sprintf(`
{
"name": "%s",
"age": "%s"
}`, "L", "25"))
// or
set := ndgo.SetRDF(`<_:new> <name> "L" .
<_:new> <age> "25" .`)
// or
set := ndgo.Query{}.SetPred("_:new", name, "L") +
ndgo.Query{}.SetPred("_:new", age, "25")
resp, err := set.Run(txn)
Delete:
del := ndgo.DeleteJSON(fmt.Sprintf(`
{
"uid": "%s"
}
`, uid))
// or
del := ndgo.Query{}.DeleteNode("0x420") +
ndgo.Query{}.DeleteEdge("0x420", "edgeName", "0x42") +
ndgo.Query{}.DeletePred("0x42", "name")
resp, err := del.Run(txn)
Query:
q := ndgo.QueryDQL(fmt.Sprintf(`
{
%s(func: eq(%s, "%s")) {
uid
}
}
`, "favActor", "name", "Keanu Reeves"))
response, err := q.Run(txn)
Join:
You can chain queries and JSON mutations with Join, RDF mutations with + operator, assuming they are the same type:
q1 := ndgo.QueryDQL(`{q1(func:eq(name,"a")){uid}})`
q2 := ndgo.QueryDQL(`{q2(func:eq(name,"b")){uid}})`
resp, err := q1.Join(q2).Run(txn)
Note that query blocks have to be named uniquely.
Other helpers
FlattenResp
Sometimes, when querying dgraph, we want just 1 resulting element, instead of a nested array.
// Instead of having this:
type Queries struct {
Q []struct {
UID string `json:"uid"`
} `json:"q"`
}
// We can have:
type MyObj struct {
UID string `json:"uid"`
}
resp, _ := ndgo.QueryDQL(`{q(func:uid(0x123)){uid}}`).Run(txn)
// query block name -------^ must be one letter and only one query block must be in the query for this helper to work!
var result MyObj
if err := json.Unmarshal(ndgo.Unsafe{}.FlattenRespToObject(resp.GetJson()), &result); err != nil {
panic(err) // will fail, if result has more than 1 element!
}
var resultSlice []MyObj
if err := json.Unmarshal(ndgo.Unsafe{}.FlattenRespToArray(resp.GetJson()), &resultSlice); err != nil {
panic(err) // will fail, if multiple query blocks are used in Query, but can have multiple results!
}
log.Print(result)
log.Print(resultSlice)
Future plans
- add more upsert things
Note
This project uses semantic versioning, see the changelog for details.
Documentation
¶
Overview ¶
Package ndgo <read iNDiGO> provides dgo abstractions and helpers - github.com/ppp225/ndgo
Index ¶
- func Debug()
- type DeleteJSON
- type DeleteRDF
- type Query
- func (Query) DeleteEdge(from, predicate, to string) DeleteRDF
- func (Query) DeleteNode(uid string) DeleteRDF
- func (Query) DeletePred(uid, predicate string) DeleteRDF
- func (Query) GetPredExpandType(blockID, fx, pred, val, funcParams, directives, dgPreds, dgTypes string) QueryDQL
- func (Query) GetUIDExpandType(blockID, fx, uid, funcParams, directives, dgPreds, dgTypes string) QueryDQL
- func (Query) SetEdge(from, predicate, to string) SetRDF
- func (Query) SetPred(uid, predicate, value string) SetRDF
- type QueryDQL
- type SetJSON
- type SetRDF
- type Txn
- func (v *Txn) Commit() (err error)
- func (v *Txn) Deleteb(json, rdf []byte) (resp *api.Response, err error)
- func (v *Txn) Deletei(jsonMutations ...interface{}) (resp *api.Response, err error)
- func (v *Txn) Deletenq(rdf string) (resp *api.Response, err error)
- func (v *Txn) Discard()
- func (v *Txn) Do(req *api.Request) (resp *api.Response, err error)
- func (v *Txn) DoSetb(query, cond string, json, rdf []byte) (resp *api.Response, err error)
- func (v *Txn) DoSeti(query string, jsonMutations ...interface{}) (resp *api.Response, err error)
- func (v *Txn) DoSetnq(query, nquads string) (resp *api.Response, err error)
- func (v *Txn) GetDatabaseTime() float64
- func (v *Txn) GetNetworkTime() float64
- func (v *Txn) Mutate(mu *api.Mutation) (resp *api.Response, err error)
- func (v *Txn) Query(q string) (resp *api.Response, err error)
- func (v *Txn) QueryWithVars(q string, vars map[string]string) (resp *api.Response, err error)
- func (v *Txn) Setb(json, rdf []byte) (resp *api.Response, err error)
- func (v *Txn) Seti(jsonMutations ...interface{}) (resp *api.Response, err error)
- func (v *Txn) Setnq(rdf string) (resp *api.Response, err error)
- type Unsafe
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type DeleteJSON ¶
type DeleteJSON string
DeleteJSON represents a dgraph delete mutation string with some methods defined
func (DeleteJSON) Join ¶
func (v DeleteJSON) Join(json DeleteJSON) DeleteJSON
Join allows to join multiple json Query of same type
type DeleteRDF ¶
type DeleteRDF string
DeleteRDF represents a dgraph delete rdf mutation string with some methods defined
type Query ¶
type Query struct{}
Query groups. Usage: ndgo.Query{}... It's recommended to create your own helpers, than to use the build in ones.
func (Query) DeleteEdge ¶
DeleteEdge Usage: _, err = ndgo.Query{}.DeleteEdge(parentUID, "edgeName", childUID).Run(txn)
func (Query) DeleteNode ¶
DeleteNode Usage: _, err = ndgo.Query{}.DeleteNode(UID).Run(txn)
func (Query) DeletePred ¶
DeletePred Usage: ndgo.Query{}.DeletePred(from, predicate)
func (Query) GetPredExpandType ¶
func (Query) GetPredExpandType(blockID, fx, pred, val, funcParams, directives, dgPreds, dgTypes string) QueryDQL
GetPredExpandType constructs a complete query. It's for convenience, so formatting can be done only once. Also one liner! Usage: resp, err := ndgo.Query{}.GetPredExpandType("q", "eq", predicate, value, ",first:1", "", "uid dgraph.type", dgTypes).Run(txn)
func (Query) GetUIDExpandType ¶
func (Query) GetUIDExpandType(blockID, fx, uid, funcParams, directives, dgPreds, dgTypes string) QueryDQL
GetUIDExpandType constructs a complete query. It's for convenience, so formatting can be done only once. Also one liner! Usage: resp, err := ndgo.Query{}.GetUIDExpandType("q", "uid", uid, "", "", "", "_all_").Run(txn)
type QueryDQL ¶
type QueryDQL string
QueryDQL represents a dgraph query string with some methods defined
type SetJSON ¶
type SetJSON string
SetJSON represents a dgraph set mutation string with some methods defined
type SetRDF ¶
type SetRDF string
SetRDF represents a dgraph set rdf mutation string with some methods defined
type Txn ¶
type Txn struct {
// contains filtered or unexported fields
}
Txn is a dgo.Txn wrapper with additional diagnostic data Helps with Queries, by providing abstractions for dgraph Query and Mutation
func NewTxnWithoutContext ¶
func NewTxnWithoutContext(txn *dgo.Txn) *Txn
NewTxnWithoutContext creates new Txn (without ctx)
func (*Txn) Deletei ¶
Deletei is equivalent to Deleteb, but it marshalls structs into one slice of mutations
func (*Txn) Discard ¶
func (v *Txn) Discard()
Discard cleans up dgo.Txn resources. Always defer this on creation.
func (*Txn) Do ¶
Do executes a query followed by one or more mutations. Possible to run query without mutations, or vice versa
func (*Txn) GetDatabaseTime ¶
GetDatabaseTime gets time txn spend in db
func (*Txn) GetNetworkTime ¶
GetNetworkTime gets total time until response
func (*Txn) QueryWithVars ¶
QueryWithVars performs dgraph query with vars
type Unsafe ¶
type Unsafe struct{}
Unsafe collects helpers, which require knowledge of how they work to operate correctly
func (Unsafe) FlattenRespToArray ¶
FlattenRespToArray flattens resp.GetJson() to only contain array without query block. i.e. transforms `{"q":[...]}` to `[...]`. QueryBlockID must be single letter. One QueryBlock supported, otherwise will return gibberish and unmarshal will error.
func (Unsafe) FlattenRespToObject ¶
FlattenRespToObject flattens resp.GetJson() to only contain a single object, without array or query block. i.e. transforms `{"q":[{...}]}` to `{...}`. QueryBlockID must be single letter. One QueryBlock supported. Response array should only have 0 or 1 object, otherwise will return gibberish and unmarshal will error.
Source Files