• Stars
    star
    215
  • Rank 183,925 (Top 4 %)
  • Language
    Python
  • License
    Apache License 2.0
  • Created almost 4 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

GQLAlchemy is a library developed with the purpose of assisting in writing and running queries on Memgraph. GQLAlchemy supports high-level connection to Memgraph as well as modular query builder.

GQLAlchemy

Code style: black

GQLAlchemy is a fully open-source Python library and Object Graph Mapper (OGM) - a link between graph database objects and Python objects.

An Object Graph Mapper or OGM provides a developer-friendly workflow that allows for writing object-oriented notation to communicate with graph databases. Instead of writing Cypher queries, you will be able to write object-oriented code, which the OGM will automatically translate into Cypher queries.

Installation

GQLAlchemy is built on top of Memgraph's low-level Python client pymgclient (PyPI / Documentation / GitHub).

To install GQLAlchemy, you first need to install pymgclient build prerequisites.

After you have installed the prerequisites, run the following command:

pip install gqlalchemy

With the above command, you get the basic GQLAlchemy capabilities. To add additional import/export capabilities, install GQLAlchemy with one of the following commands:

  • pip install gqlalchemy[arrow] # Support for the CSV, Parquet, ORC and IPC/Feather/Arrow formats

  • pip install gqlalchemy[dgl] # DGL support (includes PyTorch)

  • pip install gqlalchemy[all] # All of the above

If you intend to use GQLAlchemy with PyTorch Geometric support, that library must be installed manually:

pip install gqlalchemy[torch_pyg] # prerequisite
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -f https://data.pyg.org/whl/torch-1.13.0+cpu.html"

If you are using Conda for Python environment management, you can install GQLAlchemy through pip.

Build & Test

The project uses Poetry to build the library. Clone or download the GQLAlchemy source code locally and run the following command to build it from source with Poetry:

poetry install --all-extras

The poetry install --all-extras command installs GQLAlchemy with all extras (optional dependencies). Alternatively, you can use the -E option to define what extras to install:

poetry install # No extras

poetry install -E arrow # Support for the CSV, Parquet, ORC and IPC/Feather/Arrow formats
poetry install -E dgl # DGL support (also includes torch)

To run the tests, make sure you have an active Memgraph instance, and execute one of the following commands:

poetry run pytest . -k "not slow" # If all extras installed

poetry run pytest . -k "not slow and not extras" # Otherwise

If you’ve installed only certain extras, it’s also possible to run their associated tests:

poetry run pytest . -k "arrow"
poetry run pytest . -k "dgl"

GQLAlchemy capabilities

🗺️ Object graph mapper

Below you can see an example of how to create User and Language node classes, and a relationship class of type SPEAKS. Along with that, you can see how to create a new node and relationship and how to save them in the database. After that, you can load those nodes and relationship from the database.

from gqlalchemy import Memgraph, Node, Relationship, Field
from typing import Optional

db = Memgraph()

class User(Node, index=True, db=db):
    id: str = Field(index=True, exist=True, unique=True, db=db)

class Language(Node):
    name: str = Field(unique=True, db=db)

class Speaks(Relationship, type="SPEAKS"):
    pass

user = User(id="3", username="John").save(db)
language = Language(name="en").save(db)
speaks_rel = Speaks(
    _start_node_id = user._id,
    _end_node_id = language._id
).save(db)

loaded_user = User(id="3").load(db=db)
print(loaded_user)
loaded_speaks = Speaks(
        _start_node_id=user._id,
        _end_node_id=language._id
    ).load(db)
print(loaded_speaks)
🔨 Query builder
When building a Cypher query, you can use a set of methods that are wrappers around Cypher clauses.

from gqlalchemy import create, match
from gqlalchemy.query_builder import Operator

query_create = create()
        .node(labels="Person", name="Leslie")
        .to(relationship_type="FRIENDS_WITH")
        .node(labels="Person", name="Ron")
        .execute()

query_match = match()
        .node(labels="Person", variable="p1")
        .to()
        .node(labels="Person", variable="p2")
        .where(item="p1.name", operator=Operator.EQUAL, literal="Leslie")
        .return_(results=["p1", ("p2", "second")])
        .execute()
🚰 Manage streams

You can create and start Kafka or Pulsar stream using GQLAlchemy.

Kafka stream

from gqlalchemy import MemgraphKafkaStream

stream = MemgraphKafkaStream(name="ratings_stream", topics=["ratings"], transform="movielens.rating", bootstrap_servers="localhost:9093")
db.create_stream(stream)
db.start_stream(stream)

Pulsar stream

from gqlalchemy import MemgraphPulsarStream

