neo4j

package module
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 10, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package neo4j exposes the official neo4j-go-driver v5 through the Core vector-store capability interfaces. Documents become nodes labeled `:Document` (or whatever StoreConfig.Label picks) — metadata keys are stored as flat properties named `metadata.<key>`, the embedding rides on the configured property, and the id has a uniqueness constraint. Documents containing media are rejected before indexing I/O because this adapter persists document text and metadata only.

Requirements: Neo4j 5.13+ for `CREATE VECTOR INDEX` and the `db.index.vector.queryNodes` procedure. Earlier 5.x releases ship the procedure under a different signature; the store hard-codes the 5.13+ shape.

Similarity functions: SimilarityCosine / SimilarityEuclidean. Both are mapped to a [0, 1] similarity score by Neo4j itself.

Indexing — the store creates two things under StoreConfig.InitializeSchema = true:

  • a uniqueness constraint on the id property
  • a `VECTOR INDEX` carrying dimensions + similarity function

Search calls `CALL db.index.vector.queryNodes($index, $k, $vec) YIELD node, score WHERE score >= $threshold AND <filter>`. The filter visitor produces a Cypher predicate plus a `$pN`-keyed parameter map (Cypher uses named parameters).

TopK is a candidate budget, not a result count. The procedure takes no predicate, so it returns the k nearest nodes first and the metadata filter then removes some of them: a selective filter yields fewer than TopK results, possibly none, however many matching nodes the graph holds. Raise TopK to widen the pool a filter draws from.

LIKE maps onto Cypher's `=~` (regex). Note that NOT in Cypher must precede an expression — the visitor emits `NOT (<expr>)`.

See https://neo4j.com/docs/cypher-manual/current/indexes-for-vector-search/ for index syntax and the vector-search reference. Metadata numbers use signed 64-bit integers where exact, otherwise doubles whose decimal JSON value round-trips without loss. Unrepresentable numbers are rejected at the payload boundary.

Index

Constants

View Source
const (
	DefaultLabel             = "Document"
	DefaultIndexName         = "scope-vector-index"
	DefaultEmbeddingProperty = "embedding"
	DefaultIDProperty        = "id"
	DefaultTextProperty      = "text"
	DefaultMetadataPrefix    = "metadata"
)

Exported defaults keep constructor behavior visible and overridable.

View Source
const Provider = "Neo4j"

Provider is the stable backend name for host-side attribution.

Variables

This section is empty.

Functions

This section is empty.

Types

type SimilarityFunction

type SimilarityFunction string

SimilarityFunction selects the function written into the vector index definition. The chosen value is recorded at index creation time and cannot be changed without rebuilding the index.

const (
	// SimilarityCosine — cosine similarity. Default.
	SimilarityCosine SimilarityFunction = "cosine"

	// SimilarityEuclidean — Euclidean distance, mapped to a [0, 1]
	// similarity score by Neo4j itself.
	SimilarityEuclidean SimilarityFunction = "euclidean"
)

func (SimilarityFunction) String

func (s SimilarityFunction) String() string

func (SimilarityFunction) Valid

func (s SimilarityFunction) Valid() bool

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store implements vector-store capabilities with Neo4j. Each document maps to a node with the configured label and flattened metadata properties.

func NewStore

func NewStore(ctx context.Context, config StoreConfig) (*Store, error)

NewStore performs schema setup during construction, which is why it takes a context: a store returned before its graph schema and index exist would fail on the first index rather than at wiring, where the misconfiguration actually is.

func (*Store) DeleteIDs

func (s *Store) DeleteIDs(ctx context.Context, ids []string) (err error)

DeleteIDs removes nodes by document id — `MATCH ... WHERE n.<id> IN $ids DETACH DELETE n`. An empty slice is a no-op; unknown ids are silently ignored (idempotent). Implements vectorstore.IDDeleter.

func (*Store) DeleteWhere

func (s *Store) DeleteWhere(ctx context.Context, expr filter.Predicate) (err error)

func (*Store) Index

func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)

Index embeds documents and upserts them as nodes.

func (*Store) Search

func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)

Search calls db.index.vector.queryNodes and returns matching documents above MinScore.

type StoreConfig

type StoreConfig struct {
	// Driver is the Neo4j context-aware driver instance. Required.
	Driver neo4j.DriverWithContext

	// Database is the Neo4j database name. Optional: defaults to the
	// driver's default database (typically "neo4j").
	Database string

	// Label is the node label used for documents. Optional: defaults
	// to [DefaultLabel].
	Label string

	// IndexName is the vector index name. Optional: defaults to
	// [DefaultIndexName].
	IndexName string

	// EmbeddingProperty is the node property that stores the vector.
	// Optional: defaults to [DefaultEmbeddingProperty].
	EmbeddingProperty string

	// IDProperty is the node property that stores the document id.
	// Optional: defaults to [DefaultIDProperty].
	IDProperty string

	// TextProperty is the node property that stores the document
	// text. Optional: defaults to [DefaultTextProperty].
	TextProperty string

	// MetadataPrefix is the property-name prefix used for metadata
	// keys (so "metadata.author" instead of "author"). Optional:
	// defaults to [DefaultMetadataPrefix]. The prefix is always present so
	// metadata keys cannot collide with storage properties.
	MetadataPrefix string

	// EmbeddingModel produces vectors for the documents. Required.
	EmbeddingModel embedding.Model

	// DocumentBatcher batches documents before upsert. Required.
	DocumentBatcher vectorstore.Batcher

	// Dimensions sets the vector width recorded in a new index definition, and
	// is required when InitializeSchema is true: the width is part of the index
	// definition, and nothing here can read it off an index that does not exist
	// yet.
	Dimensions int

	// Similarity selects the vector similarity function. Optional:
	// defaults to [SimilarityCosine].
	Similarity SimilarityFunction

	// InitializeSchema, when true, creates the unique-id constraint
	// and the vector index if they don't already exist.
	InitializeSchema bool
}

StoreConfig contains configuration options for the Neo4j vector store.

func (StoreConfig) Validate

func (s StoreConfig) Validate() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL