Query options

The Search API is a powerful and flexible tool that allows you to combine a wide variety of search criteria with operators. This page explains how to construct query criteria so you can search for exactly what you need. This page also lists the standard search criteria available in Orange Logic.

Custom fields that are searchable can also be included as search criteria. Use the List Criteria endpoint to get a list of criteria specific to your environment.

Query construction

You can use criteria and search terms in the query parameter to describe the attributes of the assets you need. Criteria are the metadata fields, Tags, and other information about assets hosted in Orange Logic. Search terms are an asset’s specific information related to each criterion, such as words, phrases, categories, or the tags applied to that asset. Queries are included in the Search API in the format criterion:search_term. For example, let’s say you want to find all assets with “London” in the title. The criterion is Title, the search term is London, and your query parameter is Title:London.

You can use operators to specify two search terms for one criterion with the syntax criterion1:search_term1 [Operator] search_term2. Alternatively, you can use the syntax criterion1:search_term1 [Operator] criterion1:search_term2 to get the same result. For example, suppose you want to find all assets with "London" and "Bridge" in the title. The criterion is title and the search terms are London and Bridge. You could write the query parameter as either Title:London AND Bridge or Title:London AND Title:Bridge.

To combine multiple criteria in one Search API call, use operators to add criteria to the query in the format criterion1:search_term1 [Operator] criterion2:search_term2. For example, if you want to find only images with "London" in the title, the criteria are DocType and Title. Your query parameter is DocType:Image AND Title:London.

ℹ️

Note