stream = MemgraphPulsarStream(name="ratings_stream", topics=["ratings"], transform="movielens.rating", service_url="localhost:6650")
db.create_stream(stream)
db.start_stream(stream)
🗄️ Import table data from different sources

Import table data to a graph database

You can translate table data from a file to graph data and import it to Memgraph. Currently, we support reading of CSV, Parquet, ORC and IPC/Feather/Arrow file formats via the PyArrow package.

Read all about it in table to graph importer how-to guide.

Make a custom file system importer

If you want to read from a file system not currently supported by GQLAlchemy, or use a file type currently not readable, you can implement your own by extending abstract classes FileSystemHandler and DataLoader, respectively.

Read all about it in custom file system importer how-to guide.

⚙️ Manage Memgraph instances

You can start, stop, connect to and monitor Memgraph instances with GQLAlchemy.

Manage Memgraph Docker instance

from gqlalchemy.instance_runner import (
    DockerImage,
    MemgraphInstanceDocker
)

memgraph_instance = MemgraphInstanceDocker(
    docker_image=DockerImage.MEMGRAPH, docker_image_tag="latest", host="0.0.0.0", port=7687
)
memgraph = memgraph_instance.start_and_connect(restart=False)

memgraph.execute_and_fetch("RETURN 'Memgraph is running' AS result"))[0]["result"]

Manage Memgraph binary instance

from gqlalchemy.instance_runner import MemgraphInstanceBinary

memgraph_instance = MemgraphInstanceBinary(
    host="0.0.0.0", port=7698, binary_path="/usr/lib/memgraph/memgraph", user="memgraph"
)
memgraph = memgraph_instance.start_and_connect(restart=False)

memgraph.execute_and_fetch("RETURN 'Memgraph is running' AS result"))[0]["result"]
🔫 Manage database triggers

Because Memgraph supports database triggers on CREATE, UPDATE and DELETE operations, GQLAlchemy also implements a simple interface for maintaining these triggers.

from gqlalchemy import Memgraph, MemgraphTrigger
from gqlalchemy.models import (
    TriggerEventType,
    TriggerEventObject,
    TriggerExecutionPhase,
)

db = Memgraph()

trigger = MemgraphTrigger(
    name="ratings_trigger",
    event_type=TriggerEventType.CREATE,
    event_object=TriggerEventObject.NODE,
    execution_phase=TriggerExecutionPhase.AFTER,
    statement="UNWIND createdVertices AS node SET node.created_at = LocalDateTime()",
)

db.create_trigger(trigger)
triggers = db.get_triggers()
print(triggers)
💽 On-disk storage

Since Memgraph is an in-memory graph database, the GQLAlchemy library provides an on-disk storage solution for large properties not used in graph algorithms. This is useful when nodes or relationships have metadata that doesn’t need to be used in any of the graph algorithms that need to be carried out in Memgraph, but can be fetched after. Learn all about it in the on-disk storage how-to guide.


If you want to learn more about OGM, query builder, managing streams, importing data from different source, managing Memgraph instances, managing database triggers and using on-disk storage, check out the GQLAlchemy how-to guides.

Development (how to build)

poetry run flake8 .
poetry run black .
poetry run pytest . -k "not slow and not extras"

Documentation

The GQLAlchemy documentation is available on memgraph.com/docs/gqlalchemy.

The documentation can be generated by executing:

pip3 install pydoc-markdown
pydoc-markdown

License

Copyright (c) 2016-2022 Memgraph Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

More Repositories

1

memgraph

Open-source graph database, tuned for dynamic analytics environments. Easy to adopt, scale and own.
C++
2,280
star
2

odin

TypeScript
563
star
3

orb

Graph visualization library
TypeScript
343
star
4

mage

MAGE - Memgraph Advanced Graph Extensions 🔮
C++
250
star
5

example-streaming-app

An example repository on how to start building graph applications on streaming data. Just clone and start building 💻 💪
Rust
55
star
6

docs

The official documentation for Memgraph, Memgraph Lab, GQLAlchemy and MAGE
MDX
55
star
7

reddit-network-explorer

A graph-powered Reddit explorer that can perform real-time graph visualizations and sentiment analysis.
Python
48
star
8

mgconsole

mgconsole is a command-line interface (CLI) used to interact with Memgraph from any terminal or operating system.
C++
44
star
9

pymgclient

Python Memgraph Client
C
43
star
10

twitter-network-analysis

Analyzing a network of tweets and retweets using graph algorithms
JavaScript
41
star
11

spotify-song-recommender

A Spotify song recommendation engine built with the power of graph analytics.
Python
40
star
12

