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

109
docs/user_technical/installation.md
View File

@ -1,85 +1,102 @@
## Installation
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
[Docker](https://www.docker.com) image. Before proceeding with the
installation, please install the Docker engine on your system. Instructions
how to install Docker can be found
[here](https://docs.docker.com/engine/installation). Memgraph Docker image was
built with Docker version `1.12`, so all Docker versions since version `1.12`
should work.
Memgraph is a 64-bit Linux compatible database management system. For the
purpose of Alpha testing Memgraph has been packed into a
[Docker](https://www.docker.com) image based on Ubuntu 16.04. Before
proceeding with the installation, please install the Docker engine on your
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 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
```
### 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>
```
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
folder for database snapshots needs to be created and mounted on the host file
system. It is also recommended to run the container in the background. On Linux
system all of that can be executed as follows
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.
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
# Docker expects full path to the created folder
# Docker expects full path to the created folder.
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>
```
`-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
appended at the end of `docker run` command in the following format
`--param-name=param-value`.
Below is a list of all available parameters
### 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
-------|------|:-------:|-------------
port | integer | 7687 | Communication port on which to listen.
num_workers | integer | 8 | Number of workers (concurrent threads).
snapshot_cycle_sec | integer | 300 | Interval, `in seconds`, between two database snapshots. Value of -1 turns the snapshots off.
max_retained_snapshots | integer | 3 | Number of retained snapshots, -1 means without limit.
snapshot_on_db_destruction | bool | false | Make a snapshot when closing Memgraph.
recover_on_startup | bool | false | Recover the database on startup.
--port | integer | 7687 | Communication port on which to listen.
--num-workers | integer | CPU count[^1] | Number of Memgraph worker threads.
--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.<br/>Value -1 means without limit.
--snapshot-on-db-destruction | bool | false | Make a snapshot when closing Memgraph.
--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
the database please proceed to [Quick Start](quick-start.md).
[^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](quick-start.md).
### Cleanup
Status & Memgraph's logging messages can be checked with:
Status and Memgraph's logging messages can be checked with:
```
docker ps -a
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>
```
After the container has been stopped, it can be removed by
executing
After the container has stopped, it can be removed by
executing:
```
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.
Currently supported interface is the [*Bolt protocol*](#bolt-protocol). We are
also working on providing a web based interface, which could be used through a
web browser.
Currently only the [*Bolt protocol*](#bolt-protocol) is supported. We are
working on implementing a web-browser interface.
### Bolt Protocol
The [Bolt protocol](https://boltprotocol.org/) was designed for database
applications and it aims to be efficient. Memgraph is using
The [Bolt protocol](https://boltprotocol.org/) was designed for efficient
communication with graph databases. Memgraph supports
[Version 1](https://boltprotocol.org/v1/) of the protocol.
Besides using the Bolt protocol specification to build a custom driver, you
can use the already available drivers. Official Bolt protocol drivers are
provided for the following languages.
Official Bolt protocol drivers are provided for multiple programming languages:
* [C#](http://neo4j.com/docs/api/dotnet-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)
* [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
recommend using drivers starting from version 1.3.

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

@ -1,25 +1,30 @@
## Quick Start
This chapter outlines several ways to connect and execute openCypher queries
against Memgraph using available Bolt clients and drivers.
This chapter outlines several ways to execute openCypher queries on Memgraph,
but first it's important to outline several technologies Memgraph uses.
Before the start, it is important to mention a couple of current limitations.
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.
### OpenCypher
SSL is also not supported yet, so a driver has to be configured without
encryption. This is usually accomplished by modifying the configuration
parameters before using them to construct the driver. There should be a
parameter controlling the encryption and it should be set to a disabled state.
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 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.
Memgraph is 100% Bolt compliant. That means every Bolt compliant driver should
work. The following clients and drivers are tested `libneo4j-client` (C),
`neo4j-driver` (Python), `neo4j-driver` (Javascript), `Neo4j Driver` (Java).
### Bolt
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
@ -29,67 +34,94 @@ execute the queries against Memgraph. We welcome your feedback!
### neo4j-client Example
Please take a look [here](https://neo4j-client.net) for the installation details
and complete documentation.
The command-line neo4j-client can be installed as described
[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
# to establish a connection the connect command has to be excuted as follows
:connect localhost 7687
neo4j-client 2.1.3
Enter `:help` for usage hints.
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
The details about Python driver can be found [on
GitHub](https://github.com/neo4j/neo4j-python-driver). Below is a very basic
example how to execute queries against Memgraph.
Similar to all other drivers, driver and session have to be initialized (at the
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.
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()
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()
returned_result_set = session.run('MATCH (n) RETURN n').data()
returned_result = returned_result_set.pop()
alice = returned_result["n"]
# 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(alice['name'])
print(alice.labels)
print(alice['age'])
# 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 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
@ -104,7 +136,7 @@ import java.util.*;
public class JavaQuickStart {
public static void main(String[] args) {
// Init driver.
// Initialize driver.
Config config = Config.build().withoutEncryption().toConfig();
Driver driver = GraphDatabase.driver("bolt://localhost:7687",
AuthTokens.basic("",""),
@ -131,11 +163,11 @@ public class JavaQuickStart {
### Javascript Driver Example
The details about Javascript driver can be found [on
GitHub] (https://github.com/neo4j/neo4j-javascript-driver).
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
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
@ -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,
[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
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.
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;
@ -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.