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.

Parameters

Optional[Union[str, List[str]]]

default:"'main_dataset'"

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

Optional[User]

default:"None"

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

Only one graph is checked per call: dataset is resolved to the datasets 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.

If none of the given names resolves to a dataset you can read, no dataset context is entered. With backend access control enabled (ENABLE_BACKEND_ACCESS_CONTROL=True, the default) that raises — a dataset is required to resolve the per-dataset databases. With access control disabled, the call falls back to the single shared graph and vector stores instead, so a typo in a dataset name yields a report about the default stores rather than an error. Check summary["graph_nodes"] before reading a healthy status as proof that a specific dataset is intact.

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 (the first authorized one is 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.

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": ...}.

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."
    }
  ]
}

Reference

validate()

cognee.validate()

Description

Parameters

Returns

What is checked

Cost and when to run

Examples

Over HTTP

See also

​cognee.validate()

​Description

​Parameters

​Returns

​What is checked

​Cost and when to run

​Examples

​Over HTTP

​See also

cognee.validate()

Description

Parameters

Returns

What is checked

Cost and when to run

Examples

Over HTTP

See also