github.com/vescale/zgraph@v0.0.0-20230410094002-959c02d50f95/README.md (about)

     1  # What is zGraph
     2  [![Go Reference](https://pkg.go.dev/badge/github.com/vescale/zgraph.svg)](https://pkg.go.dev/github.com/vescale/zgraph)
     3  [![GitHub Actions](https://github.com/vescale/zgraph/workflows/Check/badge.svg)](https://github.com/vescale/zgraph/actions?query=workflow%3ACheck)
     4  
     5  zGraph is a [PGQL](https://pgql-lang.org/)-compatible embeddable graph database for large-scale vertices. 
     6  You can find the specification [here](https://pgql-lang.org/spec/1.5/).
     7  
     8  ## Installation
     9  
    10  ```bash
    11  go get -u github.com/vescale/zgraph
    12  ```
    13  
    14  ## Quick Start
    15  
    16  ### Playground
    17  
    18  ```bash
    19  > make build
    20  > ./bin/zgraph play
    21  ```
    22  
    23  ### Build Application
    24  zGraph implements driver for [database/sql](https://golang.org/pkg/database/sql/). To use zGraph, you can simply import zGraph package and use `zgraph` as the driver name in `sql.Open`.
    25  
    26  Here is an example of how to use create a graph and query it. The graph is an example in [PGQL specification](https://pgql-lang.org/spec/1.5/#edge-patterns).
    27  
    28  ```go
    29  package main
    30  
    31  import (
    32  	"context"
    33  	"database/sql"
    34  	"fmt"
    35  	"log"
    36  
    37  	_ "github.com/vescale/zgraph"
    38  )
    39  
    40  func main() {
    41  	db, err := sql.Open("zgraph", "test.db")
    42  	if err != nil {
    43  		log.Fatal(err)
    44  	}
    45  	defer db.Close()
    46  
    47  	ctx, cancel := context.WithCancel(context.Background())
    48  	defer cancel()
    49  
    50  	conn, err := db.Conn(ctx)
    51  	if err != nil {
    52  		log.Fatal(err)
    53  	}
    54  
    55  	// Create a graph.
    56  	mustExec(ctx, conn, "CREATE GRAPH student_network")
    57  
    58  	// Change the current graph.
    59  	mustExec(ctx, conn, "USE student_network")
    60  
    61  	// Create labels.
    62  	mustExec(ctx, conn, "CREATE LABEL Person")
    63  	mustExec(ctx, conn, "CREATE LABEL University")
    64  	mustExec(ctx, conn, "CREATE LABEL knows")
    65  	mustExec(ctx, conn, "CREATE LABEL studentOf")
    66  
    67  	// Create vertices.
    68  	mustExec(ctx, conn, `INSERT VERTEX x LABELS (Person) PROPERTIES (x.name = 'Kathrine', x.dob = DATE '1994-01-15')`)
    69  	mustExec(ctx, conn, `INSERT VERTEX x LABELS (Person) PROPERTIES (x.name = 'Riya', x.dob = DATE '1995-03-20')`)
    70  	mustExec(ctx, conn, `INSERT VERTEX x LABELS (Person) PROPERTIES (x.name = 'Lee', x.dob = DATE '1996-01-20')`)
    71  	mustExec(ctx, conn, `INSERT VERTEX x LABELS (University) PROPERTIES (x.name = 'UC Berkeley')`)
    72  
    73  	// Create edges.
    74  	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'`)
    75  	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'`)
    76  	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'`)
    77  	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'`)
    78  	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'`)
    79  	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'`)
    80  
    81  	// Query the graph.
    82  	rows, err := conn.QueryContext(ctx, "SELECT a.name AS a, b.name AS b FROM MATCH (a:Person) -[e:knows]-> (b:Person)")
    83  	if err != nil {
    84  		log.Fatal(err)
    85  	}
    86  	var a, b string
    87  	for rows.Next() {
    88  		if err := rows.Scan(&a, &b); err != nil {
    89  			log.Fatal(err)
    90  		}
    91  		fmt.Printf("'%s' knows '%s'\n", a, b)
    92  	}
    93  }
    94  
    95  func mustExec(ctx context.Context, conn *sql.Conn, query string) {
    96  	_, err := conn.ExecContext(ctx, query)
    97  	if err != nil {
    98  		log.Fatal(err)
    99  	}
   100  }
   101  ```
   102  
   103  ## Contributing
   104  
   105  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.
   106  
   107  ## License
   108  
   109  zGraph is licensed under the Apache 2.0 license. See [LICENSE](LICENSE) for the full license text.