Zep v3 icon

Zep v3

Interact with Zep Cloud v3 API
Join our community

Actions44

Overview

The "Search Graph" operation in the Zep node allows users to perform advanced searches within a knowledge graph. This operation queries entities (nodes), relationships (edges), or events (episodes) stored in the graph based on a textual search string and various filtering and reranking options.

This node is beneficial for scenarios where you want to extract relevant information from complex interconnected data, such as customer profiles, product relationships, event logs, or any domain modeled as a graph. For example, you could search a customer interaction graph for nodes related to "user preferences and shopping history" to personalize recommendations, or find edges representing relationships like "WORKS_FOR" between people and organizations.

Practical examples:

  • Searching for all nodes related to a specific topic or keyword.
  • Finding edges that represent certain types of relationships with a minimum confidence rating.
  • Retrieving episodes/events mentioning particular concepts, reranked by relevance or diversity.
  • Using breadth-first search origins or center nodes to influence reranking based on graph topology.

Properties

Name Meaning
User ID The unique identifier of the user. Optional if Graph ID is provided. Used to scope graph operations to a specific user.
Graph ID The unique identifier of the graph. Required for most operations except some search/addData/entityType cases when User ID is used instead.
Search Query The text string to search for within the graph (max 400 characters). Example: "user preferences and shopping history".
Limit Maximum number of results to return. Minimum value is 1. Default is 50.
Scope The part of the graph to search:
• Edges — relationships between entities
• Nodes — entities/nodes themselves
• Episodes — events recorded in the graph
Reranker Method to rerank search results:
• Cross Encoder — advanced neural reranking
• Episode Mentions — frequency-based reranking
• MMR — balances relevance and diversity
• Node Distance — distance-based reranking
• RRF — default combined ranking method
Minimum Fact Rating Filters edges by minimum fact rating (0.0 to 1.0). Only applies when searching edges. Default is 0.
MMR Lambda Required when using MMR reranker. Controls balance between relevance (0.0) and diversity (1.0). Default 0.5.
Center Node UUID Required when using Node Distance reranker. UUID of the center node to calculate distances from.
BFS Origin Node UUIDs Comma-separated list of node UUIDs to seed breadth-first searches from. Influences search traversal and scoring.
Search Filters JSON object to filter search results by properties such as node labels, edge types, creation/expiration dates, etc. Example: {"node_labels": ["Person"], "edge_types": ["KNOWS"]}

Output

The output is a JSON array containing the search results matching the query and filters. Each item represents an entity, edge, or episode depending on the selected scope. The structure includes details about the matched graph elements, their properties, and metadata such as relevance scores or ratings.

No binary data output is produced by this operation.

Dependencies

  • Requires an API key credential for authenticating with the Zep Cloud v3 API.
  • The node makes HTTP POST requests to the endpoint https://api.getzep.com/api/v2/graph/search.
  • Proper configuration of the API key credential in n8n is necessary.
  • Input parameters must be valid and consistent (e.g., required fields present, correct UUID formats).

Troubleshooting

  • Missing Graph ID or User ID: If neither Graph ID nor User ID is provided, the search request may fail or return no results. Ensure at least one is specified.
  • Invalid JSON in Search Filters: The searchFilters property expects valid JSON. Malformed JSON will cause errors. Validate JSON syntax before input.
  • MMR Lambda or Center Node UUID Missing: When selecting the MMR reranker, mmrLambda must be set; when using Node Distance reranker, centerNodeUuid is required. Omitting these causes errors.
  • Exceeded Character Limits: The search query has a max length of 400 characters. Longer inputs will be rejected.
  • API Authentication Errors: Ensure the API key credential is correctly configured and has permissions for graph search operations.
  • Empty Results: Could indicate no matches for the query or overly restrictive filters. Try broadening the search or adjusting filters.

Common error messages typically relate to invalid parameters, missing required fields, or authentication failures. Review the node's input parameters and credentials setup to resolve.

Links and References

Discussion