PoC for auth replication

Co-authored-by: Antonio Andelic <antonio.andelic@memgraph.io>

.arcconfig

@@ -1,7 +0,0 @@
-{
-  "project_id" : "memgraph",
-  "conduit_uri" : "https://phabricator.memgraph.io",
-  "phabricator_uri" : "https://phabricator.memgraph.io",
-  "git.default-relative-commit": "origin/master",
-  "arc.land.onto.default": "master"
-}

.clang-format

@@ -6,4 +6,5 @@ UseTab:       Never
 DerivePointerAlignment: false
 PointerAlignment: Right
 ColumnLimit : 80
+IncludeBlocks: Preserve
 ...

.clang-tidy

@@ -0,0 +1,82 @@
+---
+Checks: '*,
+         -android-*,
+         -cert-err58-cpp,
+         -cppcoreguidelines-avoid-c-arrays,
+         -cppcoreguidelines-avoid-goto,
+         -cppcoreguidelines-avoid-magic-numbers,
+         -cppcoreguidelines-no-malloc,
+         -cppcoreguidelines-non-private-member-variables-in-classes,
+         -cppcoreguidelines-owning-memory,
+         -cppcoreguidelines-pro-bounds-array-to-pointer-decay,
+         -cppcoreguidelines-pro-bounds-constant-array-index,
+         -cppcoreguidelines-pro-bounds-pointer-arithmetic,
+         -cppcoreguidelines-pro-type-member-init,
+         -cppcoreguidelines-pro-type-reinterpret-cast,
+         -cppcoreguidelines-pro-type-static-cast-downcast,
+         -cppcoreguidelines-pro-type-union-access,
+         -cppcoreguidelines-pro-type-vararg,
+         -cppcoreguidelines-special-member-functions,
+         -fuchsia-default-arguments,
+         -fuchsia-default-arguments-calls,
+         -fuchsia-default-arguments-declarations,
+         -fuchsia-overloaded-operator,
+         -fuchsia-statically-constructed-objects,
+         -fuchsia-trailing-return,
+         -fuchsia-virtual-inheritance,
+         -google-explicit-constructor,
+         -google-readability-*,
+         -hicpp-avoid-c-arrays,
+         -hicpp-avoid-goto,
+         -hicpp-braces-around-statements,
+         -hicpp-member-init,
+         -hicpp-no-array-decay,
+         -hicpp-no-assembler,
+         -hicpp-no-malloc,
+         -hicpp-use-equals-default,
+         -hicpp-vararg,
+         -llvm-header-guard,
+         -llvmlibc-callee-namespace,
+         -llvmlibc-implementation-in-namespace,
+         -llvmlibc-restrict-system-libc-headers,
+         -misc-non-private-member-variables-in-classes,
+         -misc-unused-parameters,
+         -modernize-avoid-c-arrays,
+         -modernize-concat-nested-namespaces,
+         -modernize-pass-by-value,
+         -modernize-use-equals-default,
+         -modernize-use-nodiscard,
+         -modernize-use-trailing-return-type,
+         -performance-unnecessary-value-param,
+         -readability-braces-around-statements,
+         -readability-else-after-return,
+         -readability-implicit-bool-conversion,
+         -readability-magic-numbers,
+         -readability-named-parameter'
+WarningsAsErrors: ''
+HeaderFilterRegex: ''
+AnalyzeTemporaryDtors: false
+FormatStyle:     none
+CheckOptions:
+  - key:             google-readability-braces-around-statements.ShortStatementLines
+    value:           '1'
+  - key:             google-readability-function-size.StatementThreshold
+    value:           '800'
+  - key:             google-readability-namespace-comments.ShortNamespaceLines
+    value:           '10'
+  - key:             google-readability-namespace-comments.SpacesBeforeComments
+    value:           '2'
+  - key:             modernize-loop-convert.MaxCopySize
+    value:           '16'
+  - key:             modernize-loop-convert.MinConfidence
+    value:           reasonable
+  - key:             modernize-loop-convert.NamingStyle
+    value:           CamelCase
+  - key:             modernize-pass-by-value.IncludeStyle
+    value:           llvm
+  - key:             modernize-replace-auto-ptr.IncludeStyle
+    value:           llvm
+  - key:             modernize-use-nullptr.NullMacros
+    value:           'NULL'
+...
+

.githooks/pre-commit

@@ -0,0 +1,43 @@
+#!/bin/sh
+
+project_folder=$(git rev-parse --show-toplevel)
+if git rev-parse --verify HEAD >/dev/null 2>&1
+then
+	against=HEAD
+else
+	# Initial commit: diff against an empty tree object
+	against=$(git hash-object -t tree /dev/null)
+fi
+
+# Redirect output to stderr.
+exec 1>&2
+
+tmpdir=$(mktemp -d repo-XXXXXXXX)
+trap "rm -rf $tmpdir" EXIT INT
+
+modified_files=$(git diff --cached --name-only --diff-filter=AM $against | sed -nE "/.*\.(cpp|cc|cxx|c|h|hpp|lcp)$/p")
+for file in $modified_files; do
+  echo "Checking $file..."
+
+  cp $project_folder/.clang-format $project_folder/.clang-tidy $tmpdir
+
+  git checkout-index --prefix="$tmpdir/" -- $file
+
+  echo "Running clang-format..."
+  $project_folder/tools/git-clang-format $tmpdir/$file
+  code=$?
+
+  if [ $code -ne 0 ]; then
+    break
+  fi
+
+  echo "Running clang-tidy..."
+  $project_folder/tools/git-clang-tidy $tmpdir/$file
+  code=$?
+
+  if [ $code -ne 0 ]; then
+   break
+  fi
+done;
+
+return $code

.github/workflows/diff.yaml

@@ -0,0 +1,330 @@
+name: Diff
+
+on:
+  push:
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
+
+jobs:
+  community_build:
+    name: "Community build"
+    runs-on: [self-hosted, General, Linux, X64, Debian10]
+    env:
+      THREADS: 24
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build community binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build community binaries.
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=release -DMG_ENTERPRISE=OFF ..
+          make -j$THREADS
+
+      - name: Run unit tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run unit tests.
+          cd build
+          ctest -R memgraph__unit --output-on-failure
+
+      - name: Run stress test
+        run: |
+          cd tests/stress
+          ./continuous_integration
+
+  coverage_build:
+    name: "Coverage build"
+    runs-on: [self-hosted, General, Linux, X64, Debian10]
+    env:
+      THREADS: 24
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build coverage binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build coverage binaries.
+          cd build
+          cmake -DTEST_COVERAGE=ON ..
+          make -j$THREADS memgraph__unit
+
+      - name: Run unit tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run unit tests.
+          cd build
+          ctest -R memgraph__unit --output-on-failure
+
+      - name: Compute code coverage
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Compute code coverage.
+          cd tools/github
+          ./coverage_convert
+
+          # Package code coverage.
+          cd generated
+          tar -czf code_coverage.tar.gz coverage.json html report.json summary.rmu
+
+      - name: Save code coverage
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Code coverage"
+          path: tools/github/generated/code_coverage.tar.gz
+
+  debug_build:
+    name: "Debug build"
+    runs-on: [self-hosted, General, Linux, X64, Debian10]
+    env:
+      THREADS: 24
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build debug binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build debug binaries.
+          cd build
+          cmake ..
+          make -j$THREADS
+
+      - name: Run leftover CTest tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run leftover CTest tests (all except unit and benchmark tests).
+          cd build
+          ctest -E "(memgraph__unit|memgraph__benchmark)" --output-on-failure
+
+      - name: Run drivers tests
+        run: |
+          ./tests/drivers/run.sh
+
+      - name: Run integration tests
+        run: |
+          cd tests/integration
+          for name in *; do
+            if [ ! -d $name ]; then continue; fi
+            pushd $name >/dev/null
+            echo "Running: $name"
+            if [ -x prepare.sh ]; then
+              ./prepare.sh
+            fi
+            if [ -x runner.py ]; then
+              ./runner.py
+            elif [ -x runner.sh ]; then
+              ./runner.sh
+            fi
+            echo
+            popd >/dev/null
+          done
+
+      - name: Run cppcheck and clang-format
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run cppcheck and clang-format.
+          cd tools/github
+          ./cppcheck_and_clang_format diff
+
+      - name: Save cppcheck and clang-format errors
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Code coverage"
+          path: tools/github/cppcheck_and_clang_format.txt
+
+  release_build:
+    name: "Release build"
+    runs-on: [self-hosted, General, Linux, X64, Debian10]
+    env:
+      THREADS: 24
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Set up parent
+        run: |
+          # Remove parent folder (if it exists).
+          cd ..
+          if [ -d parent ]; then
+            rm -rf parent
+          fi
+
+          # Copy untouched repository to parent folder.
+          cp -r memgraph parent
+
+          # Checkout previous commit
+          cd parent
+          git checkout HEAD~1
+
+      - name: Build release binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build release binaries.
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=release ..
+          make -j$THREADS
+
+      - name: Build parent binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          cd ../parent
+          ./init
+
+          # Build parent binaries.
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=release ..
+          make -j$THREADS memgraph memgraph__macro_benchmark
+
+      - name: Run macro benchmark tests
+        run: |
+          cd tests/macro_benchmark
+          ./harness QuerySuite MemgraphRunner \
+            --groups aggregation 1000_create unwind_create dense_expand match \
+            --no-strict
+
+      - name: Run parent macro benchmark tests
+        run: |
+          cd ../parent/tests/macro_benchmark
+          ./harness QuerySuite MemgraphRunner \
+            --groups aggregation 1000_create unwind_create dense_expand match \
+            --no-strict
+
+      - name: Compute macro benchmark summary
+        run: |
+          ./tools/github/macro_benchmark_summary \
+            --current tests/macro_benchmark/.harness_summary \
+            --previous ../parent/tests/macro_benchmark/.harness_summary \
+            --output macro_benchmark_summary.txt
+
+      - name: Save macro benchmark summary
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Macro benchmark summary"
+          path: macro_benchmark_summary.txt
+
+      - name: Run GQL Behave tests
+        run: |
+          cd tests/gql_behave
+          ./continuous_integration
+
+      - name: Save quality assurance status
+        uses: actions/upload-artifact@v2
+        with:
+          name: "GQL Behave Status"
+          path: |
+            tests/gql_behave/gql_behave_status.csv
+            tests/gql_behave/gql_behave_status.html
+
+      - name: Run stress test (plain)
+        run: |
+          cd tests/stress
+          ./continuous_integration
+
+      - name: Run stress test (SSL)
+        run: |
+          cd tests/stress
+          ./continuous_integration --use-ssl
+
+      - name: Run durability test
+        run: |
+          cd tests/stress
+          source ve3/bin/activate
+          python3 durability --num-steps 5
+
+  release_jepsen_test:
+    name: "Release Jepsen Test"
+    runs-on: [self-hosted, Linux, X64, Debian10, JepsenControl]
+    #continue-on-error: true
+    env:
+      THREADS: 24
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build release binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build only memgraph release binarie.
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=release ..
+          make -j$THREADS memgraph
+
+      - name: Run Jepsen tests
+        run: |
+          cd tests/jepsen
+          ./run.sh test --binary ../../build/memgraph --run-args "test-all --node-configs resources/node-config.edn" --ignore-run-stdout-logs --ignore-run-stderr-logs
+
+      - name: Save Jepsen report
+        uses: actions/upload-artifact@v2
+        if: ${{ always() }}
+        with:
+          name: "Jepsen Report"
+          path: tests/jepsen/Jepsen.tar.gz

.github/workflows/release.yaml

@@ -0,0 +1,309 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 1 * * *"
+
+jobs:
+  community_build:
+    name: "Community build"
+    runs-on: [self-hosted, General, Linux, X64, Debian10]
+    env:
+      THREADS: 24
+    timeout-minutes: 960
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build community binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build community binaries.
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=release -DMG_ENTERPRISE=OFF ..
+          make -j$THREADS
+
+      - name: Create community DEB package
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Create community DEB package.
+          cd build
+          mkdir output && cd output
+          cpack -G DEB --config ../CPackConfig.cmake
+
+      - name: Save community DEB package
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Community DEB package"
+          path: build/output/memgraph*.deb
+
+      - name: Run unit tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run unit tests.
+          cd build
+          ctest -R memgraph__unit --output-on-failure
+
+      - name: Run stress test (plain)
+        run: |
+          cd tests/stress
+          ./continuous_integration
+
+      - name: Run stress test (large)
+        run: |
+          cd tests/stress
+          ./continuous_integration --large-dataset
+
+  coverage_build:
+    name: "Coverage build"
+    runs-on: [self-hosted, General, Linux, X64, Debian10]
+    env:
+      THREADS: 24
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build coverage binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build coverage binaries.
+          cd build
+          cmake -DTEST_COVERAGE=ON ..
+          make -j$THREADS memgraph__unit
+
+      - name: Run unit tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run unit tests.
+          cd build
+          ctest -R memgraph__unit --output-on-failure
+
+      - name: Compute code coverage
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Compute code coverage.
+          cd tools/github
+          ./coverage_convert
+
+          # Package code coverage.
+          cd generated
+          tar -czf code_coverage.tar.gz coverage.json html report.json summary.rmu
+
+      - name: Save code coverage
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Code coverage"
+          path: tools/github/generated/code_coverage.tar.gz
+
+  debug_build:
+    name: "Debug build"
+    runs-on: [self-hosted, General, Linux, X64, Debian10]
+    env:
+      THREADS: 24
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build debug binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build debug binaries.
+          cd build
+          cmake ..
+          make -j$THREADS
+
+      - name: Run leftover CTest tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run leftover CTest tests (all except unit and benchmark tests).
+          cd build
+          ctest -E "(memgraph__unit|memgraph__benchmark)" --output-on-failure
+
+      - name: Run drivers tests
+        run: |
+          ./tests/drivers/run.sh
+
+      - name: Run integration tests
+        run: |
+          cd tests/integration
+          for name in *; do
+            if [ ! -d $name ]; then continue; fi
+            pushd $name >/dev/null
+            echo "Running: $name"
+            if [ -x prepare.sh ]; then
+              ./prepare.sh
+            fi
+            if [ -x runner.py ]; then
+              ./runner.py
+            elif [ -x runner.sh ]; then
+              ./runner.sh
+            fi
+            echo
+            popd >/dev/null
+          done
+
+      - name: Run cppcheck and clang-format
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run cppcheck and clang-format.
+          cd tools/github
+          ./cppcheck_and_clang_format diff
+
+      - name: Save cppcheck and clang-format errors
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Code coverage"
+          path: tools/github/cppcheck_and_clang_format.txt
+
+  release_build:
+    name: "Release build"
+    runs-on: [self-hosted, General, Linux, X64, Debian10]
+    env:
+      THREADS: 24
+    timeout-minutes: 960
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build release binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build release binaries.
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=release ..
+          make -j$THREADS
+
+      - name: Create enterprise DEB package
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Create enterprise DEB package.
+          cd build
+          mkdir output && cd output
+          cpack -G DEB --config ../CPackConfig.cmake
+
+      - name: Save enterprise DEB package
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Enterprise DEB package"
+          path: build/output/memgraph*.deb
+
+      - name: Run micro benchmark tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run micro benchmark tests.
+          cd build
+          # The `eval` benchmark needs a large stack limit.
+          ulimit -s 262144
+          ctest -R memgraph__benchmark -V
+
+      - name: Run macro benchmark tests
+        run: |
+          cd tests/macro_benchmark
+          ./harness QuerySuite MemgraphRunner \
+            --groups aggregation 1000_create unwind_create dense_expand match \
+            --no-strict
+
+      - name: Run parallel macro benchmark tests
+        run: |
+          cd tests/macro_benchmark
+          ./harness QueryParallelSuite MemgraphRunner \
+            --groups aggregation_parallel create_parallel bfs_parallel \
+            --num-database-workers 9 --num-clients-workers 30 \
+            --no-strict
+
+      - name: Run GQL Behave tests
+        run: |
+          cd tests/gql_behave
+          ./continuous_integration
+
+      - name: Save quality assurance status
+        uses: actions/upload-artifact@v2
+        with:
+          name: "GQL Behave Status"
+          path: |
+            tests/gql_behave/gql_behave_status.csv
+            tests/gql_behave/gql_behave_status.html
+
+      - name: Run stress test (plain)
+        run: |
+          cd tests/stress
+          ./continuous_integration
+
+      - name: Run stress test (SSL)
+        run: |
+          cd tests/stress
+          ./continuous_integration --use-ssl
+
+      - name: Run stress test (large)
+        run: |
+          cd tests/stress
+          ./continuous_integration --large-dataset
+
+      - name: Run durability test (plain)
+        run: |
+          cd tests/stress
+          source ve3/bin/activate
+          python3 durability --num-steps 5
+
+      - name: Run durability test (large)
+        run: |
+          cd tests/stress
+          source ve3/bin/activate
+          python3 durability --num-steps 20

.github/workflows/release_centos.yaml

@@ -0,0 +1,308 @@
+name: Release CentOS
+
+on: [workflow_dispatch]
+
+jobs:
+  community_build:
+    name: "Community build"
+    runs-on: [self-hosted, General, Linux, X64, CentOS7]
+    env:
+      THREADS: 24
+    timeout-minutes: 960
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build community binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build community binaries.
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=release -DMG_ENTERPRISE=OFF ..
+          make -j$THREADS
+
+      - name: Create community RPM package
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Create community RPM package.
+          cd build
+          mkdir output && cd output
+          cpack -G RPM --config ../CPackConfig.cmake
+          rpmlint memgraph*.rpm
+
+      - name: Save community RPM package
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Community RPM package"
+          path: build/output/memgraph*.rpm
+
+      - name: Run unit tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run unit tests.
+          cd build
+          ctest -R memgraph__unit --output-on-failure
+
+      - name: Run stress test (plain)
+        run: |
+          cd tests/stress
+          ./continuous_integration
+
+      - name: Run stress test (large)
+        run: |
+          cd tests/stress
+          ./continuous_integration --large-dataset
+
+  coverage_build:
+    name: "Coverage build"
+    runs-on: [self-hosted, General, Linux, X64, CentOS7]
+    env:
+      THREADS: 24
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build coverage binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build coverage binaries.
+          cd build
+          cmake -DTEST_COVERAGE=ON ..
+          make -j$THREADS memgraph__unit
+
+      - name: Run unit tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run unit tests.
+          cd build
+          ctest -R memgraph__unit --output-on-failure
+
+      - name: Compute code coverage
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Compute code coverage.
+          cd tools/github
+          ./coverage_convert
+
+          # Package code coverage.
+          cd generated
+          tar -czf code_coverage.tar.gz coverage.json html report.json summary.rmu
+
+      - name: Save code coverage
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Code coverage"
+          path: tools/github/generated/code_coverage.tar.gz
+
+  debug_build:
+    name: "Debug build"
+    runs-on: [self-hosted, General, Linux, X64, CentOS7]
+    env:
+      THREADS: 24
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build debug binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build debug binaries.
+          cd build
+          cmake ..
+          make -j$THREADS
+
+      - name: Run leftover CTest tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run leftover CTest tests (all except unit and benchmark tests).
+          cd build
+          ctest -E "(memgraph__unit|memgraph__benchmark)" --output-on-failure
+
+      - name: Run drivers tests
+        run: |
+          ./tests/drivers/run.sh
+
+      - name: Run integration tests
+        run: |
+          cd tests/integration
+          for name in *; do
+            if [ ! -d $name ]; then continue; fi
+            pushd $name >/dev/null
+            echo "Running: $name"
+            if [ -x prepare.sh ]; then
+              ./prepare.sh
+            fi
+            if [ -x runner.py ]; then
+              ./runner.py
+            elif [ -x runner.sh ]; then
+              ./runner.sh
+            fi
+            echo
+            popd >/dev/null
+          done
+
+      - name: Run cppcheck and clang-format
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run cppcheck and clang-format.
+          cd tools/github
+          ./cppcheck_and_clang_format diff
+
+      - name: Save cppcheck and clang-format errors
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Code coverage"
+          path: tools/github/cppcheck_and_clang_format.txt
+
+  release_build:
+    name: "Release build"
+    runs-on: [self-hosted, General, Linux, X64, CentOS7]
+    env:
+      THREADS: 24
+    timeout-minutes: 960
+
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+        with:
+          # Number of commits to fetch. `0` indicates all history for all
+          # branches and tags. (default: 1)
+          fetch-depth: 0
+
+      - name: Build release binaries
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Initialize dependencies.
+          ./init
+
+          # Build release binaries.
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=release ..
+          make -j$THREADS
+
+      - name: Create enterprise RPM package
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Create enterprise RPM package.
+          cd build
+          mkdir output && cd output
+          cpack -G RPM --config ../CPackConfig.cmake
+          rpmlint memgraph*.rpm
+
+      - name: Save enterprise RPM package
+        uses: actions/upload-artifact@v2
+        with:
+          name: "Enterprise RPM package"
+          path: build/output/memgraph*.rpm
+
+      - name: Run micro benchmark tests
+        run: |
+          # Activate toolchain.
+          source /opt/toolchain-v2/activate
+
+          # Run micro benchmark tests.
+          cd build
+          # The `eval` benchmark needs a large stack limit.
+          ulimit -s 262144
+          ctest -R memgraph__benchmark -V
+
+      - name: Run macro benchmark tests
+        run: |
+          cd tests/macro_benchmark
+          ./harness QuerySuite MemgraphRunner \
+            --groups aggregation 1000_create unwind_create dense_expand match \
+            --no-strict
+
+      - name: Run parallel macro benchmark tests
+        run: |
+          cd tests/macro_benchmark
+          ./harness QueryParallelSuite MemgraphRunner \
+            --groups aggregation_parallel create_parallel bfs_parallel \
+            --num-database-workers 9 --num-clients-workers 30 \
+            --no-strict
+
+      - name: Run GQL Behave tests
+        run: |
+          cd tests/gql_behave
+          ./continuous_integration
+
+      - name: Save quality assurance status
+        uses: actions/upload-artifact@v2
+        with:
+          name: "GQL Behave Status"
+          path: |
+            tests/gql_behave/gql_behave_status.csv
+            tests/gql_behave/gql_behave_status.html
+
+      - name: Run stress test (plain)
+        run: |
+          cd tests/stress
+          ./continuous_integration
+
+      - name: Run stress test (SSL)
+        run: |
+          cd tests/stress
+          ./continuous_integration --use-ssl
+
+      - name: Run stress test (large)
+        run: |
+          cd tests/stress
+          ./continuous_integration --large-dataset
+
+      - name: Run durability test (plain)
+        run: |
+          cd tests/stress
+          source ve3/bin/activate
+          python3 durability --num-steps 5
+
+      - name: Run durability test (large)
+        run: |
+          cd tests/stress
+          source ve3/bin/activate
+          python3 durability --num-steps 20

.github/workflows/test_all_workers.yaml

@@ -0,0 +1,118 @@
+name: Test All Workers
+
+on: [workflow_dispatch]
+
+jobs:
+  HP-DL360G6-1:
+    name: "HP-DL360G6-1"
+    runs-on: [HP-DL360G6-1]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system
+  HP-DL360G6-2:
+    name: "HP-DL360G6-2"
+    runs-on: [HP-DL360G6-2]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system
+  HP-DL360G6-3:
+    name: "HP-DL360G6-3"
+    runs-on: [HP-DL360G6-3]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system
+          docker --version
+          docker ps | grep jepsen
+
+  HP-DL360G6-v2-1:
+    name: "HP-DL360G6-v2-1"
+    runs-on: [HP-DL360G6-v2-1]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system
+  HP-DL360G6-v2-2:
+    name: "HP-DL360G6-v2-2"
+    runs-on: [HP-DL360G6-v2-2]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system
+  HP-DL360G6-v2-3:
+    name: "HP-DL360G6-v2-3"
+    runs-on: [HP-DL360G6-v2-3]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system
+  HP-DL360G6-v2-4:
+    name: "HP-DL360G6-v2-4"
+    runs-on: [HP-DL360G6-v2-4]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system
+  HP-DL360G6-v2-5:
+    name: "HP-DL360G6-v2-5"
+    runs-on: [HP-DL360G6-v2-5]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system
+  HP-DL360G6-v2-6:
+    name: "HP-DL360G6-v2-6"
+    runs-on: [HP-DL360G6-v2-6]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system
+  HP-DL360G6-v2-7:
+    name: "HP-DL360G6-v2-7"
+    runs-on: [HP-DL360G6-v2-7]
+    timeout-minutes: 10
+    steps:
+      - name: Set up repository
+        uses: actions/checkout@v2
+      - name: Check the system
+        run: |
+          source /opt/toolchain-v2/activate
+          ./tools/check-build-system

.gitignore

@@ -34,43 +34,35 @@ TAGS
 *.fas
 *.fasl
 
-# Cap'n Proto generated files
-*.capnp.c++
-*.capnp.h
-
-# LCP generated C++ & Cap'n Proto files
+# LCP generated C++ files
 *.lcp.cpp
-src/database/counters_rpc_messages.capnp
-src/database/counters_rpc_messages.hpp
-src/database/state_delta.capnp
-src/database/state_delta.hpp
-src/distributed/bfs_rpc_messages.capnp
+
+src/database/distributed/serialization.hpp
+src/database/single_node_ha/serialization.hpp
 src/distributed/bfs_rpc_messages.hpp
-src/distributed/coordination_rpc_messages.capnp
 src/distributed/coordination_rpc_messages.hpp
-src/distributed/data_rpc_messages.capnp
 src/distributed/data_rpc_messages.hpp
-src/distributed/durability_rpc_messages.capnp
 src/distributed/durability_rpc_messages.hpp
-src/distributed/index_rpc_messages.capnp
+src/distributed/dynamic_worker_rpc_messages.hpp
 src/distributed/index_rpc_messages.hpp
-src/distributed/plan_rpc_messages.capnp
 src/distributed/plan_rpc_messages.hpp
-src/distributed/pull_produce_rpc_messages.capnp
 src/distributed/pull_produce_rpc_messages.hpp
-src/distributed/storage_gc_rpc_messages.capnp
 src/distributed/storage_gc_rpc_messages.hpp
-src/distributed/token_sharing_rpc_messages.capnp
 src/distributed/token_sharing_rpc_messages.hpp
-src/distributed/transactional_cache_cleaner_rpc_messages.capnp
-src/distributed/transactional_cache_cleaner_rpc_messages.hpp
-src/distributed/updates_rpc_messages.capnp
 src/distributed/updates_rpc_messages.hpp
-src/query/plan/operator.capnp
+src/query/frontend/ast/ast.hpp
+src/query/distributed/frontend/ast/ast_serialization.hpp
+src/durability/distributed/state_delta.hpp
+src/durability/single_node/state_delta.hpp
+src/durability/single_node_ha/state_delta.hpp
+src/query/frontend/semantic/symbol.hpp
+src/query/distributed/frontend/semantic/symbol_serialization.hpp
+src/query/distributed/plan/ops.hpp
 src/query/plan/operator.hpp
-src/stats/stats_rpc_messages.capnp
+src/raft/log_entry.hpp
+src/raft/raft_rpc_messages.hpp
+src/raft/snapshot_metadata.hpp
+src/raft/storage_info_rpc_messages.hpp
 src/stats/stats_rpc_messages.hpp
-src/storage/concurrent_id_mapper_rpc_messages.capnp
-src/storage/concurrent_id_mapper_rpc_messages.hpp
-src/transactions/engine_rpc_messages.capnp
-src/transactions/engine_rpc_messages.hpp
+src/storage/distributed/rpc/concurrent_id_mapper_rpc_messages.hpp
+src/transactions/distributed/engine_rpc_messages.hpp

.ycm_extra_conf.py

@@ -1,171 +0,0 @@
-import os
-import os.path
-import fnmatch
-import logging
-import ycm_core
-
-BASE_FLAGS = [
-    '-Wall',
-    '-Wextra',
-    '-Werror',
-    '-Wno-long-long',
-    '-Wno-variadic-macros',
-    '-fexceptions',
-    '-ferror-limit=10000',
-    '-std=c++1z',
-    '-xc++',
-    '-I/usr/lib/',
-    '-I/usr/include/',
-    '-I./src',
-    '-I./include',
-    '-I./libs/fmt',
-    '-I./libs/yaml-cpp',
-    '-I./libs/glog/include',
-    '-I./libs/googletest/googletest/include',
-    '-I./libs/googletest/googlemock/include',
-    '-I./libs/benchmark/include',
-    '-I./libs/cereal/include',
-    # We include cppitertools headers directly from libs directory.
-    '-I./libs',
-    '-I./libs/rapidcheck/include',
-    '-I./libs/antlr4/runtime/Cpp/runtime/src',
-    '-I./libs/gflags/include',
-    '-I./experimental/distributed/src',
-    '-I./libs/postgresql/include',
-    '-I./libs/bzip2',
-    '-I./libs/zlib',
-    '-I./libs/rocksdb/include',
-    '-I./build/include'
-]
-
-SOURCE_EXTENSIONS = [
-    '.cpp',
-    '.cxx',
-    '.cc',
-    '.c',
-    '.m',
-    '.mm'
-]
-
-HEADER_EXTENSIONS = [
-    '.h',
-    '.hxx',
-    '.hpp',
-    '.hh'
-]
-
-# set the working directory of YCMD to be this file
-os.chdir(os.path.dirname(os.path.realpath(__file__)))
-
-def IsHeaderFile(filename):
-    extension = os.path.splitext(filename)[1]
-    return extension in HEADER_EXTENSIONS
-
-def GetCompilationInfoForFile(database, filename):
-    if IsHeaderFile(filename):
-        basename = os.path.splitext(filename)[0]
-        for extension in SOURCE_EXTENSIONS:
-            replacement_file = basename + extension
-            if os.path.exists(replacement_file):
-                compilation_info = database.GetCompilationInfoForFile(replacement_file)
-                if compilation_info.compiler_flags_:
-                    return compilation_info
-        return None
-    return database.GetCompilationInfoForFile(filename)
-
-def FindNearest(path, target):
-    candidate = os.path.join(path, target)
-    if(os.path.isfile(candidate) or os.path.isdir(candidate)):
-        logging.info("Found nearest " + target + " at " + candidate)
-        return candidate;
-    else:
-        parent = os.path.dirname(os.path.abspath(path));
-        if(parent == path):
-            raise RuntimeError("Could not find " + target);
-        return FindNearest(parent, target)
-
-def MakeRelativePathsInFlagsAbsolute(flags, working_directory):
-    if not working_directory:
-        return list(flags)
-    new_flags = []
-    make_next_absolute = False
-    path_flags = [ '-isystem', '-I', '-iquote', '--sysroot=' ]
-    for flag in flags:
-        new_flag = flag
-
-        if make_next_absolute:
-            make_next_absolute = False
-            if not flag.startswith('/'):
-                new_flag = os.path.join(working_directory, flag)
-
-        for path_flag in path_flags:
-            if flag == path_flag:
-                make_next_absolute = True
-                break
-
-            if flag.startswith(path_flag):
-                path = flag[ len(path_flag): ]
-                new_flag = path_flag + os.path.join(working_directory, path)
-                break
-
-        if new_flag:
-            new_flags.append(new_flag)
-    return new_flags
-
-
-def FlagsForClangComplete(root):
-    try:
-        clang_complete_path = FindNearest(root, '.clang_complete')
-        clang_complete_flags = open(clang_complete_path, 'r').read().splitlines()
-        return clang_complete_flags
-    except:
-        return None
-
-def FlagsForInclude(root):
-    try:
-        include_path = FindNearest(root, 'include')
-        flags = []
-        for dirroot, dirnames, filenames in os.walk(include_path):
-            for dir_path in dirnames:
-                real_path = os.path.join(dirroot, dir_path)
-                flags = flags + ["-I" + real_path]
-        return flags
-    except:
-        return None
-
-def FlagsForCompilationDatabase(root, filename):
-    try:
-        compilation_db_path = FindNearest(root, 'compile_commands.json')
-        compilation_db_dir = os.path.dirname(compilation_db_path)
-        logging.info("Set compilation database directory to " + compilation_db_dir)
-        compilation_db =  ycm_core.CompilationDatabase(compilation_db_dir)
-        if not compilation_db:
-            logging.info("Compilation database file found but unable to load")
-            return None
-        compilation_info = GetCompilationInfoForFile(compilation_db, filename)
-        if not compilation_info:
-            logging.info("No compilation info for " + filename + " in compilation database")
-            return None
-        return MakeRelativePathsInFlagsAbsolute(
-            compilation_info.compiler_flags_,
-            compilation_info.compiler_working_dir_)
-    except:
-        return None
-
-def FlagsForFile(filename):
-    root = os.path.realpath(filename);
-    compilation_db_flags = FlagsForCompilationDatabase(root, filename)
-    if compilation_db_flags:
-        final_flags = compilation_db_flags
-    else:
-        final_flags = BASE_FLAGS
-        clang_flags = FlagsForClangComplete(root)
-        if clang_flags:
-            final_flags = final_flags + clang_flags
-        include_flags = FlagsForInclude(root)
-        if include_flags:
-            final_flags = final_flags + include_flags
-    return {
-        'flags': final_flags,
-        'do_cache': True
-    }

CHANGELOG.md

@@ -1,5 +1,260 @@
 # Change Log
 
+## Future
+
+### Breaking Changes
+
+* Added extra information in durability files to support replication making
+  it incompatible with the durability files generated by older versions of
+  Memgraph. Even though the replication is an Enterprise feature, the files
+  are compatible with the Community version.
+
+## v1.2.0
+
+### Breaking Changes
+
+* SSL is disabled by default (`--bolt-cert-file` and `--bolt-key-file` are
+  empty). This change might only affect the client connection configuration.
+
+### Major Features and Improvements
+
+* Added support for Bolt v4.0 and v4.1.
+* Added `mgp_networkx.py` as an alternative implementation of NetworkX graph
+  objects, which is useful to use Memgraph data from NetworkX algorithms
+  optimally.
+* Added `nxalg.py` query module as a proxy to NetworkX algorithms.
+* Added plan optimization to use a label-property index where the property is
+  not null. As a result, the query engine, instead of scanning all elements and
+  applying the filter, performs a label-property index lookup when possible.
+
+### Bug Fixes and Other Changes
+
+* Fixed Cypher `ID` function `Null` handling. When the `ID` function receives
+  `Null`, it will also return `Null`.
+* Fixed bug that caused random crashes in SSL communication on platforms
+  that use older versions of OpenSSL (< 1.1) by adding proper multi-threading
+  handling.
+* Fix `DISCARD` message handling. The query is now executed before discarding
+  the results.
+
+## v1.1.0
+
+### Major Features and Improvements
+
+* Properties in nodes and edges are now stored encoded and compressed. This
+  change significantly reduces memory usage. Depending on the specific dataset,
+  total memory usage can be reduced up to 50%.
+* Added support for rescanning query modules. Previously, the query modules
+  directory was scanned only upon startup. Now it is scanned each time the user
+  requests to load a query module. The functions used to load the query modules
+  were renamed to `mg.load()` and `mg.load_all()` (from `mg.reload()` and
+  `mg.reload_all()`).
+* Improved execution performance of queries that have an IN list filter by
+  using label+property indices.
+  Example: `MATCH (n:Label) WHERE n.property IN [] ...`
+* Added support for `ANY` and `NONE` openCypher functions. Previously, only
+  `ALL` and `SINGLE` functions were implemented.
+
+### Bug Fixes and Other Changes
+
+* Fixed invalid paths returned by variable expansion when the starting node and
+  destination node used the same symbol.
+  Example: `MATCH path = (n:Person {name: "John"})-[:KNOWS*]->(n) RETURN path`
+* Improved semantics of `ALL` and `SINGLE` functions to be consistent with
+  openCypher when handling lists with `Null`s.
+* `SHOW CONSTRAINT INFO` now returns property names as a list for unique
+  constraints.
+* Escaped label/property/edgetype names in `DUMP DATABASE` to support names
+  with spaces in them.
+* Fixed handling of `DUMP DATABASE` queries in multi-command transactions
+  (`BEGIN`, ..., `COMMIT`).
+* Fixed handling of various query types in explicit transactions. For example,
+  constraints were allowed to be created in multi-command transactions
+  (`BEGIN`, ..., `COMMIT`) but that isn't a transactional operation and as such
+  can't be allowed in multi-command transactions.
+* Fixed integer overflow bugs in `COUNT`, `LIMIT` and `SKIP`.
+* Fixed integer overflow bugs in weighted shortest path expansions.
+* Fixed various other integer overflow bugs in query execution.
+* Added Marvel Comic Universe tutorial.
+* Added FootballTransfers tutorial.
+
+## v1.0.0
+
+### Major Features and Improvements
+
+* [Enterprise Ed.] Exposed authentication username/rolename regex as a flag
+  (`--auth-user-or-role-name-regex`).
+* [Enterprise Ed.] Improved auth module error handling and added support for
+  relative paths.
+* Added support for Python query modules. This release of Memgraph supports
+  query modules written using the already existing C API and the new Python
+  API.
+* Added support for unique constraints. The unique constraint is created with a
+  label and one or more properties.
+* Implemented support for importing CSV files (`mg_import_csv`). The importer
+  is compatible with the Neo4j batch CSV importer.
+* Snapshot and write-ahead log format changed (backward compatible with v0.50).
+* Vertices looked up by their openCypher ID (`MATCH (n) WHERE ID(n) = ...`)
+  will now find the node in O(logn) instead of O(n).
+* Improved planning of BFS expansion, a faster, specific approach is now
+  favored instead of a ScanAll+Filter operation.
+* Added syntax for limiting memory of `CALL`.
+* Exposed server name that should be used for Bolt handshake as flag
+  (`--bolt-server-name-for-init`).
+* Added several more functions to the query module C API.
+* Implemented a storage locking mechanism that prevents the user from
+  concurrently starting two Memgraph instances with the same data directory.
+
+### Bug Fixes and Other Changes
+
+* [Enterprise Ed.] Fixed a bug that crashed the database when granting
+  privileges to a user.
+* [Enterprise Ed.] Improved Louvain algorithm for community detection.
+* Type of variable expansion is now printed in `EXPLAIN` (e.g. ExpandVariable,
+  STShortestPath, BFSExpand, WeightedShortestPath).
+* Correctly display `CALL` in `EXPLAIN` output.
+* Correctly delimit arguments when printing the signature of a query module.
+* Fixed a planning issue when `CALL` preceded filtering.
+* Fixed spelling mistakes in the storage durability module.
+* Fixed storage GC indices/constraints subtle race condition.
+* Reduced memory allocations in storage API and indices.
+* Memgraph version is now outputted to `stdout` when Memgraph is started.
+* Improved RPM packaging.
+* Reduced number of errors reported in production log when loading query
+  modules.
+* Removed `early access` wording from the Community Offering license.
+
+## v0.50.0
+
+### Breaking Changes
+
+* [Enterprise Ed.] Remove support for Kafka streams.
+* Snapshot and write-ahead log format changed (not backward compatible).
+* Removed support for unique constraints.
+* Label indices aren't created automatically, create them explicitly instead.
+* Renamed several database flags. Please see the configuration file for a list of current flags.
+
+### Major Features and Improvements
+
+* [Enterprise Ed.] Add support for auth module.
+* [Enterprise Ed.] LDAP support migrated to auth module.
+* Implemented new graph storage engine.
+* Add support for disabling properties on edges.
+* Add support for existence constraints.
+* Add support for custom openCypher procedures using a C API.
+* Support loading query modules implementing read-only procedures.
+* Add `CALL <procedure> YIELD <result>` syntax for invoking loaded procedures.
+* Add `CREATE INDEX ON :Label` for creating label indices.
+* Add `DROP INDEX ON :Label` for dropping label indices.
+* Add `DUMP DATABASE` clause to openCypher.
+* Add functions for treating character strings as byte strings.
+
+### Bug Fixes and Other Changes
+
+* Fix several memory management bugs.
+* Reduce memory usage in query execution.
+* Fix bug that crashes the database when `EXPLAIN` is used.
+
+## v0.15.0
+
+### Breaking Changes
+
+* Snapshot and write-ahead log format changed (not backward compatible).
+* `indexInfo()` function replaced with `SHOW INDEX INFO` syntax.
+* Removed support for unique index. Use unique constraints instead.
+* `CREATE UNIQUE INDEX ON :label (property)` replaced with `CREATE CONSTRAINT ON (n:label) ASSERT n.property IS UNIQUE`.
+* Changed semantics for `COUNTER` openCypher function.
+
+### Major Features and Improvements
+
+* [Enterprise Ed.] Add new privilege, `STATS` for accessing storage info.
+* [Enterprise Ed.] LDAP authentication and authorization support.
+* [Enterprise Ed.] Add audit logging feature.
+* Add multiple properties unique constraint which replace unique indices.
+* Add `SHOW STORAGE INFO` feature.
+* Add `PROFILE` clause to openCypher.
+* Add `CREATE CONSTRAINT` clause to openCypher.
+* Add `DROP CONSTRAINT` clause to openCypher.
+* Add `SHOW CONSTRAINT INFO` feature.
+* Add `uniformSample` function to openCypher.
+* Add regex matching to openCypher.
+
+### Bug Fixes and Other Changes
+
+* Fix bug in explicit transaction handling.
+* Fix bug in edge filtering by edge type and destination.
+* Fix bug in query comment parsing.
+* Fix bug in query symbol table.
+* Fix OpenSSL memory leaks.
+* Make authentication case insensitive.
+* Remove `COALESCE` function.
+* Add movie tutorial.
+* Add backpacking tutorial.
+
+## v0.14.0
+
+### Breaking Changes
+
+* Write-ahead log format changed (not backward compatible).
+
+### Major Features and Improvements
+
+* [Enterprise Ed.] Reduce memory usage in distributed usage.
+* Add `DROP INDEX` feature.
+* Improve SSL error messages.
+
+### Bug Fixes and Other Changes
+
+* [Enterprise Ed.] Fix issues with reading and writing in a distributed query.
+* Correctly handle an edge case with unique constraint checks.
+* Fix a minor issue with `mg_import_csv`.
+* Fix an issue with `EXPLAIN`.
+
+## v0.13.0
+
+### Breaking Changes
+
+* Write-ahead log format changed (not backward compatible).
+* Snapshot format changed (not backward compatible).
+
+### Major Features and Improvements
+
+* [Enterprise Ed.] Authentication and authorization support.
+* [Enterprise Ed.] Kafka integration.
+* [Enterprise Ed.] Support dynamic worker addition in distributed.
+* Reduce memory usage and improve overall performance.
+* Add `CREATE UNIQUE INDEX` clause to openCypher.
+* Add `EXPLAIN` clause to openCypher.
+* Add `inDegree` and `outDegree` functions to openCypher.
+* Improve BFS performance when both endpoints are known.
+* Add new `node-label`, `relationship-type` and `quote` options to
+  `mg_import_csv` tool.
+* Reduce memory usage of `mg_import_csv`.
+
+### Bug Fixes and Other Changes
+
+* [Enterprise Ed.] Fix an edge case in distributed index creation.
+* [Enterprise Ed.] Fix issues with Cartesian in distributed queries.
+* Correctly handle large messages in Bolt protocol.
+* Fix issues when handling explicitly started transactions in queries.
+* Allow openCypher keywords to be used as variable names.
+* Revise and make user visible error messages consistent.
+* Improve aborting time consuming execution.
+
+## v0.12.0
+
+### Breaking Changes
+
+* Snapshot format changed (not backward compatible).
+
+### Major Features and Improvements
+
+* Improved Id Cypher function.
+* Added string functions to openCypher (`lTrim`, `left`, `rTrim`, `replace`,
+ `reverse`, `right`, `split`, `substring`, `toLower`, `toUpper`, `trim`).
+* Added `timestamp` function to openCypher.
+* Added support for dynamic property access with `[]` operator.
+
 ## v0.11.0
 
 ### Major Features and Improvements
