Building Blocks
DataPoints
Atomic units of knowledge in Cognee
DataPoints: Atomic Units of Knowledge
DataPoints are the smallest building blocks in Cognee.They represent atomic units of knowledge — carrying both your actual content and the context needed to process, index, and connect it. They’re the reason Cognee can turn raw documents into something that’s both searchable (via vectors) and connected (via graphs).
What are DataPoints
- Atomic — each DataPoint represents one concept or unit of information.
- Structured — implemented as Pydantic models for validation and serialization.
- Contextual — carry provenance, versioning, and indexing hints so every step downstream knows where data came from and how to use it.
Core Structure
A DataPoint is just a Pydantic model with a set of standard fields.See example class definition
See example class definition
id— unique identifiercreated_at,updated_at— timestamps (ms since epoch)version— for tracking changes and schema evolutionmetadata.index_fields— critical: determines which fields are embedded for vector searchtype— class namebelongs_to_set— groups related DataPoints
Indexing & Embeddings
Themetadata.index_fields tells Cognee which fields to embed into the vector store.
This is the mechanism behind semantic search.
- Fields in
index_fields→ converted into embeddings - Each indexed field → its own vector collection (
Class_field) - Non-indexed fields → stay as regular properties
- Choosing what to index controls search granularity
From DataPoints to the Graph
When you calladd_data_points(), Cognee automatically:
- Embeds the indexed fields into vectors
- Converts the object into nodes and edges in the knowledge graph
- Stores provenance in the relational store
Examples and details
Example: indexing only one field
Example: indexing only one field
"name" is semantically searchableExample: Book → Author transformation
Example: Book → Author transformation
Relationship syntax options
Relationship syntax options
Built-in DataPoint types
Built-in DataPoint types
Cognee ships with several built-in DataPoint types:
- Documents — wrappers for source files (Text, PDF, Audio, Image)
Document(metadata.index_fields=["name"])
- Chunks — segmented portions of documents
DocumentChunk(metadata.index_fields=["text"])
- Summaries — generated text or code summaries
TextSummary/CodeSummary(metadata.index_fields=["text"])
- Entities — named objects (people, places, concepts)
Entity,EntityType(metadata.index_fields=["name"])
- Edges — relationships between DataPoints
Edge— links between DataPoints
Example: custom DataPoint with best practices
Example: custom DataPoint with best practices
- Keep it small — one concept per DataPoint
- Index carefully — only fields that matter for semantic search
- Use built-in types first — extend with custom subclasses when needed
- Version deliberately — track changes with
version - Group related points — with
belongs_to_set