zgraph

README

What is zGraph

zGraph is a PGQL-compatible embeddable graph database for large-scale vertices. You can find the specification here.

Installation

go get -u github.com/vescale/zgraph

Quick Start

Playground

> make build
> ./bin/zgraph play

Build Application

zGraph implements driver for database/sql. To use zGraph, you can simply import zGraph package and use zgraph as the driver name in sql.Open.

Here is an example of how to use create a graph and query it. The graph is an example in PGQL specification.

package main

import (
	"context"
	"database/sql"
	"fmt"
	"log"

	_ "github.com/vescale/zgraph"
)

func main() {
	db, err := sql.Open("zgraph", "test.db")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	conn, err := db.Conn(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Create a graph.
	mustExec(ctx, conn, "CREATE GRAPH student_network")

	// Change the current graph.
	mustExec(ctx, conn, "USE student_network")

	// Create labels.
	mustExec(ctx, conn, "CREATE LABEL Person")
	mustExec(ctx, conn, "CREATE LABEL University")
	mustExec(ctx, conn, "CREATE LABEL knows")
	mustExec(ctx, conn, "CREATE LABEL studentOf")

	// Create vertices.
	mustExec(ctx, conn, `INSERT VERTEX x LABELS (Person) PROPERTIES (x.name = 'Kathrine', x.dob = DATE '1994-01-15')`)
	mustExec(ctx, conn, `INSERT VERTEX x LABELS (Person) PROPERTIES (x.name = 'Riya', x.dob = DATE '1995-03-20')`)
	mustExec(ctx, conn, `INSERT VERTEX x LABELS (Person) PROPERTIES (x.name = 'Lee', x.dob = DATE '1996-01-20')`)
	mustExec(ctx, conn, `INSERT VERTEX x LABELS (University) PROPERTIES (x.name = 'UC Berkeley')`)

	// Create edges.
	mustExec(ctx, conn, `INSERT EDGE e BETWEEN x AND y LABELS ( knows ) FROM MATCH (x), MATCH (y) WHERE x.name = 'Kathrine' AND y.name = 'Lee'`)
	mustExec(ctx, conn, `INSERT EDGE e BETWEEN x AND y LABELS ( knows ) FROM MATCH (x), MATCH (y) WHERE x.name = 'Kathrine' AND y.name = 'Riya'`)
	mustExec(ctx, conn, `INSERT EDGE e BETWEEN x AND y LABELS ( knows ) FROM MATCH (x), MATCH (y) WHERE x.name = 'Lee' AND y.name = 'Kathrine'`)
	mustExec(ctx, conn, `INSERT EDGE e BETWEEN x AND y LABELS ( studentOf ) FROM MATCH (x), MATCH (y) WHERE x.name = 'Kathrine' AND y.name = 'UC Berkeley'`)
	mustExec(ctx, conn, `INSERT EDGE e BETWEEN x AND y LABELS ( studentOf ) FROM MATCH (x), MATCH (y) WHERE x.name = 'Lee' AND y.name = 'UC Berkeley'`)
	mustExec(ctx, conn, `INSERT EDGE e BETWEEN x AND y LABELS ( studentOf ) FROM MATCH (x), MATCH (y) WHERE x.name = 'Riya' AND y.name = 'UC Berkeley'`)

	// Query the graph.
	rows, err := conn.QueryContext(ctx, "SELECT a.name AS a, b.name AS b FROM MATCH (a:Person) -[e:knows]-> (b:Person)")
	if err != nil {
		log.Fatal(err)
	}
	var a, b string
	for rows.Next() {
		if err := rows.Scan(&a, &b); err != nil {
			log.Fatal(err)
		}
		fmt.Printf("'%s' knows '%s'\n", a, b)
	}
}

func mustExec(ctx context.Context, conn *sql.Conn, query string) {
	_, err := conn.ExecContext(ctx, query)
	if err != nil {
		log.Fatal(err)
	}
}

Contributing

We welcome contributions from everyone. zGraph is in its early stages, if you have any ideas or suggestions, please feel free to open an issue or pull request.

License

zGraph is licensed under the Apache 2.0 license. See LICENSE for the full license text.

Documentation

Index

• type DB
  • func Open(dirname string, opt *Options) (*DB, error)
  • func (db *DB) Catalog() *catalog.Catalog
  • func (db *DB) Close() error
  • func (db *DB) NewSession() *session.Session
  • func (db *DB) Store() kv.Storage
• type Driver
  • func (d *Driver) Open(_ string) (driver.Conn, error)
  • func (d *Driver) OpenConnector(dsn string) (driver.Connector, error)
• type Options
  • func (opt *Options) SetDefaults()

Types

type DB

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

DB represents the zGraph database instance.

func Open

func Open(dirname string, opt *Options) (*DB, error)

Open opens a zGraph database instance with specified directory name.

func (*DB) Catalog

func (db *DB) Catalog() *catalog.Catalog

Catalog returns the catalog object.

func (*DB) Close

func (db *DB) Close() error

Close destroys the zGraph database instances and all sessions will be terminated.

func (*DB) NewSession

func (db *DB) NewSession() *session.Session

NewSession returns a new session.

func (*DB) Store

func (db *DB) Store() kv.Storage

Store returns the storage engine object.

type Driver

type Driver struct{}

func (*Driver) Open

func (d *Driver) Open(_ string) (driver.Conn, error)

func (*Driver) OpenConnector

func (d *Driver) OpenConnector(dsn string) (driver.Connector, error)

type Options

type Options struct {
	// Concurrency is used to limit the max concurrent sessions count. The NewSession
	// method will block if the current alive sessions count reach this limitation.
	Concurrency int64
}

Options contains some options which is used to customize the zGraph database instance while instantiating zGraph.

func (*Options) SetDefaults

func (opt *Options) SetDefaults()

SetDefaults sets the missing options into default value.