entity-schema-reference

This document describes the valid entity and relationship schema for Lattice. Entities are extracted by Claude Code and stored directly in DuckDB - no frontmatter required in your markdown files.

Valid Entity Labels

Entities must use one of these 9 allowed labels:

Label	Use Case
`Topic`	Research areas, subjects, domains
`Technology`	Programming languages, frameworks, tools, libraries
`Concept`	Abstract ideas, patterns, methodologies
`Tool`	Specific software, utilities, applications
`Process`	Workflows, procedures, algorithms
`Person`	Individuals
`Organization`	Companies, teams, groups
`Document`	Files, papers, specs (auto-created for markdown)
`Location`	Paths, places, directories

Database Schema

Entities are stored in the nodes table:

CREATE TABLE nodes (
    label VARCHAR NOT NULL,      -- One of the 9 labels above
    name VARCHAR NOT NULL,       -- Entity identifier
    properties JSON,             -- description, title, etc.
    embedding FLOAT[512],        -- Vector for semantic search
    PRIMARY KEY(label, name)
);

Entity Properties

The properties JSON column may contain:

Property	Type	Description
`description`	string	Brief description for semantic search
`title`	string	Document title (for Document entities)
`contentHash`	string	Content hash for change detection (Documents)

Relationship Schema

Relationships are stored in the relationships table:

CREATE TABLE relationships (
    source_label VARCHAR NOT NULL,
    source_name VARCHAR NOT NULL,
    relation_type VARCHAR NOT NULL,  -- REFERENCES or APPEARS_IN
    target_label VARCHAR NOT NULL,
    target_name VARCHAR NOT NULL,
    properties JSON,
    PRIMARY KEY(source_label, source_name, relation_type, target_label, target_name)
);

Relationship Types

Type	Created By	Description
`REFERENCES`	AI extraction	Semantic connection between entities
`APPEARS_IN`	Auto-generated	Links entity to source document

AI Extraction Guidelines

When Claude Code extracts entities via /graph-sync, it follows these guidelines:

Entity Selection

Extract 3-10 significant entities per document
Focus on concepts, technologies, and tools mentioned
Use the most specific label that applies
Include brief descriptions for semantic search

Label Selection Guide

If your entity is…	Use label
A software library/framework	`Technology`
A specific CLI tool or app	`Tool`
An algorithm or workflow	`Process`
A design pattern or methodology	`Concept`
A research area or domain	`Topic`
A company or team	`Organization`
A specification or file	`Document`
A named individual	`Person`
A file path or location	`Location`

Relationship Extraction

Extract 3-7 key relationships per document
Use REFERENCES for semantic connections
APPEARS_IN is auto-generated (entity → document)

Validation

The extraction uses Zod schema internally:

const EntityLabelSchema = z.enum([
  "Topic", "Technology", "Concept", "Tool",
  "Process", "Person", "Organization", "Document", "Location"
]);

const RelationTypeSchema = z.enum([
  "REFERENCES", "APPEARS_IN"
]);

Querying Entities

Find entities by label

lattice sql "SELECT name, properties FROM nodes WHERE label = 'Technology'"

Find relationships for an entity

lattice rels "DuckDB"

Semantic search

lattice search "vector database"