mgclient

C/C++ Memgraph Client
C++
39
star
13

rsmgclient

Memgraph database adapter for Rust programming language.
Rust
37
star
14

networkx-guide

We here are very big fans of NetworkX as a graph library and its comprehensive set of graph algorithms. For many though, working with NetworkX involves a steep learning curve. This guide is designed as an aid for beginners and experienced users to find specific tips and explore the world of complex networks.
JavaScript
34
star
15

data-streams

Publicly available real-time data sets on Kafka, Redpanda, RabbitMQ & Apache Pulsar
Python
30
star
16

bluej

C++
29
star
17

jupyter-memgraph-tutorials

Learn to use Memgraph and GQLAlchemy quickly with the help of Jupyter Notebooks
Jupyter Notebook
29
star
18

memgraph-academy

Jupyter Notebook
29
star
19

twitch-analytics-demo

Visualization of Twitch analytics.
JavaScript
28
star
20

bolt-proxy

Bolt protocol support for a Kubernetes cluster with authentication via Ingress
Go
24
star
21

cypher.vim

Vim syntax for the Cypher query language
Vim Script
23
star
22

slack-influence-bot

A slack bot that helps you understand and influence your slack community
Python
23
star
23

memgraph-platform

Memgraph Platform is a multi-container application containing Memgraph+MAGE and Memgraph Lab.
Shell
21
star
24

bitclout-visualizing-hodlers

Visualizing BitClout 🪙☁️ HODLers
Python
21
star
25

nodemgclient

Node.js Memgraph Client
C++
20
star
26

mgmigrate

mgmigrate is a tool for migrating data from MySQL or PostgreSQL to Memgraph and between Memgraph instances.
Cypher
20
star
27

protein-explorer

Visualizing protein-protein interaction networks
HTML
18
star
28

mgp

Pypi package used for type hinting when creating MAGE modules.
Python
17
star
29

physics-papers-recommender

Recommendation system used for blog post on physics papers recommendation system with node2vec
Python
17
star
30

graph-landscape-2022

A graph visualization of popular graph technologies and companies
Python
16
star
31

starlink

This project implements dynamic shortest-path routing for Starlink using Memgraph. Starlink satellites are low earth orbit communications satellites currently being launched and operated by SpaceX.
JavaScript
16
star
32

helm-charts

Helm charts for deploying Memgraph, an open-source in-memory graph database.
Smarty
14
star
33

card-fraud

Python app for detecting credit card frauds using a graph database
SCSS
14
star
34

rune

TypeScript
12
star
35

memgraph-rs

Rust
12
star
36

sng-demo

A Flask web application that displays a social network graph stored in Memgraph DB.
Python
10
star
37

documentation

The official documentation for Memgraph open-source graph database.
MDX
9
star
38

docs-recommendation-system

JavaScript
8
star
39

orbicon

Explore your userbase and community with the power of graph analytics.
Python
7
star
40

insurance-fraud

Insurance companies lose a lot of money on different kinds of fraud. By using graphs along with machine learning, you can model and detect fraudulent insurance claims.
Jupyter Notebook
7
star
41

bor

Python
6
star
42

jsmgclient

JavaScript
6
star
43

hacker-news-analyzer

TypeScript
5
star
44

link-prediction-node-embeddings

Python
5
star
45

app-challenge-starter-pack

A Python starter pack for building streaming applications with Memgraph.
Python
5
star
46

design

SCSS
4
star
47

MemFlights

Tutorial app using memgraph and C#
C#
4
star
48

mgui

Memgraph user interface library.
TypeScript
3
star
49

ecommerce-recommender-demo

E-Commerce recommender demo with real-time data and a graph database
Python
3
star
50

kafka-offset-demo

Demo showing how Kafka users can manually set the offset of the next consumed message with a call to the query procedure.
Python
3
star
51

benchgraph

TypeScript
2
star
52

genai-stack

A template for building GenAI applications with Memgraph.
Python
2
star
53

roadmap

Learn more about Memgraph product roadmap!
2
star
54

cugraph-guide

JavaScript
1
star
55

conference-connector

TypeScript
1
star
56

depsy

Code dependencies analyzer
Python
1
star
57

gasoline

A safe object-graph mapper and query builder for Rust.
1
star
58

blog

1
star
59

live-stream

C
1
star
60

kubernetes-operator

Memgraph Kubernetes Operator
Go
1
star
61

cloud-interview-task

TypeScript
1
star
62

cmake

This is a collection of CMake modules that are useful for all Memgraph projects.
CMake
1
star
63

mgcxx

Rust
1
star
64

prometheus-exporter

Python
1
star