tursom/memgraph
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs - alpha user documentation work

Browse Source 
Summary:
A lot of style changes. Major content changes are the following:
- Bolt and "interface" stuff moved to quick-start (not so quick anymore?)
- removed the "Memgraph is 100% Bolt compliant" and client-compatiblity claims because they are probably not true and aren't necessary
- moved "Limitations" to the bottom
- Python quickstart - moved explanations into the code, moved DB cleanup to the end (natural data flow)

What still needs work in my opion:
- the table in the "Limitations" part renders horribly (no space between cells)
- heading3 and heading4 are rendered the same in the "QuickStart", which is bad in the "Limitations" section
- I only went through the "Installation" and part of the "QuickStart", still a lot to go

Reviewers: buda, dtomicevic, florijan

Reviewed By: buda

Subscribers: pullbot

Differential Revision: https://phabricator.memgraph.io/D473
This commit is contained in:
Teon Banek 2017-06-16 11:47:13 +02:00
parent 5403b99e18
commit 3f08614c3d
3 changed files with 189 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
docs/user_technical/installation.md
View File

@ -1,85 +1,102 @@
## Installation ## Installation
Memgraph is a 64-bit Linux compatible database management system. For the Memgraph is a 64-bit Linux compatible database management system. For the
purpose of Alpha testing Memgraph has been packed into Ubuntu 16.04 based purpose of Alpha testing Memgraph has been packed into a
[Docker](https://www.docker.com) image. Before proceeding with the [Docker](https://www.docker.com) image based on Ubuntu 16.04. Before
installation, please install the Docker engine on your system. Instructions proceeding with the installation, please install the Docker engine on your
how to install Docker can be found system. Instructions how to install Docker can be found on the
[here](https://docs.docker.com/engine/installation). Memgraph Docker image was [official Docker website](https://docs.docker.com/engine/installation).
built with Docker version `1.12`, so all Docker versions since version `1.12` Memgraph Docker image was built with Docker version `1.12` and should be
should work. compatible with all latter versions.
### Import ### Docker Import
After a successful download the Memgraph Docker image
can be imported into Docker:
After a successful download, Memgraph can be imported as follows
``` ```
docker load -i /path/to/<memgraph_docker_image_name>.tar.gz docker load -i /path/to/<memgraph_docker_image_name>.tar.gz
``` ```
### Run ### Image Configuration & Running Memgraph
Memgraph can be started by executing:
The most convenient way to start Memgraph is
``` ```
docker run -it -p 7687:7687 <memgraph_docker_image_name> docker run -it -p 7687:7687 <memgraph_docker_image_name>
``` ```
The `-it` option enables displaying Memgraph's logs inside the current shell.
The `-p` option is used to specify the port which Memgraph will use to listen
for requests. Since the default Bolt protocol is `7687`, the straightforward
option is to use that port.
The recommended way to run Memgraph requires some additional configuration. A The `-it` option enables displaying Memgraph's logs inside the current shell.
folder for database snapshots needs to be created and mounted on the host file The `-p` option is used to specify the port on which Memgraph will listen for
system. It is also recommended to run the container in the background. On Linux requests. Memgraph uses the Bolt protocol for network communication, which
system all of that can be executed as follows uses port `7687` by default.
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.
It is also recommended to run the Docker container in the background. On a
Linux system all of that can be achieved with the following shell commands:
``` ```
# create snapshots folder on the host # Create the snapshots folder on the host.
mkdir -p memgraph_snapshots mkdir -p memgraph_snapshots
# Docker expects full path to the created folder # Docker expects full path to the created folder.
FULL_SNAPSHOTS_PATH=$PWD/memgraph_snapshots FULL_SNAPSHOTS_PATH=$PWD/memgraph_snapshots
# run Memgraph # Run Memgraph.
docker run -d -p 7687:7687 -v ${FULL_SNAPSHOTS_PATH}:/memgraph/snapshots --name <memgraph_docker_container_name> <memgraph_docker_image_name> docker run -d -p 7687:7687 -v ${FULL_SNAPSHOTS_PATH}:/memgraph/snapshots --name <memgraph_docker_container_name> <memgraph_docker_image_name>
``` ```
`-d` means that the container will be detached (run in the background mode).
`-v` mounts snapshots folder inside the container on the host file system
(useful for the recovery process). With `--name` a user can set a custom name
for the container (useful when the container has to be stopped).
`<memgraph_docker_container_name>` could be any convenient name e.g.
`memgraph_alpha`.
### Configuration Parameters In the commands above `-d` means that the container will be detached (run in
the background).
`-v` mounts the snapshots folder inside the Docker container on the host file
system.
With `--name` a custom name for the container can be set (useful for easier
container management). `<memgraph_docker_container_name>` could be any
convenient name e.g. `memgraph_alpha`.
Memgraph can be run with various parameters. The parameters should be ### Memgraph Configuration Parameters
appended at the end of `docker run` command in the following format
`--param-name=param-value`. Memgraph can be configured with a number of command-line parameters. The
Below is a list of all available parameters 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 Name | Type | Default | Description
-------|------|:-------:|------------- -------|------|:-------:|-------------
port | integer | 7687 | Communication port on which to listen. --port | integer | 7687 | Communication port on which to listen.
num_workers | integer | 8 | Number of workers (concurrent threads). --num-workers | integer | CPU count[^1] | Number of Memgraph worker threads.
snapshot_cycle_sec | integer | 300 | Interval, `in seconds`, between two database snapshots. Value of -1 turns the snapshots off. --snapshot-cycle-sec | integer | 300 | Interval (seconds) between database snapshots.<br/>Value of -1 turns taking snapshots off.
max_retained_snapshots | integer | 3 | Number of retained snapshots, -1 means without limit. --max-retained-snapshots | integer | 3 | Number of retained snapshots.<br/>Value -1 means without limit.
snapshot_on_db_destruction | bool | false | Make a snapshot when closing Memgraph. --snapshot-on-db-destruction | bool | false | Make a snapshot when closing Memgraph.
recover_on_startup | bool | false | Recover the database on startup. --recover-on-startup | bool | false | Recover the database on startup using the last<br/>stored snapshot.
To find more about how to execute queries against [^1]: Maximum number of concurrent executions on the current CPU.
the database please proceed to [Quick Start](quick-start.md).
To find more about how to execute queries on Memgraph please proceed to
[Quick Start](quick-start.md).
### Cleanup ### Cleanup
Status & Memgraph's logging messages can be checked with: Status and Memgraph's logging messages can be checked with:
``` ```
docker ps -a docker ps -a
docker logs -f <memgraph_docker_container_name> docker logs -f <memgraph_docker_container_name>
``` ```
To stop Memgraph, execute
Memgraph and its Docker container can be stopped with:
``` ```
docker stop <memgraph_docker_container_name> docker stop <memgraph_docker_container_name>
``` ```
After the container has been stopped, it can be removed by After the container has stopped, it can be removed by
executing executing:
``` ```
docker rm <memgraph_docker_container_name> docker rm <memgraph_docker_container_name>
``` ```

17
docs/user_technical/interfaces.md
View File

@ -2,24 +2,21 @@
This chapter describes ways to access the Memgraph database. This chapter describes ways to access the Memgraph database.
Currently supported interface is the [*Bolt protocol*](#bolt-protocol). We are Currently only the [*Bolt protocol*](#bolt-protocol) is supported. We are
also working on providing a web based interface, which could be used through a working on implementing a web-browser interface.
web browser.
### Bolt Protocol ### Bolt Protocol
The [Bolt protocol](https://boltprotocol.org/) was designed for database The [Bolt protocol](https://boltprotocol.org/) was designed for efficient
applications and it aims to be efficient. Memgraph is using communication with graph databases. Memgraph supports
[Version 1](https://boltprotocol.org/v1/) of the protocol. [Version 1](https://boltprotocol.org/v1/) of the protocol.
Besides using the Bolt protocol specification to build a custom driver, you Official Bolt protocol drivers are provided for multiple programming languages:
can use the already available drivers. Official Bolt protocol drivers are
provided for the following languages.
* [C#](http://neo4j.com/docs/api/dotnet-driver)
* [Java](http://neo4j.com/docs/api/java-driver) * [Java](http://neo4j.com/docs/api/java-driver)
* [JavaScript](http://neo4j.com/docs/api/javascript-driver)
* [Python](http://neo4j.com/docs/api/python-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)
They can be used for easier building custom interfaces for Memgraph. We They can be used for easier building custom interfaces for Memgraph. We
recommend using drivers starting from version 1.3. recommend using drivers starting from version 1.3.

175
docs/user_technical/quick-start.md
View File

@ -1,25 +1,30 @@
## Quick Start ## Quick Start
This chapter outlines several ways to connect and execute openCypher queries This chapter outlines several ways to execute openCypher queries on Memgraph,
against Memgraph using available Bolt clients and drivers. but first it's important to outline several technologies Memgraph uses.
Before the start, it is important to mention a couple of current limitations. ### OpenCypher
Memgraph doesn't yet support multi-command transactions. In other words,
explicit start and termination of transactions isn't yet supported. A
transaction is created and committed implicitly before and after each `run`
method.
SSL is also not supported yet, so a driver has to be configured without Memgraph supports the openCypher query language which has been developed by
encryption. This is usually accomplished by modifying the configuration [Neo4j](http://neo4j.com). The language is currently going through a
parameters before using them to construct the driver. There should be a vendor-independent standardization process. It's a declarative language
parameter controlling the encryption and it should be set to a disabled state. developed specifically for interaction with graph databases.
Furthermore, the authorization isn't supported yet. Username and password
parameters are ignored during the authorization process. In other words, any
combination of username and password will work, preferably they should be empty.
Memgraph is 100% Bolt compliant. That means every Bolt compliant driver should ### Bolt
work. The following clients and drivers are tested `libneo4j-client` (C),
`neo4j-driver` (Python), `neo4j-driver` (Javascript), `Neo4j Driver` (Java). 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 ### Graph Gists
@ -29,67 +34,94 @@ execute the queries against Memgraph. We welcome your feedback!
### neo4j-client Example ### neo4j-client Example
Please take a look [here](https://neo4j-client.net) for the installation details The command-line neo4j-client can be installed as described
and complete documentation. [on the official website](https://neo4j-client.net).
#### Query execution The client can be started and connected to Memgraph with the following
shell command:
You can execute a single query by piping the query string to the client
``` ```
echo "MATCH (n) RETURN n;" | neo4j-client --insecure -u "" -p "" localhost 7687 neo4j-client bolt://<IP_ADDRESS>:<PORT> --insecure --user u --pass p
``` ```
or start the client and then make the connection. The most important thing is
not to forget `--insecure` parameter to disable SSL. 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 alpha does not support SSL). `--user` and `--pass`
parameter values are ignored by Memgraph (alpha 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 --insecure neo4j-client 2.1.3
# to establish a connection the connect command has to be excuted as follows Enter `:help` for usage hints.
:connect localhost 7687 Connected to 'neo4j://neo@127.0.0.1:7687' (insecure)
neo4j>
``` ```
Each query written in the `neo4j-client` console has to be finished with `;`
e.g.
At this point it is possible to execute openCypher queries on Memgraph. Each
query needs to end with the `;` (*semicolon*) character. For example:
``` ```
MATCH ()-[r]->() RETURN count(r); CREATE (u:User {name: "Your Name"})-[:Likes]->(m:Software {name: "Memgraph"});
```
followed by:
```
MATCH (u:User)-[r]->(x) RETURN u, r, x;
``` ```
### Python Driver Example ### Python Driver Example
The details about Python driver can be found [on Neo4j officially supports Python for interacting with an openCypher and Bolt
GitHub](https://github.com/neo4j/neo4j-python-driver). Below is a very basic compliant database. For details consult the
example how to execute queries against Memgraph. [official documentation](http://neo4j.com/docs/api/python-driver) and the
[GitHub project](https://github.com/neo4j/neo4j-python-driver). Following is
Similar to all other drivers, driver and session have to be initialized (at the a basic usage example:
end of execution they also have to be closed). To execute a query, `run` method
has to be called. `consume` is here just to block the execution until the query
is actually executed. At the end of the code snippet shown below, the `print`
function is used to display properties and labels of the obtained data.
``` ```
from neo4j.v1 import GraphDatabase, basic_auth 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", driver = GraphDatabase.driver("bolt://localhost:7687",
auth=basic_auth("", ""), auth=basic_auth("", ""),
encrypted=False) encrypted=False)
# Start a session in which queries are executed.
session = driver.session() session = driver.session()
session.run('MATCH (n) DETACH DELETE n').consume() # Execute openCypher queries.
# After each query, call either `consume()` or `data()`
session.run('CREATE (alice:Person {name: "Alice", age: 22})').consume() session.run('CREATE (alice:Person {name: "Alice", age: 22})').consume()
returned_result_set = session.run('MATCH (n) RETURN n').data() # Get all the vertices from the database (potentially multiple rows).
returned_result = returned_result_set.pop() vertices = session.run('MATCH (n) RETURN n').data()
alice = returned_result["n"] # 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(alice['name']) # Print out what we retrieved.
print(alice.labels) print("Found a vertex with labels '{}', name '{}' and age {}".format(
print(alice['age']) 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() session.close()
driver.close() driver.close()
``` ```
### Java Driver Example ### Java Driver Example
The details about Java driver can be found [on The details about Java driver can be found
GitHub](https://github.com/neo4j/neo4j-java-driver). [on GitHub](https://github.com/neo4j/neo4j-java-driver).
The example below is equivalent to Python example. Major difference is that The example below is equivalent to Python example. Major difference is that
`Config` object has to be created before the driver construction. Encryption `Config` object has to be created before the driver construction. Encryption
@ -104,7 +136,7 @@ import java.util.*;
public class JavaQuickStart { public class JavaQuickStart {
public static void main(String[] args) { public static void main(String[] args) {
// Init driver. // Initialize driver.
Config config = Config.build().withoutEncryption().toConfig(); Config config = Config.build().withoutEncryption().toConfig();
Driver driver = GraphDatabase.driver("bolt://localhost:7687", Driver driver = GraphDatabase.driver("bolt://localhost:7687",
AuthTokens.basic("",""), AuthTokens.basic("",""),
@ -131,11 +163,11 @@ public class JavaQuickStart {
### Javascript Driver Example ### Javascript Driver Example
The details about Javascript driver can be found [on The details about Javascript driver can be found
GitHub] (https://github.com/neo4j/neo4j-javascript-driver). [on GitHub](https://github.com/neo4j/neo4j-javascript-driver).
The Javascript example below is equivalent to Python and Java examples. SSL can The Javascript example below is equivalent to Python and Java examples. SSL
be disabled by passing `{encrypted: 'ENCRYPTION_OFF'}` during the driver can be disabled by passing `{encrypted: 'ENCRYPTION_OFF'}` during the driver
construction. construction.
Here is an example related to `Node.js`. Memgraph doesn't have integrated Here is an example related to `Node.js`. Memgraph doesn't have integrated
@ -143,9 +175,9 @@ support for `Web Socket` which is required during the execution in any web
browser. If you want to run `openCypher` queries from a web browser, browser. If you want to run `openCypher` queries from a web browser,
[websockify](https://github.com/novnc/websockify) has to be up and running. [websockify](https://github.com/novnc/websockify) has to be up and running.
Requests from web browsers are wrapped into `Web Socket` messages, and a proxy Requests from web browsers are wrapped into `Web Socket` messages, and a proxy
is needed to handle the overhead. The proxy has to be configured to point out to is needed to handle the overhead. The proxy has to be configured to point out
Memgraph's Bolt port and web browser driver has to send requests to the proxy to Memgraph's Bolt port and web browser driver has to send requests to the
port. proxy port.
``` ```
var neo4j = require('neo4j-driver').v1; var neo4j = require('neo4j-driver').v1;
@ -182,3 +214,34 @@ run_query("MATCH (n) DETACH DELETE n", function (result) {
}); });
}); });
``` ```
### Limitations
Memgraph is currently in alpha stage, and has a number of limitations we plan
to remove in future versions.
#### Multiple-Query Transactions
Even though Memgraph is a transactional database engine, transactions
containing multiple queries are not yet supported. In other words, explicit
transaction start and stop aren't yet supported. A transaction is created and
committed implicitly for each executed query. If query execution fails, the
transaction is aborted.
#### 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 in alpha. For this reason each client
driver needs to be configured not to use encryption. Consult driver-specific
guides for details.