Custom Data Models

A minimal guide to creating custom data models and inserting them directly into the knowledge graph using add_data_points. Before you start:

Complete Quickstart to understand basic operations
Ensure you have LLM Providers configured
Have some structured data you want to model

What Custom Data Models Do

Define your own Pydantic models that inherit from DataPoint
Insert structured data directly into the knowledge graph without cognify
Create relationships between data points programmatically
Control exactly what gets indexed and how

Code in Action

Step 1: Define Your Data Model

class Person(DataPoint):
    name: str
    knows: SkipValidation[Any] = None
    # Recommended: specify which fields to index for search
    metadata: dict = {"index_fields": ["name"]}

Create a Pydantic model that inherits from DataPoint. Use SkipValidation[Any] for fields that will hold other DataPoints to avoid forward reference issues. Metadata is recommended - it tells Cognee which fields to embed and store in the vector database for search.

Step 2: Create Data Instances

alice = Person(name="Alice")
bob = Person(name="Bob")
charlie = Person(name="Charlie")

Instantiate your models with the data you want to store. Each instance becomes a node in the knowledge graph.

Step 3: Create Relationships

alice.knows = bob
# Optional: add weights and custom relationship types
bob.knows = (Edge(weight=0.9, relationship_type="friend_of"), charlie)

Assign DataPoint instances to fields to create edges. The field name becomes the relationship label by default. Weights are optional - you can use Edge to add weights, custom relationship types, or other metadata to your relationships.

Step 4: Insert into Graph

await add_data_points([alice, bob, charlie])

This converts your DataPoint instances into nodes and edges in the knowledge graph, automatically handling the graph structure and indexing. The name field gets embedded and stored in the vector database for search.

Custom Data Model Fields

When add_data_points walks your model, it decides field-by-field whether a value is a relationship or a plain property:

Edges — a field whose value is another DataPoint, a list[DataPoint], or an (Edge(...), DataPoint) / (Edge(...), list[DataPoint]) tuple. Each referenced DataPoint becomes its own node, and the field name (or the Edge.relationship_type) becomes the edge label.
Properties — every other value type (str, int, float, bool, dict, or a list of scalar values) is stored on the node. It is not expanded into separate nodes or edges.

Only fields listed in metadata.index_fields are embedded for vector search — pick a text field (like name) for that, since a dict is stored but not meaningfully searchable. See DataPoints for more on indexing. For complex nested values, such as a list of dictionaries, prefer serializing them yourself or modeling each nested object as its own DataPoint when you need portable graph behavior across database backends.

Edge Metadata Fields

Edge accepts the following fields, all optional:

Field	Type	Description
`weight`	`float`	A single numeric weight for the relationship.
`weights`	`dict[str, float]`	Multiple named weights (e.g. `{"strength": 0.8, "confidence": 0.9}`). Each one is also stored as a separate, queryable `weight_<name>` property on the edge.
`relationship_type`	`str`	Custom relationship label. When set, it overrides the field name as the edge’s relationship name.
`properties`	`dict[str, Any]`	Arbitrary custom metadata to attach to the edge. Use this for any fields not covered above.
`edge_text`	`str`	A rich, natural-language description of the relationship that is embedded for semantic edge/triplet retrieval. When omitted, Cognee builds fallback retrieval text from the source node, relationship name, and target node.

Use properties for custom edge metadata, such as properties={"since": 2015, "context": "college"}. Advanced users can also subclass Edge; subclass fields are included in the stored edge properties.

Custom Fields and Read-Back

Use plain scalar fields when you need to keep external identifiers, labels, statuses, or other simple properties on a node. Do not add those fields to metadata.index_fields unless you actually want Cognee to embed them as searchable text.

from cognee.infrastructure.engine import DataPoint
from cognee.infrastructure.engine.models.DataPoint import MetaData

class Note(DataPoint):
    text: str
    external_id: str
    category: str
    metadata: MetaData = {"index_fields": ["text"]}

Here, text is embedded for semantic search, while external_id and category are stored as normal node properties. When you have the DataPoint object itself, read custom fields directly:

note.external_id
note.model_dump()["category"]

When a search result returns the stored payload directly, custom fields on that payload are plain keys:

import cognee
from cognee import SearchType

results = await cognee.search(
    query_text="my query",
    query_type=SearchType.CHUNKS,
)

results[0]["external_id"]

When using recall(), normalized graph entries reserve metadata for stable provenance keys such as data_id, chunk_id, chunk_index, and document_name. Custom payload fields from the result are available on raw:

import cognee
from cognee import SearchType

entries = await cognee.recall(
    query_text="my query",
    query_type=SearchType.CHUNKS,
)

entries[0].raw["external_id"]

Use in Custom Tasks and Pipelines

This approach is particularly useful when creating custom tasks and pipelines where you need to:

Insert structured data programmatically
Define specific relationships between known entities
Control exactly what gets indexed and how
Integrate with external data sources or APIs

You can combine this with cognify to extract knowledge from unstructured text, then add your own structured data on top.