@@ -7,11 +262,11 @@
 * [Enterprise Ed.] Improve Cartesian support in distributed queries.
 * [Enterprise Ed.] Improve distributed execution of BFS.
 * [Enterprise Ed.] Dynamic graph partitioner added.
-* Static vertices/edges id generators exposed through the Id Cypher function.
+* Static nodes/edges id generators exposed through the Id Cypher function.
 * Properties on disk added.
 * Telemetry added.
 * SSL support added.
-* Add `toString` function to openCypher.
+* `toString` function added.
 
 ### Bug Fixes and Other Changes
 
@@ -69,7 +324,7 @@
 
 * CASE construct (without aggregations).
 * Named path support added.
-* Maps can now be stored as vertex/edge properties.
+* Maps can now be stored as node/edge properties.
 * Map indexing supported.
 * `rand` function added.
 * `assert` function added.

CMakeLists.txt

@@ -1,6 +1,6 @@
 # MemGraph CMake configuration
 
-cmake_minimum_required(VERSION 3.1)
+cmake_minimum_required(VERSION 3.8)
 
 # !! IMPORTANT !! run ./project_root/init.sh before cmake command
 # to download dependencies
@@ -31,18 +31,101 @@ find_program(CLANGXX_FOUND clang++)
 if (CLANG_FOUND AND CLANGXX_FOUND)
   set(CMAKE_C_COMPILER ${CLANG_FOUND})
   set(CMAKE_CXX_COMPILER ${CLANGXX_FOUND})
+else()
+  message(FATAL_ERROR "Couldn't find clang and/or clang++!")
 endif()
 
-# Get current commit hash.
-execute_process(
-    OUTPUT_VARIABLE COMMIT_HASH
-    COMMAND git rev-parse --short HEAD
-)
-string(STRIP ${COMMIT_HASH} COMMIT_HASH)
-
 # -----------------------------------------------------------------------------
 
-project(memgraph VERSION 0.11.0)
+project(memgraph)
+
+# For more information about how to release a new version of Memgraph, see
+# `release/README.md`.
+
+# Option that is used to specify which version of Memgraph should be built. The
+# default is `ON` which causes the build system to build Memgraph Enterprise.
+# Memgraph Community is built if explicitly set to `OFF`.
+option(MG_ENTERPRISE "Build Memgraph Enterprise Edition" ON)
+
+# Set the current version here to override the automatic version detection. The
+# version must be specified as `X.Y.Z`. Primarily used when building new patch
+# versions.
+set(MEMGRAPH_OVERRIDE_VERSION "")
+
+# Custom suffix that this version should have. The suffix can be any arbitrary
+# string. Primarily used when building a version for a specific customer.
+set(MEMGRAPH_OVERRIDE_VERSION_SUFFIX "")
+
+# Variables used to generate the versions.
+if (MG_ENTERPRISE)
+  set(get_version_enterprise "--enterprise")
+else()
+  set(get_version_enterprise "")
+endif()
+set(get_version_script "${CMAKE_SOURCE_DIR}/release/get_version.py")
+
+# Get version that should be used in the binary.
+execute_process(
+    OUTPUT_VARIABLE MEMGRAPH_VERSION
+    COMMAND "${get_version_script}" ${get_version_enterprise}
+                "${MEMGRAPH_OVERRIDE_VERSION}"
+                "${MEMGRAPH_OVERRIDE_VERSION_SUFFIX}"
+)
+
+# Get version that should be used in the DEB package.
+execute_process(
+    OUTPUT_VARIABLE MEMGRAPH_VERSION_DEB
+    COMMAND "${get_version_script}" ${get_version_enterprise}
+                --variant deb
+                "${MEMGRAPH_OVERRIDE_VERSION}"
+                "${MEMGRAPH_OVERRIDE_VERSION_SUFFIX}"
+)
+
+# Get version that should be used in the RPM package.
+execute_process(
+    OUTPUT_VARIABLE MEMGRAPH_VERSION_RPM
+    COMMAND "${get_version_script}" ${get_version_enterprise}
+                --variant rpm
+                "${MEMGRAPH_OVERRIDE_VERSION}"
+                "${MEMGRAPH_OVERRIDE_VERSION_SUFFIX}"
+)
+
+# We want the above variables to be updated each time something is committed to
+# the repository. That is why we include a dependency on the current git HEAD
+# to trigger a new CMake run when the git repository state changes. This is a
+# hack, as CMake doesn't have a mechanism to regenerate variables when
+# something changes (only files can be regenerated).
+# https://cmake.org/pipermail/cmake/2018-October/068389.html
+#
+# The hack in the above link is nearly correct but it has a fatal flaw. The
+# `CMAKE_CONFIGURE_DEPENDS` isn't a `GLOBAL` property, it is instead a
+# `DIRECTORY` property and as such must be set in the `DIRECTORY` scope.
+# https://cmake.org/cmake/help/v3.14/manual/cmake-properties.7.html
+#
+# Unlike the above mentioned hack, we don't use the `.git/index` file. That
+# file changes on every `git add` (even on `git status`) so it triggers
+# unnecessary recalculations of the release version. The release version only
+# changes on every `git commit` or `git checkout`. That is why we watch the
+# following files for changes:
+#   - `.git/HEAD` -> changes each time a `git checkout` is issued
+#   - `.git/refs/heads/...` -> the value in `.git/HEAD` is a branch name (when
+#     you are on a branch) and you have to monitor the file of the specific
+#     branch to detect when a `git commit` was issued
+# More details about the contents of the `.git` directory and the specific
+# files used can be seen here:
+# https://git-scm.com/book/en/v2/Git-Internals-Git-References
+set(git_directory "${CMAKE_SOURCE_DIR}/.git")
+if (EXISTS "${git_directory}")
+  set_property(DIRECTORY APPEND PROPERTY
+      CMAKE_CONFIGURE_DEPENDS "${git_directory}/HEAD")
+  file(STRINGS "${git_directory}/HEAD" git_head_data)
+  if (git_head_data MATCHES "^ref: ")
+    string(SUBSTRING "${git_head_data}" 5 -1 git_head_ref)
+    set_property(DIRECTORY APPEND PROPERTY
+        CMAKE_CONFIGURE_DEPENDS "${git_directory}/${git_head_ref}")
+  endif()
+endif()
+
 # -----------------------------------------------------------------------------
 
 # setup CMake module path, defines path for include() and find_package()
