validate()

Cross-check a dataset’s graph and vector stores for integrity problems

cognee.validate()

async def validate(
    dataset: Optional[Union[str, List[str]]] = "main_dataset",
    user: Optional[User] = None,
) -> ValidationReport

Description

Cross-check the graph and vector stores of a dataset and report where they disagree. validate() answers three questions no other call answers: does every edge still point at nodes that exist, does every deduplicated node still carry the id its own dedup contract derives, and is every embeddable node actually present in its vector collection.

The check is read-only — it never writes to any store, so it is safe to run against a production dataset. It is also backend-agnostic: it is driven entirely through GraphDBInterface.get_graph_data() and VectorDBInterface.retrieve(), so it works unmodified against every supported graph and vector backend without adapter-specific code.

Run it after cognify(), after a large import, or after a migration — the moments when the graph and the vector index can drift apart.

Only one graph is checked per call: every name in dataset must resolve to a dataset you have read permission on, and the first of those determines which graph and vector store are read. Passing several dataset names does not merge them into a combined report — call validate() once per dataset instead.

A partially authorized list is rejected as a whole — dataset=["mine", "not-mine"] raises rather than silently validating mine alone — and the default dataset="main_dataset" raises too when that dataset does not exist for you yet. This does not depend on ENABLE_BACKEND_ACCESS_CONTROL: the rejection is the same with access control on or off. Note that names resolve only within datasets you own, so a dataset merely shared with you is rejected when requested by name.

Passing dataset=None (or an empty list) still skips dataset resolution entirely — the only path that enters no dataset context. With backend access control disabled that reads the unscoped shared stores; with it enabled the call fails, since a dataset is required to resolve the per-dataset databases.

validate() fails closed on a dataset it cannot read. If any of the given names does not resolve to a dataset you have read permission on, the call raises DatasetNotFoundError — message "Dataset not found or not readable.", importable from cognee.modules.data.exceptions — before any graph or vector adapter is opened. There is no fallback to the default or shared stores, so a report that comes back is always a report about the dataset you asked for.

Parameters

dataset · Optional[Union[str, List[str]]] · default: "'main_dataset'"

Dataset name(s) to validate. A single string is treated as a one-element list.

user · Optional[User] · default: "None"

User context for dataset access. Falls back to the default user.

Returns

ValidationReport — a Pydantic model with three fields:

Field	Type	Contents
status	ValidationStatus	"healthy", "degraded", or "unhealthy".
summary	Dict[str, Any]	graph_nodes (int), graph_edges (int), and node_type_distribution — a {node type: count} map over the whole graph, where typeless nodes are counted under "unknown".
issues	List[ValidationIssue]	Every issue found, each with severity ("error" / "warning"), type, and a human-readable detail naming the node or edge.

status is derived from the severities present, not from issue counts:

• any error-severity issue → unhealthy
• otherwise, any warning-severity issue → degraded
• no issues at all → healthy

validate, ValidationReport, ValidationIssue, and ValidationStatus are importable from the cognee top level; the IssueSeverity and IssueType enums are available from cognee.api.v1.validate. All three enums (ValidationStatus, IssueSeverity, IssueType) subclass str, so comparing against plain strings (report.status == "healthy") works without importing them — but printing a member shows the enum repr (ValidationStatus.HEALTHY), so use .value when you want the plain string.

What is checked

orphaned_edge — error

An edge whose source or target id is not in the graph’s node set. Traversal that reaches such an edge hits a dead end, so graph-based search silently loses the connection.

The detail names the edge as source -[relationship]-> target along with the id(s) that are missing. Typically the result of nodes being removed without their edges; re-running cognify() for the affected dataset, or deleting and re-ingesting the source data, rebuilds a consistent edge set.

identity_id_mismatch — warning

A node of a type that declares identity_fields — Entity and EntityType, both keyed on name — whose id does not equal the id its own class derives from its properties via Type.id_for(...).

Cognee’s dedup contract is that two nodes with the same identity value are the same node because they hash to the same id. A node that reached the graph without going through that contract (a raw write from an importer or a migration, or a node written by an older Cognee version) can carry a stale or arbitrary id — which means a second, correctly-derived node for the same entity can coexist as an undetected duplicate. Hence a warning rather than an error: nothing is broken yet, but deduplication is no longer guaranteed for that node.

The check is skipped for a node whose identity field is absent from its graph properties — the id cannot be recomputed, and the node may simply predate the field. To bring mismatched nodes onto the current scheme, re-cognify the affected datasets from scratch so their ids are derived by the models.

missing_vector_entry — error

A node of a type that declares index_fields — Entity (collection Entity_name) and DocumentChunk (collection DocumentChunk_text) — with no matching point in its {type}_{index_field} vector collection.

