Skip to content

Search Syntax

This syntax applies equally to DorsalHub Search and the dorsal search command in the CLI.

1. The Basics: Text Search

The simplest approach is often to type words which may appear in the file name:

annual report

dorsal search 'annual report'
  • How it Works: By default, this searches for files containing both "annual" AND "report" in the filename, extension, or media type.
  • Phrase Search: To search for an exact phrase, use quotes: "annual report".
  • OR Logic (CLI): If you're using the dorsal search command, you can use the --or flag to find files matching "annual" OR "report".

2. Narrowing Your Search with Filters

To make your search more precise, you can add filters. A filter is a special key:value pair that targets a specific piece of metadata.

Note: The operators = and : mean the same thing.

Example: Let's find all PDF "annual reports" over 5MB that were modified in 2025.

"annual report" ext:pdf size>5mb date_modified>=2025-01-01


dorsal search '"annual report" ext:pdf size>5mb date_modified>=2025-01-01'
Note: We wrap the entire query in single quotes (') because we are in a terminal environment, and use double quotes (") inside for the phrase search.

3. Filter Reference

Here are the most common filters you can use. For a complete list of operators (like >, <, etc.), see the Operators section below.

File Attribute Filters

Filter Aliases Description Examples
ext extension File extension. ext:pdf
ext=zip
media_type type, media-type, mediatype The file's MIME type. type:application/pdf
media_type:image/jpeg
size File size. Use operators like > or <=. size>100mb
size<=1.5gb

Date Filters

Filter Aliases Description Examples
date_modified date, date-modified File's last modified date. date_modified>2024-01-01
date=2025-07-04
date_created date-created Record's creation date. date_created<=2023-12-31

Other Metadata Filters

Filter Aliases Description Examples
sha256 A specific SHA-256 hash. sha256:abc123...
blake3 quick A BLAKE3 or QuickHash. blake3:abc123...
annotation Checks for the existence of an annotation. annotation:dorsal/arxiv
annotation:dorsal/image-caption

4. Searching by Tag

You can search for any tag you've added to a file.

Example: Find files you tagged as "English"

language=english

dorsal search 'language=english'

Example: Combine filters and tags

ext:pdf project_x="In Progress"

dorsal search 'ext:pdf project_x="In Progress"'

5. Operators

This is the full list of operators you can use in your filters.

Operator Meaning Example
: Equals (same as =) ext:pdf
= Equals (same as :) language=en
> Greater than size>100mb
>= Greater than or equal to date_modified>=2024-01-01
< Less than size<1gb
<= Less than or equal to date_created<=2023-12-31
````