arturolang/grafito

Portable, Serverless & Lightweight
SQLite-based Graph Database

---

• At A Glance
• Try Grafito
  • Docker
  • Installation
    • As a Library
    • As a Standalone tool
• How To
  • Create a simple Node
  • Create Relationships between Nodes
  • Search Nodes
  • Delete an existing Node
  • Delete an existing Relationship
  • More complex queries
    • Using filters
  • Preview a Set of Nodes
• Command Reference
  • put
  • unput
  • link
  • unlink
  • what
  • fetch
  • preview
• Filter Reference
  • contains
  • less
  • greater
  • lessOrEqual
  • greaterOrEqual
  • not
  • in
• Community
• License

---

At A Glance

I know you really don't care about long explanations and want to have a look at working code right away, so... here you are (this is the code the creates the graph in the image above):

red
;---------------------------------------------
; Import Grafito
; and ... let's rock'n'roll! :)
;---------------------------------------------
do.import {grafito.art}

do [
    ;---------------------------------------------
    ; Set up a new graph environment
    ; with a local database named "sample4"
    ;---------------------------------------------
    graph.create "sample4" [

        ;---------------------------------------------
        ; Populate the database
        ;---------------------------------------------

        uk: put'country [name: "United Kingdom"]
        au: put'country [name: "Australia"]
        us: put'country [name: "United States"] 
        ca: put'country [name: "Canada"]

        nolan:    put'person [name: "Christopher Nolan" birthday: 1970 sex: "m"]
        pearce:   put'person [name: "Guy Pearce" birthday: 1967 sex: "m"]
        hanson:   put'person [name: "Curtis Hanson" birthday: 1945 sex: "m"]
        spacey:   put'person [name: "Kevin Spacey" birthday: 1959 sex: "m"]
        dicaprio: put'person [name: "Leonardo DiCaprio" birthday: 1974 sex: "m"]
        moss:     put'person [name: "Carrie-Ann Moss" birthday: 1967 sex: "f"]

        wach1: put'person [name: "Lana Wachowski" birthday: 1965 sex: "f"]
        wach2: put'person [name: "Lilly Wachowski" birthday: 1967 sex: "f"]

        memento:         put'movie [title: "Memento" year: 2000]
        inception:       put'movie [title: "Inception" year: 2010]
        laconfidential:  put'movie [title: "L.A. Confidential" year: 1997]
        matrix:          put'movie [title: "The Matrix" year: 1999]

        ;---------------------------------------------
        ; Define the relationships
        ; between our nodes
        ;---------------------------------------------

        link'isFrom nolan uk
        link'isFrom pearce au
        link'isFrom @[hanson spacey dicaprio wach1 wach2] us
        link'isFrom moss ca

        link'directed nolan @[memento inception]
        link'directed hanson laconfidential
        link'directed @[wach1 wach2] matrix

        link'actedIn pearce @[memento laconfidential]
        link'actedIn spacey laconfidential
        link'actedIn dicaprio inception
        link'actedIn moss @[memento matrix]

        ;---------------------------------------------
        ; Fetch every "person" &
        ; open the Desktop app for visualization
        ;---------------------------------------------
        
        preview fetch 'person ø
    ]
]

Try Grafito!

Docker

The easiest way to try Grafito is using Docker (although, without support for the Desktop app - yet)

docker run -it arturolang/grafito

or, if you want to run a specific script:

docker run -it -v $(pwd):/home arturolang/grafito <yourscript>

Installation

To install local, first you have to have installed the latest version of https://github.com/arturo-lang/arturo.

Then, just clone this repo and simply go to the folder via your terminal.

As a Library

After having installed the latest version of Arturo, you can use Grafito from any Arturo script as a library.

For example, here's how you run one of the included examples:

arturo examples/sample3.art

As a Standalone tool

Of course, you can also run Grafito as a tool on it own:

./grafito.art <database>

(If you pass a name, it will use it as your database file. If not, the database will be in-memory)

And you can see your lightweight graph engine in action!

How To

Create a simple Node

red
graph.create "mygraph" [
	put'person [name: "John" sex: 'm]
]

Create Relationships between Nodes

red
graph.create "mygraph" [
	john: put'person [name: "John" sex: 'm]
	joan: put'person [name: "Joan" sex: 'f]

	link 'marriedTo john joan
]

Search Nodes

red
graph "mygraph" [
	inspect what'person [name: "Joan"]
]

Delete an existing Node

