Overhaul documentation in Quick Start and Installation
Summary: This change should simplify the documentation by providing minimal descriptions and runnable commands to the user. A user should be able to follow the steps in Quick Start and have Memgraph working and executing queries. Installation has been merged into Quick Start and Docker details removed. Debian package installation is added. Configuration section has been removed since it is duplicated from the configuration file we ship and all of the details are unnecessary for basic users. A new chapter is added, Drivers. It is extracted from the original Quick Start so as not to clutter it. Additionally, C# example is now included. Reviewers: florijan, dgleich, buda, msantl Reviewed By: dgleich Differential Revision: https://phabricator.memgraph.io/D1005
This commit is contained in:
Teon Banek
parent
ba8a3f9e7b
commit
26aea646c7
@ -11,8 +11,8 @@ data structures, multi-version concurrency control and asynchronous IO.
|
||||
## Contents
|
||||
|
||||
* [About Memgraph](#about-memgraph)
|
||||
* [Installation](installation.md)
|
||||
* [Quick Start](quick-start.md)
|
||||
* [Drivers](drivers.md)
|
||||
* [Storable Data Types](data-types.md)
|
||||
* [openCypher Query Language](open-cypher.md)
|
||||
* [Upcoming Features](upcoming-features.md)
|
||||
|
||||
205
docs/user_technical/drivers.md
Normal file
205
docs/user_technical/drivers.md
Normal file
@ -0,0 +1,205 @@
|
||||
## Bolt Drivers
|
||||
|
||||
Clients connect to Memgraph using the
|
||||
[Bolt protocol](https://boltprotocol.org/). Bolt was designed for efficient
|
||||
communication with graph databases. Memgraph supports
|
||||
[Version 1](https://boltprotocol.org/v1/) of the protocol. Official Bolt
|
||||
protocol drivers are provided for multiple programming languages:
|
||||
|
||||
* [Java](https://github.com/neo4j/neo4j-java-driver)
|
||||
* [Python](https://github.com/neo4j/neo4j-python-driver)
|
||||
* [Javascript](https://github.com/neo4j/neo4j-javascript-driver)
|
||||
* [C#](https://github.com/neo4j/neo4j-dotnet-driver)
|
||||
|
||||
### Python Driver Example
|
||||
|
||||
Neo4j officially supports Python for interacting with an openCypher and Bolt
|
||||
compliant database. For details consult the
|
||||
[official documentation](http://neo4j.com/docs/api/python-driver) and the
|
||||
[GitHub project](https://github.com/neo4j/neo4j-python-driver). Following is
|
||||
a basic usage example:
|
||||
|
||||
```
|
||||
from neo4j.v1 import GraphDatabase, basic_auth
|
||||
|
||||
# Initialize and configure the driver.
|
||||
# * provide the correct URL where Memgraph is reachable;
|
||||
# * use an empty user name and password, and
|
||||
# * disable encryption (not supported).
|
||||
driver = GraphDatabase.driver("bolt://localhost:7687",
|
||||
auth=basic_auth("", ""),
|
||||
encrypted=False)
|
||||
|
||||
# Start a session in which queries are executed.
|
||||
session = driver.session()
|
||||
|
||||
# Execute openCypher queries.
|
||||
# After each query, call either `consume()` or `data()`
|
||||
session.run('CREATE (alice:Person {name: "Alice", age: 22})').consume()
|
||||
|
||||
# Get all the vertices from the database (potentially multiple rows).
|
||||
vertices = session.run('MATCH (n) RETURN n').data()
|
||||
# Assuming we started with an empty database, we should have Alice
|
||||
# as the only row in the results.
|
||||
only_row = vertices.pop()
|
||||
alice = only_row["n"]
|
||||
|
||||
# Print out what we retrieved.
|
||||
print("Found a vertex with labels '{}', name '{}' and age {}".format(
|
||||
alice['name'], alice.labels, alice['age'])
|
||||
|
||||
# Remove all the data from the database.
|
||||
session.run('MATCH (n) DETACH DELETE n').consume()
|
||||
|
||||
# Close the session and the driver.
|
||||
session.close()
|
||||
driver.close()
|
||||
```
|
||||
|
||||
### Java Driver Example
|
||||
|
||||
The details about Java driver can be found
|
||||
[on GitHub](https://github.com/neo4j/neo4j-java-driver).
|
||||
|
||||
The example below is equivalent to Python example. Major difference is that
|
||||
`Config` object has to be created before the driver construction. Encryption
|
||||
has to be disabled by calling `withoutEncryption` method against the `Config`
|
||||
builder.
|
||||
|
||||
```
|
||||
import org.neo4j.driver.v1.*;
|
||||
import org.neo4j.driver.v1.types.*;
|
||||
import static org.neo4j.driver.v1.Values.parameters;
|
||||
import java.util.*;
|
||||
|
||||
public class JavaQuickStart {
|
||||
public static void main(String[] args) {
|
||||
// Initialize driver.
|
||||
Config config = Config.build().withoutEncryption().toConfig();
|
||||
Driver driver = GraphDatabase.driver("bolt://localhost:7687",
|
||||
AuthTokens.basic("",""),
|
||||
config);
|
||||
// Execute basic queries.
|
||||
try (Session session = driver.session()) {
|
||||
StatementResult rs1 = session.run("MATCH (n) DETACH DELETE n");
|
||||
StatementResult rs2 = session.run(
|
||||
"CREATE (alice: Person {name: 'Alice', age: 22})");
|
||||
StatementResult rs3 = session.run( "MATCH (n) RETURN n");
|
||||
List<Record> records = rs3.list();
|
||||
Record record = records.get(0);
|
||||
Node node = record.get("n").asNode();
|
||||
System.out.println(node.get("name").asString());
|
||||
} catch (Exception e) {
|
||||
System.out.println(e);
|
||||
System.exit(1);
|
||||
}
|
||||
// Cleanup.
|
||||
driver.close();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Javascript Driver Example
|
||||
|
||||
The details about Javascript driver can be found
|
||||
[on GitHub](https://github.com/neo4j/neo4j-javascript-driver).
|
||||
|
||||
The Javascript example below is equivalent to Python and Java examples. SSL
|
||||
can be disabled by passing `{encrypted: 'ENCRYPTION_OFF'}` during the driver
|
||||
construction.
|
||||
|
||||
Here is an example related to `Node.js`. Memgraph doesn't have integrated
|
||||
support for `WebSocket` which is required during the execution in any web
|
||||
browser. If you want to run `openCypher` queries from a web browser,
|
||||
[websockify](https://github.com/novnc/websockify) has to be up and running.
|
||||
Requests from web browsers are wrapped into `WebSocket` messages, and a proxy
|
||||
is needed to handle the overhead. The proxy has to be configured to point out
|
||||
to Memgraph's Bolt port and web browser driver has to send requests to the
|
||||
proxy port.
|
||||
|
||||
```
|
||||
var neo4j = require('neo4j-driver').v1;
|
||||
var driver = neo4j.driver("bolt://localhost:7687",
|
||||
neo4j.auth.basic("neo4j", "1234"),
|
||||
{encrypted: 'ENCRYPTION_OFF'});
|
||||
var session = driver.session();
|
||||
|
||||
function die() {
|
||||
session.close();
|
||||
driver.close();
|
||||
}
|
||||
|
||||
function run_query(query, callback) {
|
||||
var run = session.run(query, {});
|
||||
run.then(callback).catch(function (error) {
|
||||
console.log(error);
|
||||
die();
|
||||
});
|
||||
}
|
||||
|
||||
run_query("MATCH (n) DETACH DELETE n", function (result) {
|
||||
console.log("Database cleared.");
|
||||
run_query("CREATE (alice: Person {name: 'Alice', age: 22})", function (result) {
|
||||
console.log("Record created.");
|
||||
run_query("MATCH (n) RETURN n", function (result) {
|
||||
console.log("Record matched.");
|
||||
var alice = result.records[0].get("n");
|
||||
console.log(alice.labels[0]);
|
||||
console.log(alice.properties["name"]);
|
||||
session.close();
|
||||
driver.close();
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### C# Driver Example
|
||||
|
||||
The C# driver is hosted
|
||||
[on GitHub](https://github.com/neo4j/neo4j-dotnet-driver). The example below
|
||||
performs the same work as all of the previous examples. Encryption is disabled
|
||||
by setting `EncryptionLevel.NONE` on the `Config`.
|
||||
|
||||
```
|
||||
using System;
|
||||
using System.Linq;
|
||||
using Neo4j.Driver.V1;
|
||||
|
||||
public class Basic {
|
||||
public static void Main(string[] args) {
|
||||
// Initialize the driver.
|
||||
var config = Config.DefaultConfig;
|
||||
config.EncryptionLevel = EncryptionLevel.None;
|
||||
using(var driver = GraphDatabase.Driver("bolt://localhost:7687", AuthTokens.None, config))
|
||||
using(var session = driver.Session())
|
||||
{
|
||||
// Run basic queries.
|
||||
session.Run("MATCH (n) DETACH DELETE n").Consume();
|
||||
session.Run("CREATE (alice:Person {name: \"Alice\", age: 22})").Consume();
|
||||
var result = session.Run("MATCH (n) RETURN n").First();
|
||||
var alice = (INode) result["n"];
|
||||
Console.WriteLine(alice["name"]);
|
||||
Console.WriteLine(string.Join(", ", alice.Labels));
|
||||
Console.WriteLine(alice["age"]);
|
||||
}
|
||||
Console.WriteLine("All ok!");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Limitations
|
||||
|
||||
Memgraph is currently in early stage, and has a number of limitations we plan
|
||||
to remove in future versions.
|
||||
|
||||
#### Multiple Users & Authorization
|
||||
|
||||
Memgraph is currently single-user only. There is no way to control user
|
||||
privileges. The default user has read and write privileges over the whole
|
||||
database.
|
||||
|
||||
#### Secure Sockets Layer (SSL)
|
||||
|
||||
Secure connections are not supported. For this reason each client
|
||||
driver needs to be configured not to use encryption. Consult driver-specific
|
||||
guides for details.
|
||||
@ -1,152 +0,0 @@
|
||||
## Installation
|
||||
|
||||
Memgraph is a 64-bit Linux compatible database management system. Currently,
|
||||
the Memgraph binary is offered only as a [Docker](https://www.docker.com)
|
||||
image based on Debian Stretch. Before proceeding with the installation, please
|
||||
install the Docker engine on the system. Instructions how to install Docker
|
||||
can be found on the
|
||||
[official Docker website](https://docs.docker.com/engine/installation).
|
||||
Memgraph Docker image was built with Docker version `1.12` and should be
|
||||
compatible with all later versions.
|
||||
|
||||
### Docker Import
|
||||
|
||||
After a successful download the Memgraph Docker image
|
||||
can be imported into Docker:
|
||||
|
||||
```
|
||||
docker load -i /path/to/memgraph-<version>-docker.tar.gz
|
||||
```
|
||||
|
||||
### Image Configuration & Running Memgraph
|
||||
|
||||
Memgraph can be started by executing:
|
||||
|
||||
```
|
||||
docker run -it -p 7687:7687 memgraph:<version>
|
||||
```
|
||||
|
||||
The `-it` option enables displaying Memgraph's logs inside the current shell.
|
||||
The `-p` option is used to specify the port on which Memgraph will listen for
|
||||
requests. Memgraph uses the Bolt protocol for network communication, which
|
||||
uses port `7687` by default. The `<version>` part are 3 numbers specifying the
|
||||
version, e.g. `1.2.3`. To always run the latest version, `:<version>` part can
|
||||
be omitted.
|
||||
|
||||
```
|
||||
docker run -it -p 7687:7687 memgraph
|
||||
```
|
||||
|
||||
It is recommended to perform some additional Docker configuration. Memgraph is
|
||||
currently an in-memory database management system, but it periodically stores
|
||||
all data to the hard drive. These storages are referred to as *snapshots* and
|
||||
are used for recovering data in case of a restart.
|
||||
|
||||
When starting Memgraph, a folder for snapshots needs to be created and mounted
|
||||
on the host file system. This can be easily done using Docker's named
|
||||
volumes. For example:
|
||||
|
||||
```
|
||||
# Run Memgraph.
|
||||
docker run -p 7687:7687 -v mg_data:/var/lib/memgraph memgraph
|
||||
```
|
||||
|
||||
The `-v` option will make a named volume directory called `mg_data` and
|
||||
Memgraph will store snapshots there. Named volumes are usually found in
|
||||
`/var/lib/docker/volumes`. This is the recommended way to create persistent
|
||||
storage.
|
||||
|
||||
The same can be achieved for logs and configuration. All supported volumes
|
||||
which can be mounted are:
|
||||
|
||||
* `/var/lib/memgraph`, for storing snapshots;
|
||||
* `/var/log/memgraph`, for storing *full* logs and
|
||||
* `/etc/memgraph`, for Memgraph configuration (in `memgraph.conf` file).
|
||||
|
||||
Another way to expose the configuration and data is to use a full path to some
|
||||
directory on the system. In such a case, the directory first needs to be
|
||||
created and allow docker image to write inside. For example, to create a
|
||||
snapshots volume in the current directory:
|
||||
|
||||
```
|
||||
# Create the snapshots folder on the host.
|
||||
mkdir -m 777 mg_data
|
||||
# Docker expects full path to the created folder.
|
||||
FULL_OUTPUT_PATH=$PWD/mg_data
|
||||
# Run Memgraph.
|
||||
docker run -p 7687:7687 -v ${FULL_OUTPUT_PATH}:/var/lib/memgraph memgraph
|
||||
```
|
||||
|
||||
In this example, `-v` mounts a host folder `$PWD/mg_data` to a path inside the
|
||||
Docker container. Note that full paths will not be initially populated with
|
||||
files from the container. This means that if you expose the configuration
|
||||
`/etc/memgraph` to a full path, the default configuration `memgraph.conf` will
|
||||
be missing. To avoid confusion, using named volumes is preferred.
|
||||
|
||||
Other than setting the configuration, it is also recommended to run the Docker
|
||||
container in the background. This is achieved with `-d` option. In such a
|
||||
case, the name should be set for the running container, so that it can be
|
||||
easily found and shut down when needed. For example:
|
||||
|
||||
```
|
||||
# Run Memgraph.
|
||||
docker run -p 7687:7687 -d --name <memgraph_docker_container_name> memgraph
|
||||
```
|
||||
|
||||
### Memgraph Configuration Parameters
|
||||
|
||||
Memgraph can be configured with a number of command-line parameters. The
|
||||
parameters should be appended to the end of the `docker run` command in the
|
||||
`--param-name=param-value` format. Following is a list of available
|
||||
parameters:
|
||||
|
||||
Name | Type | Default | Description
|
||||
-------|------|:-------:|-------------
|
||||
--interface | string | "0.0.0.0" | IP address on which to listen.
|
||||
--port | integer | 7687 | Communication port on which to listen.
|
||||
--num-workers | integer | CPU count[^1] | Number of Memgraph worker threads.
|
||||
--gc-cycle-sec | integer | 30 | Interval, in seconds, when the garbage collection (GC) should run. <br/>If set to -1 the GC will never run (use with caution, memory will never get released).
|
||||
--memory-warning-threshold | integer | 1024 | Memory warning threshold, in MB. If Memgraph detects there is less available RAM available it will log a warning. Set to 0 to disable.
|
||||
--query-execution-time-sec | integer | 30 | Maximum allowed query execution time, in seconds. <br/>Queries exceeding this limit will be aborted. Value of -1 means no limit.
|
||||
--query-plan-cache | bool | true | Cache generated query plans.
|
||||
--query-plan-cache-ttl | int | 60 | Time to live for cached query plans, in seconds.
|
||||
--durability-enabled | bool | true | If database state persistence is enabled (snapshot and write-ahead log).
|
||||
--durability-directory | string | "/var/lib/memgraph/durability" | Path to the directory where durability files will be stored.
|
||||
--db-recover-on-startup | bool | true | Recover the database on startup (from snapshots and write-ahead logs).
|
||||
--snapshot-cycle-sec | integer | 300 | Interval between database snapshots, in seconds.
|
||||
--snapshot-max-retained | integer | 3 | Number of retained snapshots.<br/>Value -1 means without limit.
|
||||
--snapshot-on-exit | bool | true | Make a snapshot when closing Memgraph.
|
||||
--log-file | string | "/var/log/memgraph/memgraph.log" | Path to where the log should be stored.
|
||||
--also-log-to-stderr | bool | false | If `true`, log messages will go to stderr in addition to logfiles.
|
||||
--flag-file | string | "" | Path to a file containing additional configuration settings.
|
||||
|
||||
All of the parameters can also be found in `/etc/memgraph/memgraph.conf`.
|
||||
|
||||
[^1]: Maximum number of concurrent executions on the current CPU.
|
||||
|
||||
To find more about how to execute queries on Memgraph please proceed to
|
||||
**Quick Start**.
|
||||
|
||||
### Cleanup
|
||||
|
||||
Status and Memgraph's logging messages can be checked with:
|
||||
|
||||
```
|
||||
docker ps -a
|
||||
docker logs -f <memgraph_docker_container_name>
|
||||
```
|
||||
|
||||
|
||||
Memgraph and its Docker container can be stopped with:
|
||||
|
||||
```
|
||||
docker stop <memgraph_docker_container_name>
|
||||
```
|
||||
|
||||
After the container has stopped, it can be removed by
|
||||
executing:
|
||||
|
||||
```
|
||||
docker rm <memgraph_docker_container_name>
|
||||
```
|
||||
|
||||
@ -1,253 +1,158 @@
|
||||
## Quick Start
|
||||
|
||||
This chapter outlines several ways to execute openCypher queries on Memgraph,
|
||||
but first it's important to outline several technologies Memgraph uses.
|
||||
This chapter outlines installing and running Memgraph, as well as executing
|
||||
basic queries against the database.
|
||||
|
||||
### OpenCypher
|
||||
### Installation
|
||||
|
||||
The Memgraph binary is offered as:
|
||||
|
||||
* Debian package for Debian 9 (Stretch) and
|
||||
* Docker image.
|
||||
|
||||
After downloading the binary, proceed to the corresponding section below.
|
||||
|
||||
#### Docker Installation
|
||||
|
||||
Before proceeding with the installation, please install the Docker engine on
|
||||
the system. Instructions on how to install Docker can be found on the
|
||||
[official Docker website](https://docs.docker.com/engine/installation).
|
||||
Memgraph Docker image was built with Docker version `1.12` and should be
|
||||
compatible with all later versions.
|
||||
|
||||
After installing and running Docker, download the Memgraph Docker image and
|
||||
import it with the following command.
|
||||
|
||||
```
|
||||
docker load -i /path/to/memgraph-<version>-docker.tar.gz
|
||||
```
|
||||
|
||||
Memgraph is then started with another docker command.
|
||||
|
||||
```
|
||||
docker run -p 7687:7687 \
|
||||
-v mg_lib:/var/lib/memgraph -v mg_log:/var/log/memgraph -v mg_etc:/etc/memgraph \
|
||||
memgraph
|
||||
```
|
||||
|
||||
On success, expect to see output similar to the following.
|
||||
|
||||
```
|
||||
Starting 8 workers
|
||||
Server is fully armed and operational
|
||||
Listening on 0.0.0.0 at 7687
|
||||
```
|
||||
|
||||
Memgraph is now ready to process queries, you may now proceed to
|
||||
[querying](#querying). To stop Memgraph, press `Ctrl-c`.
|
||||
|
||||
Memgraph configuration is available in Docker's named volume `mg_etc`. On
|
||||
Linux systems it should be in
|
||||
`/var/lib/docker/volumes/mg_etc/_data/memgraph.conf`. After changing the
|
||||
configuration, Memgraph needs to be restarted.
|
||||
|
||||
#### Debian Package Installation
|
||||
|
||||
After downloading Memgraph as a Debian package, install it by running the
|
||||
following.
|
||||
|
||||
```
|
||||
dpkg -i /path/to/memgraph_<version>.deb
|
||||
```
|
||||
|
||||
If the installation was successful, Memgraph should already be running. To
|
||||
make sure that is true, start it explicitly with the command:
|
||||
|
||||
```
|
||||
systemctl start memgraph
|
||||
```
|
||||
|
||||
To verify that Memgraph is running, run the following command.
|
||||
|
||||
```
|
||||
journalctl --unit memgraph
|
||||
```
|
||||
|
||||
It is expected to see something like the following output.
|
||||
|
||||
```
|
||||
Nov 23 13:40:13 hostname memgraph[14654]: Starting 8 workers
|
||||
Nov 23 13:40:13 hostname memgraph[14654]: Server is fully armed and operational
|
||||
Nov 23 13:40:13 hostname memgraph[14654]: Listening on 0.0.0.0 at 7687
|
||||
```
|
||||
|
||||
Memgraph is now ready to process queries, you may now proceed to
|
||||
[querying](#querying). To shutdown Memgraph server, issue the following
|
||||
command.
|
||||
|
||||
```
|
||||
systemctl stop memgraph
|
||||
```
|
||||
|
||||
Memgraph configuration is available in `/etc/memgraph/memgraph.conf`. After
|
||||
changing the configuration, Memgraph needs to be restarted.
|
||||
|
||||
### Querying
|
||||
|
||||
Memgraph supports the openCypher query language which has been developed by
|
||||
[Neo4j](http://neo4j.com). The language is currently going through a
|
||||
vendor-independent standardization process. It's a declarative language
|
||||
developed specifically for interaction with graph databases.
|
||||
|
||||
### Bolt
|
||||
The easiest way to execute openCypher queries against Memgraph, is using
|
||||
Neo4j's command-line tool. The command-line `neo4j-client` can be installed as
|
||||
described [on the official website](https://neo4j-client.net).
|
||||
|
||||
Clients connect to Memgraph using the
|
||||
[Bolt protocol](https://boltprotocol.org/). Bolt was designed for efficient
|
||||
communication with graph databases. Memgraph supports
|
||||
[Version 1](https://boltprotocol.org/v1/) of the protocol. Official Bolt
|
||||
protocol drivers are provided for multiple programming languages:
|
||||
|
||||
* [Java](http://neo4j.com/docs/api/java-driver)
|
||||
* [Python](http://neo4j.com/docs/api/python-driver)
|
||||
* [JavaScript](http://neo4j.com/docs/api/javascript-driver)
|
||||
* [C#](http://neo4j.com/docs/api/dotnet-driver)
|
||||
|
||||
It's also possible to interact with Memgraph using Neo4j's command-line tool,
|
||||
which is the easiest way for executing openCypher queries on Memgraph.
|
||||
|
||||
### Graph Gists
|
||||
|
||||
A nice looking set of small graph examples could be found
|
||||
[here](https://neo4j.com/graphgists/). You can take any use-case and try to
|
||||
execute the queries against Memgraph. We welcome your feedback!
|
||||
|
||||
### neo4j-client Example
|
||||
|
||||
The command-line neo4j-client can be installed as described
|
||||
[on the official website](https://neo4j-client.net).
|
||||
|
||||
The client can be started and connected to Memgraph with the following
|
||||
shell command:
|
||||
After installing `neo4j-client`, connect to the running Memgraph instance by
|
||||
issuing the following shell command.
|
||||
|
||||
```
|
||||
neo4j-client bolt://<IP_ADDRESS>:<PORT> --insecure --user u --pass p
|
||||
neo4j-client --insecure -u "" -p "" localhost 7687
|
||||
```
|
||||
|
||||
Where `<IP_ADDRESS>` and `<PORT>` should be replaced with the network location
|
||||
where Memgraph is reachable. The `--insecure` option specifies that SLL should
|
||||
be disabled (Memgraph currently does not support SSL). `--user` and `--pass`
|
||||
parameter values are ignored by Memgraph (currently the database is
|
||||
single-user), but need to be provided for the client to connect automatically.
|
||||
|
||||
After the client has started it should present a command prompt similar to:
|
||||
|
||||
```
|
||||
neo4j-client 2.1.3
|
||||
Enter `:help` for usage hints.
|
||||
Connected to 'neo4j://neo@127.0.0.1:7687' (insecure)
|
||||
Connected to 'neo4j://@localhost:7687' (insecure)
|
||||
neo4j>
|
||||
```
|
||||
|
||||
|
||||
At this point it is possible to execute openCypher queries on Memgraph. Each
|
||||
query needs to end with the `;` (*semicolon*) character. For example:
|
||||
|
||||
```
|
||||
CREATE (u:User {name: "Your Name"})-[:Likes]->(m:Software {name: "Memgraph"});
|
||||
CREATE (u:User {name: "Alice"})-[:Likes]->(m:Software {name: "Memgraph"});
|
||||
```
|
||||
|
||||
followed by:
|
||||
The above will create 2 nodes in the database, one labeled "User" with name
|
||||
"Alice" and the other labeled "Software" with name "Memgraph". It will also
|
||||
create a relationship that "Alice" *likes* "Memgraph".
|
||||
|
||||
To find created nodes and relationships, execute the following query:
|
||||
|
||||
```
|
||||
MATCH (u:User)-[r]->(x) RETURN u, r, x;
|
||||
```
|
||||
|
||||
### Python Driver Example
|
||||
#### Graph Gists Examples
|
||||
|
||||
Neo4j officially supports Python for interacting with an openCypher and Bolt
|
||||
compliant database. For details consult the
|
||||
[official documentation](http://neo4j.com/docs/api/python-driver) and the
|
||||
[GitHub project](https://github.com/neo4j/neo4j-python-driver). Following is
|
||||
a basic usage example:
|
||||
A nice looking set of small graph examples can be found
|
||||
[here](https://neo4j.com/graphgists/). You can take any use-case and try to
|
||||
execute the queries against Memgraph. To clear the database between trying out
|
||||
examples, execute the query:
|
||||
|
||||
```
|
||||
from neo4j.v1 import GraphDatabase, basic_auth
|
||||
|
||||
# Initialize and configure the driver.
|
||||
# * provide the correct URL where Memgraph is reachable;
|
||||
# * use an empty user name and password, and
|
||||
# * disable encryption (not supported).
|
||||
driver = GraphDatabase.driver("bolt://localhost:7687",
|
||||
auth=basic_auth("", ""),
|
||||
encrypted=False)
|
||||
|
||||
# Start a session in which queries are executed.
|
||||
session = driver.session()
|
||||
|
||||
# Execute openCypher queries.
|
||||
# After each query, call either `consume()` or `data()`
|
||||
session.run('CREATE (alice:Person {name: "Alice", age: 22})').consume()
|
||||
|
||||
# Get all the vertices from the database (potentially multiple rows).
|
||||
vertices = session.run('MATCH (n) RETURN n').data()
|
||||
# Assuming we started with an empty database, we should have Alice
|
||||
# as the only row in the results.
|
||||
only_row = vertices.pop()
|
||||
alice = only_row["n"]
|
||||
|
||||
# Print out what we retrieved.
|
||||
print("Found a vertex with labels '{}', name '{}' and age {}".format(
|
||||
alice['name'], alice.labels, alice['age'])
|
||||
|
||||
# Remove all the data from the database.
|
||||
session.run('MATCH (n) DETACH DELETE n').consume()
|
||||
|
||||
# Close the session and the driver.
|
||||
session.close()
|
||||
driver.close()
|
||||
MATCH (n) DETACH DELETE n;
|
||||
```
|
||||
|
||||
### Java Driver Example
|
||||
### Where to Next
|
||||
|
||||
The details about Java driver can be found
|
||||
[on GitHub](https://github.com/neo4j/neo4j-java-driver).
|
||||
To learn more about the openCypher language, visit **openCypher Query
|
||||
Language** chapter in this document. If you wish to use a programming language
|
||||
to execute queries on Memgraph, go to the **Drivers** chapter. Details on what
|
||||
can be stored in Memgraph are in **Storable Data Types** chapter.
|
||||
|
||||
The example below is equivalent to Python example. Major difference is that
|
||||
`Config` object has to be created before the driver construction. Encryption
|
||||
has to be disabled by calling `withoutEncryption` method against the `Config`
|
||||
builder.
|
||||
We *welcome and encourage* your feedback!
|
||||
|
||||
```
|
||||
import org.neo4j.driver.v1.*;
|
||||
import org.neo4j.driver.v1.types.*;
|
||||
import static org.neo4j.driver.v1.Values.parameters;
|
||||
import java.util.*;
|
||||
|
||||
public class JavaQuickStart {
|
||||
public static void main(String[] args) {
|
||||
// Initialize driver.
|
||||
Config config = Config.build().withoutEncryption().toConfig();
|
||||
Driver driver = GraphDatabase.driver("bolt://localhost:7687",
|
||||
AuthTokens.basic("",""),
|
||||
config);
|
||||
// Execute basic queries.
|
||||
try (Session session = driver.session()) {
|
||||
StatementResult rs1 = session.run("MATCH (n) DETACH DELETE n");
|
||||
StatementResult rs2 = session.run(
|
||||
"CREATE (alice: Person {name: 'Alice', age: 22})");
|
||||
StatementResult rs3 = session.run( "MATCH (n) RETURN n");
|
||||
List<Record> records = rs3.list();
|
||||
Record record = records.get(0);
|
||||
Node node = record.get("n").asNode();
|
||||
System.out.println(node.get("name").asString());
|
||||
} catch (Exception e) {
|
||||
System.out.println(e);
|
||||
System.exit(1);
|
||||
}
|
||||
// Cleanup.
|
||||
driver.close();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Javascript Driver Example
|
||||
|
||||
The details about Javascript driver can be found
|
||||
[on GitHub](https://github.com/neo4j/neo4j-javascript-driver).
|
||||
|
||||
The Javascript example below is equivalent to Python and Java examples. SSL
|
||||
can be disabled by passing `{encrypted: 'ENCRYPTION_OFF'}` during the driver
|
||||
construction.
|
||||
|
||||
Here is an example related to `Node.js`. Memgraph doesn't have integrated
|
||||
support for `WebSocket` which is required during the execution in any web
|
||||
browser. If you want to run `openCypher` queries from a web browser,
|
||||
[websockify](https://github.com/novnc/websockify) has to be up and running.
|
||||
Requests from web browsers are wrapped into `WebSocket` messages, and a proxy
|
||||
is needed to handle the overhead. The proxy has to be configured to point out
|
||||
to Memgraph's Bolt port and web browser driver has to send requests to the
|
||||
proxy port.
|
||||
|
||||
```
|
||||
var neo4j = require('neo4j-driver').v1;
|
||||
var driver = neo4j.driver("bolt://localhost:7687",
|
||||
neo4j.auth.basic("neo4j", "1234"),
|
||||
{encrypted: 'ENCRYPTION_OFF'});
|
||||
var session = driver.session();
|
||||
|
||||
function die() {
|
||||
session.close();
|
||||
driver.close();
|
||||
}
|
||||
|
||||
function run_query(query, callback) {
|
||||
var run = session.run(query, {});
|
||||
run.then(callback).catch(function (error) {
|
||||
console.log(error);
|
||||
die();
|
||||
});
|
||||
}
|
||||
|
||||
run_query("MATCH (n) DETACH DELETE n", function (result) {
|
||||
console.log("Database cleared.");
|
||||
run_query("CREATE (alice: Person {name: 'Alice', age: 22})", function (result) {
|
||||
console.log("Record created.");
|
||||
run_query("MATCH (n) RETURN n", function (result) {
|
||||
console.log("Record matched.");
|
||||
var alice = result.records[0].get("n");
|
||||
console.log(alice.labels[0]);
|
||||
console.log(alice.properties["name"]);
|
||||
session.close();
|
||||
driver.close();
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Multiple-Query Transactions
|
||||
|
||||
Memgraph supports transactions containing multiple queries. In other words,
|
||||
one can set an explicit transaction start and stop. All of the queries inside
|
||||
will be executed as a single transaction. This means that if a single query
|
||||
execution fails, all of the executed queries will be reverted and the
|
||||
transaction aborted.
|
||||
|
||||
### Limitations
|
||||
|
||||
Memgraph is currently in early stage, and has a number of limitations we plan
|
||||
to remove in future versions.
|
||||
|
||||
#### Multiple Users & Authorization
|
||||
|
||||
Memgraph is currently single-user only. There is no way to control user
|
||||
privileges. The default user has read and write privileges over the whole
|
||||
database.
|
||||
|
||||
#### Multiple Databases
|
||||
|
||||
Currently, a single Memgraph process exposes only one database that is
|
||||
implicitly used. To use multiple databases, it is necessary to launch multiple
|
||||
Memgraph processes.
|
||||
|
||||
#### Secure Sockets Layer (SSL)
|
||||
|
||||
Secure connections are not supported. For this reason each client
|
||||
driver needs to be configured not to use encryption. Consult driver-specific
|
||||
guides for details.
|
||||
|
||||
|
||||
#### Node and edge IDs
|
||||
Unique node and edge IDs are returned by the Bolt protocol to the client. In Memgraph
|
||||
these IDs are not guaranteed to be persistent during the whole database lifetime. They
|
||||
should never be used for any client side logic outside a single query/transaction scope.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user