Neo4j Knowledge Base

This repository is a knowledge base for Neo4j.

It contains public articles that cover questions, problems, and issues with Neo4j.

All articles will be published for everyone to see under https://neo4j.com/developer/kb/. The articles will also be available on the Zendesk knowledge base: https://support.neo4j.com/hc/en-us/sections/200574983-Knowledge-Base.

Intent / Workflow

If you answer questions on Neo4j in support, on Stack Overflow, Google Group, Slack or Twitter, please make sure to rather link to an up-to-date article originated in the Knowledge Base than writing an answer from scratch.

This will also prevent out of date content accumulate in other places where it might get a high Google Rank without us having any means to update or clarify it.

If there is no up to date article for a topic of general interest, please create one, if there is an article but it is outdated, please update the article and also update the neo4j-versions attribute.

The goal is to start this as a GitHub repository but going forward to render it as part of the documentation / developer pages.

Also all code that will be included should be tested by a build process / being pulled out of test cases.

Structure

Each article is written in AsciiDoc.

You can start by copying the template article.

Feel free to add / edit articles directly on GitHub, but make sure to send a Pull Request so the updates are reviewed before being made public.

You can use prose, headlines, sections, images, source-code blocks, links to GH repositories and other resources.

ℹ️	But please keep it reasonably short and to the point.

It contains some additional fields:

• :author: (optionally :twitter:)

• :neo4j-versions:, e.g. 3.5, 4.0

• :category:, e.g. drivers

• :tags:, e.g. cypher,tuning

• :environment: e.g. windows

File Names & Slugs

All articles need to have a :slug: attribute so that we can tie them to the appropriate post/article on WordPress / Zendesk.

All article file names must only contains lowercase alphanumeric characters and hyphens, e.g. how-to-run-consistency-check.adoc. If an article is added and it has spaces in its filename, the noSpaces.sh script in the /articles directory will make a space-less name for it using the slug in the article.

If a slug is changed, the URL for the article will be changed and any former links to the article will be broken.

For WordPress this isn’t a problem, but for Zendesk it means that the article will be deleted and the article ID won’t be recoverable, leaving links permanently broken.

The slug must only contains lowercase alphanumeric characters and hyphens to make it a good URL. No spaces, no uppercase, no leading/trailing/double hyphens.

❗	When a slug is invalid, no document will be deployed until the slug is fixed.

You can find out if a slug failed on the GitHub Actions build. It is suggested that you subscribe to notifications for the builds so that you can receive an email whenever a build fails and whenever it starts again.

Versions

• 3.4, 3.5, 4.0, 4.1

Optionally add minor versions / milestones as additional versions separated with comma / in the prose if relevant.

Tag Taxonomy

See ./kb-categories.txt

Code Snippets

If you use code-snippets, please make sure to mark them with the correct source, e.g. [source,cypher], [source,java].

For Cypher you can also provide a setup section or file as part of the repository.

Feel also free to use graph-gist syntax here, e.g. //setup, //graph, //graph_result, //table, so that we can chose to render the files as graphgists.

For code snippets you can include tagged sections from either a runnable project in a sub-directory in any programming-language or another github-repository.

ℹ️	Make sure to update those code examples alongside with the article.

Code Snippets Example

[source,java]
----
include::sources/java/src/test/java/example/CreateData.java[tags=create_data]
----

package example;

import org.neo4j.*;

public class CreateDataTest {
  @Test public void createData() {
    //tag::create_data[]
    try (Transaction tx = db.beginTx()) {
      Node n = tx.createNode(Labels.Person);
      n.setProperty("name","Emil");
      Node m = tx.createNode(Labels.Person);
      m.setProperty("name","Peter");
      n.createRelationshipTo(m,Types.KNOWS);
      // calling success is important to mark the transaction successful
      tx.commit();
    }
    //end::create_data[]
  }
}

Will result in:

try (Transaction tx = db.beginTx()) {
   Node n = tx.createNode(Labels.Person);
   n.setProperty("name","Emil");
   Node m = tx.createNode(Labels.Person);
   m.setProperty("name","Peter");
   n.createRelationshipTo(m,Types.KNOWS);
   // calling success is important to mark the transaction successful
   tx.commit();
}

Gradle Tasks

Show taxonomies

Show all the taxonomies defined on all the articles:

$ ./gradlew showTaxonomies

ℹ️	This task can be useful to review all the taxonomies.

Synchronize taxonomies

Taxonomies are not automatically created but you can synchronize them (ie. create all missing values):

$ ./gradlew syncTaxonomy

Alternatively, it’s possible to synchronize taxonomies individually:

$ ./gradlew syncEnvironmentTaxonomy
$ ./gradlew syncDeveloperCategoryTaxonomy
$ ./gradlew syncDeveloperTagTaxonomy
$ ./gradlew syncNeo4jVersionTaxonomy

Convert articles to HTML

Before publishing you can convert the articles to HTML:

$ ./gradlew convertZenDeskHtml
$ ./gradlew convertWordPressHtml

The HTML pages will be generated respectively in build/zendesk/html and build/wordpress/html.

Publish WordPress

Properties

You can define the properties using -P in the Gradle command line.

wordpress-username

Username to authenticate on the WordPress REST API

wordpress-password

Password to authenticate on the WordPress REST API

wordpress-host

Host of the WordPress instance (for instance: neo4j.com)

stage

Either testing or production. When publishing in "testing", the slug will be automatically prefixed by _testing_ and the pages will be private.

Examples

Publish in "testing"

$ /gradlew wordPressUpload -Pwordpress-username="user" -Pwordpress-host="neo4j.com" -Pwordpress-password="password" -Pstage=testing

Publish in "production"

$ /gradlew wordPressUpload -Pwordpress-username="user" -Pwordpress-host="neo4j.com" -Pwordpress-password="password" -Pstage=production

Publish Zendesk

Properties

You can define the properties using -P in the Gradle command line.

zendesk-email

Email of an Agent account on Zendesk

zendesk-apitoken

API token generated from the Admin page on Zendesk

zendesk-host

Host of the Zendesk instance (for instance: support.neo4j.com)

Examples

Publish

$ ./gradlew zenDeskUpload -Pzendesk-email="[email protected]" -Pzendesk-host="support.neo4j.com" -Pzendesk-apitoken="apitoken"