red
graph "mygraph" [
	unput what'person [name: "John"]
]

Delete an existing Relationship

red
graph "mygraph" [
	unlink'marriedTo what'person [name: "John"]
                         what'person [name: "Joan"]
]

More complex queries

red
graph "mygraph" [
	inspect fetch'person [
		sex: "m"
		marriedTo: what 'person [name: "Joan"]
	]
]

Using filters

red
graph "mygraph" [
	fetch'person [
		surname:"Doe"
		age: -> greater: 30
	]
]

Preview a Set of Nodes

red
graph "mygraph" [
	preview fetch 'person ø
]

(If you run the sample4 in the examples folder, you'll be a minimal movie database. Running the command preview will open up the Desktop app with the image you see above ;-))

Command Reference

All of the following commands must run within a graph environment. In order to set it up, use:

red
graph <database> [
	;; your code goes here
]

⚠️ The graph command is not needed when you run Grafito as a tool, since the "environment" is already set up for you. ;-)

If you pass null (or ø) then the database will be in-memory. If you want to save to a file on disk, then pass a string with the desired database name. If the database already exists, it will be re-opened. If not, it will be created from scratch.

💡 You may force the database to be re-created from scratch, regardless of whether it exists, by setting the .create attribute. E.g.

graph.create "mygraph" [
	;; your code goes here
]

put

Description

Create a new node of given type and with given properties.

Usage

put type :literal
    properties :dictionary

Returns

• :dictionary (node)

Examples

red
put 'person [name: "John" surname: "Doe" birthday: 1986]

unput

Description

Delete given node

Usage

unput node :dictionary

Examples

red
x: put 'person [name: "John" surname: "Doe" birthday: 1986]
unput x

link

Description

Create a new relationship of given type between given nodes.

Usage

link type :literal
     source :dictionary (node), :block of :dictionary (node)
     target :dictionary (node), :block of :dictionary (node)

Returns

• :dictionary (edge)

Examples

red
link 'marriedTo put 'person [name: "John" surname: "Doe" birthday: 1986] 
                put 'person [name: "Mary" surname: "Doe" birthday: 1986]

unlink

Description

Delete given relationship between given nodes.

Usage

unlink type :literal
       source :dictionary (node)
       target :dictionary (node)

Examples

red
x: put 'person [name: "John" surname: "Doe" birthday: 1986]
y: put 'person [name: "Mary" surname: "Doe" birthday: 1986]

link 'marriedTo x y
unlink 'marriedTo x y

what

Description

Get the first node of given type, that satisfies all of given properties and/or relationships.

Usage

what type :literal
     properties :block :dictionary :null

Returns

• :dictionary (node)

Examples

red
print what 'person [name: "John"]

fetch

Description

Get all nodes of given type, that satisfy all of given properties and/or relationships.

Usage

fetch type :literal
      properties :block :dictionary :null

Returns

• :block of :dictionary (node)

Examples

red
print fetch 'person [surname: "Doe"]
print fetch 'person [
	surname: "Doe"
	marriedTo: what'person [name: "Mary"]
]

preview

Description

Preview given array of nodes in Desktop app.

Usage

preview nodes :block

Examples

red
preview fetch 'person [surname: "Doe"]

Filter Reference

When querying - e.g. with fetch or what - you can search for results, not only for exact matches, but also using one of the filters below.

red
fetch'person [
	surname: "Doe" 	; here, we are looking for an exact match
			; that is: people with the surname Doe
]

red
fetch'person [
	surname: [
		contains: "D"	; here, we are using the 'contains filter
			        ; that is: people whose surname contains the letter D
	]
]

(The above, using Arturo's powerful syntax, could also be written like:

red
fetch'person [ surname: -> contains: "D" ]

contains

Get rows that contain the given text.

less

Get rows with a numeric value less than the given one.

greater

Get rows with a numeric value greater than the given one.

lessOrEqual

Get rows with a numeric value less than or equal to the given one.

greaterOrEqual

Get rows with a numeric value greater than or equal to the given one.

not

Get rows with a value not equal to the given one (or block of given values).

in

Get rows with a numeric value equal to one of those in the given block.

Community

In case you want to ask a question, suggest an idea, or practically anything related to Grafito (or Arturo) - feel free! Everything and everyone is welcome.

For that, the most convenient place for me would be the https://github.com/arturo-lang/grafito/issues page.

![Stargazers over time]([***]

License

MIT License

Copyright (c) 2021 Yanis Zafirópulos

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.