@@ -62,21 +145,27 @@ add_custom_target(clean_all
 
 # build flags -----------------------------------------------------------------
 
-# TODO: set here 17 once it will be available in the cmake version (3.8)
-# set(CMAKE_CXX_STANDARD 17)
-# set(CMAKE_CXX_STANDARD_REQUIRED ON)
-# For now, explicitly set -std= flag for C++17.
-set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++1z -Wall \
-    -Werror=switch -Werror=switch-bool -Werror=return-type")
+# Export the compile commands so that we can use clang-tidy. Additional benefit
+# is easier debugging of compilation and linker flags.
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+# c99-designator is disabled because of required mixture of designated and
+# non-designated initializers in Python Query Module code (`py_module.cpp`).
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall \
+    -Werror=switch -Werror=switch-bool -Werror=return-type \
+    -Werror=return-stack-address \
+    -Wno-c99-designator")
 
 # Don't omit frame pointer in RelWithDebInfo, for additional callchain debug.
 set(CMAKE_CXX_FLAGS_RELWITHDEBINFO
     "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -fno-omit-frame-pointer")
 
 # Statically link libgcc and libstdc++, the GCC allows this according to:
+# https://gcc.gnu.org/onlinedocs/gcc-10.2.0/libstdc++/manual/manual/license.html
 # https://www.gnu.org/licenses/gcc-exception-faq.html
-# Last checked for gcc-7.3, we are using gcc-6.3 on build machines (license is
-# valid there also).
+# Last checked for gcc-10.2 which we are using on the build machines.
 # ** If we change versions, recheck this! **
 # ** Static linking is allowed only for executables! **
 set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -static-libgcc -static-libstdc++")
@@ -102,13 +191,6 @@ else()
     set(CMAKE_CXX_FLAGS_DEBUG "-g")
 endif()
 
-# ndebug
-option(NDEBUG "No debug" OFF)
-message(STATUS "NDEBUG: ${NDEBUG} (be careful CMAKE_BUILD_TYPE can also \
-append this flag)")
-if(NDEBUG)
-    add_definitions( -DNDEBUG )
-endif()
 # -----------------------------------------------------------------------------
 
 # default build type is debug
@@ -122,11 +204,6 @@ message(STATUS "CMake build type: ${CMAKE_BUILD_TYPE}")
 
 # threading
 find_package(Threads REQUIRED)
-
-# optional Ltalloc
-option(USE_LTALLOC "Use Ltalloc instead of default allocator (default OFF). \
-Set this to ON to link with Ltalloc." OFF)
-
 # optional readline
 option(USE_READLINE "Use GNU Readline library if available (default ON). \
 Set this to OFF to prevent linking with Readline even if it is available." ON)
@@ -137,63 +214,16 @@ if (USE_READLINE)
   endif()
 endif()
 
-# OpenSSL
-find_package(OpenSSL REQUIRED)
-
 set(libs_dir ${CMAKE_SOURCE_DIR}/libs)
 add_subdirectory(libs EXCLUDE_FROM_ALL)
 
-include_directories(SYSTEM ${GFLAGS_INCLUDE_DIR})
-include_directories(SYSTEM ${GLOG_INCLUDE_DIR})
-include_directories(SYSTEM ${FMT_INCLUDE_DIR})
-include_directories(SYSTEM ${ANTLR4_INCLUDE_DIR})
-include_directories(SYSTEM ${BZIP2_INCLUDE_DIR})
-include_directories(SYSTEM ${ZLIB_INCLUDE_DIR})
-include_directories(SYSTEM ${ROCKSDB_INCLUDE_DIR})
-include_directories(SYSTEM ${CAPNP_INCLUDE_DIR})
-# -----------------------------------------------------------------------------
-
-# openCypher parser -----------------------------------------------------------
-set(opencypher_frontend ${CMAKE_SOURCE_DIR}/src/query/frontend/opencypher)
-set(opencypher_generated ${opencypher_frontend}/generated)
-set(opencypher_grammar ${opencypher_frontend}/grammar/Cypher.g4)
-
-# enumerate all files that are generated from antlr
-set(antlr_opencypher_generated_src
-   ${opencypher_generated}/CypherLexer.cpp
-   ${opencypher_generated}/CypherParser.cpp
-   ${opencypher_generated}/CypherBaseVisitor.cpp
-   ${opencypher_generated}/CypherVisitor.cpp
-)
-
-# Provide a command to generate sources if missing. If this were a
-# custom_target, it would always run and we don't want that.
-add_custom_command(OUTPUT ${antlr_opencypher_generated_src}
-  COMMAND
-  ${CMAKE_COMMAND} -E make_directory ${opencypher_generated}
-  COMMAND
-  java -jar ${CMAKE_SOURCE_DIR}/libs/antlr-4.6-complete.jar -Dlanguage=Cpp -visitor -o ${opencypher_generated} -package antlropencypher ${opencypher_grammar}
-  WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
-  DEPENDS ${opencypher_grammar})
-
-# add custom target for generation
-add_custom_target(generate_opencypher_parser
-  DEPENDS ${antlr_opencypher_generated_src})
-
-add_library(antlr_opencypher_parser_lib STATIC ${antlr_opencypher_generated_src})
-target_link_libraries(antlr_opencypher_parser_lib antlr4)
-# -----------------------------------------------------------------------------
-
 # Optional subproject configuration -------------------------------------------
-option(POC "Build proof of concept binaries" OFF)
-option(EXPERIMENTAL "Build experimental binaries" OFF)
-option(CUSTOMERS "Build customer binaries" OFF)
 option(TEST_COVERAGE "Generate coverage reports from running memgraph" OFF)
 option(TOOLS "Build tools binaries" ON)
+option(QUERY_MODULES "Build query modules containing custom procedures" ON)
 option(ASAN "Build with Address Sanitizer. To get a reasonable performance option should be used only in Release or RelWithDebInfo build " OFF)
 option(TSAN "Build with Thread Sanitizer. To get a reasonable performance option should be used only in Release or RelWithDebInfo build " OFF)
 option(UBSAN "Build with Undefined Behaviour Sanitizer" OFF)
-option(THIN_LTO "Build with link time optimization" OFF)
 
 if (TEST_COVERAGE)
   string(TOLOWER ${CMAKE_BUILD_TYPE} lower_build_type)
@@ -204,6 +234,10 @@ if (TEST_COVERAGE)
   set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fprofile-instr-generate -fcoverage-mapping")
 endif()
 
+if (MG_ENTERPRISE)
+  add_definitions(-DMG_ENTERPRISE)
+endif()
+
 if (ASAN)
   # Enable Addres sanitizer and get nicer stack traces in error messages.
   # NOTE: AddressSanitizer uses llvm-symbolizer binary from the Clang
@@ -255,26 +289,12 @@ if (UBSAN)
   # Make sure llvm-symbolizer binary is in path
 endif()
 
-if (THIN_LTO)
-  set(CMAKE_CXX_FLAGS"${CMAKE_CXX_FLAGS} -flto=thin")
-  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto=thin")
-endif()
-
 # Add subprojects
 include_directories(src)
 add_subdirectory(src)
 
-if(POC)
-  add_subdirectory(poc)
-endif()
-
-if(EXPERIMENTAL)
-  add_subdirectory(experimental)
-endif()
-
-if(CUSTOMERS)
-  add_subdirectory(customers)
-endif()
+# Release configuration
+add_subdirectory(release)
 
 enable_testing()
 add_subdirectory(tests)
@@ -283,58 +303,6 @@ if(TOOLS)
   add_subdirectory(tools)
 endif()
 
-# -----------------------------------------------------------------------------
-
-# ---- Setup CPack --------
-# General setup
-set(CPACK_PACKAGE_NAME memgraph)
-set(CPACK_PACKAGE_VENDOR "Memgraph Ltd.")
-set(CPACK_PACKAGE_DESCRIPTION_SUMMARY
-    "High performance, in-memory, transactional graph database")
-set(CPACK_PACKAGE_VERSION_MAJOR ${memgraph_VERSION_MAJOR})
-set(CPACK_PACKAGE_VERSION_MINOR ${memgraph_VERSION_MINOR})
-set(CPACK_PACKAGE_VERSION_PATCH ${memgraph_VERSION_PATCH})
-set(CPACK_PACKAGE_VERSION_TWEAK ${memgraph_VERSION_TWEAK})
-set(CPACK_PACKAGE_FILE_NAME ${CPACK_PACKAGE_NAME}-${memgraph_VERSION}-${COMMIT_HASH}${CPACK_SYSTEM_NAME})
-
-# DEB specific
-# Instead of using "name <email>" format, we use "email (name)" to prevent
-# errors due to full stop, '.' at the end of "Ltd". (See: RFC 822)
-set(CPACK_DEBIAN_PACKAGE_MAINTAINER "tech@memgraph.com (Memgraph Ltd.)")
-set(CPACK_DEBIAN_PACKAGE_SECTION non-free/database)
-set(CPACK_DEBIAN_PACKAGE_HOMEPAGE https://memgraph.com)
-set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
-    "${CMAKE_SOURCE_DIR}/release/debian/conffiles;"
-    "${CMAKE_SOURCE_DIR}/release/debian/copyright;"
-    "${CMAKE_SOURCE_DIR}/release/debian/prerm;"
-    "${CMAKE_SOURCE_DIR}/release/debian/postrm;"
-    "${CMAKE_SOURCE_DIR}/release/debian/postinst;")
-set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
-# Description formatting is important, summary must be followed with a newline and 1 space.
-set(CPACK_DEBIAN_PACKAGE_DESCRIPTION "${CPACK_PACKAGE_DESCRIPTION_SUMMARY}
- Contains Memgraph, the graph database. It aims to deliver developers the
- speed, simplicity and scale required to build the next generation of
- applications driver by real-time connected data.")
-# Add `openssl` package to dependencies list. Used to generate SSL certificates.
-set(CPACK_DEBIAN_PACKAGE_DEPENDS "openssl (>= 1.1.0)")
-
-# RPM specific
-set(CPACK_RPM_PACKAGE_URL https://memgraph.com)
-set(CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION
-  /var /var/lib /var/log /etc/logrotate.d
-  /lib /lib/systemd /lib/systemd/system /lib/systemd/system/memgraph.service)
-set(CPACK_RPM_PACKAGE_REQUIRES_PRE "shadow-utils")
-# NOTE: user specfile has a bug in cmake 3.7.2, this needs to be patched
-# manually in: ~/cmake/share/cmake-3.7/Modules/CPackRPM.cmake line 2273
-# Or newer cmake version used
-set(CPACK_RPM_USER_BINARY_SPECFILE "${CMAKE_SOURCE_DIR}/release/rpm/memgraph.spec.in")
-# Description formatting is important, no line must be greater than 80 characters.
-set(CPACK_RPM_PACKAGE_DESCRIPTION "Contains Memgraph, the graph database.
-It aims to deliver developers the speed, simplicity and scale required to build
-the next generation of applications driver by real-time connected data.")
-# Add `openssl` package to dependencies list. Used to generate SSL certificates.
-set(CPACK_RPM_PACKAGE_REQUIRES "openssl >= 1.0.0")
-
-# All variables must be set before including.
-include(CPack)
-# ---- End Setup CPack ----
+if(QUERY_MODULES)
+  add_subdirectory(query_modules)
+endif()

CODEOWNERS

@@ -0,0 +1,4 @@
+/docs/ @gitbuda
+/src/communication/ @antonio2368
+/src/query/ @the-joksim
+/src/storage/ @antonio2368

Doxyfile

@@ -51,7 +51,7 @@ PROJECT_BRIEF          = "The World's Most Powerful Graph Database"
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = Doxylogo.png
+PROJECT_LOGO           = docs/doxygen/memgraph_logo.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -839,7 +839,6 @@ EXCLUDE_PATTERNS      += */Testing/*
 EXCLUDE_PATTERNS      += */tests/*
 EXCLUDE_PATTERNS      += */dist/*
 EXCLUDE_PATTERNS      += */tools/*
-EXCLUDE_PATTERNS      += */customers/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

README.md

@@ -1,24 +1,47 @@
-# memgraph
+# Memgraph
 
 Memgraph is an ACID compliant high performance transactional distributed
 in-memory graph database featuring runtime native query compiling, lock free
 data structures, multi-version concurrency control and asynchronous IO.
 
-## dependencies
+## Development Documentation
 
-Memgraph can be compiled using any modern c++ compiler. It mostly relies on
-the standard template library, however, some things do require external
-libraries.
+* [Quick Start](docs/dev/quick-start.md)
+* [Workflow](docs/dev/workflow.md)
+* [Storage](docs/dev/storage/v2/contents.md)
+* [Query Engine](docs/dev/query/contents.md)
+* [Communication](docs/dev/communication/contents.md)
+* [Lisp C++ Preprocessor (LCP)](docs/dev/lcp.md)
 
-Some code contains linux-specific libraries and the build is only supported
-on a 64 bit linux kernel.
+## Feature Specifications
 
-* linux
-* clang 3.8 (good c++11 support, especially lock free atomics)
-* antlr (compiler frontend)
-* cppitertools
-* fmt format
-* google benchmark
-* google test
-* glog
-* gflags
+Each prominent Memgraph feature requires a feature specification. The purpose
+of the feature specification is to have a base for discussing all aspects of
+the feature. Elements of feature specifications should be:
+
+* High-level context.
+* Interface.
+* User stories. Usage from the end-user perspective. In the case of a library,
+  that should be cases on how to use the programming interface. In the case of
+a shell script, that should be cases on how to use flags.
+* Discussion about concurrency, memory management, error management.
+* Any other essential functional or non-functional requirements.
+* Test and benchmark strategy.
+* Possible future changes/improvements/extensions.
+* Security concerns.
+* Additional and/or optional implementation details.
+
+It's crucial to keep feature spec up-to-date with the implementation. Take a
+look at the list of [feature specifications](docs/feature_spec/contents.md) to
+learn more about powerful Memgraph features.
+
+## User Documentation
+
+Memgraph user documentation is maintained within
+[docs](https://github.com/memgraph/docs) repository. The documentation is also
+available on [GitBook](https://docs.memgraph.com).
+
+## Licences
+
+* [Community](release/LICENSE_COMMUNITY.md)
+* [Enterprise](release/LICENSE_ENTERPRISE.md)

apollo_archives.py

@@ -1,39 +0,0 @@
-#!/usr/bin/env python3
-import json
-import os
-import re
-import subprocess
-import sys
-
-# paths
-SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__))
-BUILD_OUTPUT_DIR = os.path.normpath(os.path.join(SCRIPT_DIR, "build_release", "output"))
-
-# helpers
-def run_cmd(cmd, cwd):
-    return subprocess.run(cmd, cwd=cwd, check=True,
-        stdout=subprocess.PIPE).stdout.decode("utf-8")
-
-# check project
-if re.search(r"release", os.environ.get("PROJECT", "")) is None:
-    print(json.dumps([]))
-    sys.exit(0)
-
-# generate archive
-deb_name = run_cmd(["find", ".", "-maxdepth", "1", "-type", "f",
-        "-name", "memgraph*.deb"], BUILD_OUTPUT_DIR).split("\n")[0][2:]
-arch = run_cmd(["dpkg", "--print-architecture"], BUILD_OUTPUT_DIR).split("\n")[0]
-version = deb_name.split("-")[1]
-# generate Debian package file name as expected by Debian Policy
-standard_deb_name = "memgraph_{}-1_{}.deb".format(version, arch)
-
-archive_path = os.path.relpath(os.path.join(BUILD_OUTPUT_DIR,
-        deb_name), SCRIPT_DIR)
-
-archives = [{
-    "name": "Release (deb package)",
-    "archive": archive_path,
-    "filename": standard_deb_name,
-}]
-
-print(json.dumps(archives, indent=4, sort_keys=True))

apollo_archives.yaml

@@ -1,19 +0,0 @@
-- name: Binaries
-  archive:
-    - build_debug/memgraph
-    - build_release/memgraph
-    - build_release/tools/src/mg_import_csv
-    - config
-  filename: binaries.tar.gz
-
-- name: Doxygen documentation
-  cd: docs/doxygen/html
-  archive:
-    - .
-  filename: documentation.tar.gz
-  host: true
-
-- name: Release (user docs)
-  project: ^NEVER$ # TODO (mferencevic): replace with 'release' once user documentation creation is fixed (couscous -> pandoc)
-  archive: docs/user_technical/docs.tar.gz
-  filename: release_user_docs.tar.gz

apollo_build.yaml

@@ -1,85 +0,0 @@
-- name: Diff build
-  project: ^mg-master-diff$
-  commands: |
-    # Copy untouched repository to parent folder.
-    cd ..
-    cp -r memgraph parent
-    cd memgraph
-
-    # Initialize and create documentation.
-    TIMEOUT=1200 ./init
-    doxygen Doxyfile
-
-    # Remove default build directory.
-    rm -r build
-
-    # Build debug binaries.
-    mkdir build_debug
-    cd build_debug
-    cmake ..
-    TIMEOUT=1200 make -j$THREADS
-
-    # Build coverage binaries.
-    cd ..
-    mkdir build_coverage
-    cd build_coverage
-    cmake -DTEST_COVERAGE=ON ..
-    TIMEOUT=1200 make -j$THREADS memgraph__unit
-
-    # Build release binaries.
-    cd ..
-    mkdir build_release
-    cd build_release
-    cmake -DCMAKE_BUILD_TYPE=release ..
-    TIMEOUT=1200 make -j$THREADS memgraph tools memgraph__macro_benchmark memgraph__stress memgraph__manual__card_fraud_generate_snapshot
-
-    # Checkout to parent commit and initialize.
-    cd ../../parent
-    git checkout HEAD~1
-    TIMEOUT=1200 ./init
-
-    # Build parent release binaries.
-    mkdir build_release
-    cd build_release
-    cmake -DCMAKE_BUILD_TYPE=release ..
-    TIMEOUT=1200 make -j$THREADS memgraph memgraph__macro_benchmark
-
-
-# release build is the default one
-- name: Release build
-  commands: |
-    TIMEOUT=1200 ./init
-    doxygen Doxyfile
-
-    # Remove default build directory.
-    rm -r build
-
-    # Build debug binaries.
-    mkdir build_debug
-    cd build_debug
-    cmake ..
-    TIMEOUT=1200 make -j$THREADS
-
-    # Build coverage binaries.
-    cd ..
-    mkdir build_coverage
-    cd build_coverage
-    cmake -DTEST_COVERAGE=ON ..
-    TIMEOUT=1200 make -j$THREADS memgraph__unit
-
-    # Build release binaries.
-    cd ..
-    mkdir build_release
-    cd build_release
-    cmake -DCMAKE_BUILD_TYPE=Release -DUSE_READLINE=OFF ..
-    TIMEOUT=1200 make -j$THREADS
-
-    # Create Debian package.
-    mkdir output
-    cd output
-    cpack -G DEB --config ../CPackConfig.cmake
-
-    # Create user technical documentation for community site.
-    cd ../../docs/user_technical
-    # TODO (mferencevic): uncomment this once couscous is replaced with pandoc
-    #./bundle_community

cmake/FindSeccomp.cmake

@@ -0,0 +1,90 @@
+#.rst:
+# FindSeccomp
+# -----------
+#
+# Try to locate the libseccomp library.
+# If found, this will define the following variables:
+#
+# ``Seccomp_FOUND``
+#     True if the seccomp library is available
+# ``Seccomp_INCLUDE_DIRS``
+#     The seccomp include directories
+# ``Seccomp_LIBRARIES``
+#     The seccomp libraries for linking
+#
+# If ``Seccomp_FOUND`` is TRUE, it will also define the following
+# imported target:
+#
+# ``Seccomp::Seccomp``
+#     The Seccomp library
+#
+# Since 5.44.0.
+
+#=============================================================================
+# Copyright (c) 2017 Martin Flöser <mgraesslin@kde.org>
+# Copyright (c) 2017 David Kahles <david.kahles96@gmail.com>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#=============================================================================
+
+find_package(PkgConfig QUIET)
+pkg_check_modules(PKG_Libseccomp QUIET libseccomp)
+
+find_path(Seccomp_INCLUDE_DIRS
+    NAMES
+        seccomp.h
+    HINTS
+        ${PKG_Libseccomp_INCLUDE_DIRS}
+)
+find_library(Seccomp_LIBRARIES
+    NAMES
+        seccomp
+    HINTS
+        ${PKG_Libseccomp_LIBRARY_DIRS}
+)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(Seccomp
+    FOUND_VAR
+        Seccomp_FOUND
+    REQUIRED_VARS
+        Seccomp_LIBRARIES
+        Seccomp_INCLUDE_DIRS
+)
+
+if (Seccomp_FOUND AND NOT TARGET Seccomp::Seccomp)
+    add_library(Seccomp::Seccomp UNKNOWN IMPORTED)
+    set_target_properties(Seccomp::Seccomp PROPERTIES
+        IMPORTED_LOCATION "${Seccomp_LIBRARIES}"
+        INTERFACE_INCLUDE_DIRECTORIES "${Seccomp_INCLUDE_DIRS}"
+    )
+endif()
+
+mark_as_advanced(Seccomp_LIBRARIES Seccomp_INCLUDE_DIRS)
+
+include(FeatureSummary)
+set_package_properties(Seccomp PROPERTIES
+    URL "https://github.com/seccomp/libseccomp"
+    DESCRIPTION "The enhanced seccomp library."
+)

config/benchmarking.conf

@@ -1,19 +0,0 @@
-# MEMGRAPH DEFAULT BENCHMARKING CONFIG
-
-# NOTE: all paths are relative to the run folder
-# (where the executable is run)
-
-# no durability
---durability-enabled=false
---snapshot-on-exit=false
---db-recover-on-startup=false
-
-# no GC
---gc-cycle-sec=-1
---skiplist_gc_interval=-1
-
-# no query execution time limit
---query_execution_time_sec=-1
-
-# number of workers
---num-workers=1

config/community.conf

@@ -1,122 +0,0 @@
-# Default Memgraph Configuration
-#
-# This is the default configuration for memgraph. Settings from this file will
-# be overridden by a configuration file in '$HOME/.memgraph/config', so you can
-# keep this file intact. Additional configuration can be specified in a file
-# pointed to by 'MEMGRAPH_CONFIG' environment variable or by passing arguments
-# on the command line.
-#
-# Each configuration setting is of the form: '--setting-name=value'.
-
-## Database
-
-# IP address the server should listen on.
---interface=0.0.0.0
-
-# Port the server should listen on.
---port=7687
-
-# Path to a SSL certificate file that should be used.
---cert-file=/etc/memgraph/ssl/cert.pem
-
-# Path to a SSL key file that should be used.
---key-file=/etc/memgraph/ssl/key.pem
-
-# Number of workers used by the Memgraph server. By default, this will be the
-# number of processing units available on the machine.
-# --num-workers=8
-
-# Interval, in seconds, when the garbage collection (GC) should run. GC is used
-# for releasing memory that is no longer needed. For example, deleted graph
-# elements which cannot be seen by any running or new transactions. If set to
-# -1 the GC will never run (use with caution, memory will never get released).
---gc-cycle-sec=30
-
-# If Memgraph detects there is less available RAM than the given number in MB,
-# it will log a warning.
---memory-warning-threshold=1024
-
-# The telemetry collects data about the machine that is executing the database
-# (CPU, Memory, OS and Kernel Information) and data about the database runtime
-# (CPU usage, Memory usage, Vertices and Edges count). It is used to provide a
-# better product, easy to disable and does not collect any sensitive data.
---telemetry-enabled=true
-
-# Memgraph offers an option to store a certain amount of data on a disk. More
-# precisely, the user can pass a list of properties they wish to keep stored on
-# a disk. The property names have to be separated with a comma. An example
-# would be --properties-on-disk=biography,summary.
-#--properties-on-disk=
-
-## Ids
-
-# Memgraph can generate an identifier for each vertex or edge. The
-# generated ids are returned with the id function.
-
-# Memgraph can generate an identifier for each vertex.
---generate-vertex-ids=true
-
-# Memgraph can generate an identifier for each edge.
---generate-edge-ids=true
-
-## Query
-#
-# Various settings related to openCypher query execution.
-
-# Maximum allowed query execution time, in seconds. Any queries exceeding this
-# limit will be aborted. Setting to -1 removes the limit.
---query-execution-time-sec=30
-
-# Cache generated query execution plans. This speeds up planning repeated
-# queries which produce multiple complex execution plans. The downside is that
-# some executions may use inferior plans if the database state changed. To
-# disable caching, set to false.
-#--query-plan-cache=false
-
-# Time to live for cached query plans, in seconds. This tries to minimize the
-# downside of caching by evicting old plans after the given time.
-#--query-plan-cache-ttl=60
-
-## Durability
-#
-# Memgraph can store database state to persistent storage. Two mechanisms
-# are used: snapshots store the total current database state while write-ahead
-# logs store small changes incrementally. They are used in tandem to provide
-# fast and storage-efficient persistence. Some aspects of snapshot taking
-# are configurable, while write-ahead logging is pre-configured for optimal
-# performance.
---durability-enabled=true
-
-# Path to the directory where snapshots and write-ahead log files will be stored.
---durability-directory=/var/lib/memgraph/durability
-
-# Recover the database on startup.
---db-recover-on-startup=true
-
-# Interval of taking snapshots, in seconds. If set to -1, the snapshot feature
-# will be turned off.
---snapshot-cycle-sec=300
-
-# Create a snapshot when closing Memgraph.
---snapshot-on-exit=true
-
-# Maximum number of kept snapshots. Old snapshots will be deleted to make room
-# for new ones. If set to -1, the number of kept snapshots is unlimited.
---snapshot-max-retained=3
-
-## Logging
-
-# Path to where the log should be stored.
---log-file=/var/log/memgraph/memgraph.log
-
-# If true, log messages will go to stderr in addition to logfiles.
-#--also-log-to-stderr=true
-
-## Additional Configuration Inclusion
-
-# Include additional configuration from this file. Settings with the same name
-# will override previously read values. Note, that reading the configuration,
-# which called '--flag-file' will continue after inclusion. Therefore, settings
-# after '--flag-file' may override the included ones.
-#--flag-file=another.conf
-

config/durability_stress.conf

@@ -1,15 +0,0 @@
-# MEMGRAPH DEFAULT DURABILITY STRESS TESTING CONFIG
-
-# NOTE: all paths are relative to the run folder
-# (where the executable is run)
-
-# enable durability
---durability-enabled=true
---snapshot-cycle-sec=5
---snapshot-on-exit=false
---snapshot-max-retained=2
-
---db-recover-on-startup=true
-
-# increase query timeout (10 min)
---query-execution-time-sec=600

config/flags.yaml

@@ -0,0 +1,93 @@
+header: >-
+  Memgraph Configuration
+
+  This is the main configuration file for Memgraph. You can modify this file to
+  suit your specific needs. Additional configuration can be specified by
+  including another configuration file, in a file pointed to by the
+  'MEMGRAPH_CONFIG' environment variable or by passing arguments on the command
+  line.
+
+  Each configuration setting is in the form: '--setting-name=value'.
+
+footer: >-
+  Additional Configuration Inclusion
+
+  You can include additional configuration files from this file. Additional
+  files are processed after this file. Settings that are set in the additional
+  files will override previously set values. Additional configuration files are
+  specified with the '--flag-file' flag.
+
+  Example:
+
+  --flag-file=another.conf
+
+modifications:
+
+  # Each modification should consist of the following parameters:
+  #   * name: the name of the flag that should be modified (with underscores)
+  #           [string]
+  #   * value: the value that should be set instead of the binary provided
+  #            default value [string]
+  #   * override: set to `true` to uncomment the config option by default
+  #               [boolean]
+
+  - name: "data_directory"
+    value: "/var/lib/memgraph"
+    override: true
+
+  - name: "log_file"
+    value: "/var/log/memgraph/memgraph.log"
+    override: true
+
+  - name: "bolt_num_workers"
+    value: ""
+    override: false
+
+  - name: "storage_properties_on_edges"
+    value: "true"
+    override: true
+
+  - name: "storage_recover_on_startup"
+    value: "true"
+    override: true
+
+  - name: "storage_snapshot_interval_sec"
+    value: "300"
+    override: true
+
+  - name: "storage_snapshot_on_exit"
+    value: "true"
+    override: true
+
+  - name: "storage_snapshot_retention_count"
+    value: "3"
+    override: true
+
+  - name: "storage_wal_enabled"
+    value: "true"
+    override: true
+
+  - name: "telemetry_enabled"
+    value: "true"
+    override: true
+
+  - name: "query_modules_directory"
+    value: "/usr/lib/memgraph/query_modules"
+    override: true
+
+  - name: "auth_module_executable"
+    value: "/usr/lib/memgraph/auth_module/example.py"
+    override: false
+
+undocumented:
+  - "flag_file"
+  - "log_file_mode"
+  - "log_link_basename"
+  - "log_prefix"
+  - "max_log_size"
+  - "min_log_level"
+  - "help"
+  - "help_xml"
+  - "stderr_threshold"
+  - "stop_logging_if_full_disk"
+  - "version"

config/generate.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+import argparse
+import copy
+import os
+import subprocess
+import sys
+import textwrap
+
+import xml.etree.ElementTree as ET
+
+import yaml
+
+
+SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__))
+CONFIG_FILE = os.path.join(SCRIPT_DIR, "flags.yaml")
+WIDTH = 80
+
+
+def wrap_text(s, initial_indent="# "):
+    return "\n#\n".join(
+        map(lambda x: textwrap.fill(x, WIDTH, initial_indent=initial_indent,
+                                    subsequent_indent="# "), s.split("\n")))
+
+
+def extract_flags(binary_path):
+    ret = {}
+    data = subprocess.run([binary_path, "--help-xml"],
+                          stdout=subprocess.PIPE).stdout.decode("utf-8")
+    root = ET.fromstring(data)
+    for child in root:
+        if child.tag == "usage" and child.text.lower().count("warning"):
+            raise Exception("You should set the usage message!")
+        if child.tag == "flag":
+            flag = {}
+            for elem in child:
+                flag[elem.tag] = elem.text if elem.text is not None else ""
+            flag["override"] = False
+            ret[flag["name"]] = flag
+    return ret
+
+
+def apply_config_to_flags(config, flags):
+    flags = copy.deepcopy(flags)
+    for name in config["undocumented"]:
+        flags.pop(name)
+    for modification in config["modifications"]:
+        name = modification["name"]
+        if name not in flags:
+            print("WARNING: Flag '" + name + "' missing from binary!",
+                  file=sys.stderr)
+            continue
+        flags[name]["default"] = modification["value"]
+        flags[name]["override"] = modification["override"]
+    return flags
+
+
+def extract_sections(flags):
+    sections = []
+    other = []
+    current_section = ""
+    current_flags = []
+    for name in sorted(flags.keys()):
+        section = name.split("_")[0]
+        if section == current_section:
+            current_flags.append(name)
+        else:
+            if len(current_flags) < 2:
+                other.extend(current_flags)
+            else:
+                sections.append((current_section, current_flags))
+            current_section = section
+            current_flags = [name]
+    if len(current_flags) < 2:
+        other.extend(current_flags)
+    else:
+        sections.append((current_section, current_flags))
+    sections.append(("other", other))
+    assert set(sum(map(lambda x: x[1], sections), [])) == set(flags.keys()), \
+        "The section extraction algorithm lost some flags!"
+    return sections
+
+
+def generate_config_file(sections, flags):
+    ret = wrap_text(config["header"]) + "\n\n\n"
+    for section, section_flags in sections:
+        ret += wrap_text(section.capitalize(), initial_indent="## ") + "\n\n"
+        for name in section_flags:
+            flag = flags[name]
+            helpstr = flag["meaning"] + " [" + flag["type"] + "]"
+            ret += wrap_text(helpstr) + "\n"
+            prefix = "# " if not flag["override"] else ""
+            ret += prefix + "--" + flag["name"].replace("_", "-") + \
+                "=" + flag["default"] + "\n\n"
+        ret += "\n"
+    ret += wrap_text(config["footer"])
+    return ret.strip() + "\n"
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("memgraph_binary",
+                        help="path to Memgraph binary")
+    parser.add_argument("output_file",
+                        help="path where to store the generated Memgraph "
+                        "configuration file")
+    parser.add_argument("--config-file", default=CONFIG_FILE,
+                        help="path to generator configuration file")
+
+    args = parser.parse_args()
+    flags = extract_flags(args.memgraph_binary)
+
+    with open(args.config_file) as f:
+        config = yaml.safe_load(f)
+
+    flags = apply_config_to_flags(config, flags)
+    sections = extract_sections(flags)
+    data = generate_config_file(sections, flags)
+
+    dirname = os.path.dirname(args.output_file)
+    if dirname and not os.path.exists(dirname):
+        os.makedirs(dirname)
+
+    with open(args.output_file, "w") as f:
+        f.write(data)

config/stress.conf

@@ -1,15 +0,0 @@
-# MEMGRAPH DEFAULT STRESS TESTING CONFIG
-
-# NOTE: all paths are relative to the run folder
-# (where the executable is run)
-
-# enable durability
---durability-enabled=true
---snapshot-cycle-sec=600
---snapshot-on-exit=true
---snapshot-max-retained=1
-
---db-recover-on-startup=false
-
-# increase query timeout (10 min)
---query-execution-time-sec=600

config/testing.conf

@@ -1,9 +0,0 @@
-# MEMGRAPH DEFAULT TESTING CONFIG
-
-# NOTE: all paths are relative to the run folder
-# (where the executable is run)
-
-# no durability
---durability-enabled=false
---snapshot-on-exit=false
---db-recover-on-startup=false

customers/CMakeLists.txt

@@ -1,2 +0,0 @@
-project(mg_customers)
-add_subdirectory(otto)

customers/elliott/README_internal.md

@@ -1,70 +0,0 @@
-DISCLAIMER: this is just an initial test, graph might not resemble
-the graph in the use case at all and the data might be completely
-irrelevant.
-
-We tried generating a few sample graphs from the vague description
-given in the use case doc. Then we tried writing queries that would
-solve the problem of updating nodes when a leaf value changes,
-assuming all the internal nodes compute only the sum function.
-
-We start by creating an index on `id` property to improve initial lookup
-performance:
-
-    CREATE INDEX ON :Leaf(id)
-
-Set values of all leafs to 1:
-
-    MATCH (u:Leaf) SET u.value = 1
-
-Now we initialize the values of all other nodes in the graph:
-
-    MATCH (u) WHERE NOT u:Leaf SET u.value = 0
-
-    MATCH (u) WITH u
-    ORDER BY u.topological_index DESC
-    MATCH (u)-->(v) SET u.value = u.value + v.value
-
-Change the value of a leaf:
-
-    MATCH (u:Leaf {id: "18"}) SET u.value = 10
-
-We have to reset all the updated nodes to a neutral element:
-
-    MATCH (u:Leaf {id: "18"})<-[* bfs]-(v)
-    WHERE NOT v:Leaf SET v.value = 0
-
-Finally, we recalculate their values in topological order:
-
-    MATCH (u:Leaf {id: "18"})<-[* bfs]-(v)
-    WITH v ORDER BY v.topological_index DESC
-    MATCH (v)-->(w) SET v.value = v.value + w.value
-
-There are a few assumptions made worth pointing out.
-
-* We are able to efficiently maintain topological order
-  of vertices in the graph.
-
-* It is possible to accumulate the value of the function.  Formally: 
-  $$f(x_1, x_2, ..., x_n) = g(...(g(g(x_1, x_2), x_3), ...), x_n)$$
-
-* There is a neutral element for the operation. However, this
-  assumption can be dropped by introducing an artificial neutral element.
-
-Number of operations required is proportional to the sum of degrees of affected
-nodes.
-
-We generated graph with $10^5$ nodes ($20\ 000$ nodes in each layer),  varied the
-degree distribution in node layers and measured time for the query to execute:
-
-| # |  Root-Category-Group degree | Group-CustomGroup-Leaf degree |   Time    |
-|:-:|:---------------------------:|:-----------------------------:|:---------:|
-| 1 |            [1, 10]          |           [20, 40]            |   ~1.1s   |
-| 2 |            [1, 10]          |          [50, 100]            |   ~2.5s   |
-| 3 |           [10, 50]          |          [50, 100]            |   ~3.3s   |
-
-Due to the structure of the graph, update of a leaf required update of almost
-all the nodes in the graph so we don't show times required for initial graph
-update and update after leaf change separately.
-
-However, there is not enough info on the use case to make the test more
-sophisticated.

customers/elliott/README_public.md

@@ -1,71 +0,0 @@
----
-title: "Elliott Management"
-subtitle: "Proof of Concept Report"
-header-title: "Elliott Management POC"
-date: 2017-10-28
-copyright: "©2017 Memgraph Ltd. All rights reserved."
-titlepage: true
-titlepage-color: FFFFFF
-titlepage-text-color: 101010
-titlepage-rule-color: 101010
-titlepage-rule-height: 1
-...
-
-# Introduction
-
-We tried generating a few sample graphs from the description given at
-the in-person meetings.  Then, we tried writing queries that would solve
-the problem of updating nodes when a leaf value changes, assuming all the
-internal nodes compute only the sum function.
-
-# Technical details
-
-We started by creating an index on `id` property to improve initial lookup
-performance:
-
-    CREATE INDEX ON :Leaf(id)
-
-Afther that, we set values of all leafs to 1:
-
-    MATCH (u:Leaf) SET u.value = 1
-
-We then initialized the values of all other nodes in the graph:
-
-    MATCH (u) WHERE NOT u:Leaf SET u.value = 0
-
-    MATCH (u) WITH u
-    ORDER BY u.topological_index DESC
-    MATCH (u)-->(v) SET u.value = u.value + v.value
-
-Leaf value change and update of affected values in the graph can
-be done using three queries. To change the value of a leaf:
-
-    MATCH (u:Leaf {id: "18"}) SET u.value = 10
-
-Then we had to reset all the affected nodes to the neutral element:
-
-    MATCH (u:Leaf {id: "18"})<-[* bfs]-(v)
-    WHERE NOT v:Leaf SET v.value = 0
-
-Finally, we recalculated their values in topological order:
-
-    MATCH (u:Leaf {id: "18"})<-[* bfs]-(v)
-    WITH v ORDER BY v.topological_index DESC
-    MATCH (v)-->(w) SET v.value = v.value + w.value
-
-There are a few assumptions necessary for the approach above to work.
-
-* We are able to maintain topological order of vertices during graph
-  structure changes.  
-
-* It is possible to accumulate the value of the function.  Formally: 
-  $$f(x_1, x_2, ..., x_n) = g(...(g(g(x_1, x_2), x_3), ...), x_n)$$
-
-* There is a neutral element for the operation. However, this
-  assumption can be dropped by introducing an artificial neutral element.
-
-Above assumptions could be changed, relaxed or dropped, depending on the
-specifics of the use case.
-
-Number of operations required is proportional to the sum of degrees of affected
-nodes. 

customers/elliott/commands.txt

@@ -1,12 +0,0 @@
-CREATE INDEX ON :Leaf(id);
-MATCH (u:Leaf) SET u.value = 1;
-MATCH (u) WHERE NOT u:Leaf SET u.value = 0;
-MATCH (u) WITH u 
-ORDER BY u.topological_index DESC
-MATCH (u)-->(v) SET u.value = u.value + v.value;
-MATCH (u:Leaf {id: "85000"}) SET u.value = 10;
-MATCH (u:Leaf {id: "85000"})<-[* bfs]-(v) 
-WHERE NOT v:Leaf SET v.value = 0;
-MATCH (u:Leaf {id: "85000"})<-[* bfs]-(v)
-WITH v ORDER BY v.topological_index DESC
-MATCH (v)-->(w) SET v.value = v.value + w.value;

customers/elliott/generate_dag

@@ -1,125 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""Generates a DAG from JSON spec in [config] and outputs nodes to
-[filename]_nodes, and edges to [filename]_edges in format convertible
-to Memgraph snapshot.
-
-Here's an example JSON spec:
-
-    {
-        "layers": [
-            {
-                "name": "A",
-                "sublayers": 1,
-                "degree_lo": 1,
-                "degree_hi": 3,
-                "nodes": 4
-            },
-            {
-                "name": "B",
-                "sublayers": 3,
-                "degree_lo": 2,
-                "degree_hi": 3,
-                "nodes": 10
-            },
-            {
-                "name": "C",
-                "sublayers": 1,
-                "degree_lo": 1,
-                "degree_hi": 1,
-                "nodes": 5
-            }
-        ]
-    }
-
-Nodes from each layer will be randomly divided into sublayers.  A node can
-only have edges pointing to nodes in lower sublayers of the same layer, or
-to nodes from the layer directly below it. Out-degree is chosen uniformly
-random from [degree_lo, degree_hi] interval."""
-
-import argparse
-from itertools import accumulate
-import json
-import random
-
-
-def _split_into_sum(n, k):
-    assert 1 <= n, "n should be at least 1"
-    assert k <= n, "k shouldn't be greater than n"
-    xs = [0] + sorted(random.sample(range(1, n), k-1)) + [n]
-    return [b - a for a, b in zip(xs, xs[1:])]
-
-
-def generate_dag(graph_config, seed=None):
-    random.seed(seed)
-
-    nodes = []
-    edges = []
-
-    layer_lo = 1
-    for layer in graph_config:
-        sublayers = _split_into_sum(layer['nodes'], layer['sublayers'])
-        sub_range = accumulate([layer_lo] + sublayers)
-        layer['sublayer_range'] = list(sub_range)
-        nodes.extend([
-            (u, layer['name'])
-            for u in range(layer_lo, layer_lo + layer['nodes'])
-        ])
-        layer_lo += layer['nodes']
-
-    edges = []
-
-    for layer, next_layer in zip(graph_config, graph_config[1:]):
-        degree_lo = layer['degree_lo']
-        degree_hi = layer['degree_hi']
-
-        sub_range = layer['sublayer_range']
-        sub_range_next = next_layer['sublayer_range']
-
-        layer_lo = sub_range[0]
-        next_layer_hi = sub_range_next[-1]
-
-        for sub_lo, sub_hi in zip(sub_range, sub_range[1:]):
-            for u in range(sub_lo, sub_hi):
-                num_edges = random.randint(degree_lo, degree_hi)
-                for _ in range(num_edges):
-                    v = random.randint(sub_hi, next_layer_hi - 1)
-                    edges.append((u, v))
-
-        for sub_lo, sub_hi in zip(sub_range_next, sub_range_next[1:]):
-            for u in range(sub_lo, sub_hi):
-                v = random.randint(layer_lo, sub_lo - 1)
-                edges.append((v, u))
-
-    return nodes, edges
-
-
-if __name__ == '__main__':
-    parser = argparse.ArgumentParser(
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        description=__doc__)
-    parser.add_argument('config', type=str, help='graph config JSON file')
-    parser.add_argument('filename', type=str,
-                        help='nodes will be stored to filename_nodes, '
-                        'edges to filename_edges')
-    parser.add_argument('--seed', type=int,
-                        help='seed for the random generator (default = '
-                        'current system time)')
-    args = parser.parse_args()
-
-    with open(args.config, 'r') as f:
-        graph_config = json.loads(f.read())['layers']
-
-    nodes, edges = generate_dag(graph_config, seed=args.seed)
-
-    #  print nodes into CSV file
-    with open('{}_nodes'.format(args.filename), 'w') as out:
-        out.write('nodeId:ID(Node),name,topological_index:Int,:LABEL\n')
-        for node_id, layer in nodes:
-            out.write('{0},{1}{0},{0},{1}\n'.format(node_id, layer))
-
-    # print edges into CSV file
-    with open('{}_edges'.format(args.filename), 'w') as out:
-        out.write(':START_ID(Node),:END_ID(Node),:TYPE\n')
-        for u, v in edges:
-            out.write('{},{},child\n'.format(u, v))

customers/elliott/graph1.json

@@ -1,39 +0,0 @@
-{
-    "layers": [
-        { 
-            "name": "Root",
-            "sublayers": 1,
-            "degree_lo": 1,
-            "degree_hi": 10,
-            "nodes": 20000
-        },
-        { 
-            "name": "Category",
-            "sublayers": 5,
-            "degree_lo": 1,
-            "degree_hi": 10,
-            "nodes": 20000
-        },
-        {   
-            "name": "Group",
-            "sublayers": 1,
-            "degree_lo": 20,
-            "degree_hi": 40,
-            "nodes": 20000
-        },
-        {
-            "name": "CustomGroup",
-            "sublayers": 15,
-            "degree_lo": 20,
-            "degree_hi": 40,
-            "nodes": 20000
-        },
-        { 
-            "name": "Leaf",
-            "sublayers": 1,
-            "degree_lo": 1,
-            "degree_hi": 1,
-            "nodes": 20000
-        }
-    ]
-}

customers/elliott/graph2.json

@@ -1,39 +0,0 @@
-{
-    "layers": [
-        { 
-            "name": "Root",
-            "sublayers": 1,
-            "degree_lo": 1,
-            "degree_hi": 10,
-            "nodes": 20000
-        },
-        { 
-            "name": "Category",
-            "sublayers": 5,
-            "degree_lo": 1,
-            "degree_hi": 10,
-            "nodes": 20000
-        },
-        {   
-            "name": "Group",
-            "sublayers": 1,
-            "degree_lo": 50,
-            "degree_hi": 100,
-            "nodes": 20000
-        },
-        {
-            "name": "CustomGroup",
-            "sublayers": 15,
-            "degree_lo": 50,
-            "degree_hi": 100,
-            "nodes": 20000
-        },
-        { 
-            "name": "Leaf",
-            "sublayers": 1,
-            "degree_lo": 50,
-            "degree_hi": 100,
-            "nodes": 20000
-        }
-    ]
-}

customers/elliott/graph3.json

@@ -1,39 +0,0 @@
-{
-    "layers": [
-        { 
-            "name": "Root",
-            "sublayers": 1,
-            "degree_lo": 10,
-            "degree_hi": 50,
-            "nodes": 20000
-        },
-        { 
-            "name": "Category",
-            "sublayers": 5,
-            "degree_lo": 10,
-            "degree_hi": 50,
-            "nodes": 20000
-        },
-        {   
-            "name": "Group",
-            "sublayers": 1,
-            "degree_lo": 50,
-            "degree_hi": 100,
-            "nodes": 20000
-        },
-        {
-            "name": "CustomGroup",
-            "sublayers": 15,
-            "degree_lo": 50,
-            "degree_hi": 100,
-            "nodes": 20000
-        },
-        { 
-            "name": "Leaf",
-            "sublayers": 1,
-            "degree_lo": 50,
-            "degree_hi": 100,
-            "nodes": 20000
-        }
-    ]
-}

customers/otto/CMakeLists.txt

@@ -1,3 +0,0 @@
-set(exec_name customers_otto_parallel_connected_components)
-add_executable(${exec_name} parallel_connected_components.cpp)
-target_link_libraries(${exec_name} memgraph_lib)

customers/otto/connected_components_test.py

@@ -1,118 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-This script attempts to evaluate the feasibility of using Memgraph for
-Otto group's usecase. The usecase is finding connected componentes in
-a large, very sparse graph (cca 220M nodes, 250M edges), based on a dynamic
-inclusion / exclusion of edges (w.r.t variable parameters and the source node
-type).
-
-This implementation defines a random graph with the given number of nodes
-and edges and looks for connected components using breadth-first expansion.
-Edges are included / excluded based on a simple expression, only demonstrating
-possible usage.
-"""
-
-from argparse import ArgumentParser
-import logging
-from time import time
-from collections import defaultdict
-from math import log2
-from random import randint
-
-from neo4j.v1 import GraphDatabase
-
-log = logging.getLogger(__name__)
-
-
-def generate_graph(sess, node_count, edge_count):
-    # An index that will speed-up edge creation.
-    sess.run("CREATE INDEX ON :Node(id)").consume()
-
-    # Create the given number of nodes with a randomly selected type from:
-    # [0.5, 1.5, 2.5].
-    sess.run(("UNWIND range(0, {} - 1) AS id CREATE "
-              "(:Node {{id: id, type: 0.5 + tointeger(rand() * 3)}})").format(
-                 node_count)).consume()
-
-    # Create the given number of edges, each with a 'value' property of
-    # a random [0, 3.0) float. Each edge connects two random nodes, so the
-    # expected node degree is (edge_count * 2 / node_count). Generate edges
-    # so the connectivity is non-uniform (to produce connected components of
-    # various sizes).
-    sess.run(("UNWIND range(0, {0} - 1) AS id WITH id "
-              "MATCH (from:Node {{id: tointeger(rand() * {1})}}), "
-              "(to:Node {{id: tointeger(rand() * {1} * id / {0})}}) "
-              "CREATE (from)-[:Edge {{value: 3 * rand()}}]->(to)").format(
-                 edge_count, node_count)).consume()
-
-
-def get_connected_ids(sess, node_id):
-    # Matches a node with the given ID and returns the IDs of all the nodes
-    # it is connected to. Note that within the BFS lambda expression there
-    # is an expression used to filter out edges expanded over.
-    return sess.run((
-        "MATCH (from:Node {{id: {}}})-"
-        "[*bfs (e, n | abs(from.type - e.value) < 0.80)]-(d) "
-        "RETURN count(*) AS c").format(node_id)).data()[0]['c']
-
-
-def parse_args():
-    parser = ArgumentParser(description=__doc__)
-    parser.add_argument('--endpoint', type=str, default='localhost:7687',
-                        help='Memgraph instance endpoint. ')
-    parser.add_argument('--node-count', type=int, default=1000,
-                        help='The number of nodes in the graph')
-    parser.add_argument('--edge-count', type=int, default=1000,
-                        help='The number of edges in the graph')
-    parser.add_argument('--sample-count', type=int, default=None,
-                        help='The number of samples to take')
-    return parser.parse_args()
-
-
-def main():
-    args = parse_args()
-    logging.basicConfig(level=logging.INFO)
-    log.info("Memgraph - Otto test database generator")
-    logging.getLogger("neo4j").setLevel(logging.WARNING)
-
-    driver = GraphDatabase.driver(
-        'bolt://' + args.endpoint,
-        auth=("ignored", "ignored"),
-        encrypted=False)
-    sess = driver.session()
-
-    sess.run("MATCH (n) DETACH DELETE n").consume()
-
-    log.info("Generating graph with %s nodes and %s edges...",
-             args.node_count, args.edge_count)
-    generate_graph(sess, args.node_count, args.edge_count)
-
-    # Track which vertices have been found as part of a component.
-    start_time = time()
-    max_query_time = 0
-    log.info("Looking for connected components...")
-    # Histogram of log2 sizes of connected components found.
-    histogram = defaultdict(int)
-    sample_count = args.sample_count if args.sample_count else args.node_count
-    for i in range(sample_count):
-        node_id = randint(0, args.node_count - 1)
-        query_start_time = time()
-        log2_size = int(log2(1 + get_connected_ids(sess, node_id)))
-        max_query_time = max(max_query_time, time() - query_start_time)
-        histogram[log2_size] += 1
-    elapsed = time() - start_time
-    log.info("Connected components found in %.2f sec (avg %.2fms, max %.2fms)",
-             elapsed, elapsed / sample_count * 1000, max_query_time * 1000)
-    log.info("Component size histogram (count | range)")
-    for log2_size, count in sorted(histogram.items()):
-        log.info("\t%5d | %d - %d", count, 2 ** log2_size,
-                 2 ** (log2_size + 1) - 1)
-
-    sess.close()
-    driver.close()
-
-
-if __name__ == '__main__':
-    main()

customers/otto/parallel_connected_components.cpp

@@ -1,207 +0,0 @@
-#include <algorithm>
-#include <limits>
-#include <mutex>
-#include <random>
-#include <set>
-#include <stack>
-#include <thread>
-
-#include "gflags/gflags.h"
-#include "glog/logging.h"
-
-#include "data_structures/union_find.hpp"
-#include "database/graph_db.hpp"
-#include "database/graph_db_accessor.hpp"
-#include "storage/property_value.hpp"
-#include "threading/sync/spinlock.hpp"
-#include "utils/bound.hpp"
-#include "utils/timer.hpp"
-
-DEFINE_int32(thread_count, 1, "Number of threads");
-DEFINE_int32(vertex_count, 1000, "Number of vertices");
-DEFINE_int32(edge_count, 1000, "Number of edges");
-DECLARE_int32(gc_cycle_sec);
-
-static const std::string kLabel{"kLabel"};
-static const std::string kProperty{"kProperty"};
-
-void GenerateGraph(database::GraphDb &db) {
-  {
-    database::GraphDbAccessor dba{db};
-    dba.BuildIndex(dba.Label(kLabel), dba.Property(kProperty));
-    dba.Commit();
-  }
-
-  // Randomize the sequence of IDs of created vertices and edges to simulate
-  // real-world lack of locality.
-  auto make_id_vector = [](size_t size) {
-    gid::Generator generator{0};
-    std::vector<gid::Gid> ids(size);
-    for (size_t i = 0; i < size; ++i)
-      ids[i] = generator.Next(std::experimental::nullopt);
-    std::random_shuffle(ids.begin(), ids.end());
-    return ids;
-  };
-
-  std::vector<VertexAccessor> vertices;
-  vertices.reserve(FLAGS_vertex_count);
-  {
-    CHECK(FLAGS_vertex_count % FLAGS_thread_count == 0)
-        << "Thread count must be a factor of vertex count";
-    LOG(INFO) << "Generating " << FLAGS_vertex_count << " vertices...";
-    utils::Timer timer;
-    auto vertex_ids = make_id_vector(FLAGS_vertex_count);
-
-    std::vector<std::thread> threads;
-    SpinLock vertices_lock;
-    for (int i = 0; i < FLAGS_thread_count; ++i) {
-      threads.emplace_back([&db, &vertex_ids, &vertices, &vertices_lock, i]() {
-        database::GraphDbAccessor dba{db};
-        auto label = dba.Label(kLabel);
-        auto property = dba.Property(kProperty);
-        auto batch_size = FLAGS_vertex_count / FLAGS_thread_count;
-        for (int j = i * batch_size; j < (i + 1) * batch_size; ++j) {
-          auto vertex = dba.InsertVertex(vertex_ids[j]);
-          vertex.add_label(label);
-          vertex.PropsSet(property, static_cast<int64_t>(vertex_ids[j]));
-          vertices_lock.lock();
-          vertices.emplace_back(vertex);
-          vertices_lock.unlock();
-        }
-        dba.Commit();
-      });
-    }
-    for (auto &t : threads) t.join();
-    LOG(INFO) << "Generated " << FLAGS_vertex_count << " vertices in "
-              << timer.Elapsed().count() << " seconds.";
-  }
-  {
-    database::GraphDbAccessor dba{db};
-    for (int i = 0; i < FLAGS_vertex_count; ++i)
-      vertices[i] = *dba.Transfer(vertices[i]);
-
-    LOG(INFO) << "Generating " << FLAGS_edge_count << " edges...";
-    auto edge_ids = make_id_vector(FLAGS_edge_count);
-    std::mt19937 pseudo_rand_gen{std::random_device{}()};
-    std::uniform_int_distribution<> rand_dist{0, FLAGS_vertex_count - 1};
-    auto edge_type = dba.EdgeType("edge");
-    utils::Timer timer;
-    for (int i = 0; i < FLAGS_edge_count; ++i)
-      dba.InsertEdge(vertices[rand_dist(pseudo_rand_gen)],
-                     vertices[rand_dist(pseudo_rand_gen)], edge_type,
-                     edge_ids[i]);
-    dba.Commit();
-    LOG(INFO) << "Generated " << FLAGS_edge_count << " edges in "
-              << timer.Elapsed().count() << " seconds.";
-  }
-}
-
-auto EdgeIteration(database::GraphDb &db) {
-  database::GraphDbAccessor dba{db};
-  int64_t sum{0};
-  for (auto edge : dba.Edges(false)) sum += edge.from().gid() + edge.to().gid();
-  return sum;
-}
-
-auto VertexIteration(database::GraphDb &db) {
-  database::GraphDbAccessor dba{db};
-  int64_t sum{0};
-  for (auto v : dba.Vertices(false))
-    for (auto e : v.out()) sum += e.gid() + e.to().gid();
-  return sum;
-}
-
-auto ConnectedComponentsEdges(database::GraphDb &db) {
-  UnionFind<int64_t> connectivity{FLAGS_vertex_count};
-  database::GraphDbAccessor dba{db};
-  for (auto edge : dba.Edges(false))
-    connectivity.Connect(edge.from().gid(), edge.to().gid());
-  return connectivity.Size();
-}
-
-auto ConnectedComponentsVertices(database::GraphDb &db) {
-  UnionFind<int64_t> connectivity{FLAGS_vertex_count};
-  database::GraphDbAccessor dba{db};
-  for (auto from : dba.Vertices(false)) {
-    for (auto out_edge : from.out())
-      connectivity.Connect(from.gid(), out_edge.to().gid());
-  }
-  return connectivity.Size();
-}
-
-auto ConnectedComponentsVerticesParallel(database::GraphDb &db) {
-  UnionFind<int64_t> connectivity{FLAGS_vertex_count};
-  SpinLock connectivity_lock;
-
-  // Define bounds of vertex IDs for each thread to use.
-  std::vector<PropertyValue> bounds;
-  for (int64_t i = 0; i < FLAGS_thread_count; ++i)
-    bounds.emplace_back(i * FLAGS_vertex_count / FLAGS_thread_count);
-  bounds.emplace_back(std::numeric_limits<int64_t>::max());
-
-  std::vector<std::thread> threads;
-  for (int i = 0; i < FLAGS_thread_count; ++i) {
-    threads.emplace_back(
-        [&connectivity, &connectivity_lock, &bounds, &db, i]() {
-          database::GraphDbAccessor dba{db};
-          for (auto from :
-               dba.Vertices(dba.Label(kLabel), dba.Property(kProperty),
-                            utils::MakeBoundInclusive(bounds[i]),
-                            utils::MakeBoundExclusive(bounds[i + 1]), false)) {
-            for (auto out_edge : from.out()) {
-              std::lock_guard<SpinLock> lock{connectivity_lock};
-              connectivity.Connect(from.gid(), out_edge.to().gid());
-            }
-          }
-        });
-  }
-  for (auto &t : threads) t.join();
-  return connectivity.Size();
-}
-
-auto Expansion(database::GraphDb &db) {
-  std::vector<int> component_ids(FLAGS_vertex_count, -1);
-  int next_component_id{0};
-  std::stack<VertexAccessor> expansion_stack;
-  database::GraphDbAccessor dba{db};
-  for (auto v : dba.Vertices(false)) {
-    if (component_ids[v.gid()] != -1) continue;
-    auto component_id = next_component_id++;
-    expansion_stack.push(v);
-    while (!expansion_stack.empty()) {
-      auto next_v = expansion_stack.top();
-      expansion_stack.pop();
-      if (component_ids[next_v.gid()] != -1) continue;
-      component_ids[next_v.gid()] = component_id;
-      for (auto e : next_v.out()) expansion_stack.push(e.to());
-      for (auto e : next_v.in()) expansion_stack.push(e.from());
-    }
-  }
-
-  return next_component_id;
-}
-
-int main(int argc, char **argv) {
-  gflags::ParseCommandLineFlags(&argc, &argv, true);
-  google::InitGoogleLogging(argv[0]);
-  FLAGS_gc_cycle_sec = -1;
-
-  database::SingleNode db;
-  GenerateGraph(db);
-  auto timed_call = [&db](auto callable, const std::string &descr) {
-    LOG(INFO) << "Running " << descr << "...";
-    utils::Timer timer;
-    auto result = callable(db);
-    LOG(INFO) << "\tDone in " << timer.Elapsed().count()
-              << " seconds, result: " << result;
-  };
-  timed_call(EdgeIteration, "Edge iteration");
-  timed_call(VertexIteration, "Vertex iteration");
-  timed_call(ConnectedComponentsEdges, "Connected components - Edges");
-  timed_call(ConnectedComponentsVertices, "Connected components - Vertices");
-  timed_call(ConnectedComponentsVerticesParallel,
-             "Parallel connected components - Vertices");
-  timed_call(Expansion, "Expansion");
-
-  return 0;
-}

customers/ravelin/fraud_detection.oc

@@ -1,5 +0,0 @@
-WITH tointeger(rand() * 40000000) AS from_id
-MATCH (from:Node {id : from_id}) WITH from
-MATCH path = (from)-[*bfs..50 (e, n | degree(n) < 50)]->(to) WITH path LIMIT 10000 WHERE to.fraudulent
-RETURN path, size(path)
-

customers/ravelin/snapshot_gen_config.json

@@ -1,31 +0,0 @@
-{
-   "indexes":[
-      "Node.id"
-   ],
-   "nodes":[
-      {
-         "count":40000000,
-         "labels":[
-            "Node"
-         ],
-         "properties":{
-            "id":{
-               "type":"counter",
-               "param":"Node.id"
-            },
-            "fraudulent":{
-               "type":"bernoulli",
-               "param":0.0005
-            }
-         }
-      }
-   ],
-   "edges":[
-      {
-         "count":80000000,
-         "from":"Node",
-         "to":"Node",
-         "type":"Edge"
-      }
-   ]
-}

customers/strata2018/card_fraud_config.json

@@ -1,20 +0,0 @@
-{
-  "indexes" : ["Card.id", "Pos.id", "Transaction.fraud_reported"],
-  "nodes" : [
-    {
-      "count_per_worker" : 1250000,
-      "label" : "Card"
-    },
-    {
-      "count_per_worker" : 1250000,
-      "label" : "Pos"
-    },
-    {
-      "count_per_worker" : 2500000,
-      "label" : "Transaction"
-    }
-  ],
-  "compromised_pos_probability" : 0.2,
-  "fraud_reported_probability" : 0.1,
-  "hop_probability" : 0.1
-}

docs/.gitignore

@@ -1,6 +1,2 @@
 doxygen/html/
 doxygen/latex/
-user_technical/.bundle_community/
-user_technical/.couscous/
-user_technical/couscous.phar
-user_technical/docs.tar.gz

docs/dev/code-review.md

@@ -0,0 +1,269 @@
+# Code Review Guidelines
+
+This chapter describes some of the things you should be on the lookout when
+reviewing someone else's code.
+
+## Exceptions
+
+Although the Google C++ Style Guide forbids exceptions, we do allow them in
+our codebase. As a reviewer you should watch out for the following.
+
+The documentation of throwing functions needs to be in-sync with the
+implementation. This must be enforced recursively. I.e. if a function A now
+throws a new exception, and the function B uses A, then B needs to handle that
+exception or have its documentation updated and so on. Naturally, the same
+applies when an exception is removed.
+
+Transitive callers of the function which throws a new exception must be OK
+with that. This ties into the previous point. You need to check that all users
+of the new exception either handle it correctly or propagate it.
+
+Exceptions should not escape out of class destructors, because that will
+terminate the program. The code should be changed so that such cases are not
+possible.
+
+Exceptions being thrown in class constructors. Although this is well defined
+in C++, it usually implies that a constructor is doing too much work and the
+class construction & initialization should be redesigned. Usual approaches are
+using the (Static) Factory Method pattern or having some sort of an
+initialization method that needs to be called after the construction is done.
+Prefer the Factory Method.
+
+Don't forget that STL functions may also throw!
+
+## Pointers & References
+
+In cases when some code passes a pointer or reference, or if a code stores a
+pointer or reference you should take a careful look at the following.
+
+  * Lifetime of the pointed to value (this includes both ownership and
+    multithreaded access).
+  * In case of a class, check validity of destructor and move/copy
+    constructors.
+  * Is the pointed to value mutated, if not it should be `const` (`const Type
+    *` or `const Type &`).
+
+## Allocators & Memory Resources
+
+With the introduction of polymorphic allocators (C++17 `<memory_resource>` and
+our `utils/memory.hpp`) we get a more convenient type signatures for
+containers so as to keep the outward facing API nice. This convenience comes
+at a cost of less static checks on the type level due to type erasure.
+
+For example:
+
+    std::pmr::vector<int> first_vec(std::pmr::null_memory_resource());
+    std::pmr::vector<int> second_vec(std::pmr::new_delete_resource());
+
+    second_vec = first_vec  // What happens here?
+
+    // Or with our implementation
+    utils::MonotonicBufferResource monotonic_memory(1024);
+    std::vector<int, utils::Allocator<int>> first_vec(&monotonic_memory);
+    std::vector<int, utils::Allocator<int>> second_vec(utils::NewDeleteResource());
+
+    second_vec = first_vec  // What happens here?
+
+In the above, both `first_vec` and `second_vec` have the same type, but have
+*different* allocators! This can lead to ambiguity when moving or copying
+elements between them.
+
+You need to watch out for the following.
+
+  * Swapping can lead to undefined behaviour if the allocators are not equal.
+  * Is the move construction done with the right allocator.
+  * Is the move assignment done correctly, also it may throw an exception.
+  * Is the copy construction done with the right allocator.
+  * Is the copy assignment done correctly.
+  * Using `auto` makes allocator propagation rules rather ambiguous.
+
+## Classes & Object Oriented Programming
+
+A common mistake is to use classes, inheritance and "OOP" when it's not
+needed. This sections shows examples of encountered cases.
+
+### Classes without (Meaningful) Members
+
+    class MyCoolClass {
+     public:
+      int BeCool(int a, int b) { return a + b; }
+
+      void SaySomethingCool() { std::cout << "Hello!"; }
+    };
+
+The above class has no members (i.e. state) which affect the behaviour of
+methods. This class should need not exist, it can be easily replaced with a
+more modular (and shorter) design -- top level functions.
+
+    int BeCool(int a, int b) { return a + b; }
+
+    void SaySomethingCool() { std::cout << "Hello!"; }
+
+### Classes with a Single Public Method
+
+    clas MyAwesomeClass {
+     public:
+      MyAwesomeClass(int state) : state_(state) {}
+
+      int GetAwesome() { return GetAwesomeImpl() + 1; }
+
+     private:
+      int state_;
+
+      int GetAwesomeImpl() { return state_; }
+    };
+
+The above class has a `state_` and even a private method, but there's only one
+public method -- `GetAwesome`.
+
+You should check "Does the stored state have any meaningful influence on the
+public method?", similarly to the previous point.
+
+In the above case it doesn't, and the class should be replaced with a public
+function in `.hpp` while the private method should become a private function
+in `.cpp` (static or in anonymous namespace).
+
+    // hpp
+    int GetAwesome(int state);
+
+    // cpp
+    namespace {
+      int GetAwesomeImpl(int state) { return state; }
+    }
+    int GetAwesome(int state) { return GetAwesomeImpl(state) + 1; }
+
+A counterexample is when the state is meaningful.
+
+    class Counter {
+     public:
+      Counter(int state) : state_(state) {}
+
+      int Get() { return state_++; }
+
+     private:
+      int state_;
+    };
+
+But even that could be replaced with a closure.
+
+    auto MakeCounter(int state) {
+      return [state]() mutable { return state++; };
+    }
+
+### Private Methods
+
+Instead of private methods, top level functions should be preferred. The
+reasoning is completely explained in "Effective C++" Item 23 by Scott Meyers.
+In our codebase, even improvements to compilation times can be noticed if
+private methods in interface (`.hpp`) files are replaced with top level
+functions in implementation (`.cpp`) files.
+
+### Inheritance
+
+The rule is simple -- if there are no virtual methods (but maybe destructor),
+then the class should be marked as `final` and never inherited.
+
+If there are virtual methods (i.e. class is meant to be inherited), make sure
+that either a public virtual destructor or a protected non-virtual destructor
+exist. See "Effective C++" Item 7 by Scott Meyers. Also take a look at
+"Effective C++" Items 32---39 by Scott Meyers.
+
+An example of how inheritance with no virtual methods is replaced with
+composition.
+
+    class MyBase {
+     public:
+      virtual ~MyBase() {}
+
+      void DoSomethingBase() { ... }
+    };
+
+    class MyDerived final : public MyBase {
+     public:
+      void DoSomethingNew() { ... DoSomethingBase(); ... }
+    };
+
+With composition, the above becomes.
+
+    class MyBase final {
+     public:
+      void DoSomethingBase() { ... }
+    };
+
+    class MyDerived final {
+      MyBase base_;
+
+     public:
+      void DoSomethingNew() { ... base_.DoSomethingBase(); ... }
+    };
+
+The composition approach is preferred as it encapsulates the fact that
+`MyBase` is used for the implementation and users only interact with the
+public interface of `MyDerived`. Additionally, you can easily replace `MyBase
+base_;` with a C++ PIMPL idiom (`std::unique_ptr<MyBase> base_;`) to make the
+code more modular with regards to compilation.
+
+More advanced C++ users will recognize that the encapsulation feature of the
+non-PIMPL composition can be replaced with private inheritance.
+
+    class MyDerived final : private MyBase {
+     public:
+      void DoSomethingNew() { ... MyBase::DoSomethingBase(); ... }
+    };
+
+One of the common "counterexample" is the ability to store objects of
+different type in a container or pass them to a function. Unfortunately, this
+is not that good of a design. For example.
+
+    class MyBase {
+      ... // No virtual methods (but the destructor)
+    };
+
+    class MyFirstClass final : public MyBase { ...  };
+
+    class MySecondClass final : public MyBase { ... };
+
+    std::vector<std::unique_ptr<MyBase>> first_and_second_classes;
+    first_and_second_classes.push_back(std::make_unique<MyFirstClass>());
+    first_and_second_classes.push_back(std::make_unique<MySecondClass>());
+
+    void FunctionOnFirstOrSecond(const MyBase &first_or_second, ...) { ... }
+
+With C++17, the containers for different types should be implemented with
+`std::variant`, and as before the functions can be templated.
+
+    class MyFirstClass final { ... };
+
+    class MySecondClass final { ... };
+
+    std::vector<std::variant<MyFirstClass, MySecondClass>> first_and_second_classes;
+    // Notice no heap allocation, since we don't store a pointer
+    first_and_second_classes.emplace_back(MyFirstClass());
+    first_and_second_classes.emplace_back(MySecondClass());
+
+    // You can also use `std::variant` here instead of template
+    template <class TFirstOrSecond>
+    void FunctionOnFirstOrSecond(const TFirstOrSecond &first_or_second, ...) { ... }
+
+Naturally, if the base class has meaningful virtual methods (i.e. other than
+destructor) it maybe is OK to use inheritance but also consider alternatives.
+See "Effective C++" Items 32---39 by Scott Meyers.
+
+### Multiple Inheritance
+
+Multiple inheritance should not be used unless all base classes are pure
+interface classes. This decision is inherited from [Google C++ Style
+Guide](https://google.github.io/styleguide/cppguide.html#Inheritance). For
+example on how to design with and around multiple inheritance refer to
+"Effective C++" Item 40 by Scott Meyers.
+
+Naturally, if there *really* is no better design, then multiple inheritance is
+allowed. An example of this can be found in our codebase when inheriting
+Visitor classes (though even that could be replaced with `std::variant` for
+example).
+
+## Code Format & Style
+
+If something doesn't conform to our code formatting and style, just refer the
+author to either [C++ Style](cpp-code-conventions.md) or [Other Code
+Conventions](other-code-conventions.md).

docs/dev/communication/contents.md

@@ -0,0 +1,5 @@
+# Communication
+
+## Bolt
+
+Memgraph implements [Bolt communication protocol](https://7687.org/).

docs/dev/cpp-code-conventions.md

@@ -5,15 +5,174 @@ C++ code.
 
 ## Code Style
 
-Memgraph uses the Google Style Guide for C++ in most of its code. You should
-follow them whenever writing new code. The style guide can be found
-[here](https://google.github.io/styleguide/cppguide.html).
+Memgraph uses the
+[Google Style Guide for C++](https://google.github.io/styleguide/cppguide.html)
+in most of its code.  You should follow them whenever writing new code.
+Besides following the style guide, take a look at
+[Code Review Guidelines](code-review.md) for common design issues and pitfalls
+with C++ as well as [Required Reading](required-reading.md).
+
+### Often Overlooked Style Conventions
+
+#### Pointers & References
+
+References provide a shorter syntax for accessing members and better declare
+the intent that a pointer *should* not be `nullptr`. They do not prevent
+accessing a `nullptr` and obfuscate the client/calling code because the
+reference argument is passed just like a value. Errors with such code have
+been very difficult to debug. Therefore, pointers are always used. They will
+not prevent bugs but will make some of them more obvious when reading code.
+
+The only time a reference can be used is if it is `const`. Note that this
+kind of reference is not allowed if it is stored somewhere, i.e. in a class.
+You should use a pointer to `const` then. The primary reason being is that
+references obscure the semantics of moving an object, thus making bugs with
+references pointing to invalid memory harder to track down.
+
+Example of this can be seen while capturing member variables by reference
+inside a lambda.
+Let's define a class that has two members, where one of those members is a
+lambda that captures the other member by reference.
+
+```cpp
+struct S {
+  std::function<void()> foo;
+  int bar;
+
+  S() : foo([&]() { std::cout << bar; })
+  {}
+};
+```
+What would happend if we move an instance of this object? Our lambda
+reference capture will point to the same location as before, i.e. it
+will point to the **old** memory location of `bar`. This means we have
+a dangling reference in our code!
+There are multiple ways to avoid this. The simple solutions would be
+capturing by value or disabling move constructors/assignments.
+Still, if we capture by reference an object that is not a member
+of the struct containing the lambda, we can still have a dangling
+reference if we move that object somewhere in our code and there is
+nothing we can do to prevent that.
+So, be careful with lambda catptures, and remember that references are
+still a pointer under the hood!
+
+[Style guide reference](https://google.github.io/styleguide/cppguide.html#Reference_Arguments)
+
+#### Constructors & RAII
+
+RAII (Resource Acquisition is Initialization) is a nice mechanism for managing
+resources. It is especially useful when exceptions are used, such as in our
+code. Unfortunately, they do have 2 major downsides.
+
+  * Only exceptions can be used for to signal failure.
+  * Calls to virtual methods are not resolved as expected.
+
+For those reasons the style guide recommends minimal work that cannot fail.
+Using virtual methods or doing a lot more should be delegated to some form of
+`Init` method, possibly coupled with static factory methods. Similar rules
+apply to destructors, which are not allowed to even throw exceptions.
+
+[Style guide reference](https://google.github.io/styleguide/cppguide.html#Doing_Work_in_Constructors)
+
+#### Constructors and member variables
+
+One of the most powerful tools in C++ is the move semantics. We won't go into
+detail how it works, but you should know how to utilize it as much as
+possible. In our example we will define a small `struct` called `S` which
+contains only a single member, `text` of type `std::string`.
+```cpp
+struct S {
+  std::string text;
+};
+```
+We want to define a constructor that takes a `std::string`, and saves its
+value in `text`. This is a common situation, where the constructor takes
+a value, and saves it in the object to be constructed.
+
+Our first implementation would look like this:
+```cpp
+S(const std::string &s) : text(s) {}
+```
+
+This is a valid solution but with one downside - we always copy. If we
+construct an object like this:
+```cpp
+S s("some text");
+```
+we would create a temporary `std::string` object and then copy it to our member
+variable.
+
+Of course, we know what to do now - we will capture temporary variables using
+`&&` and move it into our `text` variable.
+```cpp
+S(std::string &&s) : text(std::move(s)) {}
+```
+
+Now let's add an extra member variable of type `std::vector<int>` called
+`words`.  Our constructors accept 2 values now - `std::vector<int>` and
+`std::string`. Those arguments could be passed by value, by reference, or
+as rvalues. To cover all the cases we need to define a dedicated constructor
+for each case.
+Fortunately, there are two simpler options, the first one is writing a
+templated constructor:
+```cpp
+template<typename T1, typename T2>
+S(T1 &&s, T2 &&v) : text(std::forward<T1>(s), words(std::forward<T2>(v) {}
+```
+But don't forget to define `requires` clause so you don't accept any type. This
+solution is optimal but really hard to read AND write. The second solution is
+something you should ALWAYS prefer in these simple cases where we only store
+one of the arguments:
+```cpp
+S(std::string s, std::vector<int> v) : text(std::move(s)), words(std::move(v)) {}
+```
+This way we have an almost optimal solution. The only extra operation we have is
+the extra move when we send an `lvalue`. We would copy the value to the `s`, and
+then move it to the `text` variable. Before, we would copy directly to `text`.
+Also, you should ALWAYS write const-correct code, meaning `s` and `v` cannot be
+`const` as it's not correct here. Why is that? You CANNOT move a const object!
+It would just degrade to copying the object. I would say that this is a small
+price to pay for a much cleaner and more maintainable code.
 
 ### Additional Style Conventions
 
-Code style conventions which are left undefined by Google are specified here.
+Old code may have broken Google C++ Style accidentally, but the new code
+should adhere to it as close as possible. We do have some exceptions
+to Google style as well as additions for unspecified conventions.
 
-#### Template parameter naming
+#### Using C++ Exceptions
+
+Unlike Google, we do not forbid using exceptions.
+
+But, you should be very careful when using them and introducing new ones. They
+are indeed handy, but cause problems with understanding the control flow since
+exceptions are another form of `goto`. It also becomes very hard to determine
+that the program is in correct state after the stack is unwound and the thrown
+exception handled. Other than those issues, throwing exceptions in destructors
+will terminate the program. The same will happen if a thread doesn't handle an
+exception even though it is not the main thread.
+
+[Style guide reference](https://google.github.io/styleguide/cppguide.html#Exceptions)
+
+In general, when introducing a new exception, either via `throw` statement or
+calling a function which throws, you must examine all transitive callers and
+update their implementation and/or documentation.
+
+#### Assertions
+
+We use `CHECK` and `DCHECK` macros from glog library. You are encouraged to
+use them as often as possible to both document and validate various pre and
+post conditions of a function.
+
+`CHECK` remains even in release build and should be preferred over it's cousin
+`DCHECK` which only exists in debug builds. The primary reason is that you
+want to trigger assertions in release builds in case the tests didn't
+completely validate all code paths. It is better to fail fast and crash the
+program, than to leave it in undefined state and potentially corrupt end
+user's work. In cases when profiling shows that `CHECK` is causing visible
+slowdown you should switch to `DCHECK`.
+
+#### Template Parameter Naming
 
 Template parameter names should start with capital letter 'T' followed by a
 short descriptive name. For example:
@@ -63,11 +222,9 @@ containing 3 slashes (`///`). Take a look at the 2 examples below.
 ### Line Comment
 
 ```cpp
-///
 /// One sentence, brief description.
 ///
 /// Long form description.
-///
 ```
 
 If you only have a brief description, you may collapse the documentation into

docs/dev/memgraph/diagram/dependencies.dot

@@ -1,288 +0,0 @@
-// dot -Tpng dependencies.dot -o /path/to/output.png
-
-// TODO (buda): Put PropertyValueStore to storage namespace
-
-digraph {
-  // At the beginning of each block there is a default style for that block
-  label="Memgraph Dependencies Diagram"; fontname="Roboto Bold"; fontcolor=black;
-    fontsize=26; labelloc=top; labeljust=right;
-  compound=true; // If true, allow edges between clusters
-  rankdir=TB; // Alternatives: LR
-  node [shape=record fontname="Roboto", fontsize=12, fontcolor=white];
-  edge [color="#B5AFB7"];
-
-  // -- Legend --
-  // dir=both arrowtail=diamond arrowhead=vee -> group ownership
-  // dir=both arrowtail=none, arrowhead=vee -> ownership; stack or uptr
-
-  subgraph cluster_tcp_end_client_communication {
-    label="TCP End Client Communication"; fontsize=14;
-    node [style=filled, color="#DD2222" fillcolor="#DD2222"];
-
-    // Owned elements
-    "communication::Server";
-    "io::network::Socket";
-
-    // Intracluster connections
-    "communication::Server" -> "io::network::Socket"
-      [label="socket_" dir=both arrowtail=none arrowhead=vee];
-  }
-
-  subgraph cluster_bolt_server {
-    label="Bolt Server"; fontsize=14;
-    node [style=filled, color="#62A2CA" fillcolor="#62A2CA"];
-
-    // Owned elements
-    "communication::bolt::SessionData";
-    "communication::bolt::Session";
-    "communication::bolt::Encoder";
-    "communication::bolt::Decoder";
-
-    // Intracluster connections
-    "communication::bolt::Session" -> "communication::bolt::Encoder"
-      [label="encoder_", dir=both arrowtail=none, arrowhead=vee];
-    "communication::bolt::Session" -> "communication::bolt::Decoder"
-      [label="decoder_", dir=both arrowtail=none, arrowhead=vee];
-  }
-
-  subgraph cluster_opencypher_engine {
-    label="openCypher Engine"; fontsize=14;
-    node [style=filled, color="#68BDF6" fillcolor="#68BDF6"];
-
-    // Owned Elements
-    "query::Interpreter";
-    "query::AstTreeStorage";
-    "query::TypedValue"
-    "query::Path";
-    "query::Simbol";
-    "query::Context";
-    "query::ExpressionEvaluator";
-    "query::Frame";
-    "query::SymbolTable";
-    "query::plan::LogicalOperator";
-    "query::plan::Cursor";
-    "query::plan::CostEstimator";
-
-    // Intracluster connections
-    "query::Interpreter" -> "query::AstTreeStorage"
-      [label="ast_cache" dir=both arrowtail=diamond arrowhead=vee];
-    "query::TypedValue" -> "query::Path";
-    "query::plan::Cursor" -> "query::Frame";
-    "query::plan::Cursor" -> "query::Context";
-    "query::plan::LogicalOperator" -> "query::Symbol";
-    "query::plan::LogicalOperator" -> "query::SymbolTable";
-    "query::plan::LogicalOperator" -> "query::plan::Cursor";
-  }
-
-
-  subgraph cluster_storage {
-    label="Storage" fontsize=14;
-    node [style=filled, color="#FB6E00" fillcolor="#FB6E00"];
-
-    // Owned Elements
-    "database::GraphDb";
-    "database::GraphDbAccessor";
-    "storage::Record";
-    "storage::Vertex";
-    "storage::Edge";
-    "storage::RecordAccessor";
-    "storage::VertexAccessor";
-    "storage::EdgeAccessor";
-    "storage::Common";
-    "storage::Label";
-    "storage::EdgeType";
-    "storage::Property";
-    "storage::compression";
-    "storage::SingleNodeConcurrentIdMapper";
-    "storage::Location";
-    "storage::StorageTypesLocation";
-    "PropertyValueStore";
-    "storage::RecordLock";
-    "mvcc::Version";
-    "mvcc::Record";
-    "mvcc::VersionList";
-
-    // Intracluster connections
-    "storage::VertexAccessor" -> "storage::RecordAccessor"
-      [arrowhead=onormal];
-    "storage::EdgeAccessor" -> "storage::RecordAccessor"
-      [arrowhead=onormal];
-    "storage::RecordAccessor" -> "database::GraphDbAccessor"
-      [style=dashed arrowhead=vee];
-    "storage::Vertex" -> "mvcc::Record"
-      [arrowhead=onormal];
-    "storage::Edge" -> "mvcc::Record"
-      [arrowhead=onormal];
-    "storage::Edge" -> "PropertyValueStore"
-      [arrowhead=vee];
-    "storage::Vertex" -> "PropertyValueStore"
-      [arrowhead=vee];
-    "storage::Edge" -> "mvcc::VersionList"
-      [label="from,to" arrowhead=vee style=dashed];
-    "storage::VertexAccessor" -> "storage::Vertex"
-      [arrowhead=vee];
-    "storage::EdgeAccessor" -> "storage::Edge"
-      [arrowhead=vee];
-    "storage::SingleNodeConcurrentIdMapper" -> "storage::StorageTypesLocation"
-      [arrowhead=vee];
-    "storage::StorageTypesLocation" -> "storage::Location"
-      [arrowhead=vee];
-    "storage::Storage" -> "storage::StorageTypesLocation"
-      [arrowhead=vee];
-    "storage::Property" -> "storage::Common"
-      [arrowhead=onormal];
-    "storage::Label" -> "storage::Common"
-      [arrowhead=onormal];
-    "storage::EdgeType" -> "storage::Common"
-      [arrowhead=onormal];
-    "storage::Property" -> "storage::Location"
-      [arrowhead=vee];
-    "PropertyValueStore" -> "storage::Property"
-      [arrowhead=vee];
-    "PropertyValueStore" -> "storage::Location"
-      [arrowhead=vee];
-    "database::GraphDbAccessor" -> "database::GraphDb"
-      [arrowhead=vee];
-    "database::GraphDbAccessor" -> "tx::TransactionId"
-      [arrowhead=vee];
-    "mvcc::VersionList" -> "storge::RecordLock"
-      [label="lock" arrowhead=vee];
-    "mvcc::VersionList" -> "mvcc::Record"
-      [label="head" arrowhead=vee];
-    "mvcc::Record" -> "mvcc::Version"
-      [arrowhead=onormal];
-
-    // Explicit positioning
-    {rank=same;
-        "database::GraphDbAccessor";
-        "storage::VertexAccessor";
-        "storage::EdgeAccessor";}
-    {rank=same;
-        "storage::Common";
-        "storage::compression";}
-  }
-
-  subgraph cluster_properties_on_disk {
-    label="Properties on Disk" fontsize=14;
-    node [style=filled, color="#102647" fillcolor="#102647"];
-
-    // Owned Elements
-    "storage::KVStore";
-    "rocksdb";
-
-    // Intracluster connections
-    "storage::KVStore" -> "rocksdb";
-  }
-
-  subgraph cluster_distributed {
-    label="Distributed" fontsize=14;
-    node [style=filled, color="#FFC500" fillcolor="#FFC500"];
-
-    // Owned Elements
-    "distributed::DataManager";
-    "distributed::DataRpcClients";
-
-    // Intracluster connections
-    "distributed::DataManager" -> "distributed::DataRpcClients"
-      [arrowhead=vee];
-    "storage::RecordAccessor" -> "distributed::DataManager"
-      [style=dashed arrowhead=vee];
-  }
-
-  subgraph cluster_dynamic_partitioning {
-    label="Dynamic Partitioning" fontsize=14;
-    node [style=filled, color="#720096" fillcolor="#720096"];
-
-    // Owned Elements
-    "DynamicPartitioner";
-  }
-
-  subgraph cluster_security {
-    label="Security" fontsize=14;
-    node [style=filled, color="#857F87" fillcolor="#857F87"];
-
-    // Owned Elements
-    "Communication Encryption";
-    "Data Encryption";
-    "Access Control";
-    "Audit Logging";
-  }
-
-  subgraph cluster_web_dashboard {
-    label="Dashaboard" fontsize=14;
-    node [style=filled, color="#FF0092" fillcolor="#FF0092"];
-
-    // Owned Elements
-    "Memgraph Ops / Memgraph Cockpit";
-  }
-
-  subgraph cluster_rpc {
-    label="RPC" fontsize=14;
-    node [style=filled, color="#857F87" fillcolor="#857F87"];
-
-    // Owned Elements
-    "communication::rpc::Server";
-    "communication::rpc::Client";
-  }
-
-  subgraph cluster_ingestion {
-    label="Ingestion" fontsize=14;
-    node [style=filled, color="#0B6D88" fillcolor="#0B6D88"];
-
-    // Owned Elements
-    "Extract";
-    "Transform";
-    "Load";
-    "Amazon S3";
-    "Kafka";
-
-    // Intracluster connections
-    "Extract" -> "Amazon S3";
-    "Extract" -> "Kafka";
-
-    // Explicit positioning
-    {rank=same;"Extract";"Transform";"Load";}
-  }
-
-  // -- Intercluster connections --
-  // cluster_tcp_end_client_communication -- cluster_bolt_server
-  "communication::Server" -> "communication::bolt::SessionData" [color=black];
-  "communication::Server" -> "communication::bolt::Session" [color=black];
-  // cluster_bolt_server -> cluster_storage
-  "communication::bolt::SessionData" -> "database::GraphDb" [color=red];
-  "communication::bolt::Session" -> "database::GraphDbAccessor" [color=red];
-  // cluster_bolt_server -> cluster_opencypher_engine
-  "communication::bolt::SessionData" -> "query::Interpreter" [color=red];
-  // cluster_opencypher_engine -- cluster_storage
-  "query::Interpreter" -> "database::GraphDbAccessor" [color=black];
-  "query::Interpreter" -> "storage::VertexAccessor" [color=black];
-  "query::Interpreter" -> "storage::EdgeAccessor" [color=black];
-  "query::TypedValue" -> "storage::VertexAccessor" [color=black];
-  "query::TypedValue" -> "storage::EdgeAccessor" [color=black];
-  "query::Path" -> "storage::VertexAccessor"
-    [label="vertices" dir=both arrowtail=diamond arrowhead=vee color=black];
-  "query::Path" -> "storage::EdgeAccessor"
-    [label="edges" dir=both arrowtail=diamond arrowhead=vee color=black];
-  "query::plan::LogicalOperator" -> "database::GraphDbAccessor"
-    [color=black arrowhead=vee];
-  // cluster_distributed -- cluster_storage
-  "distributed::DataManager" -> "database::GraphDb"
-    [arrowhead=vee style=dashed color=red];
-  "distributed::DataManager" -> "tx::TransactionId"
-    [label="ves_caches_key" dir=both arrowhead=none arrowtail=diamond
-     color=red];
-  "distributed::DataManager" -> "storage::Vertex"
-    [label="vertices_caches" dir=both arrowhead=none arrowtail=diamond
-     color=red];
-  "distributed::DataManager" -> "storage::Edge"
-    [label="edges_caches" dir=both arrowhead=none arrowtail=diamond
-     color=red];
-  // cluster_storage -- cluster_properties_on_disk
-  "PropertyValueStore" -> "storage::KVStore"
-    [label="static" arrowhead=vee color=black];
-  // cluster_dynamic_partitioning -- cluster_storage
-  "database::GraphDb" -> "DynamicPartitioner"
-    [arrowhead=vee color=red];
-  "DynamicPartitioner" -> "database::GraphDbAccessor"
-    [arrowhead=vee color=black];
-}

docs/dev/memgraph/distributed/addressing.md

@@ -1,43 +0,0 @@
-# Distributed addressing
-
-In distributed Memgraph a single graph element must be owned by exactly
-one worker. It is possible that multiple workers have cached copies of
-a single graph element (which is inevitable), but there is only one
-owner.
-
-The owner of a graph element can change. This is not yet implemented,
-but is intended. Graph partitioning is intended to be dynamic.
-
-Graph elements refer to other graph elements that are possibly on some
-other worker. Even though each graph element is identified with a unique
-ID, that ID does not contain the information about where that element
-currently resides (which worker is the owner).
-
-Thus we introduce the concept of a global address. It indicates both
-which graph element is referred to (it's global ID), and where it
-resides. Semantically it's a pair of two elements, but for efficiency
-it's stored in 64 bits.
-
-The global address is efficient for usage in a cluster: it indicates
-where something can be found. However, finding a graph element based on
-it's ID is still not a free operation (in the current implementation
-it's a skiplist lookup). So, whenever possible, it's better to use local
-addresses (pointers).
-
-Succinctly, the requirements for addressing are:
-- global addressing containing location info
-- fast local addressing
-- storage of both types in the same location efficiently
-- translation between the two
-
-The `storage::Address` class handles the enumerated storage
-requirements. It stores either a local or global address in the size of
-a local pointer (typically 8 bytes).
-
-Conversion between the two is done in multiple places. The general
-approach is to use local addresses (when possible) only for local
-in-memory handling. All the communication and persistence uses global
-addresses. Also, when receiving address from another worker, attempt to
-localize addresses as soon as possible, so that least code has to worry
-about potential inefficiency of using a global address for a local graph
-element.

docs/dev/memgraph/distributed/durability.md

@@ -1,50 +0,0 @@
-# Distributed durability
-
-Durability in distributed is slightly different then in single-node as
-the state itself is shared between multiple workers and none of those
-states are independent.
-
-Note that recovering from persistent storage must result in a stable
-database state. This means that across the cluster the state
-modification of every transaction that was running is either recovered
-fully or not at all. Also, if transaction A committed before transaction B,
-then if B is recovered so must A.
-
-## Snapshots
-
-It is possibly avoidable but highly desirable that the database can be
-recovered from snapshot only, without relying on WAL files. For this to
-be possible in distributed, it must be ensured that the same
-transactions are recovered on all the workers (including master) in the
-cluster. Since the snapshot does not contain information about which
-state change happened in which transaction, the only way to achieve this
-is to have synchronized snapshots. This means that the process of
-creating a snapshot, which is in itself transactional (it happens within
-a transaction and thus observes some consistent database state), must
-happen in the same transaction. This is achieved by the master starting
-a snapshot generating transaction and triggering the process on all
-workers in the cluster.
-
-## WAL
-
-Unlike the snapshot, write-ahead logs contain the information on which
-transaction made which state change. This makes it possible to include
-or exclude transactions during the recovery process. What is necessary
-however is a global consensus on which of the transactions should be
-recovered and which not, to ensure recovery into a consistent state.
-
-It would be possible to achieve this with some kind of synchronized
-recovery process, but it would impose constraints on cluster startup and
-would not be trivial.
-
-A simpler alternative is that the consensus is achieved beforehand,
-while the database (to be recovered) is still operational. What is
-necessary is to keep track of which transactions are guaranteed to
-have been flushed to the WAL files on all the workers in the cluster. It
-makes sense to keep this record on the master, so a mechanism is
-introduced which periodically pings all the workers, telling them to
-flush their WALs, and writes some sort of a log indicating that this has
-been confirmed. The downside of this is a periodic broadcast must be
-done, and that potentially slightly less data can be recovered in the
-case of a crash then if using a post-crash consensus. It is however much
-simpler to implement.

docs/dev/memgraph/distributed/dynamic_graph_partitioning.md

@@ -1,48 +0,0 @@
-## Dynamic Graph Partitioning
-Memgraph supports dynamic graph partitioning similar to the Spinner algorithm, 
-mentioned in this paper: [https://arxiv.org/pdf/1404.3861.pdf].
-
-Dgp is useful because it tries to group `local` date on the same worker, i.e. 
-it tries to keep closely connected data on one worker. It tries to avoid jumps 
-across workers when querying/traversing the distributed graph.
-
-### Our implementation
-It works independently on each worker but it is always running the migration 
-on only one worker at the same time. It achieves that by sharing a token 
-between workers, and the token ownership is transferred to the next worker 
-when the current worker finishes its migration step. 
-
-The reason that we want workers to work in  disjoint time slots is it avoid 
-serialization errors caused by creating/removing edges of vertices during 
-migrations, which might cause an update of some vertex from two or more 
-different transactions.
-
-### Migrations
-For each vertex and workerid (label in the context of Dgp algorithm) we define  
-a score function. Score function takes into account labels of surrounding 
-endpoints of vertex edges (in/out) and the capacity of the worker with said 
-label. Score function loosely looks like this 
-```
-locality(v, l) = 
-count endpoints of edges of vertex `v` with label `l` / degree of `v`
-
-capacity(l) = 
-number of vertices on worker `l` divided by the worker capacity 
-(usually equal to the average number of vertices per worker)
-
-score(v, l) = locality(v, l) - capacity(l)
-```
-We also define two flags alongside ```dynamic_graph_partitioner_enabled```, 
-   ```dgp_improvement_threshold``` and ```dgp_max_batch_size```.
-
-These two flags are used during the migration phase.
-When deciding if we need to migrate some vertex `v` from worker `l1` to worker 
-`l2` we examine the difference in scores, i.e.
-if score(v, l1) - dgp_improvement_threshold / 100 < score(v, l2) then we 
-migrate the vertex. 
-
-Max batch size flag limits the number of vertices we can transfer in one batch 
-(one migration step). 
-Setting this value to a too large value will probably cause
-a lot of interference with client queries, and having it a small value
-will slow down convergence of the algorithm.

docs/dev/memgraph/distributed/general_concepts.md

@@ -1,54 +0,0 @@
-# Memgraph distributed
-
-This chapter describes some of the concepts used in distributed
-Memgraph. By "distributed" here we mean the sharding of a single graph
-onto multiple processing units (servers).
-
-## Conceptual organization
-
-There is a single master and multiple workers. The master contains all
-the global sources of truth (transaction engine,
-[label|edge-type|property] to name mappings). Also, in the current
-organization it is the only one that contains a Bolt server (for
-communication with the end client) and an interpretation engine. Workers
-contain the data and means of subquery interpretation (query plans
-recieved from the master) and means of communication with the master and
-other workers.
-
-In many query plans the load on the master is much larger then the load
-on the workers. For that reason it might be beneficial to make the
-master contain less data (or none at all), and/or having multiple
-interpretation masters.
-
-## Logic organization
-
-Both the distributed and the single node Memgraph use the same codebase.
-In cases where the behavior in single-node differs from that in
-distributed, some kind of dynamic behavior change is implemented (either
-through inheritance or conditional logic).
-
-### GraphDb
-
-The `database::GraphDb` is an "umbrella" object for parts of the
-database such as storage, garbage collection, transaction engine etc.
-There is a class heirarchy of `GraphDb` implementations, as well as a
-base interface object. There are subclasses for single-node, master and
-worker deplotyments. Which implementation is used depends on the
-configuration processed in the `main` entry point of memgraph.
-
-The `GraphDb` interface exposes getters to base classes of
-other similar heirarchies (for example to `tx::Engine`). In that way
-much of the code that uses those objects (for example query plan
-interpretation) is agnostic to the type of deployment.
-
-### RecordAccessors
-
-The functionality of `RecordAccessors` and it's subclasses is already
-documented. It's important to note that the same implementation of
-accessors is used in all deployments, with internal changes of behavior
-depending on the locality of the graph element (vertex or edge) the
-accessor represents. For example, if the graph element is local, an
-update operation on an accessor will make the necessary MVCC ops, update
-local data, indexes, the write-ahead log etc. However, if the accessor
-represents a remote graph element, an update will trigger an RPC message
-to the owner about the update and a change in the local cache.

docs/dev/memgraph/distributed/updates.md

@@ -1,103 +0,0 @@
-# Distributed updates
-
-Operations that modify the graph state are somewhat more complex in the
-distributed system, as opposed to a single-node Memgraph deployment. The
-complexity arises from two factors.
-
-First, the data being modified is not necessarily owned by the worker
-performing the modification. This situation is completely valid workers
-execute parts of the query plan and parts must be executed by the
-master.
-
-Second, there are less guarantees regarding multi-threaded access. In
-single-node Memgraph it was guaranteed that only one transaction will be
-performing database work in a single transaction. This implied that
-per-version storage could be thread-unsafe. In distributed Memgraph it
-is possible that multiple threads could be performing work in the same
-transaction as a consequence of the query being executed at the same
-time on multiple workers and those executions interacting with the
-globally partitioned database state.
-
-## Deferred state modification
-
-Making the per-version data storage thread-safe would most likely have a
-performance impact very undesirable in a transactional database intended
-for high throughput.
-
-An alternative is that state modification over unsafe structures is not
-performed immediately when requested, but postponed until it is safe to
-do (there is is a guarantee of no concurrent access).
-
-Since local query plan execution is done the same way on local data as
-it is in single-node Memgraph, it is not possible to deffer that part of
-the modification story. What can be deferred are modifications requested
-by other workers. Since local query plan execution still is
-single-threaded, this approach is safe.
-
-At the same time those workers requesting the remote update can update
-local copies (caches) of the not-owned data since that cache is only
-being used by the single, local-execution thread.
-
-### Visibility
-
-Since updates are deferred the question arises: when do the updates
-become visible? The above described process offers the following
-visibility guarantees:
-- updates done on the local state are visible to the owner
-- updates done on the local state are NOT visible to anyone else during
-  the same (transaction + command)
-- updates done on remote state are deferred on the owner and not
-  visible to the owner until applied
-- updates done on the remote state are applied immediately to the local
-  caches and thus visible locally
-
-This implies an inconsistent view of the database state. In a concurrent
-execution of a single query this can hardly be avoided and is accepted
-as such. It does not change the Cypher query execution semantic in any
-of the well-defined scenarios. It possibly changes some of the behaviors
-in which the semantic is not well defined even in single-node execution.
-
-### Synchronization, update application
-
-In many queries it is mandatory to observe the latest global graph state
-(typically when returning it to the client). That means that before that
-happens all the deferred updates need to be applied, and all the caches
-to remote data invalidated. Exactly this happens when executing queries
-that modify the graph state. At some point a global synchronization
-point is reached. First it is waited that all workers finish the
-execution of query plan parts performing state modifications. After that
-all the workers are told to apply the deferred updates they received to
-their graph state. Since there is no concurrent query plan execution,
-this is safe. Once that is done all the local caches are cleared and the
-requested data can be returned to the client.
-
-### Command advancement
-
-In complex queries where a read part follows a state modification part
-the synchronization process after the state modification part is
-followed by command advancement, like in single-node execution.
-
-## Creation
-
-Graph element creation is not deferred. This is practical because the
-response to a creation is the global ID of the newly created element. At
-the same time it is safe because no other worker (including the owner)
-will be using the newly added graph element.
-
-## Updating
-
-Updating is deferred, as described. Note that this also means that
-record locking conflicts are deferred and serialization errors
-(including lock timeouts) are postponed until the deferred update
-application phase. In certain scenarios it might be beneficial to force
-these errors to happen earlier, when the deferred update request is
-processed.
-
-## Deletion
-
-Deletion is also deferred. Deleting an edge implies a modification of
-it's endpoint vertices, which must be deferred as those data structures
-are not thread-safe. Deleting a vertex is either with detaching, in
-which case an arbitrary number of updates are implied in the vertex's
-neighborhood, or without detaching which relies on checking the current
-state of the graph which is generally impossible in distributed.

docs/dev/memgraph/durability/snapshots.md

@@ -1,22 +0,0 @@
-# Snapshots
-
-A "snapshot" is a record of the current database state stored in permanent
-storage. Note that the term "snapshot" is used also in the context of
-the transaction engine to denote a set of running transactions.
-
-A snapshot is written to the file by Memgraph periodically if so
-configured. The snapshot creation  process is done within a transaction created
-specifically for that purpose. The transaction is needed to ensure that
-the stored state is internally consistent.
-
-The database state can be recovered from the snapshot during startup, if
-so configured. This recovery works in conjunction with write-ahead log
-recovery.
-
-A single snapshot contains all the data needed to recover a database. In
-that sense snapshots are independent of each other and old snapshots can
-be deleted once the new ones are safely stored, if it is not necessary
-to revert the database to some older state.
-
-The exact format of the snapshot file is defined inline in the snapshot
-creation code.

docs/dev/other-code-conventions.md

@@ -0,0 +1,15 @@
+# Other Code Conventions
+
+While we are mainly programming in C++, we do use other programming languages
+when appropriate. This chapter describes conventions for such code.
+
+## Python
+
+Code written in Python should adhere to
+[PEP 8](https://www.python.org/dev/peps/pep-0008/). You should run `flake8` on
+your code to automatically check compliance.
+
+## Common Lisp
+
+Code written in Common Lisp should adhere to
+[Google Common Lisp Style](https://google.github.io/styleguide/lispguide.xml).

docs/dev/query/.gitignore

@@ -0,0 +1 @@
+html/

docs/dev/query/contents.md

@@ -0,0 +1,34 @@
+# Query Parsing, Planning and Execution
+
+This part of the documentation deals with query execution.
+
+Memgraph currently supports only query interpretation. Each new query is
+parsed, analysed and translated into a sequence of operations which are then
+executed on the main database storage. Query execution is organized into the
+following phases:
+
+  1.  [Lexical Analysis (Tokenization)](parsing.md)
+  2.  [Syntactic Analysis (Parsing)](parsing.md)
+  3.  [Semantic Analysis and Symbol Generation](semantic.md)
+  4.  [Logical Planning](planning.md)
+  5.  [Logical Plan Execution](execution.md)
+
+The main entry point is `Interpreter::operator()`, which takes a query text
+string and produces a `Results` object. To instantiate the object,
+`Interpreter` needs to perform the above steps from 1 to 4. If any of the
+steps fail, a `QueryException` is thrown. The complete `LogicalPlan` is
+wrapped into a `CachedPlan` and stored for reuse. This way we can skip the
+whole process of analysing a query if it appears to be the same as before.
+
+When we have valid plan, the client code can invoke `Results::PullAll` with a
+stream object. The `Results` instance will then execute the plan and fill the
+stream with the obtained results.
+
+Since we want to optionally run Memgraph as a distributed database, we have
+hooks for creating a different plan of logical operators.
+`DistributedInterpreter` inherits from `Interpreter` and overrides
+`MakeLogicalPlan` method. This method needs to return a concrete instance of
+`LogicalPlan`, and in case of distributed database that will be
+`DistributedLogicalPlan`.
+
+![Intepreter Class Diagram](interpreter-class.png)

docs/dev/query/execution.md

@@ -0,0 +1,373 @@
+# Logical Plan Execution
+
+We implement classical iterator style operators. Logical operators define
+operations on database. They encapsulate the following info: what the input is
+(another `LogicalOperator`), what to do with the data, and how to do it.
+
+Currently logical operators can have zero or more input operations, and thus a
+`LogicalOperator` tree is formed. Most `LogicalOperator` types have only one
+input, so we are mostly working with chains instead of full fledged trees.
+You can find information on each operator in `src/query/plan/operator.lcp`.
+
+## Cursor
+
+Logical operators do not perform database work themselves. Instead they create
+`Cursor` objects that do the actual work, based on the info in the operator.
+Cursors expose a `Pull` method that gets called by the cursor's consumer. The
+consumer keeps pulling as long as the `Pull` returns `true` (indicating it
+successfully performed some work and might be eligible for another `Pull`).
+Most cursors will call the `Pull` function of their input provided cursor, so
+typically a cursor chain is created that is analogue to the logical operator
+chain it's created from.
+
+## Frame
+
+The `Frame` object contains all the data of the current `Pull` chain. It
+serves for communicating data between cursors.
+
+For example, in a `MATCH (n) RETURN n` query the `ScanAllCursor` places a
+vertex on the `Frame` for each `Pull`. It places it on the place reserved for
+the `n` symbol. Then the `ProduceCursor` can take that same value from the
+`Frame` because it knows the appropriate symbol. `Frame` positions are indexed
+by `Symbol` objects.
+
+## ExpressionEvaluator
+
+Expressions results are not placed on the `Frame` since they do not need to be
+communicated between different `Cursors`. Instead, expressions are evaluated
+using an instance of `ExpressionEvaluator`. Since generally speaking an
+expression can be defined by a tree of subexpressions, the
+`ExpressionEvaluator` is implemented as a tree visitor. There is a performance
+sub-optimality here because a stack is used to communicate intermediary
+expression results between elements of the tree. This is one of the reasons
+why it's planned to use `Frame` for intermediary expression results as well.
+The other reason is that it might facilitate compilation later on.
+
+## Cypher Execution Semantics
+
+Cypher query execution has *mostly* well-defined semantics. Some are
+explicitly defined by openCypher and its TCK, while others are implicitly
+defined by Neo4j's implementation of Cypher that we want to be generally
+compatible with.
+
+These semantics can in short be described as follows: a Cypher query consists
+of multiple clauses some of which modify it. Generally, every clause in the
+query, when reading it left to right, operates on a consistent state of the
+property graph, untouched by subsequent clauses. This means that a `MATCH`
+clause in the beginning operates on a graph-state in which modifications by
+the subsequent `SET` are not visible.
+
+The stated semantics feel very natural to the end-user, and Neo seems to
+implement them well. For Memgraph the situation is complex because
+`LogicalOperator` execution (through a `Cursor`) happens one `Pull` at a time
+(generally meaning all the query clauses get executed for every top-level
+`Pull`). This is not inherently consistent with Cypher semantics because a
+`SET` clause can modify data, and the `MATCH` clause that precedes it might
+see the modification in a subsequent `Pull`. Also, the `RETURN` clause might
+want to stream results to the user before all `SET` clauses have been
+executed, so the user might see some intermediate graph state. There are many
+edge-cases that Memgraph does its best to avoid to stay true to Cypher
+semantics, while at the same time using a high-performance streaming approach.
+The edge-cases are enumerated in this document along with the implementation
+details they imply.
+
+## Implementation Peculiarities
+
+### Once
+
+An operator that does nothing but whose `Cursor::Pull` returns `true` on the
+first `Pull` and `false` on subsequent ones. This operator is used when
+another operator has an optional input, because in Cypher a clause will
+typically execute once for every input from the preceding clauses, or just
+once if there was no preceding input. For example, consider the `CREATE`
+clause. In the query `CREATE (n)` only one node is created, while in the query
+`MATCH (n) CREATE (m)` a node is created for each existing node. Thus in our
+`CreateNode` logical operator the input is either a `ScanAll` operator, or a
+`Once` operator.
+
+### storage::View
+
+In the previous section, [Cypher Execution
+Semantics](#cypher-execution-semantics), we mentioned how the preceding
+clauses should not see changes made in subsequent ones. For that reason, some
+operators take a `storage::View` enum value. This value determines which state of
+the graph an operator sees.
+
+Consider the query `MATCH (n)--(m) WHERE n.x = 0 SET m.x = 1`. Naive streaming
+could match a vertex `n` on the given criteria, expand to `m`, update it's
+property, and in the next iteration consider the vertex previously matched to
+`m` and skip it because it's newly set property value does not qualify. This
+is not how Cypher works. To handle this issue properly, Memgraph designed the
+`VertexAccessor` class that tracks two versions of data: one that was visible
+before the current transaction+command, and the optional other that was
+created in the current transaction+command. The `MATCH` clause will be planned
+as `ScanAll` and `Expand` operations using `storage::View::OLD` value. This
+will ensure modifications performed in the same query do not affect it. The
+same applies to edges and the `EdgeAccessor` class.
+
+### Existing Record Detection
+
+It's possible that a pattern element has already been declared in the same
+pattern, or a preceding pattern. For example `MATCH (n)--(m), (n)--(l)` or a
+cycle-detection match `MATCH (n)-->(n) RETURN n`. Implementation-wise,
+existing record detection just checks that the expanded record is equal to the
+one already on the frame.
+
+### Why Not Use Separate Expansion Ops for Edges and Vertices?
+
+Expanding an edge and a vertex in separate ops is not feasible when matching a
+cycle in bi-directional expansions. Consider the query `MATCH (n)--(n) RETURN
+n`. Let's try to expand first the edge in one op, and vertex in the next. The
+vertex expansion consumes the edge expansion input. It takes the expanded edge
+from the frame. It needs to detect a cycle by comparing the vertex existing on
+the frame with one of the edge vertices (`from` or `to`). But which one? It
+doesn't know, and can't ensure correct cycle detection.
+
+### Data Visibility During and After SET
+
+In Cypher, setting values always works on the latest version of data (from
+preceding or current clause). That means that within a `SET` clause all the
+changes from previous clauses must be visible, as well as changes done by the
+current `SET` clause. Also, if there is a clause after `SET` it must see *all*
+the changes performed by the preceding `SET`. Both these things are best
+illustrated with the following queries executed on an empty database:
+
+    CREATE (n:A {x:0})-[:EdgeType]->(m:B {x:0})
+    MATCH (n)--(m) SET m.x = n.x + 1 RETURN labels(n), n.x, labels(m), m.x
+
+This returns:
+
++---------+---+---------+---+
+|labels(n)|n.x|labels(m)|m.x|
++:=======:+:=:+:=======:+:=:+
+|[A]      |2  |[B]      |1  |
++---------+---+---------+---+
+|[B]      |1  |[A]      |2  |
++---------+---+---------+---+
+
+The obtained result implies the following operations:
+
+  1. In the first iteration set the value of the `B.x` to 1
+  2. In the second iteration the we observe `B.x` with the value of 1 and set
+     `A.x` to 2
+  3. In `RETURN` we see all the changes made in both iterations
+
+To implement the desired behavior Memgraph utilizes two techniques. First is
+the already mentioned tracking of two versions of data in vertex accessors.
+Using this approach ensures that the second iteration in the example query
+sees the data modification performed by the preceding iteration. The second
+technique is the `Accumulate` operation that accumulates all the iterations
+from the preceding logical op before passing them to the next logical op. In
+the example query, `Accumulate` ensures that the results returned to the user
+reflect changes performed in all iterations of the query (naive streaming
+could stream results at the end of first iteration producing inconsistent
+results). Note that `Accumulate` is demanding regarding memory and slows down
+query execution. For that reason it should be used only when necessary, for
+example it does not have to be used in a query that has `MATCH` and `SET` but
+no `RETURN`.
+
+### Neo4j Inconsistency on Multiple SET Clauses
+
+Considering the preceding example it could be expected that when a query has
+multiple `SET` clauses all the changes from those preceding one are visible.
+This is not the case in Neo4j's implementation. Consider the following queries
+executed on an empty database:
+
+    CREATE (n:A {x:0})-[:EdgeType]->(m:B {x:0})
+    MATCH (n)--(m) SET n.x = n.x + 1 SET m.x = m.x * 2
+    RETURN labels(n), n.x, labels(m), m.x
+
+This returns:
+
++---------+---+---------+---+
+|labels(n)|n.x|labels(m)|m.x|
++:=======:+:=:+:=======:+:=:+
+|[A]      |2  |[B]      |1  |
++---------+---+---------+---+
+|[B]      |1  |[A]      |2  |
++---------+---+---------+---+
+
+If all the iterations of the first `SET` clause were executed before executing
+the second, all the resulting values would be 2. This not being the case, we
+conclude that Neo4j does not use a barrier-like mechanism between `SET`
+clauses.  It is Memgraph's current vision that this is inconsistent and we
+plan to reduce Neo4j compliance in favour of operation consistency.
+
+### Double Deletion
+
+It's possible to match the same graph element multiple times in a single query
+and delete it. Neo supports this, and so do we. The relevant implementation
+detail is in the `GraphDbAccessor` class, where the record deletion functions
+reside, and not in the logical plan execution. It comes down to checking if a
+record has already been deleted in the current transaction+command and not
+attempting to do it again (results in a crash).
+
+### Set + Delete Edge-case
+
+It's legal for a query to combine `SET` and `DELETE` clauses. Consider the
+following queries executed on an empty database:
+
+
+    CREATE ()-[:T]->()
+    MATCH (n)--(m) SET n.x = 42 DETACH DELETE m
+
+Due to the `MATCH` being undirected the second pull will attempt to set data
+on a deleted vertex. This is not a legal operation in Memgraph storage
+implementation. For that reason the logical operator for `SET` must check if
+the record it's trying to set something on has been deleted by the current
+transaction+command. If so, the modification is not executed.
+
+### Deletion Accumulation
+
+Sometimes it's necessary to accumulate deletions of all the matches before
+attempting to execute them. Consider this the following. Start with an empty
+database and execute queries:
+
+    CREATE ()-[:T]->()-[:T]->()
+    MATCH (a)-[r1]-(b)-[r2]-(c) DELETE r1, b, c
+
+Note that the `DELETE` clause attempts to delete node `c`, but it does not
+detach it by deleting edge `r2`. However, due to undirected edge in the
+`MATCH`, both edges get pulled and deleted.
+
+Currently Memgraph does not support this behavior, Neo does. There are a few
+ways that we could do this.
+
+ * Accumulate on deletion (that sucks because we have to keep track of
+   everything that gets returned after the deletion).
+ * Maybe we could stream through the deletion op, but defer actual deletion
+   until plan-execution end.
+ * Ignore this because it's very edgy (this is the currently selected option).
+
+### Aggregation Without Input
+
+It is necessary to define what aggregation ops return when they receive no
+input. Following is a table that shows what Neo4j's Cypher implementation and
+SQL produce.
+
+
++-------------+------------------------+---------------------+---------------------+------------------+
+|    \<OP\>   | 1. Cypher, no group-by | 2. Cypher, group-by | 3. SQL, no group-by | 4. SQL, group-by |
++=============+:======================:+:===================:+:===================:+:================:+
+| Count(\*)   | 0                      | \<NO\_ROWS>         | 0                   | \<NO\_ROWS>      |
++-------------+------------------------+---------------------+---------------------+------------------+
+| Count(prop) | 0                      | \<NO\_ROWS>         | 0                   | \<NO\_ROWS>      |
++-------------+------------------------+---------------------+---------------------+------------------+
+| Sum         | 0                      | \<NO\_ROWS>         | NULL                | \<NO\_ROWS>      |
++-------------+------------------------+---------------------+---------------------+------------------+
+| Avg         | NULL                   | \<NO\_ROWS>         | NULL                | \<NO\_ROWS>      |
++-------------+------------------------+---------------------+---------------------+------------------+
+| Min         | NULL                   | \<NO\_ROWS>         | NULL                | \<NO\_ROWS>      |
++-------------+------------------------+---------------------+---------------------+------------------+
+| Max         | NULL                   | \<NO\_ROWS>         | NULL                | \<NO\_ROWS>      |
++-------------+------------------------+---------------------+---------------------+------------------+
+| Collect     | []                     | \<NO\_ROWS>         | N/A                 | N/A              |
++-------------+------------------------+---------------------+---------------------+------------------+
+
+Where:
+
+    1. `MATCH (n) RETURN <OP>(n.prop)`
+    2. `MATCH (n) RETURN <OP>(n.prop), (n.prop2)`
+    3. `SELECT <OP>(prop) FROM Table`
+    4. `SELECT <OP>(prop), prop2 FROM Table GROUP BY prop2`
+
+Neo's Cypher implementation diverges from SQL only when performing `SUM`.
+Memgraph implements SQL-like behavior. It is considered that `SUM` of
+arbitrary elements should not be implicitly 0, especially in a property graph
+without a strict schema (the property in question can contain values of
+arbitrary types, or no values at all).
+
+### OrderBy
+
+The `OrderBy` logical operator sorts the results in the desired order. It
+occurs in Cypher as part of a `WITH` or `RETURN` clause. Both the concept and
+the implementation are straightforward. It's necessary for the logical op to
+`Pull` everything from its input so it can be sorted. It's not necessary to
+keep the whole `Frame` state of each input, it is sufficient to keep a list of
+`TypedValues` on which the results will be sorted, and another list of values
+that need to be remembered and recreated on the `Frame` when yielding.
+
+The sorting itself is made to reflect that of Neo's implementation which comes
+down to these points.
+
+  * `Null` comes last (as if it's greater than anything).
+  * Primitive types compare naturally, with no implicit casting except from
+    `int` to `double`.
+  * Complex types are not comparable.
+  * Every unsupported comparison results in an exception that gets propagated
+    to the end user.
+
+### Limit in Write Queries
+
+`Limit` can be used as part of a write query, in which case it will *not*
+reduce the amount of performed updates. For example, consider a database that
+has 10 vertices. The query `MATCH (n) SET n.x = 1 RETURN n LIMIT 3` will
+result in all vertices having their property value changed, while returning
+only the first to the client. This makes sense from the implementation
+standpoint, because `Accumulate` is planned after `SetProperty` but before
+`Produce` and `Limit` operations. Note that this behavior can be
+non-deterministic in some queries, since it relies on the order of iteration
+over nodes which is undefined when not explicitly specified.
+
+### Merge
+
+`MERGE` in Cypher attempts to match a pattern. If it already exists, it does
+nothing and subsequent clauses like `RETURN` can use the matched pattern
+elements. If the pattern can't match to any data, it creates it. For detailed
+information see Neo4j's [merge
+documentation.](https://neo4j.com/docs/developer-manual/current/cypher/clauses/merge/)
+
+An important thing about `MERGE` is visibility of modified data. `MERGE` takes
+an input (typically a `MATCH`) and has two additional *phases*: the merging
+part, and the subsequent set parts (`ON MATCH SET` and `ON CREATE SET`).
+Analysis of Neo4j's behavior indicates that each of these three phases (input,
+merge, set) does not see changes to the graph state done by subsequent phase.
+The input phase does not see data created by the merge phase, nor the set
+phase. This is consistent with what seems like the general Cypher philosophy
+that query clause effects aren't visible in the preceding clauses.
+
+We define the `Merge` logical operator as a *routing* operator that uses three
+logical operator branches.
+
+  1. The input from a preceding clause.
+
+     For example in `MATCH (n), (m) MERGE (n)-[:T]-(m)`. This input is
+     optional because `MERGE` is allowed to be the first clause in a query.
+
+  2. The `merge_match` branch.
+
+     This logical operator branch is `Pull`-ed from until exhausted for each
+     successful `Pull` from the input branch.
+
+  3. The `merge_create` branch.
+
+     This branch is `Pull`ed when the `merge_match` branch does not match
+     anything (no successful `Pull`s) for an input `Pull`. It is `Pull`ed only
+     once in such a situation, since only one creation needs to occur for a
+     failed match.
+
+The `ON MATCH SET` and `ON CREATE SET` parts of the `MERGE` clause are
+included in the `merge_match` and `merge_create` branches respectively. They
+are placed on the end of their branches so that they execute only when those
+branches succeed.
+
+Memgraph strives to be consistent with Neo in its `MERGE` implementation,
+while at the same time keeping performance as good as possible. Consistency
+with Neo w.r.t. graph state visibility is not trivial. Documentation for
+`Expand` and `Set` describe how Memgraph keeps track of both the updated
+version of an edge/vertex and the old one, as it was before the current
+transaction+command. This technique is also used in `Merge`. The input
+phase/branch of `Merge` always looks at the old data. The merge phase needs to
+see the new data so it doesn't create more data then necessary.
+
+For example, consider the query.
+
+    MATCH (p:Person) MERGE (c:City {name: p.lives_in})
+
+This query needs to create a city node only once for each unique `p.lives_in`.
+Finally the set phase of a `MERGE` clause should not affect the merge phase.
+To achieve this the `merge_match` branch of the `Merge` operator should see
+the latest created nodes, but filter them on their old state (if those nodes
+were not created by the `create_branch`).  Implementation-wise that means that
+`ScanAll` and `Expand` operators in the `merge_branch` need to look at the new
+graph state, while `Filter` operators the old, if available.

docs/dev/query/interpreter-class.dot

@@ -0,0 +1,23 @@
+digraph interpreter {
+  node [fontname="dejavusansmono"]
+  edge [fontname="dejavusansmono"]
+  node [shape=record]
+  edge [dir=back,arrowtail=empty,arrowsize=1.5]
+  Interpreter [label="{\N|+ operator(query : string, ...) : Results\l|
+                      # MakeLogicalPlan(...) : LogicalPlan\l|
+                      - plan_cache_ : Map(QueryHash, CachedPlan)\l}"]
+  Interpreter -> DistributedInterpreter
+  Results [label="{\N|+ PullAll(stream) : void\l|- plan_ : CachedPlan\l}"]
+  Interpreter -> Results
+    [dir=forward,style=dashed,arrowhead=open,label="<<create>>"]
+  CachedPlan -> Results
+    [dir=forward,arrowhead=odiamond,taillabel="1",headlabel="*"]
+  Interpreter -> CachedPlan [arrowtail=diamond,taillabel="1",headlabel="*"]
+  CachedPlan -> LogicalPlan [arrowtail=diamond]
+  LogicalPlan [label="{\N|+ GetRoot() : LogicalOperator
+                      \l+ GetCost() : double\l}"]
+  LogicalPlan -> SingleNodeLogicalPlan [style=dashed]
+  LogicalPlan -> DistributedLogicalPlan [style=dashed]
+  DistributedInterpreter -> DistributedLogicalPlan
+    [dir=forward,style=dashed,arrowhead=open,label="<<create>>"]
+}

docs/dev/query/parsing.md

@@ -0,0 +1,62 @@
+# Lexical and Syntactic Analysis
+
+## Antlr
+
+We use Antlr for lexical and syntax analysis of Cypher queries. Antrl uses
+grammar file `Cypher.g4` downloaded from http://www.opencypher.org to generate
+the parser and the visitor for the Cypher parse tree. Even though the provided
+grammar is not very pleasant to work with we decided not to do any drastic
+changes to it so that our transition to newly published versions of
+`Cypher.g4` would be easier. Nevertheless, we had to fix some bugs and add
+features, so our version is not completely the same.
+
+In addition to using `Cypher.g4`, we have `MemgraphCypher.g4`. This grammar
+file defines Memgraph specific extensions to the original grammar. Most
+notable example is the inclusion of syntax for handling authorization. At the
+moment, some extensions are also found in `Cypher.g4`. For example, the syntax
+for using a lambda function in relationship patterns. These extensions should
+be moved out of `Cypher.g4`, so that it remains as close to the original
+grammar as possible. Additionally, having `MemgraphCypher.g4` may not be
+enough if we wish to split the functionality for community and enterprise
+editions of Memgraph.
+
+## Abstract Syntax Tree (AST)
+
+Since Antlr generated visitor and the official openCypher grammar are not very
+practical to use, we translate the Antlr's AST to our own AST. Currently there
+are ~40 types of nodes in our AST. Their definitions can be found in
+`src/query/frontend/ast/ast.lcp`.
+
+Major groups of types can be found under the following base types.
+
+  * `Expression` --- types corresponding to Cypher expressions.
+  * `Clause` --- types corresponding to Cypher clauses.
+  * `PatternAtom` --- node or edge related information.
+  * `Query` --- different kinds of queries, allows extending the language with
+    Memgraph specific query syntax.
+
+Memory management of created AST nodes is done with `AstStorage`. Each type
+must be created by invoking `AstStorage::Create` method. This way all of the
+pointers to nodes and their children are raw pointers. The only owner of
+allocated memory is the `AstStorage`. When the storage goes out of scope, the
+pointers become invalid. It may be more natural to handle tree ownership via
+`unique_ptr`, i.e. each node owns its children. But there are some benefits to
+having a custom storage and allocation scheme.
+
+The primary reason we opted for not using `unique_ptr` is the requirement of
+Antlr's base visitor class that the resulting values must by copyable. The
+result is wrapped in `antlr::Any` so that the derived visitor classes may
+return any type they wish when visiting Antlr's AST. Unfortunately,
+`antlr::Any` does not work with non-copyable types.
+
+Another benefit of having `AstStorage` is that we can easily add a different
+allocation scheme for AST nodes. The interface of node creation would not
+change.
+
+### AST Translation
+
+The translation process is done via `CypherMainVisitor` class, which is
+derived from Antlr generated visitor. Besides instancing our AST types, a
+minimal number of syntactic checks are done on a query. These checks handle
+the cases which were valid in original openCypher grammar, but may be invalid
+when combined with other syntax elements.

docs/dev/query/planning.md

@@ -0,0 +1,526 @@
+# Logical Planning
+
+After the semantic analysis and symbol generation, the AST is converted to a
+tree of logical operators. This conversion is called *planning* and the tree
+of logical operators is called a *plan*. The whole planning process is done in
+the following steps.
+
+  1. [AST Preprocessing](#ast-preprocessing)
+
+     The first step is to preprocess the AST by collecting
+     information on filters, divide the query into parts, normalize patterns
+     in `MATCH` clauses, etc.
+
+  2. [Logical Operator Planning](#logical-operator-planning)
+
+     After the preprocess step, the planning can be done via 2 planners:
+     `VariableStartPlanner` and `RuleBasedPlanner`. The first planner will
+     generate multiple plans where each plan has different starting points for
+     searching the patterns in `MATCH` clauses. The second planner produces a
+     single plan by mapping the query parts as they are to logical operators.
+
+  3. [Logical Plan Postprocessing](#logical-plan-postprocessing)
+
+     In this stage, we perform various transformations on the generated logical
+     plan. Here we want to optimize the operations in order to improve
+     performance during the execution. Naturally, transformations need to
+     preserve the semantic behaviour of the original plan.
+
+  4. [Cost Estimation](#cost-estimation)
+
+     After the generation, the execution cost of each plan is estimated. This
+     estimation is used to select the best plan which will be executed.
+
+The implementation can be found in the `query/plan` directory, with the public
+entry point being `query/plan/planner.hpp`.
+
+## AST Preprocessing
+
+Each openCypher query consists of at least 1 **single query**. Multiple single
+queries are chained together using a **query combinator**. Currently, there is
+only one combinator, `UNION`. The preprocessing step starts in the
+`CollectQueryParts` function. This function will take a look at each single
+query and divide it into parts. Each part is separated with `RETURN` and
+`WITH` clauses. For example:
+
+    MATCH (n) CREATE (m) WITH m MATCH (l)-[]-(m) RETURN l
+    |                          |                        |
+    |------- part 1 -----------+-------- part 2 --------|
+    |                                                   |
+    |-------------------- single query -----------------|
+
+Each part is created by collecting all `MATCH` clauses and *normalizing* their
+patterns. Pattern normalization is the process of converting an arbitrarily
+long pattern chain of nodes and edges into a list of triplets `(start node,
+edge, end node)`. The triplets should preserve the semantics of the match. For
+example:
+
+    MATCH (a)-[p]-(b)-[q]-(c)-[r]-(d)
+
+is equivalent to:
+
+    MATCH (a)-[p]-(b), (b)-[q]-(c), (c)-[r]-(d)
+
+With this representation, it becomes easier to reorder the triplets and choose
+different strategies for pattern matching.
+
+In addition to normalizing patterns, all of the filter expressions in patterns
+and inside of the `WHERE` clause (of the accompanying `MATCH`) are extracted
+and stored separately. During the extraction, symbols used in the filter
+expression are collected. This allows for planning filters in a valid order,
+as the matching for triplets is being done. Another important benefit of
+having extra information on filters, is to recognize when a database index
+could be used.
+
+After each `MATCH` is processed, they are all grouped, so that even the whole
+`MATCH` clauses may be reordered. The important thing is to remember which
+symbols were used to name edges in each `MATCH`. With those symbols we can
+plan for *cyphermorphism*, i.e. ensure different edges in the search pattern
+of a single `MATCH` map to different edges in the graph. This preserves the
+semantic of the query, even though we may have reordered the matching. The
+same steps are done for `OPTIONAL MATCH`.
+
+Another clause which needs processing is `MERGE`. Here we normalize the
+pattern, since the `MERGE` is a bit like `MATCH` and `CREATE` in one.
+
+All the other clauses are left as is.
+
+In the end, each query part consists of:
+
+  * processed and grouped `MATCH` clauses;
+  * processed and grouped `OPTIONAL MATCH` clauses;
+  * processed `MERGE` matching pattern and
+  * unchanged remaining clauses.
+
+The last stored clause is guaranteed to be either `WITH` or `RETURN`.
+
+## Logical Operator Planning
+
+### Variable Start Planner
+
+The `VariableStartPlanner` generates multiple plans for a single query. Each
+plan is generated by selecting a different starting point for pattern
+matching.
+
+The algorithm works as follows.
+
+  1. For each query part:
+     1. For each node in triplets of collected `MATCH` clauses:
+        i. Add the node to a set of `expanded` nodes
+        ii. Select a triplet `(start node, edge, end node)` whose `start node` is
+            in the `expanded` set
+        iii. If no triplet was selected, choose a new starting node that isn't in
+             `expanded` and continue expanding
+        iv. Repeat steps ii. -- iii. until all triplets have been selected
+            and store that as a variation of the `MATCH` clauses
+     2. Do step 1.1. for `OPTIONAL MATCH` and `MERGE` clauses
+     3. Take all combinations of the generated `MATCH`, `OPTIONAL MATCH` and
+        `MERGE` and store them as variations of the query part.
+  2. For each combination of query part variations:
+     1. Generate a plan using the rule based planner
+
+###  Rule Based Planner
+
+The `RuleBasedPlanner` generates a single plan for a single query. A plan is
+generated by following hardcoded rules for producing logical operators. The
+following sections are an overview on how each openCypher clause is converted
+to a `LogicalOperator`.
+
+####  MATCH
+
+`MATCH` clause is used to specify which patterns need to be searched for in
+the database. These patterns are normalized in the preprocess step to be
+represented as triplets `(start node, edge, end node)`. When there is no edge,
+then the triplet is reduced only to the `start node`. Generating the operators
+is done by looping over these triplets.
+
+##### Searching for Nodes
+
+The simplest search is finding standalone nodes. For example, `MATCH (n)`
+will find all the nodes in the graph. This is accomplished by generating a
+`ScanAll` operator and forwarding the node symbol which should store the
+results. In this case, all the nodes will be referenced by `n`.
+
+Multiple nodes can be specified in a single match, e.g. `MATCH (n), (m)`.
+Planning is done by repeating the same steps for each sub pattern (separated
+by a comma). In this case, we would get 2 `ScanAll` operators chained one
+after the other. An optimization can be obtained if the node in the pattern is
+already searched for. In `MATCH (n), (n)` we can drop the second `ScanAll`
+operator since we have already generated it for the first node.
+
+##### Searching for Relationships
+
+A more advanced search includes finding nodes with relationships. For example,
+`MATCH (n)-[r]-(m)` should find every pair of connected nodes in the database.
+This means, that if a single node has multiple connections, it will be
+repeated for each combination of pairs. The generation of operators starts
+from the first node in the pattern. If we are referencing a new starting node,
+we need to generate a `ScanAll` which finds all the nodes and stores them
+into `n`. Then, we generate an `Expand` operator which reads the `n` and
+traverses all the edges of that node. The edge is stored into `r`, while the
+destination node is stored in `m`.
+
+Matching multiple relationships proceeds similarly, by repeating the same
+steps. The only difference is that we need to ensure different edges in the
+search pattern, map to different edges in the graph. This means that after each
+`Expand` operator, we need to generate an `EdgeUniquenessFilter`. We provide
+this operator with a list of symbols for the previously matched edges and the
+symbol for the current edge.
+
+For example.
+
+    MATCH (n)-[r1]-(m)-[r2]-(l)
+
+The above is preprocessed into
+
+    MATCH (n)-[r1]-(m), (m)-[r2]-(l)
+
+Then we look at each triplet in order and perform the described steps. This
+way, we would generate:
+
+    ScanAll (n) > Expand (n, r1, m) > Expand (m, r2, l) >
+        EdgeUniquenessFilter ([r1], r2)
+
+Note that we don't need to make `EdgeUniquenessFilter` after the first
+`Expand`, since there are no edges to compare to. This filtering needs to work
+across multiple pattern, but inside a *single* `MATCH` clause.
+
+Let's take a look at the following.
+
+    MATCH (n)-[r1]-(m), (m)-[r2]-(l)
+
+We would also generate the exact same operators.
+
+    ScanAll (n) > Expand (n, r1, m) > Expand (m, r2, l) >
+        EdgeUniquenessFilter ([r1], r2)
+
+On the other hand,
+
+    MATCH (n)-[r1]-(m) MATCH (m)-[r2]-(l)-[r3]-(i)
+
+would reset the uniqueness filtering at the start of the second match. This
+would mean that we output the following:
+
+    ScanAll (n) > Expand (n, r1, m) > Expand (m, r2, l) > Expand (l, r3, i) >
+        EdgeUniquenessFilter ([r2], r3)
+
+There is a difference in how we handle edge uniqueness compared to Neo4j.
+Neo4j does not allow searching for a single edge multiple times, but we've
+decided to support that.
+
+For example, the user can say the following.
+
+    MATCH (n)-[r]-(m)-[r]-l
+
+We would ensure that both `r` variables match to the same edge. In our
+terminology, we call this the *edge cycle*. For the above example, we would
+generate this plan.
+
+    ScanAll (n) > Expand (n, r, m) > Expand (m, r, l)
+
+We do not put an `EdgeUniquenessFilter` operator between 2 `Expand`
+operators and we tell the 2nd `Expand` that it is an edge cycle. This, 2nd
+`Expand` will ensure we have matched both the same edges.
+
+##### Filtering
+
+To narrow the search down, the patterns in `MATCH` can have filtered labels
+and properties. A more general filtering is done using the accompanying
+`WHERE` clause. During the preprocess step, all filters are collected and
+extracted into expressions. Additional information on which symbols are used
+is also stored. This way, each time we generate a `ScanAll` or `Expand`, we
+look at all the filters to see if any of them can be used. I.e. if the symbols
+they use have been bound by a newly produced operator. If a filter expression
+can be used, we immediately add a `Filter` operator with that expression.
+
+For example.
+
+    MATCH (n)-[r]-(m :label) WHERE n.prop = 42
+
+We would produce:
+
+    ScanAll (n) > Filter (n.prop) > Expand (n, r, m) > Filter (m :label)
+
+This means that the same plan is generated for the query:
+
+    MATCH (n {prop: 42})-[r]-(m :label)
+
+#### OPTIONAL
+
+If a `MATCH` clause is preceded by `OPTIONAL`, then we need to generate a plan
+such that we produce results even if we fail to match anything. This is
+accomplished by generating an `Optional` operator, which takes 2 operator
+trees:
+
+  * input operation and
+  * optional operation.
+
+The input is the operation we generated for the part of the query before
+`OPTIONAL MATCH`. For the optional operation, we simply generate the `OPTIONAL
+MATCH` part just like we would for regular `MATCH`. In addition to operations,
+we need to send the symbols which are set during optional matching to the
+`Optional` operator. The operator will reset values of those symbols to
+`null`, when the optional part fails to match.
+
+#### RETURN & WITH
+
+`RETURN` and `WITH` clauses are very similar to each other. The only
+difference is that `WITH` separates parts of the query and can be paired with
+`WHERE` clause.
+
+The common part is generating operators for the body of the clause. Separation
+of query parts is mostly done in semantic analysis, which checks that only the
+symbols exposed through `WITH` are visible in the query parts after the
+clause. The minor part is done in planning.
+
+##### Named Results
+
+Both clauses contain multiple named expressions (`expr AS name`) which are
+used to generate `Produce` operator.
+
+##### Aggregations
+
+If an expression contains an aggregation operator (`sum`, `avg`, ...) we need
+to plan the `Aggregate` operator as input to `Produce`. This case is more
+complex, because aggregation in openCypher can perform implicit grouping of
+results used for aggregation.
+
+For example, `WITH/RETURN sum(n.x) AS s, n.y AS group` will implicitly group
+by `n.y` expression.
+
+Another, obscure grouping can be achieved with `RETURN sum(n.a) + n.b AS s`.
+Here, the `n.b` will be used for grouping, even though both the `sum` and
+`n.b` are in the same named expression.
+
+Therefore, we need to collect all expressions which do not contain
+aggregations and use them for grouping. You may have noticed that in the last
+example `sum` is actually a sub-expression of `+`. `Aggregate` operator does
+not see that (nor it should), so the responsibility of evaluating that falls
+on `Produce`. One way is for `Aggregate` to store results of grouping
+expressions on the frame in addition to aggregation results. Unfortunately,
+this would require rewiring named expressions in `Produce` to reference
+already evaluated expressions. In the current implementation, we opted for
+`Aggregate` to store only aggregation results on the frame, while `Produce`
+will re-evaluate all the other (grouping) expressions. To handle that, symbols
+which are used in expressions are passed to `Aggregate`, so that they can be
+remembered. `Produce` will read those symbols from the frame and use it to
+re-evaluate the needed expressions.
+
+##### Accumulation
+
+After we have `Produce` and potentially `Aggregate`, we need to handle a
+special case when the part of the query before `RETURN` or `WITH` performs
+updates. For that, we want to run that part of the query fully, so that we get
+the latest results. This is accomplished by adding `Accumulate` operator as
+input to `Aggregate` or `Produce` (if there is no aggregation). Accumulation
+will store all the values for all the used symbols inside `RETURN` and `WITH`,
+so that they can be used in the operator which follows. This way, only parts
+of the frame are copied, instead of the whole frame. Here is a minor
+difference between planning `WITH`, compared to `RETURN`. Since `WITH` can
+separate writing from reading, we need to advance the transaction command.
+This enables the later, read parts of the query to obtain the newest changes.
+This is supported by passing `advance_command` flag to `Accumulate` operator.
+
+In the simplest case, common to both clauses, we have `Accumulate > Aggregate
+> Produce` operators, where `Accumulate` and `Aggregate` may be left out.
+
+##### Ordering
+
+Planning `ORDER BY` is simple enough. Since it may see new symbols (filled in
+`Produce`), we add the `OrderBy` operator at the end. The operator will change
+the order of produced results, so we pass it the ordering expressions and the
+output symbols of named expressions.
+
+##### Filtering
+
+A final difference in `WITH`, is when it contains a `WHERE` clause. For that,
+we simply generate the `Filter` operator, appended after `Produce` or
+`OrderBy` (depending which operator is last).
+
+##### Skipping and Limiting
+
+If we have `SKIP` or `LIMIT`, we generate `Skip` or `Limit` operators,
+respectively. These operators are put at the end of the clause.
+
+This placement may have some unexpected behaviour when combined with
+operations that update the graph. For example.
+
+    MATCH (n) SET n.x = n.x + 1 RETURN n LIMIT 1
+
+The above query may be interpreted as if the `SET` will be done only once.
+Since this is a write query, we need to accumulate results, so the part before
+`RETURN` will execute completely. The accumulated results will be yielded up
+to the given limit, and the user would get only the first `n` that was
+updated.  This may confuse the user because in reality, every node in the
+database had been updated.
+
+Note that `Skip` always comes before `Limit`. In the current implementation,
+they are generated directly one after the other.
+
+#### CREATE
+
+`CREATE` clause is used to create nodes and edges (relationships).
+
+For multiple `CREATE` clauses or multiple creation patterns in a single
+clause, we perform the same, following steps.
+
+##### Creating a Single Node
+
+A node is created by simply specifying a node pattern.
+
+For example `CREATE (n :label {property: "value"}), ()` would create 2 nodes.
+The 1st one would be created with a label and a property. This node could be
+referenced later in the query, by using the variable `n`. The 2nd node cannot
+be referenced and it would be created without any labels nor properties. For
+node creation, we generate a `CreateNode` operator and pass it all the details
+of node creation: variable symbol, labels and properties. In the mentioned
+example, we would have `CreateNode > CreateNode`.
+
+##### Creating a Relationship
+
+To create a relationship, the `CREATE` clause must contain a pattern with a
+directed edge. Compared to creating a single node, this case is a bit more
+complicated, because either side of the edge may not exist. By exist, we mean
+that the endpoint is a variable which already references a node.
+
+For example, `MATCH (n) CREATE (n)-[r]->(m)` would create an edge `r` and a
+node `m` for each matched node `n`. If we focus on the `CREATE` part, we
+generate `CreateExpand (n, r, m)` where `n` already exists (refers to matched
+node) and `m` would be newly created along with edge `r`. If we had only
+`CREATE (n)-[r]->(m)`, then we would need to create both nodes of the edge
+`r`. This is done by generating `CreateNode (n) > CreateExpand(n, r, m)`. The
+final case is when both endpoints refer to an existing node. For example, when
+adding a node with a cyclical connection `CREATE (n)-[r]->(n)`. In this case,
+we would generate `CreateNode (n) > CreateExpand (n, r, n)`. We would tell
+`CreateExpand` to only create the edge `r` between the already created `n`.
+
+#### MERGE
+
+Although the merge operation is complex, planning turns out to be relatively
+simple. The pattern inside the `MERGE` clause is used for both matching and
+creating. Therefore, we create 2 operator trees, one for each action.
+
+For example.
+
+    MERGE (n)-[r:r]-(m)
+
+We would generate a single `Merge` operator which has the following.
+
+  * No input operation (since it is not preceded by any other clause).
+
+  * On match operation
+
+    `ScanAll (n) > Expand (n, r, m) > Filter (r)`
+
+  * On create operation
+
+    `CreateNode (n) > CreateExpand (n, r, m)`
+
+In cases when `MERGE` contains `ON MATCH` and `ON CREATE` parts, we simply
+append their operations to the respective operator trees.
+
+Observe the following example.
+
+    MERGE (n)-[r:r]-(m) ON MATCH SET n.x = 42 ON CREATE SET m :label
+
+The `Merge` would be generated with the following.
+
+  * No input operation (again, since there is no clause preceding it).
+
+  * On match operation
+
+    `ScanAll (n) > Expand (n, r, m) > Filter (r) > SetProperty (n.x, 42)`
+
+  * On create operation
+
+    `CreateNode (n) > CreateExpand (n, r, m) > SetLabels (n, :label)`
+
+When we have preceding clauses, we simply put their operator as input to
+`Merge`.
+
+    MATCH (n) MERGE (n)-[r:r]-(m)
+
+The above would be generated as
+
+    ScanAll (n) > Merge (on_match_operation, on_create_operation)
+
+Here we need to be careful to recognize which symbols are already declared.
+But, since the `on_match_operation` uses the same algorithm for generating a
+`Match`, that problem is handled there. The same should hold for
+`on_create_operation`, which uses the process of generating a `Create`. So,
+finally for this example, the `Merge` would have:
+
+  * Input operation
+
+    `ScanAll (n)`
+
+  * On match operation
+
+    `Expand (n, r, m) > Filter (r)`
+
+    Note that `ScanAll` is not needed since we get the nodes from input.
+
+  * On create operation
+
+    `CreateExpand (n, r, m)`
+
+    Note that `CreateNode` is dropped, since we want to expand the existing one.
+
+## Logical Plan Postprocessing
+
+Postprocessing of a logical plan is done by rewriting the original plan into
+a more efficient one while preserving the original semantic of operations.
+The rewriters are found in `query/plan/rewrite` directory, and currently we
+only have one -- `IndexLookupRewriter`.
+
+### IndexLookupRewriter
+
+The job of this rewriter is to merge `Filter` and `ScanAll` operations into
+equivalent `ScanAllBy<Index>` operations. In almost all cases using indexed
+lookup will be faster than regular lookup, so `IndexLookupRewriter` simply
+does the transformations whenever possible. The simplest case being the
+following, assuming we have an index over `id`.
+
+  * Original Plan
+
+    `ScanAll (n) > Filter (id(n) == 42) > Produce (n)`
+
+  * Rewritten Plan
+
+    `ScanAllById (n, id=42) > Produce (n)`
+
+Naturally, there are some cases we need to be careful about.
+
+  1. Operators with Multiple Branches
+
+     Here we may not carry `Filter` operations outside of the operator into
+     its branches, so the branches are rewritten as stand alone plans with a
+     branch new `IndexLookupRewriter`. Some of the operators with multiple
+     branches are `Merge`, `Optional`, `Cartesian` and `Union`.
+
+  2. Expand Operators
+
+     Expand operations aren't that tricky to handle, but they have a special
+     case where we want to use an indexed lookup of the destination so that the
+     expansion is performed between known nodes. This decision may depend on
+     various parameters which may need further tweaking as we encounter more
+     use-cases of Cypher queries.
+
+## Cost Estimation
+
+Cost estimation is the final step of processing a logical plan. The
+implementation can be found in `query/plan/cost_estimator.hpp`. We give each
+operator a cost based on the estimated cardinality of results of that operator
+and on the preset coefficient of the runtime performance of that operator.
+
+This scheme is rather simple and works quite well, but there are couple of
+improvements we may want to do at some point.
+
+  * Track more information about the stored graph and use that to improve the
+    estimates.
+  * Do a quick, partial run of the plan and tweak the estimation based on how
+    much each operator produced results. This may require us having some kind
+    of representative subset of the stored graph.
+  * Write micro benchmarks for each operator and based on the results create
+    sensible preset coefficients. This would replace the current coefficients
+    which are just assumptions on how each operator implementation performs.

docs/dev/query/semantic.md

@@ -0,0 +1,134 @@
+# Semantic Analysis and Symbol Generation
+
+In this phase, various semantic and variable type checks are performed.
+Additionally, we generate symbols which map AST nodes to stored values
+computed from evaluated expressions.
+
+## Symbol Generation
+
+Implementation can be found in `query/frontend/semantic/symbol_generator.cpp`.
+
+Symbols are generated for each AST node that represents data that needs to
+have storage. Currently, these are:
+
+  * `NamedExpression`
+  * `CypherUnion`
+  * `Identifier`
+  * `Aggregation`
+
+You may notice that the above AST nodes may not correspond to something named
+by a user. For example, `Aggregation` can be a part of larger expression and
+thus remain unnamed. The reason we still generate symbols is to have a uniform
+behaviour when executing a query as well as allow for caching the results of
+expression evaluation.
+
+AST nodes do not actually store a `Symbol` instance, instead they have a
+`int32_t` index identifying the symbol in the `SymbolTable` class. This is
+done to minimize the size of AST types as well as allow easier sharing of same
+symbols with multiple instances of AST nodes.
+
+The storage for evaluated data is represented by the `Frame` class. Each
+symbol determines a unique position in the frame. During interpretation,
+evaluation of expressions which have a symbol will either read or store values
+in the frame. For example, instance of an `Identifier` will use the symbol to
+find and read the value from `Frame`. On the other hand, `NamedExpression`
+will take the result of evaluating its own expression and store it in the
+`Frame`.
+
+When a symbol is created, context of creation is used to assign a type to that
+symbol. This type is used for simple type checking operations. For example,
+`MATCH (n)` will create a symbol for variable `n`. Since the `MATCH (n)`
+represents finding a vertex in the graph, we can set `Symbol::Type::Vertex`
+for that symbol. Later, for example in `MATCH ()-[n]-()` we see that variable
+`n` is used as an edge. Since we already have a symbol for that variable, we
+detect this type mismatch and raise a `SemanticException`.
+
+Basic rule of symbol generation, is that variables inside `MATCH`, `CREATE`,
+`MERGE`, `WITH ... AS` and `RETURN ... AS` clauses establish new symbols.
+
+### Symbols in Patterns
+
+Inside `MATCH`, symbols are created only if they didn't exist before. For
+example, patterns in `MATCH (n {a: 5})--(m {b: 5}) RETURN n, m` will create 2
+symbols: one for `n` and one for `m`. `RETURN` clause will, in turn, reference
+those symbols. Symbols established in a part of pattern are immediately bound
+and visible in later parts. For example, `MATCH (n)--(n)` will create a symbol
+for variable `n` for 1st `(n)`. That symbol is referenced in 2nd `(n)`. Note
+that the symbol is not bound inside 1st `(n)` itself. What this means is that,
+for example, `MATCH (n {a: n.b})` should raise an error, because `n` is not
+yet bound when encountering `n.b`. On the other hand,
+`MATCH (n)--(n {a: n.b})` is fine.
+
+The `CREATE` is similar to `MATCH`, but it *always* establishes symbols for
+variables which create graph elements. What this means is that, for example
+`MATCH (n) CREATE (n)` is not allowed. `CREATE` wants to create a new node,
+for which we already have a symbol. In such a case, we need to throw an error
+that the variable `n` is being redeclared. On the other hand `MATCH (n) CREATE
+(n)-[r :r]->(n)` is fine, because `CREATE` will only create the edge `r`,
+connecting the already existing node `n`. Remaining behaviour is the same as
+in `MATCH`. This means that we can simplify `CREATE` to be like `MATCH` with 2
+special cases.
+
+  1. Are we creating a node, i.e. `CREATE (n)`? If yes, then the symbol for
+     `n` must not have been created before. Otherwise, we reference the
+     existing symbol.
+  2. Are we creating an edge, i.e. we encounter a variable for an edge inside
+     `CREATE`? If yes, then that variable must not reference a symbol.
+
+The `MERGE` clause is treated the same as `CREATE` with regards to symbol
+generation. The only difference is that we allow bidirectional edges in the
+pattern. When creating such a pattern, the direction of the created edge is
+arbitrarily determined.
+
+### Symbols in WITH and RETURN
+
+In addition to patterns, new symbols are established in the `WITH` clause.
+This clause makes the new symbols visible *only* to the rest of the query.
+For example, `MATCH (old) WITH old AS new RETURN new, old` should raise an
+error that `old` is unbound inside `RETURN`.
+
+There is a special case with symbol visibility in `WHERE` and `ORDER BY`. They
+need to see both the old and the new symbols. Therefore `MATCH (old) RETURN
+old AS new ORDER BY old.prop` needs to work. On the other hand, if we perform
+aggregations inside `WITH` or `RETURN`, then the old symbols should not be
+visible neither in `WHERE` nor in `ORDER BY`. Since the aggregation has to go
+through all the results in order to generate the final value, it makes no
+sense to store old symbols and their values. A query like `MATCH (old) WITH
+SUM(old.prop) AS sum WHERE old.prop = 42 RETURN sum` needs to raise an error
+that `old` is unbound inside `WHERE`.
+
+For cases when `SKIP` and `LIMIT` appear, we disallow any identifiers from
+appearing in their expressions. Basically, `SKIP` and `LIMIT` can only be
+constant expressions[^1]. For example, `MATCH (old) RETURN old AS new SKIP
+new.prop` needs to raise that variables are not allowed in `SKIP`. It makes no
+sense to allow variables, since their values may vary on each iteration. On
+the other hand, we could support variables to constant expressions, but for
+simplicity we do not. For example, `MATCH (old) RETURN old, 2 AS limit_var
+LIMIT limit_var` would still throw an error.
+
+Finally, we generate symbols for names created in `RETURN` clause. These
+symbols are used for the final results of a query.
+
+NOTE: New symbols in `WITH` and `RETURN` should be unique. This means that
+`WITH a AS same, b AS same` is not allowed, neither is a construct like
+`RETURN 2, 2`
+
+### Symbols in Functions which Establish New Scope
+
+Symbols can also be created in some functions. These functions usually take an
+expression, bind a single variable and run the expression inside the newly
+established scope.
+
+The `all` function takes a list, creates a variable for list element and runs
+the predicate expression. For example:
+
+    MATCH (n) RETURN n, all(n IN n.prop_list WHERE n < 42)
+
+We create a new symbol for use inside `all`, this means that the `WHERE n <
+42` uses the `n` which takes values from a `n.prop_list` elements. The
+original `n` bound by `MATCH` is not visible inside the `all` function, but it
+is visible outside. Therefore, the `RETURN n` and `n.prop_list` reference the
+`n` from `MATCH`.
+
+[^1]: Constant expressions are expressions for which the result can be
+  computed at compile time.

docs/dev/quick-start.md

@@ -10,14 +10,12 @@ on your machine before you can download the source code.
 On Debian systems, you can do it inside a terminal with the following
 command:
 
-    sudo apt-get install git
-
-On ArchLinux or Gentoo, you probably already know what to do.
+    apt install git
 
 After installing `git`, you are now ready to fetch your own copy of Memgraph
 source code. Run the following command:
 
-    git clone https://phabricator.memgraph.io/diffusion/MG/memgraph.git
+    git clone https://github.com/memgraph/memgraph.git
 
 The above will create a `memgraph` directory and put all source code there.
 
@@ -32,27 +30,47 @@ In your terminal, position yourself in the obtained memgraph directory.
 
 ### Installing Dependencies
 
-On Debian systems, all of the dependencies should be setup by running the
+Dependencies that are required by the codebase should be checked by running the
 `init` script:
 
-    ./init -s
-
-Currently, other systems aren't supported in the `init` script. But you can
-issue the needed steps manually. First run the `init` script.
-
     ./init
 
-The script will output the required packages, which you should be able to
-install via your favorite package manager. For example, `pacman` on ArchLinux.
-After installing the packages, issue the following commands:
+If the script fails, dependencies installation scripts could be found under
+`environment/os/`. The directory contains dependencies management script for
+each supported operating system. E.g. if your system is **Debian 10**, run the
+following to install all required build packages:
+
+    ./environment/os/debian-10.sh install MEMGRAPH_BUILD_DEPS
+
+Once everything is installed, rerun the `init` script.
+
+Once the `init` script is successfully finished, issue the following commands:
 
     mkdir -p build
-    ./libs/setups.sh
+    ./libs/setup.sh
 
 ### Compiling
 
-With all of the dependencies installed, you need to configure the build
-system. To do that, execute the following:
+Memgraph is compiled using our own custom toolchain that can be obtained from
+the toolchain repository. You should read the `environment/README.txt` file
+in the repository and install the apropriate toolchain for your distribution.
+After you have installed the toolchain you should read the instructions for the
+toolchain in the toolchain install directory (`/opt/toolchain-vXYZ/README.md`)
+and install dependencies that are necessary to run the toolchain.
+
+When you want to compile Memgraph you should activate the toolchain using the
+prepared toolchain activation script that is also described in the toolchain
+`README`.
+
+NOTE: You **must** activate the toolchain every time you want to compile
+Memgraph!
+
+You should now activate the toolchain in your console.
+
+    source /opt/toolchain-vXYZ/activate
+
+With all of the dependencies installed and the build environment set-up, you
+need to configure the build system. To do that, execute the following:
 
     cd build
     cmake ..
@@ -76,3 +94,14 @@ To make extra sure, run the unit tests:
 If you have any trouble running the above commands, contact your nearest
 developer who successfully built Memgraph. Ask for help and insist on getting
 this document updated with correct steps!
+
+## Next Steps
+
+Familiarise yourself with our code conventions and guidelines:
+
+  * [C++ Code](cpp-code-conventions.md)
+  * [Other Code](other-code-conventions.md)
+  * [Code Review Guidelines](code-review.md)
+
+Take a look at the list of [required reading](required-reading.md) for
+brushing up on technical skills.

docs/dev/required-reading.md

@@ -0,0 +1,129 @@
+# Required Reading
+
+This chapter lists a few books that should be read by everyone working on
+Memgraph. Since Memgraph is developed primarily with C++, Python and Common
+Lisp, books are oriented around those languages. Of course, there are plenty
+of general books which will help you improve your technical skills (such as
+"The Pragmatic Programmer", "The Mythical Man-Month", etc.), but they are not
+listed here. This way the list should be kept short and the *required* part in
+"Required Reading" more easily honored.
+
+Some of these books you may find in our office, so feel free to pick them up.
+If any are missing and you would like a physical copy, don't be afraid to
+request the book for our office shelves.
+
+Besides reading, don't get stuck in a rut and be a
+[Blub Programmer](http://www.paulgraham.com/avg.html).
+
+## Effective C++ by Scott Meyers
+
+Required for C++ developers.
+
+The book is a must-read as it explains most common gotchas of using C++. After
+reading this book, you are good to write competent C++ which will pass code
+reviews easily.
+
+## Effective Modern C++ by Scott Meyers
+
+Required for C++ developers.
+
+This is a continuation of the previous book, it covers updates to C++ which
+came with C++11 and later. The book isn't as imperative as the previous one,
+but it will make you aware of modern features we are using in our codebase.
+
+## Practical Common Lisp by Peter Siebel
+
+Required for Common Lisp developers.
+
+Free: http://www.gigamonkeys.com/book/
+
+We use Common Lisp to generate C++ code and make our lives easier.
+Unfortunately, not many developers are familiar with the language. This book
+will make you familiar very quickly as it has tons of very practical
+exercises. E.g. implementing unit testing library, serialization library and
+bundling all that to create a mp3 music server.
+
+## Effective Python by Brett Slatkin
+
+(Almost) required reading for Python developers.
+
+Why the "almost"? Well, Python is relatively easy to pick up and you will
+probably learn all the gotchas during code review from someone more
+experienced. This makes the book less necessary for a newcomer to Memgraph,
+but the book is not advanced enough to delegate it to
+[Advanced Reading](#advanced-reading). The book is written in similar vein as
+the "Effective C++" ones and will make you familiar with nifty Python features
+that make everyone's lives easier.
+
+# Advanced Reading
+
+The books listed below are not required reading, but you may want to read them
+at some point when you feel comfortable enough.
+
+## Design Patterns by Gamma et. al.
+
+Recommended for C++ developers.
+
+This book is highly divisive because it introduced a culture centered around
+design patterns. The main issues is overuse of patterns which complicates the
+code. This has made many Java programs to serve as examples of highly
+complicated, "enterprise" code.
+
+Unfortunately, design patterns are pretty much missing
+language features. This is most evident in dynamic languages such as Python
+and Lisp, as demonstrated by
+[Peter Norvig](http://www.norvig.com/design-patterns/).
+
+Or as [Paul Graham](http://www.paulgraham.com/icad.html) put it:
+
+```
+This practice is not only common, but institutionalized. For example, in the
+OO world you hear a good deal about "patterns". I wonder if these patterns are
+not sometimes evidence of case (c), the human compiler, at work. When I see
+patterns in my programs, I consider it a sign of trouble. The shape of a
+program should reflect only the problem it needs to solve. Any other
+regularity in the code is a sign, to me at least, that I'm using abstractions
+that aren't powerful enough-- often that I'm generating by hand the expansions
+of some macro that I need to write
+```
+
+After presenting the book so negatively, why you should even read it then?
+Well, it is good to be aware of those design patterns and use them when
+appropriate. They can improve modularity and reuse of the code. You will also
+find examples of such patterns in our code, primarily Strategy and Visitor
+patterns. The book is also a good stepping stone to more advanced reading
+about software design.
+
+## Modern C++ Design by Andrei Alexandrescu
+
+Recommended for C++ developers.
+
+This book can be treated as a continuation of the previous "Design Patterns"
+book. It introduced "dark arts of template meta-programming" to the world.
+Many of the patterns are converted to use C++ templates which makes them even
+better for reuse. But, like the previous book, there are downsides if used too
+much. You should approach it with a critical eye and it will help you
+understand ideas that are used in some parts of our codebase.
+
+## Large Scale C++ Software Design by John Lakos
+
+Recommended for C++ developers.
+
+An old book, but well worth the read. Lakos presents a very pragmatic view of
+writing modular software and how it affects both development time as well as
+program runtime. Some things are outdated or controversial, but it will help
+you understand how the whole C++ process of working in a large team, compiling
+and linking affects development.
+
+## On Lisp by Paul Graham
+
+Recommended for Common Lisp developers.
+
+Free: http://www.paulgraham.com/onlisp.html
+
+An excellent continuation to "Practical Common Lisp". It starts of slow, as if
+introducing the language, but very quickly picks up speed. The main meat of
+the book are macros and their uses. From using macros to define cooperative
+concurrency to including Prolog as if it's part of Common Lisp. The book will
+help you understand more advanced macros that are occasionally used in our
+Lisp C++ Preprocessor (LCP).

docs/dev/storage/v1/accessors.md

@@ -38,7 +38,7 @@ interpretation code) should work with accessors. There is a
 `RecordAccessor` as a base class for `VertexAccessor` and
 `EdgeAccessor`. Following is an enumeration of their purpose.
 
-### Data access
+### Data Access
 
 The client interacts with Memgraph using the Cypher query language. That
 language has certain semantics which imply that multiple versions of the
@@ -75,7 +75,7 @@ In distributed Memgraph accessors also contain a lot of the remote graph
 element handling logic. More info on that is available in the
 documentation for distributed.
 
-### Deferred MVCC data lookup for Edges
+### Deferred MVCC Data Lookup for Edges
 
 Vertices and edges are versioned using MVCC. This means that for each
 transaction an MVCC lookup needs to be done to determine which version
@@ -100,7 +100,7 @@ working with that data directly whenever possible! Always consider the
 accessors to be the first go-to for interacting with data, especially
 when in the context of a transaction.
 
-# Skiplist accessor
+# Skiplist Accessor
 
 The term "accessor" is also used in the context of a skiplist. Every
 operation on a skiplist must be performed within on an

docs/dev/storage/v1/contents.md

@@ -0,0 +1,6 @@
+# Storage v1
+
+* [Accessors](accessors.md)
+* [Indexes](indexes.md)
+* [Property Storage](property-storage.md)
+* [Durability](durability.md)

docs/dev/storage/v1/durability.md

@@ -1,4 +1,6 @@
-# Write-ahead logging
+# Durability
+
+## Write-ahead Logging
 
 Typically WAL denotes the process of writing a "log" of database
 operations (state changes) to persistent storage before committing the
@@ -16,9 +18,17 @@ characteristics.
 
 Ensuring that the log is written before the transaction is committed can
 slow down the database. For that reason this guarantee is most often
-configurable in databases. In Memgraph it is at the moment not
-guaranteed, nor configurable. The WAL is flushed to the disk
-periodically and transactions do not wait for this to complete.
+configurable in databases.
+
+Memgraph offers two options for the WAL. The default option, where the WAL is
+flushed to the disk periodically and transactions do not wait for this to
+complete, introduces the risk of database inconsistency because an operating
+system or hardware crash might lead to missing transactions in the WAL. Memgraph
+will handle this as if those transactions never happened. The second option,
+called synchronous commit, will instruct Memgraph to wait for the WAL to be
+flushed to the disk when a transactions completes and the transaction will wait
+for this to complete. This option can be turned on with the
+`--synchronous-commit` command line flag.
 
 ### Format
 
@@ -45,3 +55,26 @@ inefficient) to recover the database from WAL only, provided all the WAL
 files created from DB start are available. It is not possible to recover
 partial database state (i.e. from some suffix of WAL files, without the
 preceding snapshot).
+
+## Snapshots
+
+A "snapshot" is a record of the current database state stored in permanent
+storage. Note that the term "snapshot" is used also in the context of
+the transaction engine to denote a set of running transactions.
+
+A snapshot is written to the file by Memgraph periodically if so
+configured. The snapshot creation  process is done within a transaction created
+specifically for that purpose. The transaction is needed to ensure that
+the stored state is internally consistent.
+
+The database state can be recovered from the snapshot during startup, if
+so configured. This recovery works in conjunction with write-ahead log
+recovery.
+
+A single snapshot contains all the data needed to recover a database. In
+that sense snapshots are independent of each other and old snapshots can
+be deleted once the new ones are safely stored, if it is not necessary
+to revert the database to some older state.
+
+The exact format of the snapshot file is defined inline in the snapshot
+creation code.

docs/dev/storage/v1/indexes.md

@@ -0,0 +1,116 @@
+# Label Indexes
+
+These are unsorted indexes that contain all the vertices that have the label
+the indexes are for (one index per label). These kinds of indexes get
+automatically generated for each label used in the database.
+
+### Updating the Indexes
+
+Whenever something gets added to the record we update the index (add that
+record to index). We keep an index which might contain garbage (not relevant
+records, because the value got removed or something similar) but we will
+filter it out when querying the index. We do it like this because we don't
+have to do bookkeeping and deciding if we update the index on the end of the
+transaction (commit/abort phase), moreover current interpreter advances the
+command in transaction and as such assumes that the indexes now contain
+objects added in the previous command inside this transaction, so we need to
+update over the whole scope of transaction (whenever something is added to the
+record).
+
+### Index Entries Label
+
+These kinds of indexes are internally keeping track of pair (record, vlist).
+Why do we need to keep track of exactly those two things?
+
+Problems with two different approaches
+
+1) Keep track of just the record:
+
+  - We need the `VersionList` for creating an accessor (this in itself is a
+    deal-breaker).
+  - Semantically it makes sense. An edge/vertex maps bijectionally to a
+    `VersionList`.
+  - We might try to access some members of record while the record is being
+    modified from another thread.
+  - A vertex/edge could get updated, thus expiring the record in the index.
+    The newly created record should be present in the index, but it's not.
+    Without the `VersionList` we can't reach the newly created record.
+  - Probably there are even more reasons... It should be obvious by now that
+    we need the `VersionList` in the index.
+
+2) Keep track of just the version list:
+
+  - Removing from an index is a problem for two major reasons. First, if we
+    only have the `VersionList`, checking if it should be removed implies
+    checking all the reachable records, which is not thread-safe. Second,
+    there are issues with concurrent removal and insertion. The cleanup thread
+    could determine the vertex/edge should be removed from the index and
+    remove it, while in between those ops another thread attempts to insert
+    the `VersionList` into the index. The insertion does nothing because the
+    `VersionList` is already in, but it gets removed immediately after.
+
+Because of inability to keep track of just the record, or value, we need to
+keep track of both of them.  Resolution of problems mentioned above, in the
+same order, with (record, vlist) pair
+
+  - simple `vlist.find(current transaction)` will get us the newest visible
+    record
+  - we'll never try to access some record if it's still being written since we
+    will always operate on vlist.find returned record
+  - newest record will contain that label
+  - since we have (record, vlist) pair as the key in the index when we update
+    and delete in the same time we will never delete the same record, vlist
+    pair we are adding because the record, vlist pair we are deleting is
+    already superseded by a newer record and as such won't be inserted while
+    it's being deleted
+
+### Querying the Index
+
+We run through the index for the given label and do `vlist.find` operation for
+the current transaction, and check if the newest return record has that
+label. If it has it then we return it. By now you are probably wondering
+aren't we sometimes returning duplicate vlist entries? And you are wondering
+correctly, we would be returning them, but we are making sure that the entires
+in the index are sorted by their `vlist*` and as such we can filter consecutive
+duplicate `vlist*` to only return one of those while still being able to create
+an iterator to index.
+
+### Cleaning the Index
+
+Cleaning the index is not as straightforward as it seems as a lot of garbage
+can accumulate, but it's hard to know when exactly can we delete some (record,
+vlist) pair. First, let's assume that we are doing the cleaning process at
+some `transaction_id`, `id` such that there doesn't exist an active transaction
+with an id lower than `id`.
+
+We scan through the whole index and for each (record, vlist) pair we first
+check if it was deleted before the id (i.e. no transaction with an id >= `id`
+will ever again see that record), if it was deleted before we might naively
+say that it's safe to delete it, but, we must take into account that when some
+new record is created from this record (update operation), that record still
+contains the label but by deleting this record we won't be able to see that
+vlist because that new record won't add again to index because we didn't
+explicitly add that label again to it.
+
+Because of this we have to 'update' this index (record, vlist) pair. We have
+to update the record to now point to a newer record in vlist, the one that is
+not deleted yet. We can do that by querying the `version_list` for the last
+record inside (oldest it has — remember that `mvcc_gc` will re-link not
+visible records so the last record will be visible for the current GC id).
+When updating the record inside the index, it's not okay to just update the
+pointer and leave the index as it is, because with updating the `record*` we
+might change the relative order of entries inside the index. We first have to
+re-insert it with new `record*`, and then delete the old entry. And we need to
+do insertion before the remove operation! Otherwise it could happen that the
+vlist with a newer record with that label won't exist while some transaction
+is querying the index.
+
+Records which we added as a consequence of deleting older records will be
+eventually removed from the index if they don't contain label because if we
+see that the record is not deleted we try to check if that record still
+contains the label. We also need to be careful here because we can't check
+that while the record is being potentially updated by some transaction (race
+condition), so we need can check if records still contain label if it's
+creation id is smaller than our `id`, as that implies that the creating
+transaction either aborted or committed as our `id` is equal to the oldest
+active transaction in time of starting the GC.

docs/dev/storage/v1/property-storage.md

@@ -1,7 +1,7 @@
-# Property storage
+# Property Storage
 
 Although the reader is probably familiar with properties in *Memgraph*, let's
-briefly recap. 
+briefly recap.
 
 Both vertices and edges can store an arbitrary number of properties. Properties
 are, in essence, ordered pairs of property names and property values. Each
@@ -21,9 +21,9 @@ must be one of the following types:
 
 Property values are modeled in a class conveniently called `PropertyValue`.
 
-## Mapping between property names and property keys.
+## Mapping Between Property Names and Property Keys.
 
-Although users think of property names in terms of descriptive strings 
+Although users think of property names in terms of descriptive strings
 (e.g. "location" or "department"), *Memgraph* internally converts those names
 into property keys which are, essentially, unsigned 16-bit integers.
 
@@ -49,7 +49,7 @@ An interface of `PropertyValueStore` is as follows:
  `clear`   | Clears the storage.
  `iterator`| Provides an extension of `std::input_iterator` that iterates over storage.
 
-## Storage location
+## Storage Location
 
 By default, *Memgraph* is an in-memory database and all properties are therefore
 stored in working memory unless specified otherwise by the user. User has an
@@ -63,12 +63,12 @@ property key has the following format:
 ```
 |---location--|------id------|
 |-Memory|Disk-|-----2^15-----|
-``` 
+```
 
 In other words, the most significant bit determines the location where the
-property will be stored. 
+property will be stored.
 
-### In-memory storage
+### In-memory Storage
 
 The underlying implementation of in-memory storage for the time being is
 `std::vector<std::pair<Property, PropertyValue>>`. Implementations of`at`, `set`
@@ -76,7 +76,7 @@ and `erase` are linear in time. This implementation is arguably more efficient
 than `std::map` or `std::unordered_map` when the average number of properties of
 a record is relatively small (up to 10) which seems to be the case.
 
-### On-disk storage
+### On-disk Storage
 
 #### KVStore
 
@@ -120,12 +120,12 @@ KVStore storage = ...;
 for (auto it = storage.begin("alpha"); it != storage.end("omega"); ++it) {}
 ```
 
-#### Data organization on disk
+#### Data Organization on Disk
 
 Each `PropertyValueStore` instance can access a static `KVStore` object that can
 store `(key, value)` pairs on disk. The key of each property on disk consists of
 two parts &mdash; a unique identifier (unsigned 64-bit integer) of the current
-record version (see mvcc docummentation for further clarification) and a 
+record version (see mvcc docummentation for further clarification) and a
 property key as described above. The actual value of the property is serialized
 into a bytestring using bolt `BaseEncoder`. Similarly, deserialization is
 performed by bolt `Decoder`.

docs/dev/storage/v2/contents.md

@@ -0,0 +1,3 @@
+# Storage v2
+
+TODO(gitbuda): Write documentation.

docs/dev/toolchain-bootstrap.md

@@ -1,152 +0,0 @@
-# Bootstrapping Compilation Toolchain for Memgraph
-
-Requirements:
-
-  * libstdc++ shipped with gcc-6.3 or gcc-6.4
-  * cmake >= 3.1, Debian Stretch uses cmake-3.7.2
-  * clang-3.9
-
-## Installing gcc-6.4
-
-gcc-6.3 has a bug, so use the 6.4 version which is just a bugfix release.
-
-Requirements on CentOS 7:
-
-  * wget
-  * make
-  * gcc (bootstrap)
-  * gcc-c++ (bootstrap)
-  * gmp-devel (bootstrap)
-  * mpfr-devel (bootstrap)
-  * libmpc-devel (bootstrap)
-  * zip
-  * perl
-  * dejagnu (testing)
-  * expect (testing)
-  * tcl (testing)
-
-```
-wget ftp://ftp.mpi-sb.mpg.de/pub/gnu/mirror/gcc.gnu.org/pub/gcc/releases/gcc-6.4.0/gcc-6.4.0.tar.gz
-tar xf gcc-6.4.0.tar.gz
-cd gcc-6.4.0
-mkdir build
-cd build
-../configure --disable-multilib --prefix=<install-dst>
-make
-# Testing
-make -k check
-make install
-```
-
-*Do not put gcc + libs on PATH* (unless you know what you are doing).
-
-## Installing cmake-3.7.2
-
-Requirements on CentOS 7:
-
-  * wget
-  * make
-  * gcc
-  * gcc-c++
-  * ncurses-devel (optional, for ccmake)
-
-```
-wget https://cmake.org/files/v3.7/cmake-3.7.2.tar.gz
-tar xf cmake-3.7.2.tar.gz
-cd cmake-3.7.2.tar.gz
-./bootstrap --prefix<install-dst>
-make
-make install
-```
-
-Put cmake on PATH (if appropriate)
-
-**Fix the bug in CpackRPM**
-
-`"<path-to-cmake>/share/cmake-3.7/Modules/CPackRPM.cmake" line 2273 of 2442`
-
-The line
-
-```
-set(RPMBUILD_FLAGS "-bb")
-```
-needs to be before
-
-```
-if(CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE OR NOT CPACK_RPM_USER_BINARY_SPECFILE)
-```
-
-It was probably accidentally placed after, and is fixed in later cmake
-releases.
-
-## Installing clang-3.9
-
-Requirements on CentOS 7:
-
-  * wget
-  * make
-  * cmake
-
-```
-wget http://releases.llvm.org/3.9.1/llvm-3.9.1.src.tar.xz
-tar xf llvm-3.9.1.src.tar.xz
-mv llvm-3.9.1.src llvm
-
-wget http://releases.llvm.org/3.9.1/cfe-3.9.1.src.tar.xz
-tar xf cfe-3.9.1.src.tar.xz
-mv cfe-3.9.1.src llvm/tools/clang
-
-cd llvm
-mkdir build
-cd build
-cmake -DCMAKE_BUILD_TYPE="Release" -DGCC_INSTALL_PREFIX=<gcc-dir> \
--DCMAKE_C_COMPILER=<gcc> -DCMAKE_CXX_COMPILER=<g++> \
--DCMAKE_CXX_LINK_FLAGS="-L<gcc-dir>/lib64 -Wl,-rpath,<gcc-dir>/lib64" \
--DCMAKE_INSTALL_PREFIX=<install-dst> ..
-make
-# Testing
-make check-clang
-make install
-```
-
-Put clang on PATH (if appropriate)
-
-## Memgraph
-
-Requirements on CentOS 7:
-
-  * libuuid-devel (antlr4)
-  * java-1.8.0-openjdk (antlr4)
-  * boost-static (too low version --- compile manually)
-  * rpm-build (RPM)
-  * python3 (tests, ...)
-  * which (required for rocksdb)
-  * sbcl (lisp C++ preprocessing)
-
-### Boost 1.62
-
-```
-wget https://netix.dl.sourceforge.net/project/boost/boost/1.62.0/boost_1_62_0.tar.gz
-tar xf boost_1_62_0.tar.gz
-cd boost_1_62_0
-./bootstrap.sh --with-toolset=clang --with-libraries=iostreams,serialization --prefix=<install-dst>
-./b2
-# Default installs to /usr/local/
-./b2 install
-```
-
-### Building Memgraph
-
-clang is *required* to be findable by cmake, i.e. it should be on PATH.
-cmake isn't required to be on the path, since you run it manually, so can use
-the full path to executable in order to run it. Obviously, it is convenient to
-put cmake also on PATH.
-
-Building is done as explained in [Quick Start](quick-start.md), but each
-`make` invocation needs to be prepended with:
-
-`LD_RUN_PATH=<gcc-dir>/lib64 make ...`
-
-### RPM
-
-Name format: `memgraph-<version>-<pkg-version>.<arch>.rpm`

docs/dev/workflow.md

@@ -20,54 +20,51 @@ Finally, make git aware of your favourite editor:
 
     git config --global core.editor "vim"
 
-## Phabricator
+## Github
 
 All of the code in Memgraph needs to go through code review before it can be
-accepted in the codebase. This is done through
-[Phabricator](https://phacility.com/phabricator/). The command line tool for
-interfacing with Phabricator is
-[arcanist](https://phacility.com/phabricator/arcanist/). You should already
-have it installed if you followed the steps in [Quick Start](quick-start.md).
-
-The only required setup is to go in the root of Memgraph's project and run:
-
-    arc install-certificate
+accepted in the codebase. This is done through [Github](https://github.com/).
+You should already have it installed if you followed the steps in [Quick
+Start](quick-start.md).
 
 ## Working on Your Feature Branch
 
-Git has a concept of source code *branches*. The `master` branch contains all
+Git has a concept of source code **branches**. The `master` branch contains all
 of the changes which were reviewed and accepted in Memgraph's code base. The
 `master` branch is selected by default.
 
 ### Creating a Branch
 
 When working on a new feature or fixing a bug, you should create a new branch
-out of the `master` branch. For example, let's say you are adding static type
-checking to the query language compiler. You would create a branch called
-`mg_query_static_typing` with the following command:
+out of the `master` branch. There are two branch types, **epic** and **task**
+branches. The epic branch is created when introducing a new feature or any work
+unit requiring more than one commit. More commits are required to split the
+work into chunks to be able to easier review code or find a bug (in each
+commit, there could be various problems, e.g., related to performance or
+concurrency issues, which are the hardest to track down). Each commit on the
+master or epic branch should be a compilable and well-documented set of
+changes. Task branches should be created when a smaller work unit has to be
+integrated into the codebase. The task branch could be branched out of the
+master or an epic branch. We manage epics and tasks on the project management
+tool called [Airtable](https://airtable.com/tblTUqycq8sHTTkBF). Each epic is
+prefixed by `Exyz-MG`, on the other hand, each task has `Tabcd-MG` prefix.
+Examples on how to create branches follow:
 
-    git branch mg_query_static_typing
-
-To switch to that branch, type:
-
-    git checkout mg_query_static_typing
-
-Since doing these two steps will happen often, you can use a shortcut command:
-
-    git checkout -b mg_query_static_typing
+```
+git checkout master
+git checkout -b T0025-MG-fix-a-problem
+...
+git checkout master
+git checkout -b E025-MG-huge-feature
+...
+git checkout E025-MG-huge-feature
+git checkout -b T0123-MG-add-feature-part
+```
 
 Note that a branch is created from the currently selected branch. So, if you
 wish to create another branch from `master` you need to switch to `master`
 first.
 
-The usual convention for naming your branches is `mg_<feature_name>`, you may
-switch underscores ('\_') for hyphens ('-').
-
-Do take care not to mix the case of your branch names! Certain operating
-systems (like Windows) don't distinguish the casing in git branches. This may
-cause hard to track down issues when trying to switch branches. Therefore, you
-should always name your branches with lowercase letters.
-
 ### Making and Committing Changes
 
 When you have a branch for your new addition, you can now actually start
@@ -98,80 +95,72 @@ possible.
 ### Sending Changes on a Review
 
 After finishing your work on your feature branch, you will want to send it on
-code review. This is done through Arcanist. To do that, run the following
-command:
+code review. This is done by pushing the branch to Github and creating a pull
+request. You can find all PRs
+[here](https://github.com/memgraph/memgraph/pulls).
 
-    arc diff
+### Code Integration
 
-You will, once again, be presented with an editor where you need to describe
-your whole work. `arc` will by default fill that description with your commit
-messages. The title and summary of your work should also follow the
-conventions of git messages as described above. If you followed the
-guidelines, the message filled by `arc` should be fine.
+When working, you have to integrate some changes to your work or push your work
+to be available for others. To pull changes into a local `branch`, usually run
+the following:
 
-In addition to the message, you need to fill the `Reviewers:` line with
-usernames of people who should do the code review.
+    git checkout {{branch}}
+    git pull origin {{branch}}
 
-You changes will be visible on Phabricator as a so called "diff". You can find
-the default view of active diffs
-[here](https://phabricator.memgraph.io/differential/)
+To push your changes, usually run the following:
 
-### Updating Changes Based on Review
+    git checkout {{branch}}
+    git push origin {{branch}}
 
-When you get comments in the code review, you will want to make additional
-modifications to your work. The same workflow as before applies: [Making and
-Committing Changes](#making-and-committing-changes)
+Sometimes, things could get a little bit more complicated. Diagram below shows
+which git operation should be performed if a piece of code has to be integrated
+from one branch to another. Note, `main_branch` is the **master** branch in our
+case.
 
-After making those changes, send them back on code review:
+```
+      |<---------------------------|
+      |       squash merge         |
+      |--------------------------->|
+      |          merge             |
+      |                            |
+      |<-----------|<--------------|
+      |   merge    | squash merge  |
+      |            |               |
+      |----------->|-------------->|
+      |   rebase   |     merge     |
+      |            | rebase --onto |
+      |            |               |
+ main_branch  epic_branch     task_branch
+```
 
-    arc diff
+There are a couple of cases:
 
+* If a code has to be integrated from a task branch to the main branch, use
+  **squash merge**. While you were working on a task, you probably committed a
+couple of cleanup commits that are not relevant to the main branch. In the
+other direction, while integrating the main branch to a task branch, the
+**regular merge** is ok because changes from the task branch will later be
+squash merged.
 
-### Updating From New Master
+* You should use **squash merge** when integrating changes from task to epic
+  branch (task might have irrelevant commits). On the other hand, you should
+use a **regular merge** when an epic is completed and has to be integrated into
+the main branch. Epic is a more significant piece of work, decoupled in
+compilable and testable commits. All these commits should be preserved to be
+able to find potential issues later on.
 
-Let's say that, while you were working, someone else added some new features
-to the codebase that you would like to use in your current work. To obtain
-those changes you should update your `master` branch:
+* You should use **rebase** when integrating changes from main to an epic
+  branch. The epic branch has to be as clean as possible, avoid pure merge
+commits. Once you rebase epic on main, all commits on the epic branch will
+change the hashes. The implications are: 1) you have to force push your local
+branch to the origin, 2) if you made a task branch out of the epic branch, you
+would have to use **rebase --onto** (please refer to `git help rebase` for
+details). In simple cases, **regular merge** should be sufficient to integrate
+changes from epic to a task branch (that can even be done via GitHub web
+interface).
 
-    git checkout master
-    git pull origin master
-
-Now, these changes are on `master`, but you want them in your local branch. To
-do that, use `git rebase`:
-
-    git checkout mg_query_static_typing
-    git rebase master
-
-During `git rebase`, you may get reports that some files have conflicting
-changes. If you need help resolving them, don't be afraid to ask around! After
-you've resolved them, mark them as done with `git add` command. You may
-then continue with `git rebase --continue`.
-
-After the `git rebase` is done, you will now have new changes from `master` on
-your feature branch as if you just created and started working on that branch.
-You may continue with the usual workflow of [Making and Committing
-Changes](#making-and-committing-changes) and [Sending Changes on a
-Review](#sending-changes-on-a-review).
-
-### Sending Your Changes on Master Branch
-
-When your changes pass the code review, you are ready to integrate them in the
-`master` branch. To do that, run the following command:
-
-    arc land
-
-Arcanist will take care of obtaining the latest changes from `master` and
-merging your changes on top. If the `land` was successful, Arcanist will
-delete your local branch and you will be back on `master`. Continuing from the
-examples above, the deleted branch would be `mg_query_static_typing`.
-
-This marks the completion of your changes, and you are ready to work on
-something else.
-
-### Note For People Familiar With Git
-
-Since Arcanist takes care of merging your git commits and pushing them on
-`master`, you should *never* have to call `git merge` and `git push`. If you
-find yourself typing those commands, check that you are doing the right thing.
-The most common mistake is to use `git merge` instead of `git rebase` for the
-case described in [Updating From New Master](#updating-from-new-master).
+During any code integration, you may get reports that some files have
+conflicting changes. If you need help resolving them, don't be afraid to ask
+around! After you've resolved them, mark them as done with `git add` command.
+You may then continue with `git {{action}} --continue`.

docs/doxygen/README.md

@@ -1,7 +1,6 @@
 # Memgraph Code Documentation
 
-IMPORTANT: auto-generated (run doxygen Doxyfile in the project root)
+IMPORTANT: Auto-generated (run doxygen Doxyfile in the project root).
 
-* HTML - just open docs/doxygen/html/index.html
-
-* Latex - run make inside docs/doxygen/latex
+* HTML - Open docs/doxygen/html/index.html.
+* Latex - Run make inside docs/doxygen/latex.

docs/feature_spec/contents.md

@@ -0,0 +1,3 @@
+# Feature Specifications
+
+* [Python Query Modules](python-query-modules.md)

docs/feature_spec/distributed.md

@@ -0,0 +1,78 @@
+# Distributed Memgraph specs
+This document describes reasnonings behind Memgraphs distributed concepts.
+
+## Distributed state machine
+Memgraphs distributed mode introduces two states of the cluster, recovering and
+working. The change between states shouldn't happen often, but when it happens
+it can take a while to make a transition from one to another.
+
+### Recovering
+This state is the default state for Memgraph when the cluster starts with
+recovery flags. If the recovery finishes successfully, the state changes to
+working. If recovery fails, the user will be presented with a message that
+explains what happened and what are the next steps.
+
+Another way to enter this state is failure. If the cluster encounters a failure,
+the master will enter the Recovering mode. This time, it will wait for all
+workers to respond with a message saying they are alive and well, and making
+sure they all have consistent state.
+
+### Working
+This state should be the default state of Memgraph most of the time. When in
+this state, Memgraph accepts connections from Bolt clients and allows query
+execution.
+
+If distributed execution fails for a transaction, that transaction, and all
+other active transactions will be aborted and the cluster will enter the
+Recovering state.
+
+## Durability
+One of the important concepts in distributed Memgraph is durability.
+
+### Cluster configuration
+When running Memgraph in distributed mode, the master will store cluster
+metadata in a persistent store. If fore some reason the cluster shuts down,
+recovering Memgraph from durability files shouldn't require any additional
+flags.
+
+### Database ID
+Each new and clean run of Memgraph should generate a new globally unique
+database id.  This id will associate all files that have persisted with this
+run. Adding the database id to snapshots, write-ahead logs and cluster metadata
+files ties them a specific Memgraph run, and it makes recovery easier to reason
+about.
+
+When recovering, the cluster won't generate a new id, but will reuse the one
+from the snapshot/wal that it was able to recover from.
+
+### Durability files
+Memgraph uses snapshots and write-ahead logs for durability.
+
+When Memgraph recovers it has to make sure all machines in the cluster recover
+to the same recovery point. This is done by finding a common snapshot and
+finding common transactions in per-machine available write-ahead logs.
+
+Since we can not be sure that each machine persisted durability files, we need
+to be able to negotiate a common recovery point in the cluster. Possible
+durability file failures could require to start the cluster from scratch,
+purging everything from storage and recovering from existing durability files.
+
+We need to ensure that we keep wal files containing information about
+transactions between all existing snapshots. This will provide better durability
+in the case of a random machine durability file failure, where the cluster can
+find a common recovery point that all machines in the cluster have.
+
+Also, we should suggest and make clear docs that anything less than two
+snapshots isn't considered safe for recovery.
+
+### Recovery
+The recovery happens in following steps:
+* Master enables worker registration.
+* Master recovers cluster metadata from the persisted storage.
+* Master waits all required workers to register.
+* Master broadcasts a recovery request to all workers.
+* Workers respond with with a set of possible recovery points.
+* Master finds a common recovery point for the whole cluster.
+* Master broadcasts a recovery request with the common recovery point.
+* Master waits for the cluster to recover.
+* After a successful cluster recovery, master can enter Working state.

docs/feature_spec/dynamic_graph_partitioning.md

@@ -0,0 +1,75 @@
+# Dynamic Graph Partitioning (abbr. DGP)
+
+## Implementation
+
+Take a look under `dev/memgraph/distributed/dynamic_graph_partitioning.md`.
+
+### Implemented parameters
+
+--dynamic-graph-partitioner-enabled (If the dynamic graph partitioner should be
+  enabled.) type: bool default: false (start time)
+--dgp-improvement-threshold (How much better should specific node score be
+  to consider a migration to another worker. This represents the minimal
+  difference between new score that the vertex will have when migrated
+  and the old one such that it's migrated.) type: int32 default: 10
+  (start time)
+--dgp-max-batch-size (Maximal amount of vertices which should be migrated
+  in one dynamic graph partitioner step.) type: int32 default: 2000
+  (start time)
+
+## Planning
+
+### Design decisions
+
+* Each partitioning session has to be a new transaction.
+* When and how does an instance perform the moves?
+  * Periodically.
+  * Token sharing (round robin, exactly one instance at a time has an
+    opportunity to perform the moves).
+* On server-side serialization error (when DGP receives an error).
+  -> Quit partitioning and wait for the next turn.
+* On client-side serialization error (when end client receives an error).
+  -> The client should never receive an error because of any
+     internal operation.
+  -> For the first implementation, it's good enough to wait until data becomes
+     available again.
+  -> It would be nice to achieve that DGP has lower priority than end client
+     operations.
+
+### End-user parameters
+
+* --dynamic-graph-partitioner-enabled (execution time)
+* --dgp-improvement-threshold (execution time)
+* --dgp-max-batch-size (execution time)
+* --dgp-min-batch-size (execution time)
+  -> Minimum number of nodes that will be moved in each step.
+* --dgp-fitness-threshold (execution time)
+  -> Do not perform moves if partitioning is good enough.
+* --dgp-delta-turn-time (execution time)
+  -> Time between each turn.
+* --dgp-delta-step-time (execution time)
+  -> Time between each step.
+* --dgp-step-time (execution time)
+  -> Time limit per each step.
+
+### Testing
+
+The implementation has to provide good enough results in terms of:
+  * How good the partitioning is (numeric value), aka goodness.
+  * Workload execution time.
+  * Stress test correctness.
+
+Test cases:
+  * N not connected subgraphs
+    -> shuffle nodes to N instances
+    -> run partitioning
+    -> test perfect partitioning.
+  * N connected subgraph
+    -> shuffle nodes to N instance
+    -> run partitioning
+    -> test partitioning.
+  * Take realistic workload (Long Running, LDBC1, LDBC2, Card Fraud, BFS, WSP)
+    -> measure exec time
+    -> run partitioning
+    -> test partitioning
+    -> measure exec time (during and after partitioning).

docs/feature_spec/high_availability.md

@@ -0,0 +1,275 @@
+# High Availability (abbr. HA)
+
+## High Level Context
+
+High availability is a characteristic of a system which aims to ensure a
+certain level of operational performance for a higher-than-normal period.
+Although there are multiple ways to design highly available systems, Memgraph
+strives to achieve HA by elimination of single points of failure. In essence,
+this implies adding redundancy to the system so that a failure of a component
+does not imply the failure of the entire system. To ensure this, HA Memgraph
+implements the [Raft consensus algorithm](https://raft.github.io/).
+
+Correct implementation of the algorithm guarantees that the cluster will be
+fully functional (available) as long as any strong majority of the servers are
+operational and can communicate with each other and with clients. For example,
+clusters of three or four machines can tolerate the failure of a single server,
+clusters of five and six machines can tolerate the failure of any two servers,
+and so on. Therefore, we strongly recommend a setup of an odd-sized cluster.
+
+### Performance Implications
+
+Internally, Raft achieves high availability by keeping a consistent replicated
+log on each server within the cluster. Therefore, we must successfully replicate
+a transaction on the majority of servers within the cluster before we actually
+commit it and report the result back to the client. This operation represents
+a significant performance hit when compared with single node version of
+Memgraph.
+
+Luckily, the algorithm can be tweaked in a way which allows read-only
+transactions to perform significantly better than those which modify the
+database state. That being said, the performance of read-only operations
+is still not going to be on par with single node Memgraph.
+
+This section will be updated with exact numbers once we integrate HA with
+new storage.
+
+With the old storage, write throughput was almost five times lower than read
+throughput (~30000 reads per second vs ~6000 writes per second).
+
+## User Facing Setup
+
+### How to Setup HA Memgraph Cluster?
+
+First, the user needs to install `memgraph_ha` package on each machine
+in their cluster. HA Memgraph should be available as a Debian package,
+so its installation on each machine should be as simple as:
+
+```plaintext
+dpkg -i /path/to/memgraph_ha_<version>.deb
+```
+
+After successful installation of the `memgraph_ha` package, the user should
+finish its configuration before attempting to start the cluster.
+
+There are two main things that need to be configured on every node in order for
+the cluster to be able to run:
+
+1. The user has to edit the main configuration file and specify the unique node
+   ID to each server in the cluster
+2. The user has to create a file that describes all IP addresses of all servers
+   that will be used in the cluster
+
+The `memgraph_ha` binary loads all main configuration parameters from
+`/etc/memgraph/memgraph_ha.conf`. On each node of the cluster, the user should
+uncomment the `--server-id=0` parameter and change its value to the `server_id`
+of that node.
+
+The last step before starting the server is to create a `coordination`
+configuration file. That file is already present as an example in
+`/etc/memgraph/coordination.json.example` and you have to copy it to
+`/etc/memgraph/coordination.json` and edit it according to your cluster
+configuration. The file contains coordination info consisting of a list of
+`server_id`, `ip_address` and `rpc_port` lists. The assumed contents of the
+`coordination.json` file are:
+
+```plaintext
+[
+  [1, "192.168.0.1", 10000],
+  [2, "192.168.0.2", 10000],
+  [3, "192.168.0.3", 10000]
+]
+```
+Here, each line corresponds to coordination of one server. The first entry is
+that server's ID, the second is its IP address and the third is the RPC port it
+listens to. This port should not be confused with the port used for client
+interaction via the Bolt protocol.
+
+The `ip_address` entered for each `server_id` *must* match the exact IP address
+that belongs to that server and that will be used to communicate to other nodes
+in the cluster. The coordination configuration file *must* be identical on all
+nodes in the cluster.
+
+After the user has set the `server_id` on each node in
+`/etc/memgraph/memgraph_ha.conf` and provided the same
+`/etc/memgraph/coordination.json` file to each node in the cluster, they can
+start the Memgraph HA service by issuing the following command on each node in
+the cluster:
+
+```plaintext
+systemctl start memgraph_ha
+```
+
+### How to Configure Raft Parameters?
+
+All Raft configuration parameters can be controlled by modifying
+`/etc/memgraph/raft.json`.  The assumed contents of the `raft.json` file are:
+
+```plaintext
+{
+  "election_timeout_min": 750,
+  "election_timeout_max": 1000,
+  "heartbeat_interval": 100,
+  "replication_timeout": 20000,
+  "log_size_snapshot_threshold": 50000
+}
+```
+
+The meaning behind each entry is demystified in the following table:
+
+Flag                          | Description
+------------------------------|------------
+`election_timeout_min`        | Lower bound for the randomly sampled reelection timer given in milliseconds
+`election_timeout_max`        | Upper bound for the randomly sampled reelection timer given in milliseconds
+`heartbeat_interval`          | Time interval between consecutive heartbeats given in milliseconds
+`replication_timeout`         | Time interval allowed for data replication given in milliseconds
+`log_size_snapshot_threshold` | Allowed number of entries in Raft log before its compaction
+
+### How to Query HA Memgraph via Proxy?
+
+This chapter describes how to query HA Memgraph using our proxy server.
+Note that this is not intended to be a long-term solution. Instead, we will
+implement a proper Memgraph HA client which is capable of communicating with
+the HA cluster. Once our own client is implemented, it will no longer be
+possible to query HA Memgraph using other clients (such as neo4j client).
+
+The Bolt protocol that is exposed by each Memgraph HA node is an extended
+version of the standard Bolt protocol. In order to be able to communicate with
+the highly available cluster of Memgraph HA nodes, the client must have some
+logic implemented in itself so that it can communicate correctly with all nodes
+in the cluster. To facilitate a faster start with the HA cluster we will build
+the Memgraph HA proxy binary that communicates with all nodes in the HA cluster
+using the extended Bolt protocol and itself exposes a standard Bolt protocol to
+the user. All standard Bolt clients (libraries and custom systems) can
+communicate with the Memgraph HA proxy without any code modifications.
+
+The HA proxy should be deployed on each client machine that is used to
+communicate with the cluster. It can't be deployed on the Memgraph HA nodes!
+
+When using the Memgraph HA proxy, the communication flow is described in the
+following diagram:
+
+```plaintext
+Memgraph HA node 1 -----+
+                        |
+Memgraph HA node 2 -----+ Memgraph HA proxy <---> any standard Bolt client (C, Java, PHP, Python, etc.)
+                        |
+Memgraph HA node 3 -----+
+```
+
+To setup the Memgraph HA proxy the user should install the `memgraph_ha_proxy`
+package.
+
+After its successful installation, the user should enter all endpoints of the
+HA Memgraph cluster servers into the configuration before attempting to start
+the HA Memgraph proxy server.
+
+The HA Memgraph proxy server loads all of its configuration from
+`/etc/memgraph/memgraph_ha_proxy.conf`. Assuming that the cluster is set up
+like in the previous examples, the user should uncomment and enter the following
+value into the `--endpoints` parameter:
+
+```plaintext
+--endpoints=192.168.0.1:7687,192.168.0.2:7687,192.168.0.3:7687
+```
+
+Note that the IP addresses used in the example match the individual cluster
+nodes IP addresses, but the ports used are the Bolt server ports exposed by
+each node (currently the default value of `7687`).
+
+The user can now start the proxy by using the following command:
+
+```plaintext
+systemctl start memgraph_ha_proxy
+```
+
+After the proxy has been started, the user can query the HA cluster by
+connecting to the HA Memgraph proxy IP address using their favorite Bolt
+client.
+
+## Integration with Memgraph
+
+The first thing that should be defined is a single instruction within the
+context of Raft (i.e. a single entry in a replicated log).
+These instructions should be completely deterministic when applied
+to the state machine. We have therefore decided that the appropriate level
+of abstraction within Memgraph corresponds to `Delta`s (data structures
+which describe a single change to the Memgraph state, used for durability
+in WAL). Moreover, a single instruction in a replicated log will consist of a
+batch of `Delta`s which correspond to a single transaction that's about
+to be **committed**.
+
+Apart from `Delta`s, there are certain operations within the storage called
+`StorageGlobalOperations` which do not conform to usual transactional workflow
+(e.g. Creating indices).  Since our storage engine implementation guarantees
+that at the moment of their execution no other transactions are active, we can
+safely replicate them as well. In other words, no additional logic needs to be
+implemented because of them.
+
+Therefore, we will introduce a new `RaftDelta` object which can be constructed
+both from storage `Delta` and `StorageGlobalOperation`. Instead of appending
+these to WAL (as we do in single node), we will start to replicate them across
+our cluster. Once we have replicated the corresponding Raft log entry on
+majority of the cluster, we are able to safely commit the transaction or execute
+a global operation. If for any reason the replication fails (leadership change,
+worker failures, etc.) the transaction will be aborted.
+
+In the follower mode, we need to be able to apply `RaftDelta`s we got from
+the leader when the protocol allows us to do so. In that case, we will use the
+same concepts from durability in storage v2, i.e., applying deltas maps
+completely to recovery from WAL in storage v2.
+
+## Test and Benchmark Strategy
+
+We have already implemented some integration and stress tests. These are:
+
+1. leader election -- Tests whether leader election works properly.
+2. basic test -- Tests basic leader election and log replication.
+3. term updates test -- Tests a specific corner case (which used to fail)
+                        regarding term updates.
+4. log compaction test -- Tests whether log compaction works properly.
+5. large log entries -- Tests whether we can successfully replicate relatively
+                        large log entries.
+6. index test -- Tests whether index creation works in HA.
+7. normal operation stress test -- Long running concurrent stress test under
+                                   normal conditions (no failures).
+8. read benchmark -- Measures read throughput in HA.
+9. write benchmark -- Measures write throughput in HA.
+
+At the moment, our main goal is to pass existing tests and have a stable version
+on our stress test. We should also implement a stress test which occasionally
+introduces different types of failures in our cluster (we did this kind of
+testing manually thus far). Passing these tests should convince us that we have
+a "stable enough" version which we can start pushing to our customers.
+
+Additional (proper) testing should probably involve some ideas from
+[here](https://jepsen.io/analyses/dgraph-1-0-2)
+
+## Possible Future Changes/Improvements/Extensions
+
+There are two general directions in which we can alter HA Memgraph. The first
+direction assumes we are going to stick with the Raft protocol. In that case
+there are a few known ways to extend the basic algorithm in order to gain
+better performance or achieve extra functionality. In no particular order,
+these are:
+
+1. Improving read performance using leader leases [Section 6.4 from Raft thesis]
+2. Introducing cluster membership changes [Chapter 4 from Raft thesis]
+3. Introducing a [learner mode](https://etcd.io/docs/v3.3.12/learning/learner/).
+4. Consider different log compaction strategies [Chapter 5 from Raft thesis]
+5. Removing HA proxy and implementing our own HA Memgraph client.
+
+On the other hand, we might decide in the future to base our HA implementation
+on a completely different protocol which might even offer different guarantees.
+In that case we probably need to do a bit more of market research and weigh the
+trade-offs of different solutions.
+[This](https://www.postgresql.org/docs/9.5/different-replication-solutions.html)
+might be a good starting point.
+
+## Reading materials
+
+1. [Raft paper](https://raft.github.io/raft.pdf)
+2. [Raft thesis](https://github.com/ongardie/dissertation) (book.pdf)
+3. [Raft playground](https://raft.github.io/)
+4. [Leader Leases](https://blog.yugabyte.com/low-latency-reads-in-geo-distributed-sql-with-raft-leader-leases/)
+5. [Improving Raft ETH](https://pub.tik.ee.ethz.ch/students/2017-FS/SA-2017-80.pdf)

docs/feature_spec/kafka/opencypher.md

@@ -0,0 +1,80 @@
+# Kafka - openCypher clause
+
+One must be able to specify the following when importing data from Kafka:
+
+* Kafka URI
+* Kafka topic
+* Transform [script](transform.md) URI
+
+
+Minimum required syntax looks like:
+```opencypher
+CREATE STREAM stream_name AS LOAD DATA KAFKA 'URI'
+  WITH TOPIC 'topic'
+  WITH TRANSFORM 'URI';
+```
+
+
+The full openCypher clause for creating a stream is:
+```opencypher
+CREATE STREAM stream_name AS
+  LOAD DATA KAFKA 'URI'
+  WITH TOPIC 'topic'
+  WITH TRANSFORM 'URI'
+  [BATCH_INTERVAL milliseconds]
+  [BATCH_SIZE count]
+```
+The `CREATE STREAM` clause happens in a transaction.
+
+`WITH TOPIC` parameter specifies the Kafka topic from which we'll stream
+data.
+
+`WITH TRANSFORM` parameter should contain a URI of the transform script.
+
+`BATCH_INTERVAL` parameter defines the time interval in milliseconds
+which is the time between two successive stream importing operations.
+
+`BATCH_SIZE` parameter defines the count of Kafka messages that will be
+batched together before import.
+
+If both `BATCH_INTERVAL` and `BATCH_SIZE` parameters are given, the condition
+that is satisfied first will trigger the batched import.
+
+Default value for `BATCH_INTERVAL` is 100 milliseconds, and the default value
+for `BATCH_SIZE` is 10;
+
+The `DROP` clause deletes a stream:
+```opencypher
+DROP STREAM stream_name;
+```
+
+The `SHOW` clause enables you to see all configured streams:
+```opencypher
+SHOW STREAMS;
+```
+
+You can also start/stop streams with the `START` and `STOP` clauses:
+```opencypher
+START STREAM stream_name [LIMIT count BATCHES];
+STOP STREAM stream_name;
+```
+A stream needs to be stopped in order to start it and it needs to be started in
+order to stop it. Starting a started or stopping a stopped stream will not
+affect that stream.
+
+There are also convenience clauses to start and stop all streams:
+```opencypher
+START ALL STREAMS;
+STOP ALL STREAMS;
+```
+
+Before the actual import, you can also test the stream with the `TEST
+STREAM` clause:
+```opencypher
+TEST STREAM stream_name [LIMIT count BATCHES];
+```
+When a stream is tested, data extraction and transformation occurs, but no
+output is inserted in the graph.
+
+A stream needs to be stopped in order to test it. When the batch limit is
+omitted, `TEST STREAM` will run for only one batch by default.

docs/feature_spec/kafka/transform.md

@@ -0,0 +1,34 @@
+# Kafka - data transform
+
+The transform script is a user defined script written in Python.  The script
+should be aware of the data format in the Kafka message.
+
+Each Kafka message is byte length encoded, which means that the first eight
+bytes of each message contain the length of the message.
+
+A sample code for a streaming transform script could look like this:
+
+```python
+def create_vertex(vertex_id):
+  return ("CREATE (:Node {id: $id})", {"id": vertex_id})
+
+
+def create_edge(from_id, to_id):
+  return ("MATCH (n:Node {id: $from_id}), (m:Node {id: $to_id}) "\
+          "CREATE (n)-[:Edge]->(m)", {"from_id": from_id, "to_id": to_id})
+
+
+def stream(batch):
+    result = []
+    for item in batch:
+        message = item.decode('utf-8').strip().split()
+        if len(message) == 1:
+          result.append(create_vertex(message[0])))
+        else:
+          result.append(create_edge(message[0], message[1]))
+    return result
+
+```
+
+The script should output openCypher query strings based on the type of the
+records.

docs/feature_spec/python-query-modules.md

@@ -0,0 +1,185 @@
+# Python 3 Query Modules
+
+## Introduction
+
+Memgraph exposes a C API for writing the so called Query Modules. These
+modules contain definitions of procedures which can be invoked through the
+query language using the `CALL ... YIELD ...` syntax. This mechanism allows
+database users to extend Memgraph with their own algorithms and
+functionalities.
+
+Using a low level language like C can be quite cumbersome for writing modules,
+so it seems natural to add support for a higher level language on top of the
+existing C API.
+
+There are languages written exactly for this purpose of extending C with high
+level constructs, for example Lua and Guile. Instead of those, we have chosen
+Python 3 to be the first high level language we will support. The primary reason
+being that it's very popular, so more people should be able to write modules.
+Another benefit of Python which comes out of its popularity is the large
+ecosystem of libraries, especially graph algorithm related ones like NetworkX.
+Python does have significant performance and implementation downsides compared
+to Lua and Guile, but these are described in more detail later in this
+document.
+
+## Python 3 API Overview
+
+The Python 3 API should be as user friendly as possible as well as look
+Pythonic. This implies that some functions from the C API will not map to the
+exact same functions. The most obvious case for a Pythonic approach is
+registering procedures of a query module. Let's take a look at the C example
+and its transformation to Python.
+
+```c
+static void procedure(const struct mgp_list *args,
+                      const struct mgp_graph *graph, struct mgp_result *result,
+                      struct mgp_memory *memory);
+
+int mgp_init_module(struct mgp_module *module, struct mgp_memory *memory) {
+  struct mgp_proc *proc =
+      mgp_module_add_read_procedure(module, "procedure", procedure);
+  if (!proc) return 1;
+  if (!mgp_proc_add_arg(proc, "required_arg",
+                        mgp_type_nullable(mgp_type_any())))
+    return 1;
+  struct mgp_value *null_value = mgp_value_make_null(memory);
+  if (!mgp_proc_add_opt_arg(proc, "optional_arg",
+                            mgp_type_nullable(mgp_type_any()), null_value)) {
+    mgp_value_destroy(null_value);
+    return 1;
+  }
+  mgp_value_destroy(null_value);
+  if (!mgp_proc_add_result(proc, "result", mgp_type_string())) return 1;
+  if (!mgp_proc_add_result(proc, "args",
+                           mgp_type_list(mgp_type_nullable(mgp_type_any()))))
+    return 1;
+  return 0;
+}
+```
+
+In Python things should be a lot simpler.
+
+```Python
+# mgp.read_proc obtains the procedure name via __name__ attribute of a function.
+@mgp.read_proc(# Arguments passed to multiple mgp_proc_add_arg calls
+               (('required_arg', mgp.Nullable(mgp.Any)), ('optional_arg', mgp.Nullable(mgp.Any), None)),
+               # Result fields passed to multiple mgp_proc_add_result calls
+               (('result', str), ('args', mgp.List(mgp.Nullable(mgp.Any)))))
+def procedure(args, graph, result, memory):
+    pass
+```
+
+Here we have replaced `mgp_module_*` and `mgp_proc_*` C API with a much
+simpler decorator function in Python -- `mgp.read_proc`. The types of
+arguments and result fields can both be our types as well as Python builtin
+types which can map to supported `mgp_value` types. The expected builtin types
+we ought to support are: `bool`, `str`, `int`, `float` and `map`. While the
+rest of the types are provided via our Python API. Optionally, we can add
+convenience support for `object` type which would map to
+`mgp.Nullable(mgp.Any)` and `list` which would map to
+`mgp.List(mgp.Nullable(mgp.Any))`. Also, it makes sense to take a look if we
+can leverage Python's `typing` module here.
+
+Another Pythonic change is to remove `mgp_value` C API from Python altogether.
+This means that the arguments a Python procedure receives are not `mgp_value`
+instances but rather `PyObject` instances. In other words, our implementation
+would immediately marshal `mgp_value` to corresponding type in Python.
+Obviously we would need to provide our own Python types for non-builtin
+things like `mgp.Vertex` (equivalent to `mgp_vertex`) and other.
+
+Continuing from our example above, let's say the procedure was invoked through
+Cypher using the following query.
+
+    MATCH (n) CALL py_module.procedure(42, n) YIELD *;
+
+The Python procedure could then do the following and complete without throwing
+neither the AssertionError nor the ValueError.
+
+```Python
+def procedure(args, graph, result, memory):
+    assert isinstance(args, list)
+    # Unpacking throws ValueError if args does not contain exactly 2 values.
+    required_arg, optional_arg = args
+    assert isintance(required_arg, int)
+    assert isinstance(optional_arg, mgp.Vertex)
+```
+
+The rest of the C API should naturally map to either top level functions or
+class methods as appropriate.
+
+## Loading Python Query Modules
+
+Our current mechanism for loading the modules is to look for `.so` files in
+the directory specified by `--query-modules` flag. This is done when Memgraph
+is started. We can extend this mechanism to look for `.py` files in addition
+to `.so` files in the same directory and import them in the embedded Python
+interpreter. The only issue is embedding the interpreter in Memgraph.  There
+are multiple choices:
+
+  1. Building Memgraph and statically linking to Python.
+  2. Building Memgraph and dynamically linking to Python, and distributing
+     Python with Memgraph's installation.
+  3. Building Memgraph and dynamically linking to Python, but without
+     distributing the Python library.
+  4. Building Memgraph and optionally loading Python library by trying to
+     `dlopen` it.
+
+The first two options are only viable if the Python license allows, and this
+will need further investigation.
+
+The third option adds Python as an installation dependency for Memgraph, and
+without it Memgraph will not run. This is problematic for users which cannot
+or do not want to install Python 3.
+
+The fourth option avoids all of the issues present in the first 3 options, but
+comes at a higher implementation cost. We would need to try to `dlopen` the
+Python library and setup function pointers. If we succeed we would import
+`.py` files from the `--query-modules` directory. On the other hand, if the
+user does not have Python, `dlopen` would fail and Memgraph would run without
+Python support.
+
+After live discussion, we've decided to go with option 3. This way we don't
+have to worry about mismatching Python versions we support and what the users
+expect. Also, we should target Python 3.5 as that should be common between
+Debian and CentOS for which we ship installation packages.
+
+## Performance and Implementation Problems
+
+As previously mentioned, embedding Python introduces usability issues compared
+to other embeddable languages.
+
+The first, major issue is Global Interpreter Lock (GIL). Initializing Python
+will start a single global interpreter and running multiple threads will
+require acquiring GIL. In practice, this means that when multiple users run a
+procedure written in Python in parallel the execution will not actually be
+parallel. Python's interpreter will jump between executing one user's
+procedure and the other's. This can be quite an issue for long running
+procedures when multiple users are querying Memgraph. The solution for this
+issue is Python's API for sub-interpreters. Unfortunately, the support for
+them is rather poor and the API contains a lot of critical bugs when we tried
+to use them. For the time being, we will have to accept GIL and its downsides.
+Perhaps in the future we will gain more knowledge on how we could reduce the
+acquire rate of GIL or the sub-interpreter API will get improved.
+
+Another major issue is memory allocation. Python's C API does not have support
+for setting up a temporary allocator during execution of a single function.
+It only has support for setting up a global heap allocator. This obviously
+impacts our control of memory during a query procedure invocation. Besides
+potential performance penalty, a procedure could allocate much more memory
+than we would actually allow for execution of a single query. This means that
+options controlling the memory limit during query execution are useless. On
+the bright side, Python does use block style allocators and reference
+counting, so the performance penalty and global memory usage should not be
+that terrible.
+
+The final issue that isn't as major as the ones above is the global state of
+the interpreter. In practice this means that any registered procedure and
+imported module has access to any other procedure and module. This may pollute
+the namespace for other users, but it should not be much of a problem because
+Python always has things under a module scope. The other, slightly bigger
+downside is that a malicious user could use this knowledge to modify other
+modules and procedures. This seems like a major issue, but if we take the
+bigger picture into consideration, we already have a security issue in general
+by invoking `dlopen` on `.so` and potentially running arbitrary code. This was
+the trade off we chose to allow users to extend Memgraph. It's up to the users
+to write sane extensions and protect their servers from access.

docs/feature_spec/replication.md

@@ -0,0 +1,202 @@
+# Replication
+
+## High Level Context
+
+Replication is a method that ensures that multiple database instances are
+storing the same data. To enable replication, there must be at least two
+instances of Memgraph in a cluster. Each instance has one of either two roles:
+main or replica. The main instance is the instance that accepts writes to the
+database and replicates its state to the replicas. In a cluster, there can only
+be one main. There can be one or more replicas. None of the replicas will accept
+write queries, but they will always accept read queries (there is an exception
+to this rule and is described below). Replicas can also be configured to be
+replicas of replicas, not necessarily replicas of the main. Each instance will
+always be reachable using the standard supported communication protocols. The
+replication will replicate WAL data. All data is transported through a custom
+binary protocol that will try remain backward compatible, so that replication
+immediately allows for zero downtime upgrades.
+
+Each replica can be configured to accept replicated data in one of the following
+modes:
+ - synchronous
+ - asynchronous
+ - semi-synchronous
+
+### Synchronous Replication
+
+When the data is replicated to a replica synchronously, all of the data of a
+currently pending transaction must be sent to the synchronous replica before the
+transaction is able to commit its changes.
+
+This mode has a positive implication that all data that is committed to the
+main will always be replicated to the synchronous replica. It also has a
+negative performance implication because non-responsive replicas could grind all
+query execution to a halt.
+
+This mode is good when you absolutely need to be sure that all data is always
+consistent between the main and the replica.
+
+### Asynchronous Replication
+
+When the data is replicated to a replica asynchronously, all pending
+transactions are immediately committed and their data is replicated to the
+asynchronous replica in the background.
+
+This mode has a positive performance implication in which it won't slow down
+query execution. It also has a negative implication that the data between the
+main and the replica is almost never in a consistent state (when the data is
+being changed).
+
+This mode is good when you don't care about consistency and only need an
+eventually consistent cluster, but you care about performance.
+
+### Semi-synchronous Replication
+
+When the data is replicated to a replica semi-synchronously, the data is
+replicated using both the synchronous and asynchronous methodology. The data is
+always replicated synchronously, but, if the replica for any reason doesn't
+respond within a preset timeout, the pending transaction is committed and the
+data is replicated to the replica asynchronously.
+
+This mode has a positive implication that all data that is committed is
+*mostly* replicated to the semi-synchronous replica. It also has a negative
+performance implication as the synchronous replication mode.
+
+This mode is useful when you want the replication to be synchronous to ensure
+that the data within the cluster is consistent, but you don't want the main
+to grind to a halt when you have a non-responsive replica.
+
+### Addition of a New Replica
+
+Each replica, when added to the cluster (in any mode), will first start out as
+an asynchronous replica. That will allow replicas that have fallen behind to
+first catch-up to the current state of the database. When the replica is in a
+state that it isn't lagging behind the main it will then be promoted (in a brief
+stop-the-world operation) to a semi-synchronous or synchronous replica. Slaves
+that are added as asynchronous replicas will remain asynchronous.
+
+## User Facing Setup
+
+### How to Setup a Memgraph Cluster with Replication?
+
+Replication configuration is done primarily through openCypher commands. This
+allows the cluster to be dynamically rearranged (new leader election, addition
+of a new replica, etc.).
+
+Each Memgraph instance when first started will be a main. You have to change
+the role of all replica nodes using the following openCypher query before you
+can enable replication on the main:
+
+```plaintext
+SET REPLICATION ROLE TO (MAIN|REPLICA) WITH PORT <port_number>;
+```
+
+Note that the "WITH PORT <port_number>" part of the query sets the replication port,
+but it applies only to the replica. In other words, if you try to set the
+replication port as the main, a semantic exception will be thrown.
+After you have set your replica instance to the correct operating role, you can
+enable replication in the main instance by issuing the following openCypher
+command:
+```plaintext
+REGISTER REPLICA name (SYNC|ASYNC) [WITH TIMEOUT 0.5] TO <socket_address>;
+```
+
+The socket address must be a string of the following form:
+
+```plaintext
+"IP_ADDRESS:PORT_NUMBER"
+```
+
+where IP_ADDRESS is a valid IP address, and PORT_NUMBER is a valid port number,
+both given in decimal notation.
+Note that in this case they must be separated by a single colon.
+Alternatively, one can give the socket address as:
+
+```plaintext
+"IP_ADDRESS"
+```
+
+where IP_ADDRESS must be a valid IP address, and the port number will be
+assumed to be the default one (we specify it to be 10000).
+
+Each Memgraph instance will remember what the configuration was set to and will
+automatically resume with its role when restarted.
+
+### How to Setup an Advanced Replication Scenario?
+
+The configuration allows for a more advanced scenario like this:
+```plaintext
+main -[asynchronous]-> replica 1 -[semi-synchronous]-> replica 2
+```
+
+To configure the above scenario, issue the following commands:
+```plaintext
+SET REPLICATION ROLE TO REPLICA;  # on replica 1
+SET REPLICATION ROLE TO REPLICA;  # on replica 2
+
+REGISTER REPLICA replica1 ASYNC TO <replica1_sa>;  # on main
+REGISTER REPLICA replica2 SYNC WITH TIMEOUT 0.5 TO <replica2_sa>;  # on replica 1
+```
+
+### How to See the Current Replication Status?
+
+To see the replication ROLE of the current Memgraph instance, you can issue the
+following query:
+
+```plaintext
+SHOW REPLICATION ROLE;
+```
+
+To see the replicas of the current Memgraph instance, you can issue the
+following query:
+
+```plaintext
+SHOW REPLICAS;
+```
+
+To delete a replica, issue the following query:
+
+```plaintext
+DELETE REPLICA 'name';
+```
+
+### How to Promote a New Main?
+
+When you have an already set-up cluster, to promote a new main, just set the
+replica that you want to be a main to the main role.
+
+```plaintext
+SET REPLICATION ROLE TO MAIN;  # on desired replica
+```
+
+After the command is issued, if the original main is still alive, it won't be
+able to replicate its data to the replica (the new main) anymore and will enter
+an error state. You must ensure that at any given point in time there aren't
+two mains in the cluster.
+
+## Integration with Memgraph
+
+WAL `Delta`s are replicated between the replication main and replica. With
+`Delta`s, all `StorageGlobalOperation`s are also replicated. Replication is
+essentially the same as appending to the WAL.
+
+Synchronous replication will occur in `Commit` and each
+`StorageGlobalOperation` handler. The storage itself guarantees that `Commit`
+will be called single-threadedly and that no `StorageGlobalOperation` will be
+executed during an active transaction. Asynchronous replication will load its
+data from already written WAL files and transmit the data to the replica. All
+data will be replicated using our RPC protocol (SLK encoded).
+
+For each replica the replication main (or replica) will keep track of the
+replica's state. That way, it will know which operations must be transmitted to
+the replica and which operations can be skipped. When a replica is very stale,
+a snapshot will be transmitted to it so that it can quickly synchronize with
+the current state. All following operations will transmit WAL deltas.
+
+## Reading materials
+
+1. [PostgreSQL comparison of different solutions](https://www.postgresql.org/docs/12/different-replication-solutions.html)
+2. [PostgreSQL docs](https://www.postgresql.org/docs/12/runtime-config-replication.html)
+3. [MySQL reference manual](https://dev.mysql.com/doc/refman/8.0/en/replication.html)
+4. [MySQL docs](https://dev.mysql.com/doc/refman/8.0/en/replication-setup-slaves.html)
+5. [MySQL master switch](https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-switch.html)

docs/feature_spec/tensorflow_op/technicalities.md

@@ -0,0 +1,61 @@
+# Tensorflow Op - Technicalities
+
+The final result should be a shared object (".so") file that can be
+dynamically loaded by the Tensorflow runtime in order to directly
+access the bolt client.
+
+## About Tensorflow
+
+Tensorflow is usually used with Python such that the Python code is used
+to define a directed acyclic computation graph. Basically no computation
+is done in Python. Instead, values from Python are copied into the graph
+structure as constants to be used by other Ops. The directed acyclic graph
+naturally ends up with two sets of border nodes, one for inputs, one for
+outputs. These are sometimes called "feeds".
+
+Following the Python definition of the graph, during training, the entire
+data processing graph/pipeline is called from Python as a single expression.
+This leads to lazy evaluation since the called result has already been
+defined for a while.
+
+Tensorflow internally works with tensors, i.e. n-dimensional arrays. That
+means all of its inputs need to be matrices as well as its outputs. While
+it is possible to feed data directly from Python's numpy matrices straight
+into Tensorflow, this is less desirable than using the Tensorflow data API
+(which defines data input and processing as a Tensorflow graph) because:
+
+  1. The data API is written in C++ and entirely avoids Python and as such
+  is faster
+  2. The data API, unlike Python is available in "Tensorflow serving". The
+  default way to serve Tensorflow models in production.
+
+Once the entire input pipeline is defined via the tf.data API, its input
+is basically a list of node IDs the model is supposed to work with. The
+model, through the data API knows how to connect to Memgraph and execute
+openCypher queries in order to get the remaining data it needs.
+(For example features of neighbouring nodes.)
+
+## The Interface
+
+I think it's best you read the official guide...  
+<https://www.tensorflow.org/extend/adding_an_op>  
+And especially the addition that specifies how data ops are special  
+<https://www.tensorflow.org/extend/new_data_formats>  
+
+## Compiling the TF Op
+
+There are two options for compiling a custom op.  
+One of them involves pulling the TF source, adding your code to it and
+compiling via bazel.  
+This is probably awkward to do for us and would
+significantly slow down compilation.  
+
+The other method involves installing Tensorflow as a Python package and
+pulling the required headers from for example:  
+`/usr/local/lib/python3.6/site-packages/tensorflow/include`  
+We can then compile our Op with our regular build system.
+
+This is practical since we can copy the required headers to our repo.
+If necessary, we can have several versions of the headers to build several
+versions of our Op for every TF version which we want to support.
+(But this is unlikely to be required as the API should be stable).

docs/feature_spec/tensorflow_op/usage_example.md

@@ -0,0 +1,142 @@
+# Example for Using the Bolt Client Tensorflow Op
+
+## Dynamic Loading
+
+``` python3
+import tensorflow as tf
+
+mg_ops = tf.load_op_library('/usr/bin/memgraph/tensorflow_ops.so')
+```
+
+## Basic Usage
+
+``` python3
+dataset = mg_ops.OpenCypherDataset(
+            # This is probably unfortunate as the username and password
+            # get hardcoded into the graph, but for the simple case it's fine
+            "hostname:7687", auth=("user", "pass"),
+
+            # Our query
+            '''
+            MATCH (n:Train) RETURN n.id, n.features
+            ''',
+
+            # Cast return values to these types
+            (tf.string, tf.float32))
+
+# Some Tensorflow data api boilerplate
+iterator = dataset.make_one_shot_iterator()
+next_element = iterator.get_next()
+
+# Up to now we have only defined our computation graph which basically
+# just connects to Memgraph
+# `next_element` is not really data but a handle to a node in the Tensorflow
+# graph, which we can and do evaluate
+# It is a Tensorflow tensor with shape=(None, 2)
+# and dtype=(tf.string, tf.float)
+# shape `None` means the shape of the tensor is unknown at definition time
+# and is dynamic and will only be known once the tensor has been evaluated
+
+with tf.Session() as sess:
+    node_ids = sess.run(next_element)
+    # `node_ids` contains IDs and features of all the nodes 
+    # in the graph with the label "Train"
+    # It is a numpy.ndarray with a shape ($n_matching_nodes, 2)
+```
+
+## Memgraph Client as a Generic Tensorflow Op
+
+Other than the Tensorflow Data Op, we'll want to support a generic Tensorflow
+Op which can be put anywhere in the Tensorflow computation Graph. It takes in
+an arbitrary tensor and produces a tensor. This would be used in the GraphSage
+algorithm to fetch the lowest level features into Tensorflow
+
+```python3
+requested_ids = np.array([1, 2, 3])
+ids_placeholder = tf.placeholder(tf.int32)
+
+model = mg_ops.OpenCypher()
+    "hostname:7687", auth=("user", "pass"),
+    """
+    UNWIND $node_ids as nid
+    MATCH (n:Train {id: nid})
+    RETURN n.features
+    """,
+
+    # What to call the input tensor as an openCypher parameter
+    parameter_name="node_ids",
+
+    # Type of our resulting tensor
+    dtype=(tf.float32)
+)
+
+features = model(ids_placeholder)
+
+with tf.Session() as sess:
+    result = sess.run(features,
+                    feed_dict={ids_placeholder: requested_ids})
+```
+
+This is probably easier to implement than the Data Op, so it might be a good
+idea to start with.
+
+## Production Usage
+
+During training, in the GraphSage algorithm at least, Memgraph is at the
+beginning and at the end of the Tensorflow computation graph.  
+At the beginning, the Data Op provides the node IDs which are fed into the
+generic Tensorflow Op to find their neighbours and their neighbours and
+their features.
+
+Production usage differs in that we don't use the Data Op. The Data Op is
+effectively cut off and the initial input is fed by Tensorflow serving,
+with the data found in the request.
+
+For example a JSON request to classify a node might look like:
+
+`POST http://host:port/v1/models/GraphSage/versions/v1:classify`
+
+With the contents:
+
+```json
+{
+    "examples": [
+        {"node_id": 1},
+        {"node_id": 2}
+    ],
+}
+```
+
+Every element of the "examples" list is an example to be computed. Each is
+represented by a dict with keys matching names of feeds in the Tensorflow
+graph and values being the values we want fed in for each example
+
+The REST API then replies in kind with the classification result in JSON
+
+Note about adding our custom Op to Tensorflow serving.  
+Our Ops .so can be added into the Bazel build to link with Tensorflow serving
+or it can be dynamically loaded by starting Tensorflow serving with a flag
+`--custom_op_paths`
+
+## Considerations
+
+There might be issues here that the url to connect to Memgraph is
+hardcoded into the op and would thus be wrong when moved to production,
+requiring some type of a hack to make work. We probably want to solve
+this by having the client op take in another tf.Variable as an input
+which would contain a connection url and username/password.  
+We have to research whether this makes it easy enough to move to
+production, as the connection string variable is still a part of the
+graph, but maybe easier to replace.  
+
+It is probably the best idea to utilize openCypher parameters to make
+our queries flexible. The exact API as to how to declare the parameters
+in Python is open to discussion.
+
+The Data Op might not even be necessary to implement as it is not
+key for production use. It can be replaced in training mode with
+feed dicts and either
+
+ 1. Getting the initial list of nodes via a Python Bolt client
+ 2. Creating a separate Tensorflow computation graph that gets all the
+ relevant node IDs into Python

docs/feature_specs/kafka/extractor.md

@@ -1,20 +0,0 @@
-# Kafka - data extractor
-
-The data extractor is responsible for loading data from Kafka.  In order to do
-so, it needs to know the URI of the Kafka leader broker.  Once the extractor
-connects to Kafka, it starts importing data.
-
-Data extractor depends on [cppkafka](https://github.com/mfontanini/cppkafka)
-which makes message consumption just a few API calls, as seen
-[here](https://github.com/mfontanini/cppkafka/wiki/Consuming-messages).
-
-There are also other metadata that can be passed to data extractor that are
-defined with our [extension](opencypher.md) of openCypher.
-
-A full list of configurable metadata can be found
-[here](https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md).
-
-Memgraph supports customizing the following:
-
-  * `metadata.broker.list` which is a required parameter, set by `KAFKA 'URI'`
-  * `queue.buffering.max.ms` set by `BATCH INTERVAL`

docs/feature_specs/kafka/opencypher.md

@@ -1,52 +0,0 @@
-# Kafka - openCypher clause
-
-One must be able to specify the following when importing data from Kafka:
-* Kafka URI
-* Transform [script](transform.md) URI
-
-
-Kafka endpoint is the URI of the leader broker and it is required for data
-[extractor](extractor.md).
-
-Minimum required syntax looks like:
-```opencypher
-CREATE STREAM kafka_stream AS LOAD DATA KAFKA '127.0.0.1/topic' WITH TRANSFORM
-'127.0.0.1/transform.py';
-```
-
-The `CREATE STREAM` clause happens in a transaction.
-
-The full openCypher clause for creating a stream is:
-```opencypher
-CREATE STREAM stream_name AS
-  LOAD DATA KAFKA 'URI'
-  WITH TRANSFORM 'URI'
-  [BATCH INTERVAL milliseconds]
-```
-
-The `WITH TRANSFORM` parameter should contain a URI of the transform script.
-
-The `BATCH_INTERVAL` parameter defines the time interval in milliseconds
-that defines the time between two successive stream importing operations.
-
-The `DROP` clause deletes a stream:
-```opencypher
-DROP STREAM stream_name;
-```
-
-The `SHOW` clause enables you to see all configured streams:
-```opencypher
-SHOW STREAMS;
-```
-
-You can also start/stop streams with the `START` and `STOP` clauses:
-```opencypher
-START STREAM stream_name [LIMIT count BATCHES];
-STOP STREAM stream_name;
-```
-
-There are also convenience clauses to start and stop all streams:
-```opencypher
-START ALL STREAMS;
-STOP ALL STREAMS;
-```

docs/feature_specs/kafka/transform.md

@@ -1,52 +0,0 @@
-# Kafka - data transform
-
-The transform script is a user defined script written in Python.  The script
-should be aware of the data format in the Kafka message.
-
-Each Kafka message is byte length encoded, which means that the first eight
-bytes of each message contain the length of the message.
-
-More on the message format can be seen
-[here](https://cwiki.apache.org/confluence/display/KAFKA/A+Guide+To+The+Kafka+Protocol#AGuideToTheKafkaProtocol-Messagesets).
-
-
-The script will be embedded in our C++ codebase using pythons
-[embedding](https://docs.python.org/3.5/extending/embedding.html) feature.
-
-A sample code for a streaming transform script could look like this:
-
-```python
-import struct
-import sys
-
-def get_records():
-    while True:
-        message_len = sys.stdin.read(8)
-        if len(message_len) == 8:
-            message_len = struct.unpack("L", message_len)[0]
-            record = sys.stdin.read(message_len)
-            yield record
-        else:
-            assert len(message_len) == 0, message_len
-            return
-
-def create_vertex(fields):
-  return "CREATE (n:Node {{id: {}}})".format(fields[1])
-
-
-def create_edge(fields):
-  return "MATCH (n:Node {{id: {}}}) "\
-         "MATCH ((m:Node {{id : {}}})) "\
-         "CREATE (n)-[e:Edge{{value: {}}}]->(m) "\
-         .format(fields[1], fields[2], fields[3])
-
-for record in get_records():
-  fields = record.split("\t")
-  if fields[0] == "v":
-    return create_vertex(fields):
-  else:
-    return create_edge(fields)
-```
-
-The script should output openCypher query strings based on the type of the
-records.

docs/presentation/latex-template/README.md

@@ -0,0 +1,22 @@
+# Memgraph LaTeX Beamer Template
+
+This folder contains all of the needed files for creating a presentation with
+Memgraph styling. You should use this style for any public presentations.
+
+Feel free to improve it according to style guidelines and raise issues if you
+find any.
+
+## Usage
+
+Copy the contents of this folder (excluding this README file) to where you
+want to write your own presentation. After copying, you can start editing the
+`template.tex` with your content.
+
+To compile the presentation to a PDF, run `latexmk -pdf -xelatex`. Some
+directives require XeLaTeX, so you need to pass `-xelatex` as the final option
+of `latexmk`. You may also need to install some packages if the compilation
+complains about missing packages.
+
+To clean up the generated files, use `latexmk -C`. This will also delete the
+generated PDF. If you wish to remove generated files except the PDF, use
+`latexmk -c`.

docs/presentation/latex-template/mg-beamer.cls

@@ -0,0 +1,82 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesClass{mg-beamer}[2018/03/26 Memgraph Beamer]
+
+\DeclareOption*{\PassOptionsToClass{\CurrentOption}{beamer}}
+
+\ProcessOptions \relax
+
+\LoadClass{beamer}
+
+\usetheme{Pittsburgh}
+
+% Memgraph color palette
+\definecolor{mg-purple}{HTML}{720096}
+\definecolor{mg-red}{HTML}{DD2222}
+\definecolor{mg-orange}{HTML}{FB6E00}
+\definecolor{mg-yellow}{HTML}{FFC500}
+\definecolor{mg-gray}{HTML}{857F87}
+\definecolor{mg-black}{HTML}{231F20}
+
+\RequirePackage{fontspec}
+% Title fonts
+\setbeamerfont{frametitle}{family={\fontspec[Path = ./mg-style/fonts/]{EncodeSansSemiCondensed-Regular.ttf}}}
+\setbeamerfont{title}{family={\fontspec[Path = ./mg-style/fonts/]{EncodeSansSemiCondensed-Regular.ttf}}}
+% Body font
+\RequirePackage[sfdefault,light]{roboto}
+% Roboto is pretty bad for monospace font. We will find a replacement.
+% \setmonofont{RobotoMono-Regular.ttf}[Path = ./mg-style/fonts/]
+
+% Title slide styles
+% \setbeamerfont{frametitle}{size=\huge}
+% \setbeamerfont{title}{size=\huge}
+% \setbeamerfont{date}{size=\tiny}
+
+% Other typography styles
+\setbeamertemplate{frametitle}[default][center]
+\setbeamercolor{frametitle}{fg=mg-black}
+\setbeamercolor{title}{fg=mg-black}
+\setbeamercolor{section in toc}{fg=mg-black}
+\setbeamercolor{local structure}{fg=mg-orange}
+\setbeamercolor{alert text}{fg=mg-red}
+
+% Commands
+\newcommand{\mgalert}[1]{{\usebeamercolor[fg]{alert text}#1}}
+\newcommand{\titleframe}{\frame[plain]{\titlepage}}
+\newcommand{\mgtexttt}[1]{{\textcolor{mg-gray}{\texttt{#1}}}}
+
+% Title slide background
+\RequirePackage{tikz,calc}
+% Use title-slide-169 if aspect ration is 16:9
+\pgfdeclareimage[interpolate=true,width=\paperwidth,height=\paperheight]{logo}{mg-style/title-slide-169}
+\setbeamertemplate{background}{
+  \begin{tikzpicture}
+  \useasboundingbox (0,0) rectangle (\the\paperwidth,\the\paperheight);
+    \pgftext[at=\pgfpoint{0}{0},left,base]{\pgfuseimage{logo}};
+  \ifnum\thepage>1\relax
+  \useasboundingbox (0,0) rectangle (\the\paperwidth,\the\paperheight);
+      \fill[white, opacity=1](0,\the\paperheight)--(\the\paperwidth,\the\paperheight)--(\the\paperwidth,0)--(0,0)--(0,\the\paperheight);
+  \fi
+  \end{tikzpicture}
+}
+
+% Footline content
+\setbeamertemplate{navigation symbols}{}%remove navigation symbols
+ \setbeamertemplate{footline}{
+  \begin{beamercolorbox}[ht=1.6cm,wd=\paperwidth]{footlinecolor}
+    \vspace{0.1cm}
+    \hfill
+    \begin{minipage}[c]{3cm}
+      \begin{center}
+       \includegraphics[height=0.8cm]{mg-style/memgraph-logo.png}
+      \end{center}
+    \end{minipage}
+    \begin{minipage}[c]{7cm}
+         \insertshorttitle\ --- \insertsection
+    \end{minipage}
+    \begin{minipage}[c]{2cm}
+        \tiny{\insertframenumber{} of \inserttotalframenumber}
+    \end{minipage}
+   \end{beamercolorbox}
+}
+
+\endinput

docs/presentation/latex-template/template.tex

@@ -0,0 +1,40 @@
+% Set 16:9 aspect ratio
+\documentclass[aspectratio=169]{mg-beamer}
+% Default directive sets the regular 4:3 aspect ratio
+% \documentclass{mg-beamer}
+\mode<presentation>
+
+% requires xelatex
+\usepackage{ccicons}
+
+\title{Insert Presentation Title}
+\titlegraphic{\ccbyncnd}
+\author{Insert Name}
+
+% Institute doesn't look good in our current styling class.
+% \institute[Memgraph Ltd.]{\pgfimage[height=1.5cm]{mg-logo.png}}
+
+% Date is autogenerated on compilation, so no need to set it explicitly,
+% unless you wish to override it with a different date.
+% \date{March 23, 2018}
+
+\begin{document}
+
+\titleframe
+
+\section{Intro}
+
+\begin{frame}{Contents}
+  \tableofcontents
+\end{frame}
+
+\begin{frame}{Memgraph Markup Test}
+  \begin{itemize}
+    \item \mgtexttt{Prefer \\mgtexttt for monospace}
+    \item Replace this slide with your own
+    \item Add even more slides in different sections
+    \item Make sure you spellcheck your presentation
+  \end{itemize}
+\end{frame}
+
+\end{document}

docs/user_technical/README.md

@@ -1,23 +0,0 @@
-# Technical Documentation
-
-## About Memgraph
-
-Memgraph is an ACID compliant high performance transactional in-memory graph
-database management system featuring highly concurrent
-data structures, multi-version concurrency control and asynchronous IO.
-
-[//]: # (When adding a new documentation file, please add it to the list)
-
-## Contents
-
-  * [About Memgraph](#about-memgraph)
-  * [Quick Start](quick-start.md)
-  * [Examples](examples.md)
-  * [Drivers](drivers.md)
-  * [Data Storage](storage.md)
-  * [openCypher Query Language](open-cypher.md)
-  * [Import Tools](import-tools.md)
-  * [Concepts](concepts.md)
-  * [Upcoming Features](upcoming-features.md)
-
-[//]: # (Nothing should go below the contents section)

docs/user_technical/bundle_community

@@ -1,58 +0,0 @@
-#!/bin/bash
-
-working_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-build_dir=.bundle_community
-
-# curl and php are required
-if ! which php >/dev/null; then
-    echo "php is required!"
-    exit 1
-fi
-
-cd ${working_dir}
-generator="couscous.phar"
-
-# download the generator if it's not already downloaded
-if [ ! -f ${generator} ]; then
-    curl -OS http://couscous.io/${generator}
-fi
-
-# create build directory
-if [ -d $build_dir ]; then
-    rm -rf $build_dir
-fi
-mkdir $build_dir
-
-# copy all files to build directory
-cp couscous.yml *.md $generator $build_dir
-
-# go to build directory
-cd $build_dir
-
-# modify config file
-cat >> couscous.yml <<EOF
-template:
-    directory: .
-EOF
-
-# create template file
-echo "{{ content|raw }}" > default.twig
-
-# generate the site
-php ${generator} generate
-
-# create contents file
-cd .couscous/generated
-tail -n +$( grep -n "Contents" index.html | cut -d ':' -f 1 ) index.html | \
-    grep href | grep .html | \
-    sed -r 's/^[^"]+"//' | sed -r 's/.html">/ /' | sed -r 's/<.+//' > .contents
-rm index.html
-
-# create archive
-target=docs.tar.gz
-if [ -f $target ]; then
-    rm $target
-fi
-tar -czf $working_dir/$target .contents *.html
-
-echo "Created archive: $working_dir/$target"

docs/user_technical/concepts.md

@@ -1,72 +0,0 @@
-## Concepts
-
-### Weighted Shortest Path
-
-Weighted shortest path problem is the problem of finding a path between two
-nodes in a graph such that the sum of the weights of edges connecting nodes on
-the path is minimized.
-More about the *weighted shortest path* problem can be found
-[here](https://en.wikipedia.org/wiki/Shortest_path_problem).
-
-## Implementation
-
-Our implementation of the *weighted shortest path* algorithm uses a modified
-version of Dijkstra's algorithm that can handle length restriction. The length
-restriction parameter is optional, and when it's not set it could increase the
-complexity of the algorithm.
-
-A sample query that finds a shortest path between two nodes can look like this:
-
-```opencypher
-MATCH (a {id: 723})-[edge_list *wShortest 10 (e, n | e.weight) total_weight]-(b {id: 882}) RETURN *
-```
-
-This query has an upper bound length restriction set to `10`. This means that no
-path that traverses more than `10` edges will be considered as a valid result.
-
-
-#### Upper Bound Implications
-
-Since the upper bound parameter is optional, we can have different results based
-on this parameter.
-
-Lets take a look at the following graph and queries.
-
-```
-      5            5
-      /-----[1]-----\
-     /               \
-    /                 \      2
-  [0]                 [4]---------[5]
-    \                 /
-     \               /
-      \--[2]---[3]--/
-      3      3     3
-```
-
-```opencypher
-MATCH (a {id: 0})-[edge_list *wShortest 3 (e, n | e.weight) total_weight]-(b {id: 5}) RETURN *
-```
-
-```opencypher
-MATCH (a {id: 0})-[edge_list *wShortest   (e, n | e.weight) total_weight]-(b {id: 5}) RETURN *
-```
-
-The first query will try to find the weighted shortest path between nodes `0`
-and `5` with the restriction on the path length set to `3`, and the second query
-will try to find the weighted shortest path with no restriction on the path
-length.
-
-The expected result for the first query is `0 -> 1 -> 4 -> 5` with total cost of
-`12`, while the expected result for the second query is `0 -> 2 -> 3 -> 4 -> 5`
-with total cost of `11`. Obviously, the second query can find the true shortest
-path because it has no restrictions on the length.
-
-To handle cases when the length restriction is set, *weighted shortest path*
-algorithm uses both vertex and distance as the state. This causes the search
-space to increase by the factor of the given upper bound. On the other hand, not
-setting the upper bound parameter, the search space might contain the whole
-graph.
-
-Because of this, one should always try to narrow down the upper bound limit to
-be as precise as possible in order to have a more performant query.

docs/user_technical/couscous.yml

@@ -1,2 +0,0 @@
-title: Memgraph
-subTitle: Technical Documentation

docs/user_technical/distributed.md

@@ -1,4 +0,0 @@
-## Dynamic Graph Partitioner
-
-Memgraph supports dynamic graph partitioning which improves performance on badly partitioned dataset over workers dynamically. To enable it, use the
-```--dynamic_graph_partitioner_enabled``` flag.

docs/user_technical/drivers.md

@@ -1,191 +0,0 @@
-## Bolt Drivers
-
-### 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:
-
-```python
-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.
-driver = GraphDatabase.driver("bolt://localhost:7687",
-                              auth=basic_auth("", ""))
-
-# 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.
-
-```java
-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().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.
-
-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.
-
-```javascript
-var neo4j = require('neo4j-driver').v1;
-var driver = neo4j.driver("bolt://localhost:7687",
-                          neo4j.auth.basic("neo4j", "1234"));
-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.
-
-```csh
-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;
-    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!");
-  }
-}
-```
-
-### Secure Sockets Layer (SSL)
-
-Secure connections are supported and enabled by default. The server initially
-ships with a self-signed testing certificate. The certificate can be replaced
-by editing the following parameters in `/etc/memgraph/memgraph.conf`:
-```
---cert-file=/path/to/ssl/certificate.pem
---key-file=/path/to/ssl/privatekey.pem
-```
-To disable SSL support and use insecure connections to the database you should
-set both parameters (`--cert-file` and `--key-file`) to empty values.
-
-### 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.

docs/user_technical/examples.md

@@ -1,519 +0,0 @@
-## Examples
-
-This chapter shows you how to use Memgraph on real-world data and how to get
-interesting and useful information out of it.
-
-### TED Talks Example
-
-[TED](https://www.ted.com/) is a nonprofit organization devoted to spreading
-ideas, usually in the form of short, powerful talks.
-Today, TED talks are influential videos from expert speakers on almost all
-topics — from science to business to global issues.
-Here we present a small dataset which consists of 97 talks. We'll show you how
-to model this data as a graph and demonstrate a few example queries.
-
-#### Data Model
-Each TED talk has a main speaker, so we
-identify two types of nodes — `Talk` and `Speaker`. Also, we will add
-an edge of type `Gave` pointing to a `Talk` from its main `Speaker`.
-Each speaker has a name so we can add property `name` to `Speaker` node.
-Likewise, we'll add properties `name`, `title` and `description` to node
-`Talk`. Furthermore, each talk is given in a specific TED event, so we can
-create node `Event` with property `name` and relationship `InEvent` between
-talk and event.
-
-Talks are tagged with keywords to facilitate searching, hence we
-add node `Tag` with property `name` and relationship `HasTag` between talk and
-tag. Moreover, users give ratings to each talk by selecting up to three
-predefined string values. Therefore we add node `Rating` with these values as
-property `name` and relationship`HasRating` with property `user_count` between
-talk and rating nodes.
-
-#### Example Queries
-
-We have prepared a database snapshot for this example, so you can easily import
-it when starting Memgraph using the `--durability-directory` option.
-
-```bash
-/usr/lib/memgraph/memgraph --durability-directory /usr/share/memgraph/examples/TEDTalk \
-  --durability-enabled=false --snapshot-on-exit=false
-```
-
-When using Memgraph installed from DEB or RPM package, you may need to stop
-the currently running Memgraph server before you can import the example. Use
-the following command:
-
-```bash
-systemctl stop memgraph
-```
-
-When using Docker, you can import the example with the following command:
-
-```bash
-docker run -p 7687:7687 \
-  -v mg_lib:/var/lib/memgraph -v mg_log:/var/log/memgraph -v mg_etc:/etc/memgraph \
-  memgraph --durability-directory /usr/share/memgraph/examples/TEDTalk \
-  --durability-enabled=false --snapshot-on-exit=false
-```
-
-Now you're ready to try out some of the following queries.
-
-NOTE: If you modify the dataset, the changes will stay only during this run of
-Memgraph.
-
-1) Find all talks given by specific speaker:
-
-```opencypher
-MATCH (n:Speaker {name: "Hans Rosling"})-[:Gave]->(m:Talk)
-RETURN m.title;
-```
-
-2) Find the top 20 speakers with most talks given:
-
-```opencypher
-MATCH (n:Speaker)-[:Gave]->(m)
-RETURN n.name, COUNT(m) as TalksGiven
-ORDER BY TalksGiven DESC LIMIT 20;
-```
-
-3) Find talks related by tag to specific talk and count them:
-
-```opencypher
-MATCH (n:Talk {name: "Michael Green: Why we should build wooden skyscrapers"})
-      -[:HasTag]->(t:Tag)<-[:HasTag]-(m:Talk)
-WITH * ORDER BY m.name
-RETURN t.name, COLLECT(m.name), COUNT(m) AS TalksCount
-ORDER BY TalksCount DESC;
-```
-
-4) Find 20 most frequently used tags:
-
-```opencypher
-MATCH (t:Tag)<-[:HasTag]-(n:Talk)
-RETURN t.name as Tag, COUNT(n) AS TalksCount
-ORDER BY TalksCount DESC, Tag LIMIT 20;
-```
-
-5) Find 20 talks most rated as "Funny". If you want to query by other ratings,
-possible values are: Obnoxious, Jaw-dropping, OK, Persuasive, Beautiful,
-Confusing, Longwinded, Unconvincing, Fascinating, Ingenious, Courageous, Funny,
-Informative and Inspiring.
-
-```opencypher
-MATCH (r:Rating{name:"Funny"})<-[e:HasRating]-(m:Talk)
-RETURN m.name, e.user_count ORDER BY e.user_count DESC LIMIT 20;
-```
-
-6) Find inspiring talks and their speakers from the field of technology:
-
-```opencypher
-MATCH (n:Talk)-[:HasTag]->(m:Tag {name: "technology"})
-MATCH (n)-[r:HasRating]->(p:Rating {name: "Inspiring"})
-MATCH (n)<-[:Gave]-(s:Speaker)
-WHERE r.user_count > 1000
-RETURN n.title, s.name, r.user_count ORDER BY r.user_count DESC;
-```
-
-7) Now let's see one real-world example &mdash; how to make a real-time
-recommendation. If you've just watched a talk from a certain
-speaker (e.g. Hans Rosling) you might be interested in finding more talks from
-the same speaker on a similar topic:
-
-```opencypher
-MATCH (n:Speaker {name: "Hans Rosling"})-[:Gave]->(m:Talk)
-MATCH (t:Talk {title: "New insights on poverty"})-[:HasTag]->(tag:Tag)<-[:HasTag]-(m)
-WITH * ORDER BY tag.name
-RETURN m.title as Title, COLLECT(tag.name), COUNT(tag) as TagCount
-ORDER BY TagCount DESC, Title;
-```
-
-The following few queries are focused on extracting information about
-TED events.
-
-8) Find how many talks were given per event:
-
-```opencypher
-MATCH (n:Event)<-[:InEvent]-(t:Talk)
-RETURN n.name as Event, COUNT(t) AS TalksCount
-ORDER BY TalksCount DESC, Event
-LIMIT 20;
-```
-
-9) Find the most popular tags in the specific event:
-
-```opencypher
-MATCH (n:Event {name:"TED2006"})<-[:InEvent]-(t:Talk)-[:HasTag]->(tag:Tag)
-RETURN tag.name as Tag, COUNT(t) AS TalksCount
-ORDER BY TalksCount DESC, Tag
-LIMIT 20;
-```
-
-10) Discover which speakers participated in more than 2 events:
-
-```opencypher
-MATCH (n:Speaker)-[:Gave]->(t:Talk)-[:InEvent]->(e:Event)
-WITH n, COUNT(e) AS EventsCount WHERE EventsCount > 2
-RETURN n.name as Speaker, EventsCount
-ORDER BY EventsCount DESC, Speaker;
-```
-
-11) For each speaker search for other speakers that participated in same
-events:
-
-```opencypher
-MATCH (n:Speaker)-[:Gave]->()-[:InEvent]->(e:Event)<-[:InEvent]-()<-[:Gave]-(m:Speaker)
-WHERE n.name != m.name
-WITH DISTINCT n, m ORDER BY m.name
-RETURN n.name AS Speaker, COLLECT(m.name) AS Others
-ORDER BY Speaker;
-```
-
-### Football Example
-
-[Football](https://en.wikipedia.org/wiki/Association_football)
-(soccer for the heathens) is a team sport played between two teams of eleven
-players with a spherical ball. The game is played on a rectangular pitch with
-a goal at each and. The object of the game is to score by moving the ball
-beyond the goal line into the opposing goal. The game is played by more than
-250 million players in over 200 countries, making it the world's most
-popular sport.
-
-In this example, we will present a graph model of a reasonably sized dataset
-of football matches across world's most popular leagues.
-
-#### Data Model
-
-In essence, we are trying to model a set of football matches. All information
-about a single match is going to be contained in three nodes and two edges.
-Two of the nodes will represent the teams that have played the match, while the
-third node will represent the game itself. Both edges are directed from the
-team nodes to the game node and are labeled as `:Played`.
-
-Let us consider a real life example of this model&mdash;Arsene Wenger's 1000th.
-game in charge of Arsenal. This was a regular fixture of a 2013/2014
-English Premier League, yet it was written in the stars that this historic
-moment would be a big London derby against Chelsea on Stanford Bridge. The
-sketch below shows how this game is being modeled in our database.
-
-```
-+---------------+                                            +-----------------------------+
-|n: Team        |                                            |w: Game                      |
-|               |-[:Played {side: "home", outcome: "won"}]-->|                             |
-|name: "Chelsea"|                                            |HT_home_score: 4             |
-+---------------+                                            |HT_away_score: 0             |
-                                                             |HT_result: "H"               |
-                                                             |FT_home_score: 6             |
-                                                             |FT_away_score: 0             |
-                                                             |FT_result: "H"               |
-+---------------+                                            |date: "2014-03-22"           |
-|m: Team        |                                            |league: "ENG-Premier League" |
-|               |-[:Played {side: "away", outcome: "lost"}]->|season: 2013                 |
-|name: "Arsenal"|                                            |referee: "Andre Marriner"    |
-+---------------+                                            +-----------------------------+
-```
-
-#### Example Queries
-
-We have prepared a database snapshot for this example, so you can easily import
-it when starting Memgraph using the `--durability-directory` option.
-
-```bash
-/usr/lib/memgraph/memgraph --durability-directory /usr/share/memgraph/examples/football \
-  --durability-enabled=false --snapshot-on-exit=false
-```
-
-When using Docker, you can import the example with the following command:
-
-```bash
-docker run -p 7687:7687 \
-  -v mg_lib:/var/lib/memgraph -v mg_log:/var/log/memgraph -v mg_etc:/etc/memgraph \
-  memgraph --durability-directory /usr/share/memgraph/examples/football \
-  --durability-enabled=false --snapshot-on-exit=false
-```
-
-Now you're ready to try out some of the following queries.
-
-NOTE: If you modify the dataset, the changes will stay only during this run of
-Memgraph.
-
-1) You might wonder, what leagues are supported?
-
-```opencypher
-MATCH (n:Game)
-RETURN DISTINCT n.league AS League
-ORDER BY League;
-```
-
-2) We have stored a certain number of seasons for each league. What is the
-oldest/newest season we have included?
-
-```opencypher
-MATCH (n:Game)
-RETURN DISTINCT n.league AS League, MIN(n.season) AS Oldest, MAX(n.season) AS Newest
-ORDER BY League;
-```
-
-3) You have already seen one game between Chelsea and Arsenal, let's list all of
-them in chronological order.
-
-```opencypher
-MATCH (n:Team {name: "Chelsea"})-[e:Played]->(w:Game)<-[f:Played]-(m:Team {name: "Arsenal"})
-RETURN w.date AS Date, e.side AS Chelsea, f.side AS Arsenal,
-       w.FT_home_score AS home_score, w.FT_away_score AS away_score
-ORDER BY Date;
-```
-
-4) How about filtering games in which Chelsea won?
-
-```opencypher
-MATCH (n:Team {name: "Chelsea"})-[e:Played {outcome: "won"}]->
-      (w:Game)<-[f:Played]-(m:Team {name: "Arsenal"})
-RETURN w.date AS Date, e.side AS Chelsea, f.side AS Arsenal,
-       w.FT_home_score AS home_score, w.FT_away_score AS away_score
-ORDER BY Date;
-```
-
-5) Home field advantage is a thing in football. Let's list the number of home
-defeats for each Premier League team in the 2016/2017 season.
-
-```opencypher
-MATCH (n:Team)-[:Played {side: "home", outcome: "lost"}]->
-      (w:Game {league: "ENG-Premier League", season: 2016})
-RETURN n.name AS Team, count(w) AS home_defeats
-ORDER BY home_defeats, Team;
-```
-
-6) At the end of the season the team with the most points wins the league. For
-each victory, a team is awarded 3 points and for each draw it is awarded
-1 point. Let's find out how many points did reigning champions (Chelsea) have
-at the end of 2016/2017 season.
-
-```opencypher
-MATCH (n:Team {name: "Chelsea"})-[:Played {outcome: "drew"}]->(w:Game {season: 2016})
-WITH n, COUNT(w) AS draw_points
-MATCH (n)-[:Played {outcome: "won"}]->(w:Game {season: 2016})
-RETURN draw_points + 3 * COUNT(w) AS total_points;
-```
-
-7) In fact, why not retrieve the whole table?
-
-```opencypher
-MATCH (n)-[:Played {outcome: "drew"}]->(w:Game {league: "ENG-Premier League", season: 2016})
-WITH n, COUNT(w) AS draw_points
-MATCH (n)-[:Played {outcome: "won"}]->(w:Game {league: "ENG-Premier League", season: 2016})
-RETURN n.name AS Team, draw_points + 3 * COUNT(w) AS total_points
-ORDER BY total_points DESC;
-```
-
-8) People have always debated which of the major leagues is the most exciting.
-One basic metric is the average number of goals per game. Let's see the results
-at the end of the 2016/2017 season. WARNING: This might shock you.
-
-```opencypher
-MATCH (w:Game {season: 2016})
-RETURN w.league, AVG(w.FT_home_score) + AVG(w.FT_away_score) AS avg_goals_per_game
-ORDER BY avg_goals_per_game DESC;
-```
-
-9) Another metric might be the number of comebacks&mdash;games where one side
-was winning at half time but were overthrown by the other side by the end
-of the match. Let's count such occurrences during all supported seasons across
-all supported leagues.
-
-```opencypher
-MATCH (g:Game) WHERE
-(g.HT_result = "H" AND g.FT_result = "A") OR
-(g.HT_result = "A" AND g.FT_result = "H")
-RETURN g.league AS League, count(g) AS Comebacks
-ORDER BY Comebacks DESC;
-```
-
-10) Exciting leagues also tend to be very unpredictable. On that note, let's list
-all triplets of teams where, during the course of one season, team A won against
-team B, team B won against team C and team C won against team A.
-
-```opencypher
-MATCH (a)-[:Played {outcome: "won"}]->(p:Game {league: "ENG-Premier League", season: 2016})<--
-      (b)-[:Played {outcome: "won"}]->(q:Game {league: "ENG-Premier League", season: 2016})<--
-      (c)-[:Played {outcome: "won"}]->(r:Game {league: "ENG-Premier League", season: 2016})<--(a)
-WHERE p.date < q.date AND q.date < r.date
-RETURN a.name AS Team1, b.name AS Team2, c.name AS Team3;
-```
-
-### European road network example
-
-In this section we will show how to use some of Memgraph's built-in graph
-algorithms. More specifically, we will show how to use breadth-first search
-graph traversal algorithm, and Dijkstra's algorithm for finding weighted
-shortest paths between nodes in the graph.
-
-#### Data model
-
-One of the most common applications of graph traversal algorithms is driving
-route computation, so we will use European road network graph as an example.
-The graph consists of 999 major European cities from 39 countries in total.
-Each city is connected to the country it belongs to via an edge of type `:In_`.
-There are edges of type `:Road` connecting cities less than 500 kilometers
-apart. Distance between cities is specified in the `length` property of the
-edge.
-
-
-#### Example queries
-
-We have prepared a database snapshot for this example, so you can easily import
-it when starting Memgraph using the `--durability-directory` option.
-
-```bash
-/usr/lib/memgraph/memgraph --durability-directory /usr/share/memgraph/examples/Europe \
-  --durability-enabled=false --snapshot-on-exit=false
-```
-
-When using Docker, you can import the example with the following command:
-
-```bash
-docker run -p 7687:7687 \
-  -v mg_lib:/var/lib/memgraph -v mg_log:/var/log/memgraph -v mg_etc:/etc/memgraph \
-  memgraph --durability-directory /usr/share/memgraph/examples/Europe \
-  --durability-enabled=false --snapshot-on-exit=false
-```
-
-Now you're ready to try out some of the following queries.
-
-NOTE: If you modify the dataset, the changes will stay only during this run of
-Memgraph.
-
-Let's start off with a few simple queries.
-
-1) Let's list all of the countries in our road network.
-
-```opencypher
-MATCH (c:Country) RETURN c.name ORDER BY c.name;
-```
-
-2) Which Croatian cities are in our road network?
-
-```opencypher
-MATCH (c:City)-[:In_]->(:Country {name: "Croatia"})
-RETURN c.name ORDER BY c.name;
-```
-
-3) Which cities in our road network are less than 200 km away from Zagreb?
-
-```opencypher
-MATCH (:City {name: "Zagreb"})-[r:Road]->(c:City)
-WHERE r.length < 200
-RETURN c.name ORDER BY c.name;
-```
-
-Now let's try some queries using Memgraph's graph traversal capabilities.
-
-4) Say you want to drive from Zagreb to Paris. You might wonder, what is the
-least number of cities you have to visit if you don't want to drive more than
-500 kilometers between stops. Since the edges in our road network don't connect
-cities that are more than 500 km apart, this is a great use case for the
-breadth-first search (BFS) algorithm.
-
-```opencypher
-MATCH p = (:City {name: "Zagreb"})
-          -[:Road * bfs]->
-          (:City {name: "Paris"})
-RETURN nodes(p);
-```
-
-5) What if we want to bike to Paris instead of driving? It is unreasonable (and
-dangerous!) to bike 500 km per day. Let's limit ourselves to biking no more
-than 200 km in one go.
-
-```opencypher
-MATCH p = (:City {name: "Zagreb"})
-          -[:Road * bfs (e, v | e.length <= 200)]->
-          (:City {name: "Paris"})
-RETURN nodes(p);
-```
-
-"What is this special syntax?", you might wonder.
-
-`(e, v | e.length <= 200)` is called a *filter lambda*. It's a function that
-takes an edge symbol `e` and a vertex symbol `v` and decides whether this edge
-and vertex pair should be considered valid in breadth-first expansion by
-returning true or false (or nil). In the above example, lambda is returning
-true if edge length is not greater than 200, because we don't want to bike more
-than 200 km in one go.
-
-6) Let's say we also don't want to visit Vienna on our way to Paris, because we
-have a lot of friends there and visiting all of them would take up a lot of our
-time. We just have to update our filter lambda.
-
-```opencypher
-MATCH p = (:City {name: "Zagreb"})
-          -[:Road * bfs (e, v | e.length <= 200 AND v.name != "Vienna")]->
-          (:City {name: "Paris"})
-RETURN nodes(p);
-```
-
-As you can see, without the additional restriction we could visit 11 cities. If
-we want to avoid Vienna, we must visit at least 12 cities.
-
-7) Instead of counting the cities visited, we might want to find the shortest
-paths in terms of distance travelled. This is a textbook application of
-Dijkstra's algorithm. The following query will return the list of cities on the
-shortest path from Zagreb to Paris along with the total length of the path.
-
-```opencypher
-MATCH p = (:City {name: "Zagreb"})
-          -[:Road * wShortest (e, v | e.length) total_weight]->
-          (:City {name: "Paris"})
-RETURN nodes(p) as cities, total_weight;
-```
-
-As you can see, the syntax is quite similar to breadth-first search syntax.
-Instead of a filter lambda, we need to provide a *weight lambda* and the *total
-weight symbol*. Given an edge and vertex pair, weight lambda must return the
-cost of expanding to the given vertex using the given edge. The path returned
-will have the smallest possible sum of costs and it will be stored in the total
-weight symbol. A limitation of Dijkstra's algorithm is that the cost must be
-non-negative.
-
-8) We can also combine weight and filter lambdas in the shortest-path query.
-Let's say we're interested in the shortest path that doesn't require travelling
-more that 200 km in one go for our bike route.
-
-```opencypher
-MATCH p = (:City {name: "Zagreb"})
-      -[:Road * wShortest (e, v | e.length) total_weight (e, v | e.length <= 200)]->
-      (:City {name: "Paris"})
-RETURN nodes(p) as cities, total_weight;
-```
-
-9) Let's try and find 10 cities that are furthest away from Zagreb.
-
-```opencypher
-MATCH (:City {name: "Zagreb"})
-      -[:Road * wShortest (e, v | e.length) total_weight]->
-      (c:City)
-RETURN c, total_weight
-ORDER BY total_weight DESC LIMIT 10;
-```
-
-It is not surprising to see that they are all in Siberia.
-
-
-To learn more about these algorithms, we suggest you check out their Wikipedia
-pages:
-* [Breadth-first search](https://en.wikipedia.org/wiki/Breadth-first_search)
-* [Dijkstra's algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm)
-
-
-Now you're ready to explore the world of graph databases with Memgraph
-by yourself and try it on many more examples and datasets.
-
-### Graph Gists Examples
-
-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:
-
-```opencypher
-MATCH (n) DETACH DELETE n;
-```