How to search your PhotoStructure library

April 5, 2021

Asset search was a user-requested feature: be sure to join us in the PhotoStructure forum to discuss and vote on what gets built next!

What do search queries look like? 🔗

A search query includes one or more search terms.

What’s a search term? 🔗

Search terms may be simple words, like cat.

Simple terms match all assets associated to any tag whose path contains the search term.

Search terms may be “filtered”, like camera:canon.

Filtered search terms limit matches to the filter. In the case of camera:canon, only assets associated to “camera” tags that contain the word “canon” will be matched.

Search term filters 🔗

Filter	Description	Examples
`camera:`	matches all assets whose camera make or model includes the search term	`camera:canon`, `camera:EOS`
`lens:`	matches all assets whose lens make or model includes the search term	`lens:50mm`, `lens:Nikkor`
`type:`	matches all assets that have an asset file variant whose type is the search term	`type:image`, `type:video`, `type:jpeg`, `type:heic`, `type:raw/sony`
`who:`	matches all assets associated to a `Who` tag that includes the search term	`who:alice`, `who:rogers/fred`
`kw:`	matches all assets associated to a `Keywords` tag that includes the search term	`kw:sky`
`fs:`	matches all assets where any asset file variant pathname includes the search term	`fs:backup`
`faved`	matches assets that have been marked as a favorite. For convenience, `faved`, `favorite`, and `favourite` are all equivalent to `faved:true`.	`faved`, `faved:true`, `faved:false`
`deleted`	matches assets that have been marked for deletion. For convenience, `deleted` is equivalent to `deleted:true`.	`deleted`, `deleted:true`, `deleted:false`

Note that all root tags are valid filters.

Dated search term filters 🔗

The date:, before:, after:, and updated: filters accept a date term and, optionally, an operator.

Operators are “<”, “<=”, “>”, and “>=”.

The search term for dated filters must be formatted as YYYY-MM-DD, YYYY-MM, or YYYY.

Filter	Description	Examples
`date:`	matches assets’ captured at time.	`date:2018`, `date:<=2018-09-03`
`before:`	is added as a convenience, and is equivalent to `date:<`	`before:2018`, `before:2010-04-03`
`after:`	is added as a convenience, and is equivalent to `date:>`	`after:2018`, `after:2010-04-03`
`updated:`	matches all assets last synchronized with your PhotoStructure library	`updated:>=2021-04-21`

Tag path terms 🔗

PhotoStructure’s tags are hierarchical. You can match on parent/child paths by including a slash in your search term to limit to specific parent-child tags.

who:Fred will match all people whose first or last name contains the word “Fred”
who:Rogers/Fred will limit matches to Fred Rogers 🚋.

Prefixed search terms 🔗

Note that PhotoStructure indexes tags with a word tokenizer. To match words that start with your search term, add a “*”:

Term	Tag	Match	Why?
`kw:abc`	`Keywords/abc`	✅	`kw:` is an alias for `Keywords:`. `kw:abc` matches Keywords tags whose path elements include the word “abc”
`kw:abc`	`Keywords/ABC`	✅	Latin characters are matched case-insensitively, so `abc` also matches “ABC”
`kw:abc`	`Keywords/2018-12-30_abc`	✅	Path elements are split into words, so this matches as well,
`kw:abc`	`Keywords/abcdef`	❌	but `abc` doesn’t match words that start with “abc”,
`kw:abc`	`Keywords/a/b/c`	❌	or paths that contain “a”, followed by “b”, followed by “c”.
`kw:abc*`	`Keywords/abc`	✅	Adding an asterisk still matches all tags without the asterisk,
`kw:abc*`	`Keywords/2018-12-30_abc`	✅	and paths including the word “abc”,
`kw:abc*`	`Keywords/abcdef`	✅	and also matches any word that starts with that term,
`kw:abc*`	`Keywords/a/b/c`	❌	but still doesn’t match “a”, followed by “b”, followed by “c”.
`kw:a/b/c`	`Keywords/a/b/c`	✅	To match partial path hierarchies, use `/` in your search term.
`kw:a/b/c`	`Keywords/abc`	❌	The paths must match words.
`kw:a/b/c`	`Keywords/a/b/c`	✅	You can combine both `/` path separators and `*` to match word prefixes
`kw:a/b/c`	`Keywords/aaa/b/cde`	✅

Quoted terms 🔗

Terms with whitespace may use double-quotes, like fs:"My Pictures".

Exact-match search terms 🔗

PhotoStructure applies “inheritance” to tagged assets.

To disable inheritance and only match assets directly tagged with a path, use the := operator.

tag:TERM will match assets tagged with any path that includes TERM.
tag:=TERM will match assets tagged with any path that ends with TERM.

To match tags that start with a TERM, start the TERM with a “/”.

tag:/TERM will match assets tagged with any path that starts with TERM.
tag:=/TERM will match assets tagged with the tag that exactly matches TERM, because the /TERM means it must start with TERM, and := means it must end with TERM.

Term	Tag	Match	Why?
`where:california`	`Where/California/San Francisco/Golden Gate`	✅	Terms normally match any word in the tag’s path
`where:"san francisco"`	`Where/California/San Francisco/Golden Gate`	✅	Use double quotes for paths that include spaces
`where:"golden gate"`	`Where/California/San Francisco/Golden Gate`	✅	Terms are matched case-insensitively for latin-based characters.
`where:="golden gate"`	`Where/California/San Francisco/Golden Gate`	✅	Adding the `=` operator disables tag inheritance
`where:="san francisco"`	`Where/California/San Francisco/Golden Gate`	❌	The tag doesn’t end with “san francisco”
`where:="san francisco"`	`Where/California/San Francisco`	✅	The tag ends with “san francisco”
`who:chris`	`Who/Robin/Chris`	✅	`Who/Robin/Chris` includes “Chris”
`who:=chris`	`Who/Robin/Chris`	✅	`Who/Robin/Chris` ends with “Chris”
`who:chris`	`Who/Chris/Robin`	✅	`Who/Chris/Robin` includes “Chris”
`who:=chris`	`Who/Chris/Robin`	❌	`Who/Chris/Robin` doesn’t end with “Chris”
`what:a`	`What/a/b/c`	✅	Matches due to tag inheritance
`what:b`	`What/a/b/c`	✅
`what:c`	`What/a/b/c`	✅
`what:a/b`	`What/a/b/c`	✅	Any portion of the path can match if the term doesn’t start or end with “`/`”
`what:b/c`	`What/a/b/c`	✅
`what:a/b/c`	`What/a/b/c`	✅
`what:=a/b/c`	`What/a/b/c`	✅	The tag ends with “a/b/c”
`what:=a/b`	`What/a/b/c`	❌	The tag doesn’t end with “a/b”
`what:=b/c`	`What/a/b/c`	✅	The tag ends with “b/c”
`what:/a/b`	`What/a/b/c`	✅	The tag starts with `/a/b`
`what:/b/c`	`What/a/b/c`	❌	The tag doesn’t start with `/b/c`
`what:=/a/b/c`	`What/a/b/c`	✅	The tag exactly matches the term
`what:=/a/b/c`	`What/ZZZ/a/b/c`	❌	The tag doesn’t exactly match the term

Negated terms 🔗

All filtered terms may be negated by prefixing the filter with a minus sign.

For example, -lens:nikkor will return all assets not captured with a Nikkor lens.

Clauses of terms 🔗

Terms may be grouped together with AND, OR, and parenthesis.

faved AND (who:alice OR date:2020-07-04) will match all faved assets that include Alice or were taken on 4 July 2020.
Terms separated by whitespace are grouped together with AND.

faved after:2012 is equivalent to faved AND after:2012.
Search terms, filters, and AND and OR are all case-insensitive.

More examples 🔗

faved after:1990 who:alice matches all assets marked as a favorite taken after 1990 that includes Alice.
type:video faved after:2010 before:2015 matches all video assets marked as a favorite taken in 2011 through and including 2014.
(type:video after:2010) or (faved date:2015) matches all video assets taken after 2010 as well as all favorite assets taken in 2015.

FAQ
Docs

Hi! I’m Matthew, the author of PhotoStructure. I’m a dad, amateur photographer, and author of open source, adtech, fintech, and edtech software since the turn of the millennium. He/him. I am building a self-hosted, safe, and fast new home for all your photos and videos.
Your memories deserve PhotoStructure. Try it out for free!