SearchItems

Important

Economy v2.0 Public Preview has released. Use these features to participate in the active development of our latest code, and provide feedback to the developers via the PlayFab Forum.

The SearchItems API executes a search against the public Catalog using the provided search parameters and returns a paged list of items.

At its most basic, the Search parameter is a plain-text fuzzy search against the Title, Description, Keywords, and Searchable String Display Properties fields. However Filter, OrderBy, and Select are OData Query additions that can be used to alter the search parameters. Search results can be filtered and ordered by any field in the search document (barring Title and Description).

More information on the OData Query Syntax can be found here

An example SearchItems request:

{
  "Search": "Pirates",
  "Filter": "Tags/any(t:t eq 'desert') and ContentType eq 'map'",
  "OrderBy": "lastModifiedDate asc",
  "ContinuationToken": "abc=",
  "Count": 2
}

A sample response:

{
    "code": 200,
    "status": "OK",
    "data": {
        "Items": [
            {
               <item metadata> 
            }
        ],
      "ContinuationToken": "MTA="
    }
}

Continuation Tokens

The ContinuationToken field that is returned from a search response can be passed into a search request to paginate through multiple counts of results.

Display Properties

Searches, filters, and orderings can be also done on specific DisplayProperties fields that are configured for custom search. Titles can configure their custom search and filter properties in the Display Properties Mappings setting in Game Manager.

Display Properties screenshot in Game Manager

When you add a field to DisplayProperties, it will create a new index for you in the database. Only documents added or updated after index creation will be included. If you need the Display Property to apply to all items, you'll need to republish the entire catalog.

DateTime, Double, and Queryable String display properties are queryable, these properties can be used in Filter and OrderBy statements.

Searchable String display properties are searchable, these properties will be queried with fuzzy search against the Search field. Searchable properties can't be used in Filter and OrderBy statements.

Titles are limited to five display properties of each type.

Warning

Display property mappings are stored as an indexed list of key-value pairs. Deleting existing display property mappings can shift indexes and break the behavior of all remaining properties. It is suggested to add an additional property rather than deleting or editing an existing one and you should avoid deleting property mappings unless absolutely necessary

Filter

The Filter parameter allows you to filter the collection of items returned by the search request. The expression specified with filter is evaluated against each Catalog Item in the results, and only items where the expression evaluates to "true" are included.

Filter supports OData logical operators and precedence using parenthesis:

  • Equal: ‘eq’
  • Not Equal: ‘ne’
  • Greater Than: ‘gt’
  • Greater than or Equal: ‘ge’
  • Less than: ‘lt’
  • Less than or Equal: ‘le’
  • Logical And: ‘and’
  • Logical Or: ‘or’
  • Logical Negation ‘not’

Filter doesn't support arithmetic operators or string functions.

The following are Filter examples:

Filtering by ContentType

  "Filter": "ContentType eq 'Sword'"

Filtering with Conjunctions

  "Filter": "rating/average gt 1 and rating/average lt 4"

Filtering with null values

OData supports a null type for filtering

"Filter": "rating eq null"

The above request returns all items with no reviews

Filtering by Creator ID

To filter by a specific creator, you should use the syntax title_player_account!<ID>

  "Filter": "creatorId eq 'title_player_account!C88F55C6A734B1DC'"

Filtering by Array fields

Filter also supports any() for filtering against arrays. For example: alternateIds/any(a: a/value eq ‘StoreOfferId’)

  "Filter": "tags/any(t: t eq 'featured')"

Filtering with Arrays and null checks

The filter below will check for any items that have a contents field with non-null values

  "Filter": "contents/any(content: content ne null)"

Note

By default, Search will NOT return contents for items unless specified with a Select statement. If the above query is run without a `"Select": "contents"`` statement, it will correctly apply the filter but all returned Search results will have empty content fields

Filtering by Display Properties

Filtering can only be done with queryable Display Properties

  "Filter": "DisplayProperties/DifficultyRating ge 5"

OrderBy

OrderBy is a comma-separated list used to sort search results.

  "OrderBy": "rating/average asc"

You can pass a secondary property to break sorting ‘ties’:

  "OrderBy": "rating/average asc, rating/totalCount desc"

Catalog items without a secondary value have an internal ‘score’ attribute that used for breaking ties. That scoring is based on the storage order in the underlying database and is constantly changing as items are added and removed.

OrderBy supports a handful of OData properties for ordering:

  • asc
  • desc

If you don't specify a direction, the default is ascending. If there are null values in the field, they appear first for asc and last for desc. If no OrderBy value is passed, a default id asc value is used.

The following are OrderBy examples:

Sorting by Title

Use the title/<LANG> parameter combined with asc or desc to indicate order preference.

  "OrderBy": "title/en-GB asc"

Use NEUTRAL to order by the neutral strings

  "OrderBy": "description/NEUTRAL desc"

Sorting by Display Properties

Sorting can only be done with queryable Display Properties

  "OrderBy": "DisplayProperties/DifficultyRating desc"

Select

By Default, Search returns a rich set of item metadata:

  • Id
  • Type
  • AlternateIds
  • Title (NEUTRAL or Accept-Language locale)
  • Description (NEUTRAL or Accept-Language locale)
  • Keywords (NEUTRAL or Accept-Language locale)
  • ContentType
  • Images (Thumbnail only)
  • Tags
  • CreationDate
  • LastModifiedDate
  • CreatorEntityKey (CreatorId in earlier API versions)
  • DisplayProperties

Only the neutral strings used in title and description are returned by default. If a Thumbnail image exists, it's returned by default. Each item is limited to only one image of a "Thumbnail" type.

With Select more fields can optionally be returned within the paged search results, including content metadata (contents), images, StartDate, EndDate and the full set of localized strings in title and description. If the select field is left empty, the search results will be a subset of the full document metadata, to facilitate faster load times.

This request would return the default item metadata in addition to the content and images:

"Select": "contents,images"

Selecting title, description, and/or keywords will return the full set of localized string data:

"Select": "title,description,keywords"

Localization

A locale can be passed into the Accept-Language header. Passing a locale causes all Title, Description, Keywords fields to return the locale by default or NEUTRAL if the item doesn't have that localization.

Limits

The complexity of search filter queries is limited per request. Expensive queries can be rejected and titles should ensure that they aren't attempting overly complicated queries. The following are examples of queries close to maximum complexity:

  • contentType eq 'testType' and tags/any(t: t eq 'blue') or tags/any(t: t eq 'green') or tags/any(t: t eq 'violet')
  • contents/any(c: c/minClientVersion gt '1.2.3' and c/maxClientVersion lt '4.5.6')

High complexity filter queries will throw a 400 error with a message: "The filter provided in the request does not meet the complexity requirements for source".

Escaping special characters

In order to use any of the special characters as part of the search text, escape the character by prefixing it with a double backslash (\\). For example, for a wildcard search on https://, where :// is part of the query string, you would specify "Search":"https\\:\\/\\/*". Similarly, an escaped phone number pattern might look like this \\+1 \\(800\\) 642\\-7676.

Special characters that require escaping: \+ - | ! ( ) { } [ ] ^ " ~ ? : \ /