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

# Search

> Semantically search through a video

## What is Search?

Search lets you locate exact moments across thousands of hours of video using natural language or an image reference. Results are split into three specialized buckets—embeddings, transcript, and ocr— So you can quickly see why something matched.

The path to use search:

```
core/search
```

## Running Search

### Natural Language Search

To search with natural language:

<CodeGroup>
  ```python python theme={null}
  resp = moonshine.run(
      flow="core/search",
      index="your-index-name",
      query="your search query, ex: red car",
      num_args=10  # optional, defaults to 5
  )
  ```
</CodeGroup>

Where `num_args` are the max number of results returned and is optional.

### Image Search

To search with an image:

<CodeGroup>
  ```python python theme={null}
  resp = moonshine.run(
      flow="core/search",
      image="./reference.png",  # local path or public URL
      image="path/to/image.jpg",
  )
  ```
</CodeGroup>

If both an `image` and `query` are supplied, the image will take precedence.

### Sub-Search

Using a Subindex will isolate a search a subset of the videos in an index. To use it:

<CodeGroup>
  ```python python theme={null}
  resp = moonshine.run(
      flow="core/search",
      index="your-index-name",
      query="your search query, ex: red car",
      subindex=[
          "FHXYU838JHDWK.mp4",
          "AJDIEUJDKSLW.mp4"
      ],
  )
  ```
</CodeGroup>

where the `subindex` is a list of video IDs to search within.

## Search Response Format

Search returns a list of match objects. The match object schema is:

<Tabs>
  <Tab title="0">
    <ParamField path="[0]" type="string">
      Moonshine-assigned `file_id`

      e.g. `FHXYU838JHDWK.mp4`
    </ParamField>
  </Tab>

  <Tab title="1">
    <ParamField path="[1]" type="int">
      Start frame number of the match\
      e.g. `600`
    </ParamField>
  </Tab>

  <Tab title="2">
    <ParamField path="[2]" type="int">
      End frame number of the match\
      e.g.  `725`
    </ParamField>
  </Tab>

  <Tab title="3">
    <ParamField path="[3]" type="string">
      Start timestamp (human-readable)\
      e.g. `0 min, 22 sec`
    </ParamField>
  </Tab>

  <Tab title="4">
    <ParamField path="[4]" type="string">
      End timestamp (human-readable)\
      e.g. `0 min, 34 sec`
    </ParamField>
  </Tab>
</Tabs>

<CodeGroup>
  ```python python theme={null}
  for match in resp["output"]["embeddings"]:
      file_id      = match[0]
      start_frame  = match[1]
      end_frame    = match[2]
      start_time   = match[3]
      end_time     = match[4]
  ```
</CodeGroup>

## Search JSON

Workflows are in a private beta. Please contact us at [team@usemoonshine.com](mailto:team@usemoonshine.com) to request access.

***

<Accordion title=".run(flow='core/search', ...) params" icon="code-simple">
  <ParamField path="index" type="string" required>
    Name/ID of the parent index to search.
  </ParamField>

  <ParamField path="query" type="string">
    Natural-language text.\
    Ignored if `image` is supplied.
  </ParamField>

  <ParamField path="image" type="string">
    Local file path or public URL to an image used as the search reference.
  </ParamField>

  <ParamField path="subindex" type="List[str]">
    An optional list of `file_id`to narrow the search scope.
  </ParamField>

  <ParamField path="num_args" type="int" placeholder="5">
    Max results per result-type bucket.
  </ParamField>
</Accordion>