Asset search conventions

Keywords

When using assetSearch to find assets by keywords, remember that the keywords are case insensitive strings. Partial matches will also be included in your results. When searching for assets using keywords, you can make a request using single terms, multiple terms, phrases or multiple phrases, as demonstrated below:

Rule	Example
Single terms	"red"
Multiple terms	"red pink"
Phrases	"\"extra small\""
Multiple phrases	"\"extra small\" \"extra extra small\""

Searches are only scoped to the asset stores that you already have access to.

Examples: single and multiple term keywords

For example, if we wanted to search for assets including the single term woman, and return their id and name fields, our query would look like this:

{
  assetSearch(keyword: "woman", first: 5, sort: { createdDate: DESC }) {
    total
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        name
      }
    }
  }
}

This would give us the following response:

{
  "data": {
    "assetSearch": {
      "total": 90,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJtYXJrZXIiOiJBb04vK0tQNi9ZRURDRUdUSkVBL0JUbGxObUl6T0dZMUxUZGhZMlF0TkRJeVlTMWlNR1ZoTFRJeE9ERmtZamMxTnpKaU5BPT0iLCJ0b3RhbEZvdW5kIjo5MCwidG90YWxSZXR1cm5lZCI6NX0="
      },
      "edges": [
        {
          "node": {
            "id": "QXNzZXQ6ODdkNGU5OGMtMGY5Yi00YTBmLTg2NDMtZjZmM2IxZjgxNzMy",
            "name": "woman-laptop-celebrate"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6YTc2YThhNWQtZmVlOS00ZGVlLWI0ZTMtNTI2ZmQ4MjI4ZTM1",
            "name": "woman-signaturehat"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6ZDk2Y2QzM2MtYTI2Ny00MTkwLWIyNmItNmM0MDZmNjU3MzQ0",
            "name": "woman-yellow-dress-and-shoes_1"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6MWMzYTUzNDUtM2I1Yi00ZjdmLThjNWItOTY0ZDBlYWE4ZDI1",
            "name": "woman-in-winter-coat"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6OWU2YjM4ZjUtN2FjZC00MjJhLWIwZWEtMjE4MWRiNzU3MmI0",
            "name": "woman-in-blue-dress-on-beach"
          }
        }
      ]
    }
  }
}

If we wanted to search for all assets that contains the terms woman and laptop, we would simple alter our query to look like the below:

{
  assetSearch(keyword: "woman laptop", first: 5, sort: { createdDate: DESC }) {
    total
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        name
      }
    }
  }
}

As seen in the response below, we receive assets that has names including either the keyword laptop or woman or both. This is because using keywords can produce partial matches in your results.

{
  "data": {
    "assetSearch": {
      "total": 97,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJtYXJrZXIiOiJBb041aUtxcWpJTURDRUdmckpvL0JUazJORFV5T1dFeExUTmlZVEF0TkRCaE15MDVOV1ExTFRKaVptTTRZekptTVRkaFpBPT0iLCJ0b3RhbEZvdW5kIjo5NywidG90YWxSZXR1cm5lZCI6NX0="
      },
      "edges": [
        {
          "node": {
            "id": "QXNzZXQ6OTg5ZTZmY2MtNTZhNC00ZjVmLTkyOGQtNTRkNGNiZWIxNWZj",
            "name": "icon-laptop-image-light-salmon"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6NmZmOWQwNTktZWEyMi00MjkxLTkwOWItMzgyNjMyN2UzYjZl",
            "name": "icon-laptop-streaming-media-light-salmon"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6ODdkNGU5OGMtMGY5Yi00YTBmLTg2NDMtZjZmM2IxZjgxNzMy",
            "name": "woman-laptop-celebrate"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6NDgzYzk5OWMtYzYwOS00ZGRhLWE4NTktNzBlNDExZGFhMDA0",
            "name": "icon-laptop-image-dark"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6OTY0NTI5YTEtM2JhMC00MGEzLTk1ZDUtMmJmYzhjMmYxN2Fk",
            "name": "icon-laptop-image-light"
          }
        }
      ]
    }
  }
}

Examples: single and multiple term phrases

A phrase is a group of words surrounded by double quotes such as "extra small". Using the assetSearch API, you can also search for assets by phrases as well as keywords.

For example, if we wanted to search for all assets that contains the phrase woman in, we would do this by using double-quotes escaped with a backslash, as demonstrated below:

{
  assetSearch(keyword: "\"woman in\"", first: 5, sort: { createdDate: DESC }) {
    total
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        name
      }
    }
  }
}

Searching for a phrase returns a more exact match than searching for two keyword terms separated by a space, which would otherwise produce partial results.

As seen in the response below, we receive a result that has assets that includes the exact keyword phrase woman-in. These results vary from woman-in-winter-coat to woman-in-blue-dress-on-beach:

{
  "data": {
    "assetSearch": {
      "total": 17,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJtYXJrZXIiOiJBb044N0lyeSsvY0NDRUg3KzRnL0JXTTVOems0TlRSa0xUVXpPVFF0TkRrNE5DMDRNR0ZqTFRWa1ltUmlZek01WWpGa1pnPT0iLCJ0b3RhbEZvdW5kIjoxNywidG90YWxSZXR1cm5lZCI6NX0="
      },
      "edges": [
        {
          "node": {
            "id": "QXNzZXQ6MWMzYTUzNDUtM2I1Yi00ZjdmLThjNWItOTY0ZDBlYWE4ZDI1",
            "name": "woman-in-winter-coat"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6OWU2YjM4ZjUtN2FjZC00MjJhLWIwZWEtMjE4MWRiNzU3MmI0",
            "name": "woman-in-blue-dress-on-beach"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6MzcxMWYyNGEtNzE5MS00ZjM2LWJmZjUtNTM4YzFkMjY5MDli",
            "name": "woman-in-chair"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6NjA5MDI1ZTQtY2MxMS00ZTVlLWE5ZDctZTFmMDFkZjZiYWJm",
            "name": "woman-in-clothes-shop"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6Yzk3OTg1NGQtNTM5NC00OTg0LTgwYWMtNWRiZGJjMzliMWRm",
            "name": "woman-in-coat-and-brown-hat"
          }
        }
      ]
    }
  }
}

If you would like to search by multiple phrases (or a phrase plus a term), use double-quotes escaped with a backslash, separating them with a space. Here we are searching for the phrase winter coat alongside the keyword term spring:

{
  assetSearch(
    keyword: "\"spring\" \"winter coat\""
    first: 5
    sort: { createdDate: DESC }
  ) {
    total
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        name
      }
    }
  }
}

We receive results from the above query that show assets exclusively containing the phrase winter coat or spring:

{
  "data": {
    "assetSearch": {
      "total": 22,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJtYXJrZXIiOiJBb053eXErMWkvZ0NDRUdQN2lJL0JXRXlZbVF6TVRnNUxUSXpOekl0TkRZMU5TMDRaVEJqTFdOaE5URmxaR000T0dGaFpBPT0iLCJ0b3RhbEZvdW5kIjoyMiwidG90YWxSZXR1cm5lZCI6NX0="
      },
      "edges": [
        {
          "node": {
            "id": "QXNzZXQ6Mzg4MDY0MWEtNjQ3Zi00Nzg5LThmMjQtOGUxN2Q4MzBiN2Vi",
            "name": "white-top-spring"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6MzM3Yjc5NjEtYmEwYi00Njg0LWJmM2ItMDBmYTk4Yzc4ODk1",
            "name": "blue-coat-spring"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6MWMzYTUzNDUtM2I1Yi00ZjdmLThjNWItOTY0ZDBlYWE4ZDI1",
            "name": "woman-in-winter-coat"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6ZDBlYmZlZWItMmY5Yi00YjNjLWI1YjMtZWNiZWZjNTY0Y2Zk",
            "name": "man-in-winter-coat-video"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6YTJiZDMxODktMjM3Mi00NjU1LThlMGMtY2E1MWVkYzg4YWFk",
            "name": "spring-collection-set"
          }
        }
      ]
    }
  }
}

note

Searches are only scoped to the asset stores that you already have access to. Keyword searches are scoped to search against the SearchableFields listed below.

Modifiers

Modifier	Description
*	The sole use of this wildcard modifier is supported. It can be used on it's own or in middle of query or at the end of query.
> 0 character searches	Searches for multiple characters (searches with zero or more sequential characters) are supported. However, partial matches will be returned by default so a wildcard is not needed at the end of a term unless the fields parameter is used.
?	The use of this modifier is unsupported and will return an invalid character error.
leading *	A term or phrase beginning with a leading asterisk is not be supported.
wildcard on it's own	You can use any other wildcard modifier on it's own in your search.

Wildcards

When searching for assets using assetSearch, you can also make use of wildcard syntax within your query. Wildcards are made up of modifier characters that allow you to find assets in a more succinct manner.

It should be noted, however, that if you need to use a wildcard after a special character, you must specify a field with your query. A field can contain any of the following descriptors:

• NAME
• FILENAME
• assetsS
• TAG_CASE_SENSITIVE
• MIME TYPE
• TAGS
• LABEL

If you do not specify a field, a wildcard character cannot be used at the end of a query if it’s preceded by special characters, numbers or punctuation characters like _. For exact queries using wildcards it is recommended to use the fields parameter.

For example, in the below query, we are searching for any assets that has the key phrase preview- followed by anything else. To make this query more concise, we use the wildcard modifier * to denote that we want anything to follow after the key phrase we just specified.

{
  assetSearch(
    keyword: "preview-*"
    fields: FILENAME
    first: 100
    sort: { createdDate: DESC }
  ) {
    total
    edges {
      node {
        id
        assetId
        name
        createdDate
        updatedDate
        lastPublishDate
      }
    }
  }
}

