Programmable Media
Menu

Search expressions

Last updated: Nov-20-2023

The expression parameter used in the search and 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"

Important
The following special characters should be escaped with a backslash (\) in order to be used in a search expression or as a part of search term: ! ( ) { } [ ] * ^ ~ ? : \ = & > < and whitespace

For example: ~shirt becomes \~shirt

On this page:

Fields

By default, the term is searched for in all the asset's string fields, except for strings with a value that is limited to a fixed list (e.g. access_mode is limited to the values 'public' or 'authenticated'). The search can be confined to a specific field (including fields not automatically included in the default search) by typing the field name followed by a colon : (or other relevant operator) and then the term you are looking for. For example, if you want to find assets of type "authenticated":

Field names are case sensitive. For a list of all supported fields, see Expression fields.

Tip
When searching for a term in all the asset's string fields, you may also want to sort the results by relevance (e.g., results are more relevant if the search term is found in multiple fields). You can add the sort_by search parameter, set the key to score and give a sort direction as the value.

Field operators

When using fields in your query, you need to indicate the relationship between the search value and the field. For example, whether you are searching for assets where the field value is greater than, less than, or equal to the value you specify. The following operators are supported: : = > >= < <= [ ] { }

The supported operators and values you can use for a particular field depend on the type of that field, as detailed in Field types and supported operators.

String operators - exact or tokenized searches

  • Using the = operator finds matches where the value is an exact match.
  • Using the : operator finds matches where the value matches any complete token within the string value.

A token is a part of a search string that is separated by a separator character. Spaces, hyphens, and underscores are the most common characters that separate tokens within a search string. For example:

Finds a match only when the tag equals shirt

Finds a match as long as any of the tokens in a tag entry includes shirt, for example, tag values of shirt and pants or long-shirt return as matches but shirts doesn't.

You can also append an asterisk (*) to the end of a search term in order to look for your search term as a prefix. For example, to search for "shirt" or "shirts", you can use the search term:

You can also combine the use of asterisks with exact (=) or tokenized (:) searches to further fine-tune your result:

  • If you only want to return results where the entire value starts with shirt*, use an exact (=) search. For example, tags=shirt*
  • If you want to return all results where any token in the value starts with shirt*, use a tokenized (:) search. For example, tags:shirt*

Notes
  • Some string fields support only exact matches. In these cases, even if you use a : operator, it will still behave as an exact match search. Fields that support exact match only are indicated in the Expression fields reference table.
  • The values of some string fields are case-sensitive, and some are a combination: case-sensitive when performing an exact (=) search and case-insensitive when performing a tokenized (:) search. Those that support exact match only are usually case-sensitive, while free text fields are either case-insensitive or a combination. The case sensitivity of each string field is indicated in the Expression fields reference table.
  • You cannot use the asterisk or token (:) operator to search for the middle or end of a string or token. For example, you cannot use *irt or :irt to find shirt.

Range operators - inclusive or exclusive ranges

To search for a value that falls within a specific range, enclose the range values within square brackets to include the specified values or within curly braces to exclude the specified values, and separated with the TO operator. For example, to find assets with a file size within the range 1000 to 20000 bytes:

You can also search for an alphabetic range, using any alphanumeric characters in your range query, for example, searching for public_ids with names that are alphabetically between "a" and "mz":

Boolean Operators

Boolean operators allow search terms to be combined through logic operators. Note that Boolean operators must be ALL CAPS.

Operator Example Description
OR or || tags:shirt OR public_id:shirt
tags:shirt || public_id:shirt
tags:shirt public_id:shirt		 Links two search terms and finds a match if either of the terms exist.
This is the default operator for linking 2 terms.
AND or && tags:shirt AND public_id:shirt
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
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:
    (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:
    clothes
    +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 will only be used for prioritizing the order of the results. For example, to search for "clothes" and prioritize results that also have "shirts":
    +clothes OR shirts
    +clothes shirts
  • By default, the search results do not 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:
    shirt AND moderation_status:pending
  • You can use the - operator with a specified structured metadata external_id, 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':
    -metadata=meta1

Expression examples

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

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

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

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

  5. PNG images with some transparency:

  6. Images with more than 2 faces:

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

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

✔️ Feedback sent!

Rate this page: