Use case: Search assets in a project

You can use the Unity Cloud Assets package to filter assets in a Project based on a set of search criteria.

Organization or Asset Manager Project role Search
Asset Management Viewer yes
Asset Management Consumer yes
Asset Management Contributor yes
Organization Owner yes

How do I...?

Built-in Search Filter

The Unity Assets package provides a built-in search filter that you can use to search for assets: the AssetSearchFilter class. The AssetSearchFilter class provides the set of properties that can be used to filter assets.

Create a new search filter

You can create a new search filter by instantiating the AssetSearchFilter class, like so:


var assetSearchFilter = new AssetSearchFilter();

The filter provides 3 methods for searching assets:

  • Include() - The properties added here must match the value.
  • Exclude() - The properties added here must not match the value.
  • Any() - The properties added here may match the value. This represents an OR operation to be applied on all properties added via the Any() method.

To compute the search results, you can use the QueryAssets method of an IAssetProject, like so:


var results = project.QueryAssets()
    .SelectWhereMatchesFilter(assetSearchFilter)
    .OrderBy(nameof(IAsset.Name), SortingOrder.Descending)
    .LimitTo(Range.EndAt(10))
    .ExecuteAsync(CancellationToken.None);

In this example, only the first 10 results will be returned and are sorted by the asset name in ascending order. The execution of the query returns an awaitable IAsyncEnumerable that will return each IAsset result.

The results can be iterated over using a foreach loop and used as they become available, like so:


await foreach (var asset in results)
{
    Debug.Log(asset.Name + " is available for use.");

    // Do something with each `asset` as it becomes available.
}

Alternatively, the results can be iterated over and compiled into a list, so that the complete set of results can be used, like so:


var assetList = new List<IAsset>();
await foreach (var asset in results)
{
    assetList.Add(asset);
}

return assetList;

Search by Name

  • You can search for assets by name using the Name property of the AssetSearchFilter.Include(), like so:

assetSearchFilter.Include().Name.WithValue("my cool asset");
Note

This type of search checks for assets whose entire name exactly matches the parameter.

  • You can also exclude assets by name, like so:

assetSearchFilter.Exclude().Name.WithValue("my mediocre asset");
  • You can also search for assets whose name contains a specific string, like so:

assetSearchFilter.Any().Name.WithValue("cool");

Search by Tags

You can search for assets by tag using the Tags property of the AssetSearchFilter class, like so:


assetSearchFilter.Include().Tags.WithValue("tag1", "tag2", "tag3");
Note

This type of search checks for assets whose tag list contains all the included parameters.

Filter by Collections

You can search for assets in specific collections by adding them to the search filter's list of collections, like so:


assetSearchFilter.Collections.WhereContains("my awesome collection", "my other awesome collection");

Custom Search Filter

You can also create a custom search filter by implementing the IAssetSearchFilter interface.