The node exists in the graph but is unreachable by every embedding-based search type, silently: semantic search cannot surface it and cannot use it to seed graph traversal. Re-running cognify() for the dataset re-indexes the missing nodes. If an entire node type reports one issue per node, the collection itself is likely missing or empty rather than individual points having been lost.

The checked types are read from the real model classes’ identity_fields / index_fields metadata rather than being hardcoded, so a change to either contract is picked up here automatically.

Cost and when to run

• No LLM calls and no writes. The cost is entirely database reads.
• The graph is read in full through get_graph_data(), so time and memory scale with the total number of nodes and edges — not with a sample. There is no sampling or limit parameter.
• Vector lookups are one batched retrieve() per collection (at most two: Entity_name and DocumentChunk_text), not one call per node.
• Because it is read-only, it is safe against production stores — but on a very large dataset prefer a low-load window, and note that the number of issues is unbounded: a badly drifted graph can return one issue per affected node or edge.

Good moments to run it: after cognify() or a bulk import, after applying migrations, as a pre-flight check in CI, or on a schedule as integrity monitoring.

Examples

import cognee

await cognee.add("docs/handbook.pdf", dataset_name="onboarding")
await cognee.cognify(datasets=["onboarding"])

report = await cognee.validate(dataset="onboarding")

print(report.status.value)                # "healthy" | "degraded" | "unhealthy"
print(report.summary["graph_nodes"], report.summary["graph_edges"])
print(report.summary["node_type_distribution"])  # {"Entity": 128, "DocumentChunk": 14, ...}

for issue in report.issues:
    print(f"[{issue.severity.value}] {issue.type.value}: {issue.detail}")

Acting on the status — for example, failing a CI pre-flight check on errors while letting warnings through:

import cognee
from cognee import ValidationStatus

report = await cognee.validate(dataset="onboarding")

if report.status == ValidationStatus.UNHEALTHY:
    errors = [i for i in report.issues if i.severity == "error"]
    raise SystemExit(f"dataset integrity check failed with {len(errors)} error(s)")

if report.status == ValidationStatus.DEGRADED:
    print(f"{len(report.issues)} warning(s) — deduplication may be incomplete")

Grouping issues by type to decide what to remediate:

from collections import Counter

report = await cognee.validate(dataset="onboarding")
print(Counter(issue.type.value for issue in report.issues))
# Counter({'missing_vector_entry': 12, 'identity_id_mismatch': 3})

Over HTTP

The same check is exposed as a read-only endpoint on the API server:

GET /api/v1/validate

Aspect	Behavior
dataset query parameter	Repeatable; defaults to main_dataset. Pass ?dataset=a&dataset=b to hand several names to the same resolution rule — every one must be readable by the caller, and the first is the one read.
Authentication	Required — the endpoint resolves the calling user and applies the same read permission check as the SDK function.
200 OK	Report body, when status is healthy or degraded.
503 Service Unavailable	Report body, when status is unhealthy — that is, whenever at least one error-severity issue was found.
500 Internal Server Error	{"status": "error", "reason": "validation failed: ..."} if the check itself raised — including a dataset the caller cannot read, which arrives as "validation failed: DatasetNotFoundError: Dataset not found or not readable. (Status code: 404)". The 404 inside that string is the exception’s own string form; the HTTP status is still 500.

The 503 is the single detail to plan for when wiring this into a health probe or a CI check: an unhealthy report is returned with a 503 status code, not a 200. Clients that raise on non-2xx responses will treat a successful-but-failing validation as a transport error, and a load balancer pointed at this path will pull the instance out of rotation on a data-integrity finding. Read the response body to tell the two apart — a 503 from this endpoint still carries the full report JSON, while a 500 carries {"status": "error", "reason": ...}. The endpoint wraps every exception into that 500 — an unreadable or unknown dataset name is a server error here, never a 404 — so if you alert on rejected datasets, match the reason for Dataset not found or not readable. rather than watching for a 4xx status code.

curl -i "$COGNEE_URL/api/v1/validate?dataset=onboarding" \
  -H "Authorization: Bearer $COGNEE_TOKEN"

{
  "status": "unhealthy",
  "summary": {
    "graph_nodes": 142,
    "graph_edges": 310,
    "node_type_distribution": { "Entity": 128, "DocumentChunk": 14 }
  },
  "issues": [
    {
      "severity": "error",
      "type": "missing_vector_entry",
      "detail": "Entity node '...' has no matching point in vector collection 'Entity_name' — it exists in the graph but is unreachable by semantic search."
    }
  ]
}

See also

• report() — the other read-only diagnostic: what the graph contains, rather than whether it is consistent
• cognify() — the pipeline that writes the nodes, edges, and vector points this call cross-checks
• DataPoints — identity_fields, index_fields, and the id_for() contract the identity check verifies
• run_migrations() — apply pending schema migrations; validating afterwards confirms the stores still agree