Skip to main content

​
Overview

Search for entities in the knowledge graph by name or alias. Display entity details, connections, and descriptions.

​
Usage

sift search QUERY [OPTIONS]

​
Arguments

​
query
string
required
Search term that matches entity names and aliases (case-insensitive).

​
Options

​
--relations
boolean
default:"false"
Show connected entities (incoming and outgoing relations). Use -r as shorthand.
​
--description
boolean
default:"false"
Show entity description generated by sift narrate. Use -d as shorthand.
​
--type
string
Filter results by entity type (e.g., PERSON, ORGANIZATION). Use -t as shorthand.
​
--output
string
Output directory containing graph data. Use -o as shorthand.
​
--verbose
boolean
default:"false"
Show all relations (default: limit to 10). Use -v as shorthand.

​
Behavior

​
Search Algorithm

Matches query against:
  • Entity names (case-insensitive partial match)
  • Entity aliases (from aliases or also_known_as attributes)

​
Result Display

For each match:
  • Entity Type - E.g., PERSON, ORGANIZATION
  • Name - Primary entity name
  • Aliases - Alternative names (if any)
  • Connections - Degree (number of relations)
  • Source Documents - Origin documents
  • Description - Narrative summary (if --description and available)
  • Relations - Connected entities (if --relations)

​
Relation Format

Outgoing relations: 
→ RELATION_TYPE → Target Entity
Incoming relations: 
← Source Entity → RELATION_TYPE

​
Examples

sift search "John"
Finds all entities with “John” in name or aliases.

​
With relations

sift search "Acme Corp" --relations
Shows Acme Corp and all connected entities (limit 10).

​
With descriptions

sift search "Jane Doe" --description
Displays narrative description (requires sift narrate to have been run).

​
Filter by type

sift search "Smith" --type PERSON
Only shows PERSON entities matching “Smith”.

​
Full details with all relations

sift search "Berlin" -r -d -v
Shows all relations, description, and verbose output. 
sift search "University" -t ORGANIZATION --relations
Finds organizations with “University” in name and shows connections.

​
Output Format

​
Example Output

2 results

  PERSON: John Smith
    aka: J. Smith, Johnny
    Connections: 12
    Sources: document1.pdf, document2.pdf
    Description: Senior researcher at MIT specializing in AI...
    → WORKS_AT → MIT
    → COLLABORATED_WITH → Jane Doe
    ← Harvard University → EMPLOYED

  PERSON: John Doe
    Connections: 5
    Sources: document3.pdf

​
Relation Limits

By default, shows up to 10 relations per entity: 
... 23 more (use --verbose to show all)
Use --verbose to show all relations.

​
Integration with Narrate

The --description flag requires entity_descriptions.json: 
# Generate descriptions first
sift narrate

# Then search with descriptions
sift search "Einstein" --description
If descriptions not found: 
No descriptions found. Run sift narrate first.

​
No Results

If no matches found: 
No entities matching "xyz"

​
Error Handling

Exits with error if:
  • No graph_data.json found (run sift build first)

​
Use Cases

​
Find entity by partial name

sift search "mit"
Matches “MIT”, “Committee”, “Yosemite”, etc.

​
Explore entity network

sift search "Key Person" -r -v
See all connections to understand entity’s role.

​
Verify entity exists

sift search "Exact Name" -t PERSON
Check if specific entity was extracted.

​
See Also

  • view - Visual graph exploration
  • narrate - Generate entity descriptions
  • export - Export graph data

Build docs developers (and LLMs) love

Get started for freeTalk to us