To make this query work, we must specify a field in our query, or run the query without the preview- preceding the wildcard character, as by default we will return partial matches. This is because wildcards are accepted on their own.

If we do not specify the fields in our query, our results will come back as the below, showing that our search was invalid and produces no results:

{
  "data": {
    "assetSearch": {
      "total": 0,
      "edges": []
    }
  }
}

In another example, we see that using a wildcard after a dot for any file extension works only when you specify a field in your query:

{
  assetSearch(
    keyword: "blue-*.*"
    fields: FILENAME
    first: 100
    sort: { createdDate: DESC }
  ) {
    total
    edges {
      node {
        id
        assetId
        name
        createdDate
        updatedDate
        lastPublishDate
      }
    }
  }
}

Booleans

Supported Boolean	Description
AND	AND requires both terms on either side of the Boolean operator to be present for a match. e.g. navigation AND footer
OR	OR requires that either term (or both terms) be present for a match. This is the default behaviour if two terms or phrases are included in the keyword.
NOT	The use of this Boolean character is supported regardless of use.
+	Requires only the secondary term to be present for a match. Note that this Boolean only works at the start of the term or phrase. A + symbol in the middle of a term will be treated as part of the search term. e.g. if you would like to search for assets that must contain the keyword XS, you can use : +XS
-	Matches on assets that does not include the term following the - symbol. Note that this works at the start of the term or phrase, not in the middle. A - symbol in the middle of a term will be treated as part of the search term. e.g. if you would like to search for assets that must not contain the keyword v1, you can use: -v1

Parentheses

Parentheses can also be used if you would like to include subqueries within your search query. In the example query below, we include Booleans within a subquery that uses parentheses to demonstrate that we're searching for assets that must contain either winter or woman and coat.

{
  assetSearch(
    keyword: "(winter or woman) AND coat"
    first: 100
    sort: { createdDate: DESC }
  ) {
    total
    edges {
      node {
        id
        assetId
        name
        createdDate
        updatedDate
        lastPublishDate
      }
    }
  }
}

It should be noted that fields should not be specified in search queries that use parentheses and booleans.

Escaping special characters

It should be noted that we only support the use of double quotes (") to escape special characters. The use of backslashes are unsupported (\).

Using Fields

Fields can be used to scope the keyword search to search in specific fields. If not specified, all SearchableFields will be searched, as follows:

• NAME
• LABEL
• FILENAME
• TAGS
• TAGS_CASE_SENSITIVE
• MIME_TYPE
• assetsS

Ascending or descending sort

All search results are sorted in descending order by default. Descending order is also added a tiebreaker automatically when using other sorts, unless overridden by the sort query.

Filters

Filter can be used to return a subset of your query results. For example, a single filter can be used to return only your unpublished assets with the inclusion of filters:

{
  assetSearch(
    keyword: "woman*"
    filters: { published: false }
    first: 100
    sort: { createdDate: DESC }
  ) {
    total
    edges {
      node {
        id
        assetId
        name
        createdDate
        updatedDate
        lastPublishDate
      }
    }
  }
}

You can also use multiple filters in your query with the AND operator to ensure results are filtered down. In the following example, we're using filters to query for all unpublished assets that are tagged blue:

{
  assetSearch(
    keyword: "*"
    filters: { tags: ["blue"], published: false }
    first: 100
    sort: { createdDate: DESC }
  ) {
    total
    edges {
      node {
        id
        assetId
        name
        createdDate
        updatedDate
        lastPublishDate
      }
    }
  }
}

This gives us the following result:

{
  "data": {
    "assetSearch": {
      "total": 1,
      "edges": [
        {
          "node": {
            "id": "QXNzZXQ6MzM3Yjc5NjEtYmEwYi00Njg0LWJmM2ItMDBmYTk4Yzc4ODk1",
            "assetId": "337b7961-ba0b-4684-bf3b-00fa98c78895",
            "name": "blue-coat-spring",
            "createdDate": "2023-03-20T11:12:05.752Z",
            "updatedDate": "2023-07-04T11:07:06.548Z",
            "lastPublishDate": null
          }
        }
      ]
    }
  }
}

As shown from the results, we are shown assets that is tagged as blue AND unpublished - ie. (tags:blue)AND(published:false)

Similarly, we can also use an array of values within a filter to mimic the usage of the OR operator, so that all possible results are displayed for both specified terms in our search. For example, if we wanted to filter our search results by all assets that is tagged either blue or yellow, we would do the following:

{
  assetSearch(
    keyword: "*"
    filters: { tags: ["blue", "yellow"] }
    first: 100
    sort: { createdDate: DESC }
  ) {
    total
    edges {
      node {
        id
        assetId
        name
        createdDate
        updatedDate
        lastPublishDate
      }
    }
  }
}