Star Wars Example

The canonical Star Wars example lives in examples/starwars/. It now serves three purposes at once:

a full graph example with lineage, affiliation, and film traversal
the primary user-facing search example
the canonical CLI E2E fixture for Star Wars workflows

Setup

The example ships with a checked-in nanograph.toml, so you can work from the example directory without repeating --db or query paths:

cd examples/starwars

nanograph init
nanograph load --data starwars.jsonl --mode overwrite
nanograph check --query starwars.gq

Key defaults from examples/starwars/nanograph.toml:

[db]
default_path = "starwars.nano"

[query]
roots = ["."]

[embedding]
provider = "mock"

[query_aliases.search]
query = "starwars.gq"
name = "semantic_search"
args = ["q"]
format = "table"

That means:

the example uses deterministic mock embeddings by default
nanograph run search "father and son conflict" works out of the box
explicit flags still override config when you need them

See Project Config for the full config, env, and alias rules.

Schema metadata

The example schema also demonstrates agent-oriented metadata:

Character has @description(...) and @instruction(...)
HasMentor and DebutsIn describe relationship intent
Character.slug, Character.note, and Character.embedding carry property descriptions

Inspect it with:

nanograph describe --type Character --format json

That JSON now includes:

description
instruction
key_property
property descriptions
incoming and outgoing edge summaries

Query metadata and aliases

Several example queries also include @description(...) and @instruction(...). In normal table mode, nanograph run prints that context before the result rows.

nanograph run search "father and son conflict"

Example shape:

Query: semantic_search
Description: Rank characters by semantic similarity against their embedded notes.
Instruction: Use for broad conceptual search, not exact spelling.

Useful commands

Semantic search across character notes:

nanograph run search "who turned evil"

Hybrid search with lexical + semantic fusion:

nanograph run hybrid "father and son conflict"

Graph-constrained semantic search over Luke's parents:

nanograph run family luke-skywalker "chosen one prophecy"

Cross-type traversal from character to debut film:

nanograph run debut anakin-skywalker

Exact query-name form still works when you want full control:

nanograph run --query starwars.gq --name same_debut --format json --param film=a-new-hope

What this example shows