Linking DataPoints to a Dataset

When you call add_data_points standalone, nodes are inserted globally with no dataset association. Dataset-level forget() calls will not remove them. To delete those unassociated DataPoints, call prune_system() instead of forget(dataset=...). To associate DataPoints with a dataset so that forget(dataset=...) can clean them up, pass a PipelineContext as the ctx argument:

from cognee.modules.pipelines.models import PipelineContext

await add_data_points(
    [alice, bob, charlie],
    ctx=PipelineContext(
        user=user,           # authenticated user object
        dataset=dataset,     # dataset object
        data_item=data_item, # source data item for provenance
    ),
)

When ctx carries all three values, each node and edge is tagged with dataset_id and data_id in the relational database. forget(dataset=...) then finds and removes exactly those records — nodes shared across other datasets are preserved. When using Task(add_data_points) inside cognee.run_custom_pipeline(), the pipeline machinery builds and injects ctx automatically. If you write a custom task that calls add_data_points internally, declare ctx in your task signature so the pipeline forwards it:

from cognee.modules.pipelines.models import PipelineContext

async def my_custom_task(data, ctx: PipelineContext = None) -> list:
    points = build_data_points(data)
    return await add_data_points(points, ctx=ctx)  # forward ctx for dataset linking

Additional examples

Additional examples about Custom data models are available on our github.

Full Example

Latest guide

import asyncio
from typing import Any
from pydantic import SkipValidation

import cognee
from cognee.infrastructure.engine import DataPoint
from cognee.infrastructure.engine.models.Edge import Edge
from cognee.tasks.storage import add_data_points

class Person(DataPoint):
    name: str
    # Keep it simple for forward refs / mixed values
    knows: SkipValidation[Any] = None  # single Person or list[Person]
    # Recommended: specify which fields to index for search
    metadata: dict = {"index_fields": ["name"]}

async def main():
    # Start clean (optional in your app)
    await cognee.forget(everything=True)

    alice = Person(name="Alice")
    bob = Person(name="Bob")
    charlie = Person(name="Charlie")

    # Create relationships - field name becomes edge label
    alice.knows = bob
    # You can also do lists: alice.knows = [bob, charlie]
    
    # Optional: add weights and custom relationship types
    bob.knows = (Edge(weight=0.9, relationship_type="friend_of"), charlie)

    await add_data_points([alice, bob, charlie])

if __name__ == "__main__":
    asyncio.run(main())

Legacy guide

import asyncio
from typing import Any
from pydantic import SkipValidation

import cognee
from cognee.infrastructure.engine import DataPoint
from cognee.infrastructure.engine.models.Edge import Edge
from cognee.tasks.storage import add_data_points

class Person(DataPoint):
    name: str
    # Keep it simple for forward refs / mixed values
    knows: SkipValidation[Any] = None  # single Person or list[Person]
    # Recommended: specify which fields to index for search
    metadata: dict = {"index_fields": ["name"]}

async def main():
    # Start clean (optional in your app)
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)

    alice = Person(name="Alice")
    bob = Person(name="Bob")
    charlie = Person(name="Charlie")

    # Create relationships - field name becomes edge label
    alice.knows = bob
    # You can also do lists: alice.knows = [bob, charlie]
    
    # Optional: add weights and custom relationship types
    bob.knows = (Edge(weight=0.9, relationship_type="friend_of"), charlie)

    await add_data_points([alice, bob, charlie])

if __name__ == "__main__":
    asyncio.run(main())

This example shows the complete workflow with metadata for indexing and optional edge weights. In practice, you can create complex nested models with multiple relationships and sophisticated data structures.

Low-Level LLM

Learn about direct LLM interaction

Core Concepts

Understand knowledge graph fundamentals

API Reference

Explore API endpoints

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Rust SDK

TypeScript SDK

OSS

What Custom Data Models Do

Code in Action

Step 1: Define Your Data Model

Step 2: Create Data Instances

Step 3: Create Relationships

Step 4: Insert into Graph

Custom Data Model Fields

Edge Metadata Fields

Custom Fields and Read-Back

Use in Custom Tasks and Pipelines

Linking DataPoints to a Dataset

Additional examples

Full Example

Low-Level LLM

Core Concepts

API Reference

​What Custom Data Models Do

​Code in Action

​Step 1: Define Your Data Model

​Step 2: Create Data Instances

​Step 3: Create Relationships

​Step 4: Insert into Graph

​Custom Data Model Fields

​Edge Metadata Fields

​Custom Fields and Read-Back

​Use in Custom Tasks and Pipelines

​Linking DataPoints to a Dataset

​Additional examples

​Full Example

Low-Level LLM

Core Concepts

API Reference

What Custom Data Models Do

Code in Action

Step 1: Define Your Data Model

Step 2: Create Data Instances

Step 3: Create Relationships

Step 4: Insert into Graph

Custom Data Model Fields

Edge Metadata Fields

Custom Fields and Read-Back

Use in Custom Tasks and Pipelines

Linking DataPoints to a Dataset

Additional examples

Full Example