diff --git a/docs/user_technical/installation.md b/docs/user_technical/installation.md index 9ae8fb099..6e12183ea 100644 --- a/docs/user_technical/installation.md +++ b/docs/user_technical/installation.md @@ -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> ``` + diff --git a/docs/user_technical/interfaces.md b/docs/user_technical/interfaces.md index 3af5eac6c..69fb5279a 100644 --- a/docs/user_technical/interfaces.md +++ b/docs/user_technical/interfaces.md @@ -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. diff --git a/docs/user_technical/quick-start.md b/docs/user_technical/quick-start.md index 42e10e8a5..def429c76 100644 --- a/docs/user_technical/quick-start.md +++ b/docs/user_technical/quick-start.md @@ -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.