sift search

Search entities in knowledge graph by name or alias

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

Basic search

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.

Type-specific search

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