> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/juanceresa/sift-kg/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
sift search QUERY [OPTIONS]
```

## Arguments

<ParamField path="query" type="string" required>
  Search term that matches entity names and aliases (case-insensitive).
</ParamField>

## Options

<ParamField path="--relations" type="boolean" default="false">
  Show connected entities (incoming and outgoing relations). Use `-r` as shorthand.
</ParamField>

<ParamField path="--description" type="boolean" default="false">
  Show entity description generated by `sift narrate`. Use `-d` as shorthand.
</ParamField>

<ParamField path="--type" type="string">
  Filter results by entity type (e.g., `PERSON`, `ORGANIZATION`). Use `-t` as shorthand.
</ParamField>

<ParamField path="--output" type="string">
  Output directory containing graph data. Use `-o` as shorthand.
</ParamField>

<ParamField path="--verbose" type="boolean" default="false">
  Show all relations (default: limit to 10). Use `-v` as shorthand.
</ParamField>

## 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

```bash theme={null}
sift search "John"
```

Finds all entities with "John" in name or aliases.

### With relations

```bash theme={null}
sift search "Acme Corp" --relations
```

Shows Acme Corp and all connected entities (limit 10).

### With descriptions

```bash theme={null}
sift search "Jane Doe" --description
```

Displays narrative description (requires `sift narrate` to have been run).

### Filter by type

```bash theme={null}
sift search "Smith" --type PERSON
```

Only shows PERSON entities matching "Smith".

### Full details with all relations

```bash theme={null}
sift search "Berlin" -r -d -v
```

Shows all relations, description, and verbose output.

### Type-specific search

```bash theme={null}
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`:

```bash theme={null}
# 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

```bash theme={null}
sift search "mit"
```

Matches "MIT", "Committee", "Yosemite", etc.

### Explore entity network

```bash theme={null}
sift search "Key Person" -r -v
```

See all connections to understand entity's role.

### Verify entity exists

```bash theme={null}
sift search "Exact Name" -t PERSON
```

Check if specific entity was extracted.

## See Also

* [view](/api/cli/view) - Visual graph exploration
* [narrate](/api/cli/narrate) - Generate entity descriptions
* [export](/api/cli/export) - Export graph data