cli-search-commands

Purpose

Document the different ways to query the Lattice knowledge graph and when to use each approach.

Command Overview

1. Semantic Search: lattice search <query>

Purpose

Natural language search using AI embeddings for conceptual similarity.

How It Works

1. Generates embedding vector for your query using Voyage AI
2. Performs HNSW vector similarity search across all entities in DuckDB
3. Returns results ranked by cosine similarity score

Options

lattice search <query>           # Search all entity types
lattice search <query> -l <label>  # Filter by label (e.g., Technology, Document)
lattice search <query> --limit <n> # Limit results (default: 20, max: 100)

Output Format

=== Semantic Search Results for "react state management" ===

1. [Concept] React Hooks
   Stateful logic in functional components...
   Similarity: 92.45%

2. [Technology] Redux
   Predictable state container for JavaScript apps...
   Similarity: 88.12%

3. [Document] /home/user/.lattice/docs/react/state-patterns.md
   Title: React State Patterns
   Similarity: 85.70%

Requirements

• Embeddings must be generated first via lattice sync
• Requires VOYAGE_API_KEY environment variable

Use Cases

• Finding concepts by meaning, not just keywords
• Discovering related topics you didn’t know existed
• Exploring the graph without knowing exact entity names

2. Raw SQL: lattice sql <query>

Purpose

Direct database access for custom queries and advanced analysis.

Usage

lattice sql "SELECT * FROM nodes LIMIT 10"
lattice sql "SELECT label, COUNT(*) as count FROM nodes GROUP BY label"

Output Format

Raw JSON dump of query results:

[
  {
    "label": "Technology",
    "name": "React",
    "properties": {"description": "JavaScript library for building user interfaces"}
  }
]

Database Schema

-- Nodes (entities)
CREATE TABLE nodes (
    label VARCHAR NOT NULL,      -- Entity type: Document, Technology, etc.
    name VARCHAR NOT NULL,       -- Unique identifier
    properties JSON,             -- Additional metadata
    embedding FLOAT[512],        -- Vector for semantic search
    PRIMARY KEY(label, name)
);

-- Relationships
CREATE TABLE relationships (
    source_label VARCHAR NOT NULL,
    source_name VARCHAR NOT NULL,
    relation_type VARCHAR NOT NULL,
    target_label VARCHAR NOT NULL,
    target_name VARCHAR NOT NULL,
    properties JSON
);

Use Cases

• Complex filtering and aggregations
• Custom analytics and reporting
• When you need raw data for scripting/processing
• Debugging and exploring the database

3. Relationship Lookup: lattice rels <name>

Purpose

Show all relationships for a specific entity.

Usage

lattice rels "TypeScript"
lattice rels "/home/user/.lattice/docs/react/README.md"

Output Format

=== Relationships for "TypeScript" ===

Relationships:
  -[USED_BY]-> React
  -[COMPILES_TO]-> JavaScript
  -[SUPPORTS]-> Type Safety

Use Cases

• Exploring entity connections
• Understanding how concepts relate
• Navigating the knowledge graph

Key Differences Summary

lattice search (semantic)

• Abstraction: High-level, natural language
• Query Building: Vector similarity from AI embeddings
• Output: User-friendly with similarity percentages
• Best For: Conceptual searches, discovery, “things like this”

lattice sql

• Abstraction: Low-level, direct database access
• Query Building: Manual SQL syntax
• Output: Raw JSON data structures
• Best For: Complex queries, scripting, advanced analysis

lattice rels

• Abstraction: Mid-level, entity-focused
• Query Building: Automatic from entity name
• Output: Formatted relationship list
• Best For: Graph exploration, understanding connections

Decision Tree

Need to query the graph?
│
├─ Want to explore an entity's connections?
│  └─ Use: lattice rels "entity name"
│
├─ Need custom SQL logic or aggregations?
│  └─ Use: lattice sql "SELECT ..."
│
└─ Want conceptual/semantic matching?
   └─ Use: lattice search "natural language query"

Examples

Find all Technology nodes

# Semantic search (filtered)
lattice search "programming" -l Technology

# SQL (direct)
lattice sql "SELECT name, properties FROM nodes WHERE label = 'Technology'"

Find React-related content

# Semantic search (conceptual)
lattice search "react component patterns"

# SQL (exact match)
lattice sql "SELECT * FROM nodes WHERE name LIKE '%React%'"

Explore entity relationships

# Show what React connects to
lattice rels "React"

# SQL (all relationships for an entity)
lattice sql "SELECT relation_type, target_name FROM relationships WHERE source_name = 'React'"

Get graph statistics

lattice sql "SELECT label, COUNT(*) as count FROM nodes GROUP BY label ORDER BY count DESC"
lattice sql "SELECT relation_type, COUNT(*) as count FROM relationships GROUP BY relation_type"

Related Commands

• lattice status - Show documents needing sync
• lattice sync - Synchronize documents to the graph
• lattice ontology - Display derived entity types and relationships

Technology Stack

• Database: DuckDB (embedded, zero external dependencies)
• Vector Search: DuckDB VSS extension (HNSW index with cosine similarity)
• Embeddings: Voyage AI (voyage-3-lite, 512 dimensions)
• Runtime: Bun + NestJS + nest-commander