Neo4j

Neo4j stores documents in your Neo4j database and searches them by meaning, like any other vector database. It can also search directly in the nodes your graph already has, for example in the descriptions of your incidents or products.

A vector database stores texts so they can be searched by meaning, not only by exact words. That way, an agent can find the paragraph of a manual that answers a question even when it is written with other words.

If you also want to follow the graph’s relationships, combine meaning and keywords or have the model write the query, use Neo4j GraphRAG.

When to use it

• You already use Neo4j and want your documents in the same database as the rest of your data.
• You want to search by meaning in the text of nodes that already exist in your graph, without copying them to another database.
• You want to prepare documents you will later query with Neo4j GraphRAG.

Configuration

The Operation field decides what the component does, and the fields and outputs change with your choice:

• Add (default): stores in the database the documents it receives in Ingest Data. If the index does not exist, it creates it.
• Search: finds the documents closest to the text in Search Query.
• Retriever: offers the database as a retriever for another component to use, for example an agent or a question-answering chain.

You need a Neo4j API credential with the address, user and password of your database. See Credentials.

Field	What it does
Credential (required)	The Neo4j API credential. It fills in Neo4j URL, Neo4j Username and Neo4j Password.
Operation	What the component does: Add, Search or Retriever.
Ingest Data (required)	With Add. The documents to store, usually those coming from a text splitter.
Search Query	With Search. The text to search for. If you leave it empty, nothing is returned.
Embedding	The connector where you plug the component that turns texts into numbers to compare them by meaning, such as FastEmbed Embeddings (Local). Always use the same one to store and to search.
Node Label	With Search and Retriever, to search nodes you already have: the label of those nodes, for example Incident.
Text Node Properties	Together with Node Label: the properties holding the text to search, separated by commas, for example title, description.
Embedding Node Property	Together with Node Label: the property where each node’s vector is stored. Empty, embedding is used. Nodes that don’t have one yet get it the first time.

Advanced options

Field	What it does
Index Name	The name of the vector index in Neo4j. Default: nappai_neo4j_index. Use the same one to store and to search.
Number of Results	How many documents each search returns. Default: 4.
Filter by Metadata	Searches only among the documents whose data meet some conditions, for example brand equal to Vellani. Works with Search, Retriever and in tool mode. See Filter by metadata.

Filter by metadata

Besides its text, each document keeps some data (its metadata): the brand, the document type, the month… The filter makes the search look only at the documents whose data meet some conditions. It applies the same way to Results, to Retriever and when an agent uses the component as a tool.

Turn on Filter by Metadata (in the advanced options) and choose Filter Mode:

• Manual: you write the conditions on the node. In Number of Conditions you choose how many rows you want, and each row has:

  • Field: the data to check, for example brand.
  • Operator: Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan, LessThanEqual, In (one of a comma-separated list, such as Q90, S80), NotIn (none of the list) and Contains (the text or the list contains the value).
  • Type: Text, Int (whole number), Number (with decimals) or Boolean (true or false).
  • Value: the value to compare with. Left empty, that row does not filter.

  Combine Conditions decides whether all of them must match (AND) or one is enough (OR).

• Dynamic: the conditions arrive as JSON in Metadata Filter (JSON), from another component or written by an agent:

  • {"brand": "Vellani"}: exact value.
  • {"model": ["Q90", "S80"]}: any of the list.
  • {"year": {">=": 2024}, "status": {"!=": "archived"}}: with the operators =, !=, >, >=, <, <=, in, not in and contains.

  With several fields, all of them must match. Empty, it does not filter. A badly written JSON gives an error instead of searching without the filter.

Let the agent fill it in. With the component in tool mode, turn on tool mode for Value (with Field and Operator fixed, for example model and Equal) or for Metadata Filter (JSON). The agent writes the value when the question asks for it (“only the Q90 machine”) and leaves it empty when not. Tell it in the tool description which fields and values exist.

Lists. When a piece of data is a list, like the tags Metadata Tagger writes, Equal and In match when one of its items does, and Contains looks inside them.

In Neo4j the filter needs Neo4j 5.18 or later. Contains ignores upper/lower case, and no operator looks inside a list: to filter by lists, use FAISS, Qdrant, PGVector or Elasticsearch.

Example: only one brand’s manuals

1. When storing, each chunk carries its data, for example type: manual and brand: Vellani (set by the file loader or by Metadata Tagger).
2. On the node with Operation set to Search, turn on Filter by Metadata, leave Filter Mode on Manual and fill in the row: Field brand, Operator Equal, Type Text, Value Vellani.
3. Search for “what does error E07 mean”: only chunks from Vellani documents come back.

The same filter in Dynamic mode is {"brand": "Vellani"}. Nodes saved earlier keep their filters; the new field names appear when you update the node.

Output

The outputs depend on Operation:

• Results: with Add and Search. With Search, the list of documents found, which you can pass to a prompt or an agent.
• Vector Store: with Add. The database, to connect to components that work with a vector database.
• Retriever: with Retriever. The retriever, to connect to components that ask for one.

In tool mode, an agent can use the component to search on its own. See Tool Mode.

Example

A repair service already has its incidents in Neo4j, each with a description of the fault, and wants to find faults similar to the one a customer reports.

1. Add Neo4j with Operation set to Search and choose your Neo4j API credential.
2. Type Incident in Node Label and description in Text Node Properties.
3. Connect FastEmbed Embeddings (Local) to Embedding and run the flow once: the incidents get their vector.
4. Type “the coffee machine leaks water from underneath” in Search Query and check Results.

Good practices

• Always store and search with the same embeddings component: if you change model, store the documents again in a new index.
• For questions that count, compare or cross relationships (“which customer has the most incidents?”), use Neo4j GraphRAG in Text2Cypher mode.

Related components

• Neo4j GraphRAG: questions to a Neo4j graph, following its relationships or writing the query.
• FastEmbed Embeddings (Local): turns texts into something searchable by meaning, without leaving NappAI.

See also

• Vector databases: how FAISS, Chroma, Qdrant, PGVector and Neo4j differ, and which one to choose.