• You cannot use the query parameter multiple times in the same request. To combine multiple criteria, separate them with operators.
• Correct syntax: [https://www.mangovations.com/API/search/v3.0/search?query=keyword:LondonANDDocType:Image&fields=SystemIdentifier&format=JSON]
• Incorrect syntax:
  [https://www.mangovations.com/API/search/v3.0/search?query=keyword:Londonquery=DocType:Image&fields=SystemIdentifier&format=JSON]

The following sections provide more details and many examples that demonstrate how to combine query criteria and search terms.

Query operators

You can combine values within the same criterion, or across different criteria, with the operators listed in the following table.

Order of operations

Operators in our search have different priorities. If you don’t specify how the system should complete a query, operators are prioritized in this order: NOT > AND > OR. This order of operations applies to each search term, regardless of the criterion they’re applied to. For example, the query keyword:sun AND day OR daylight AND title:vacation returns assets that are tagged with both sun and day and assets with both the daylight tag and vacation in the title. This is because Orange Logic uses the default order of operations, which prioritizes the AND operator over the OR operator.

You can use sets of parentheses to override the default order and perform advanced searches on query criteria and search terms. For example, let’s say you want to search for assets that:

• Have the sun tag.
• Have either day or daylight as a tag.
• Have vacation in the title.

One query you can use to get this result is: keyword:sun AND (day OR daylight) AND title:vacation. Here, the parentheses tell Orange Logic to consider the operation in the parentheses before the other operations.

To get the result you want, your search must include parentheses. For example, if you change the query order and write keyword:sun AND title:vacation AND keyword:day OR daylight, Orange Logic reads the query as keyword:(sun AND title:vacation AND keyword:day) OR daylight and returns assets that are tagged with sun and day and that have vacation in the title, as well as assets that are tagged with daylight.

Date and time operators

You can use operators with date and date-time criteria, such as MediaDate or CreateDate, to search both inclusive and exclusive date or date-time intervals. Some fields only support date criteria, and some support date-time criteria.

By default, for both date and date-time criteria, the date is specified in the format YYYY-MM-DD. Year (YYYY) is required, and month (MM) and day (DD) are optional. If the date is specified as YYYY-MM, Orange Logic returns results from the entire month. If the date is specified as YYYY, Orange Logic returns results from the entire year.

By default, date-time criteria is specified in the format YYYY-MM-DDTHH.MM.SS, where T is a placeholder that indicates time, HH is hours, MM is minutes, and SS is seconds.

ℹ️

Note

You can change the date-time format with the datetime parameter.

Search one or more date ranges

You can use query operators (AND, OR, NOT) to combine date operators so that you can search one or more date ranges.

For example, the query MediaDate>:2023-12-30 AND MediaDate<:2024-01-02 returns assets created from December 30, 2023 through January 2, 2024, which means it returns assets created on four dates: December 30, 2023; December 31, 2023; January 1, 2024; and January 2, 2024. In the following example call, the following special characters are percent-encoded:

• The colon (:) is percent-encoded as %3A.
• The greater-than sign (>) is percent-encoded as %3A.
• The less-than sign (<) is percent-encoded as %3C.

curl -X 'GET' \
  'https://mangovations.com/API/Search/v4.0/Search?query=MediaDate%3E%3A2023-12-30%20AND%20MediaDate%3C%3A2024-01-02&sort=1&fields=path_TR1&fields=SystemIdentifier&pagenumber=1&format=JSON' \
  -H 'accept: application/json'

In contrast, the query MediaDate>2012-12-30 AND MediaDate<2013-01-02 returns assets created after December 30, 2023 and before January 2, 2024, which means it returns assets created on two dates: December 31, 2023 and January 1, 2024.

Query criteria

Orange Logic offers many standard search criteria, and your organization can also customize metadata fields to make them searchable.

Standard search criteria

The most commonly used criteria are listed in the following table:

Search within a folder structure

When possible, you should increase your search efficiency by using precise criteria to narrow your search. For example, the criterion ParentFolderIdentifiertakes the unique identifier of a folder and narrows your search to the specified folder’s entire folder structure.

For example, let’s say you want to find all of the images of islands from your organization’s television show “Dream Vacation Destinations.” These images are located in many season subfolders within the Dream Vacation Destinations folder, which has a unique ID of CTLSTO117374. To find all of these images, you use the ParentFolderIdentifier criterion to specify that the search should encompass the entire folder structure within the “Dream Vacation Destinations” folder with the query ParentFolderIdentifier:CTLSTO117374 and title:islands AND keywords:islands.

⚠️

Caution

• You can also use a wildcard (*) search to search for assets within the Path criterion. However, this method is less efficient than using ParentFolderIdentifier and is not recommended.
  • Wildcard searches cannot be used with quoted text. Paths that contain reserved strings (and, or, &, &&, |, ||) must be surrounded by quotes, so it is not currently possible to do a wildcard search with a quoted Path criterion.
• Wildcard searches on criteria other than the Path criterion yield unexpected results, and are not recommended.

Custom searchable fields

You can add fields to the available search criteria or make fields available to search in the text criterion with the search-related checkboxes in the Create / Edit fields window.

Metadata fields as search criteria

Any metadata fields that are “searchable individually” in your organization’s DAM can be searched by entering with the field’s Namespace and title as a search criterion in the query parameter. For example, let’s say an administrator at Mangovations creates a searchable text field called Vendors in the Marketing Namespace. She selects the Searchable individually checkbox.

You can search this field’s information using marketing.Vendors as the criterion. New metadata fields must be indexed and may not appear immediately.

Some metadata fields have the Searchable Individually setting activated by default. For more information, go to the Searchable Individually article.

🎓

Insight: Namespace

A Namespace is a category that lets you group similar fields. For example, if you have many departments with their own Asset Subtypes and metadata fields, you might want to categorize fields based on departments. Additionally, default (“Core”) fields in Orange Logic have the CoreField Namespace. You can view a field’s namespace in its settings.

For more information, go to the Namespaces article.

Parse multi-valued fields

Search API v4.0 parses custom, multi-valued fields to their original type instead of returning all values as one string.

For example, let’s say a “Content Usage” field contains three possible values:

• Social media, videos, webinars
• Live streams
• Print

Search API v4.0 splits this field into its three possible values.

ℹ️

Note

Search API v4.0 is available beginning in Orange Logic London. Earlier Orange Logic releases use Search API v3.0.