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

# Search expressions


The expression parameter used in the [search](search_method) and [cacheable search URLs](cacheable_search_urls) methods describes the query string for filtering the assets in your product environment in a Lucene-like query language. A query string contains search terms that can be combined with Boolean operators to form a more complex query. You can also limit your search to specific fields or you can run your query on all fields. 

If your search term contains a space or other reserved characters such as a colon, place the search term in quotes. For example, "long pants" or "16:9"

{info}
When using special characters in a search term, you have two options:

* **Enclose the term in quotes**: This treats the entire phrase literally and prevents special characters from being interpreted as operators. When enclosed in quotes, only the following characters need to be escaped with a backslash (\\): `" *`  
  **For example:** `product:"shirt:blue"` searches for that exact text. Or `activity:"watched \"Inside Out\" and rated it a 5 \*" searches for the exact phrase, treating the quotes and asterisk as literal characters.</p>
* **Escape special characters with a backslash (\\)**: Use this method when you need to include individual special characters within a term.  
  <p>The following characters should be escaped: `! ( ) { } [ ] * ^ ~ ? : \ = & >     >=       >=   3d indicates a date within the last 3 days.</p>
Number | `=   >   >=   3d` indicates a time more recent than 3 days ago.

## Boolean Operators

Boolean operators allow you to combine search terms using logic operators. Note that Boolean operators must be ALL CAPS.

Operator | Example | Description
---|---|---
`OR` or <code>&#124;&#124;</code> | tags:shirt OR public\_id:shirt<br/>tags:shirt &#124;&#124; public\_id:shirt<br/>tags:shirt public\_id:shirt| Links two search terms and finds a match if either of the terms exist. <br/>This is the default operator for linking 2 terms. 
`AND` or `&&` | tags:shirt AND public\_id:shirt<br/>tags:shirt && public\_id:shirt| Links two search terms and finds a match if both of the terms exist. 
`+` | +shirt +pants| Must have the term after the + symbol. 
`NOT` or `!` | clothes NOT shirts<br/>clothes !shirts| Excludes assets that contain the term after NOT.
`-` | -clothes -shirts| Must not have the term after the - symbol. 

> **NOTES**:
>
> * Use parentheses to group terms to form sub-queries. This can be useful if you want to control the boolean logic for a query. For example, to search for either "shirt" or "pants", and "clothes" use the query:<br/>
>     `(shirt OR pants) AND clothes`

> * If only a single term is used in the expression without an operator then the `+` operator is implied. For example, the following expressions are identical:<br/>
>     `clothes`<br/>
>     `+clothes`

> * If part of the query evaluates to 'must have', either by using the `+` operator or by an intersection of 2 terms with the `AND` operator, then any additional terms linked with the `OR` operator are used only for prioritizing the order of the results. For example, to search for "clothes" and prioritize results that also have "shirts":<br/>
>     `+clothes OR shirts`<br/>
>     `+clothes shirts`

> * Using NOT (or -) in queries can lead to significant latency on large asset repositories.

> * By default, the search results don't include any assets currently in the 'pending' moderation status. If you want to include these assets in the results, you need to modify your query. For example:<br>
>     `shirt AND moderation_status:pending`

> * You can use the `-` operator with a specified [structured metadata external_id](admin_api#metadata_field_structure), to search for assets with a structured metadata field that has no value set for that ID. For example, to search for all assets that have no value set for the metadata field with an ID of 'meta1':<br>
>     `-metadata=meta1`

## Expression examples

1. Assets containing "shirt" and with a tag that exactly matches "cotton":

	```
	shirt AND tags=cotton
	```

2. Images with a width between 200 and 1028, and an aspect_ratio of 16:9:

	```
	resource_type:image AND width:{200 TO 1028} AND aspect_ratio:"16:9"
	```

3. Originally created before January 15th 2017 and uploaded (overwritten) between 4 and 1 weeks ago:

	```
	created_at<2017-01-15 AND uploaded_at:[4w TO 1w] 
	```

4. Uploaded less than 2 days ago and still pending moderation:

	```
	uploaded_at>2d AND moderation_status:pending
	```

5. PNG images with some transparency:

	```
	format:png AND transparent:true
	```

6. Images with more than 2 faces:

	```
	resource_type:image AND face_count>2
	```

7. Images larger than 10 MB or videos longer than 3 minutes:

	```
	(resource_type:image AND bytes>10000000) OR (resource_type:video AND duration>180)
	```

8. Images tagged with "product" and also have one of three other tags "shirt" or "pants" or "hat", but not tagged with "discontinued":

	```
	resource_type:image AND tags=product AND (tags=shirt OR tags=pants OR tags=hat) NOT tags=discontinued
	```

9. Folders with folders with a name that includes a [token](search_expressions#string_operators_exact_or_tokenized_searches) of `folder` in a folder path that includes a [token](search_expressions#string_operators_exact_or_tokenized_searches) of `my_parent`, and was created in the past 4 weeks. 
    
	```
	name:folder AND path:my_parent AND created_at>4w
	```