Neo4j Source Connector

Type

Source

Class

org.neo4j.connectors.kafka.source.Neo4jConnector

Target System

Graph Database (Neo4j / Aura)

Maintainer

Neo4j

License

Apache License 2.0

Project

GitHub repository

Download

GitHub Releases

This page documents version 5.3.0. Newer versions should be compatible unless there are breaking changes, but field names or default values may differ. If you notice discrepancies, please contact Axual Support.

Description

The Neo4j Source Connector reads data from a Neo4j or Aura database using Cypher queries and publishes the results as records to Kafka topics.

These connectors are developed and maintained by Neo4j as part of the Neo4j Kafka Connector.

Features

  • Stream query results from Neo4j/Aura to Kafka topics using Cypher queries

  • Configurable streaming start position

  • Supports both Neo4j self-managed and Aura cloud databases

  • Works with standard Kafka Connect converters

When to Use

  • You need to stream Neo4j graph data into Kafka topics.

  • You want to replicate graph query results into downstream systems via Kafka.

When NOT to Use

  • You need to write data into Neo4j — use the Neo4j Sink Connector instead.

  • You have not yet configured a Neo4j or Aura database instance.

Installation

The connector is available from the GitHub Releases.

  1. Navigate to the releases page and select the version matching your Kafka Connect installation.

  2. Download the JAR file.

For installation steps, see Installing Connector Plugins.

Configuration

For the complete configuration reference, see the official source connector documentation.

To configure a connector in Axual Self-Service, see Starting Connectors. TIP: For Infrastructure-as-Code deployment, see the Axual Kafka Connect Boilerplates for Terraform and Management API boilerplates.

Getting Started

Prerequisites

Neo4j or Aura database

You need a running Neo4j or Aura database reachable from the Kafka Connect cluster. Consult the official connector documentation for environment setup instructions.

Axual stream

The stream where the connector will produce events must already exist in Axual Self-Service. See Creating streams if you need to create it.

Steps

Step 1 — Create a connector application

  1. Follow the Configure and install a connector documentation to set up a new Connector-Application.
    Let’s call it my_neo4j_source.
    The plugin name is org.neo4j.connectors.kafka.source.Neo4jConnector.
    If a plugin isn’t available, ask a platform operator to install plugins.

Step 2 — Configure the connector

  1. Provide the following minimal configuration:

    neo4j.uri

    neo4j://neo4j.example.com:7687

    neo4j.authentication.type

    BASIC

    neo4j.authentication.basic.username

    Your Neo4j username

    neo4j.authentication.basic.password

    Your Neo4j password

    neo4j.source-strategy

    QUERY

    neo4j.start-from

    NOW

    neo4j.query

    Cypher query to stream results from, e.g.
    MATCH (n:Person) WHERE n.timestamp > $lastCheck RETURN n.name AS name, n.timestamp AS timestamp

    neo4j.query.streaming-property

    timestamp

    neo4j.query.topic

    my_neo4j_topic

    neo4j.query.polling-interval

    10s

    key.converter

    org.apache.kafka.connect.storage.StringConverter

    value.converter

    org.apache.kafka.connect.json.JsonConverter

    value.converter.schemas.enable

    false

    For advanced options, see the official source connector documentation.

  2. Authorize the my_neo4j_source source Connector-Application to produce to the my_neo4j_topic stream.

Step 3 — Start the connector

Start the connector application from Axual Self-Service.

Step 4 — Verify

In Axual Self-Service, use stream-browse on your target stream to confirm events are arriving.

Cleanup

When you are done:

  1. Stop the connector application in Axual Self-Service.

  2. Remove stream access for the application if no longer needed.

Known limitations

  • A configured Neo4j or Aura database is required before starting this connector. No setup guidance is provided in this document — refer to the official connector documentation.

Examples

Minimal configuration

{
  "name": "my-neo4j-source",
  "config": {
    "connector.class": "org.neo4j.connectors.kafka.source.Neo4jConnector",
    "neo4j.uri": "neo4j://neo4j.example.com:7687",
    "neo4j.authentication.type": "BASIC",
    "neo4j.authentication.basic.username": "neo4j",
    "neo4j.authentication.basic.password": "<your-password>",
    "neo4j.source-strategy": "QUERY",
    "neo4j.start-from": "NOW",
    "neo4j.query": "MATCH (n:Person) WHERE n.timestamp > $lastCheck RETURN n.name AS name, n.timestamp AS timestamp",
    "neo4j.query.streaming-property": "timestamp",
    "neo4j.query.topic": "my-neo4j-topic",
    "neo4j.query.polling-interval": "10s",
    "key.converter": "org.apache.kafka.connect.storage.StringConverter",
    "value.converter": "org.apache.kafka.connect.json.JsonConverter",
    "value.converter.schemas.enable": "false"
  }
}

License

Neo4j source/sink connector is licensed under the Apache License, Version 2.0.