Links

UGC Query

Like what your seeing?

Consider supporting us as a GitHub Sponsor and get instant access to all our Unity assets, exclusive tools and assets, escalated support and issue tracking and our gratitude. These articles are made possible by our GitHub Sponsors ... become a sponsor today!

Introduction

Designed to simplify the act of querying User Generated Content aka Workshop items from Steam this object can be used to create and manage queries.
The intended use is that a query will be created through one of the static Create methods to properly initialize the base query and you can then use simple calls on the object to modify the query, execute the query and step through query pages.
This is used by the UGC Query Manager which can its self simplify UGC query even further.

Understanding UGC Queries

As with anything User Generated Content the process of querying records is done in stages. The raw API requires the following steps.
Note our UGC Query tool simplifies this for you but understanding what is happening under the hood can be helpful when debugging.

Handle

First we have to create a query handle, this is a pointer to a configuration that Valve will use when searching available UGC items. The handle is created as one of 3 types of query handles
  • All Request No base filter these types of queries return all manner of UGC items. These queries use paging pulling back up to 50 at a time
  • Details Request These queries take file IDs in as part of the argument and do not using paging. They only return the items you directly ask for.
  • User Request These queries return items related to a given user such as a friend or your self
You will notice Heathen's UGC Query doesn't ask you what type you want. We can infer what type is needed based on the arguments you pass in on the UgcQuery.Create method.

Settings

Once you have a handle you can apply various settings to it. For example you can set the language, add tags to filter on, etc. The available settings can be accessed via the methods we describe below

Execution

Finally once we have a handle and have configured it we need to execute the query. Note that query types All and User have pages so when you execute you may only receive a part of the total count. The pageCount field will tell you how many pages this query has once it has been executed at least once. You can set the page by simply setting the Page field or by calling SetPage. When the page is set the existing handle will be released and a new handle created.

Release

Note we release the handle for you at the end of each execution. This means you cannot execute the same query twice, but it also means that when you forget to dispose ... Heathen has you covered. What if you want/need to execute the same query twice? You need to rebuild the query to do that and you can do that easily by simply calling the "Create" method again or setting the page value, even if you set it to the same value it will rebuild the same query.
You should have noticed that the UgcQuery is a "Disposable" object. This means it needs to be cleaned up when your done with it and we made that easy to do. You could simply let the .NET garbage collector handle this but its advisable to call it your self
myQuery.Dispose();
This will release any open handle insure all references are free.

Definition

public class UgcQuery : IDisposable

Static Methods

These are inteded to be how you create a new UgcQuery object. Each creates a corisponding type of query.

General Query

General use query common for example when browsing all available items
public static UgcQuery Create(EUGCQuery queryType,
EUGCMatchingUGCType matchingType,
AppId_t creatorApp,
AppId_t consumerApp)
  • queryType The type of query to run, see EUGCQuery for more details.
  • matchingType Used to specify the type of UGC queried for. See EUGCMAtchingUGCType for more details.
  • creatorApp Filter by the app that created the item
  • consumerApp Filter by the app the item is created for

File Query

Returns specific files back defined by ID. Use this to get the details on a set of published file IDs such as when returning the list of subscribed items
public static UgcQuery Create(IEnumerable<PublishedFileId_t> fileIds);
  • fileIds The collection of IDs to search for

User Query

Returns items relive to the given user account e.g. the favourited files or followed files
public static UgcQuery Create(AccountID_t account,
EUserUGCList listType,
EUGCMatchingUGCType matchingType,
EUserUGCListSortOrder sortOrder,
AppId_t creatorApp,
AppId_t consumerApp)
or
public static UgcQuery Create(UserData user,
EUserUGCList listType,
EUGCMatchingUGCType matchingType,
EUserUGCListSortOrder sortOrder,
AppId_t creatorApp,
AppId_t consumerApp)
  • account or user This is the user account to search for, we can read the account from the UserData if provided.
  • listType The type of list to return ... see EUserUGCList for more details
  • matchingType Used to specify the type of UGC queried for. See EUGCMAtchingUGCType for more details.
  • sortOrder How should the results be sorted. See EUserUGCListSortOrder for more details.
  • creatorApp Filter by the app that created the item
  • consumerApp Filter by the app the item is created for

Fields and Attributes

handle

public UGCQueryHandle_t handle
The active query handle if any. This can be used to modify the query acter creating it. In most cases you wont need to use this directly.

matchedRecordCount

public uint matchedRecordCount
The number of matched records. This will be 0 untill the query is executed and should not be updated manually.

pageCount

public uint pageCount
The number of pages found for this query. This will be 0 until the query is exeucted and should not be updated manually.

Page

public uint Page { get; set; }
This indicates the current page the query is reading. Setting this value calls the SetPage method.

ResultList

public List<UGCCommunityItem> ResultsList
This will be populated with the results when the query is executed ... assuming there are results to populate.
See UGCCommunityItem for more info on how to use the items returned.

Methods

AddExcludedTag

public bool AddExcludedTag(string tagName);
Adds a excluded tag to a pending UGC Query. This will only return UGC without the specified tag.

AddRequiredKeyValueTag

public bool AddRequiredKeyValueTag(string key, string value);
Adds a required key-value tag to a pending UGC Query. This will only return workshop items that have a key = pKey and a value = pValue.

AddRequiredTag

public bool AddRequiredTag(string tagName)
Adds a required tag to a pending UGC Query. This will only return UGC with the specified tag.

SetAllowCachedResponce

public bool SetAllowCachedResponse(uint maxAgeSeconds)
Set allow cached response from UGC Query

SetCloudFileNameFilter

public bool SetCloudFileNameFilter(string fileName)
Set the cloud file name filter value

SetLanguage

public bool SetLanguage(string language);
Sets the query item language

SetMatchAnyTag

public bool SetMatchAnyTag(bool anyTag)
Sets the query match any tag

SetRankedByTrendDays

public bool SetRankedByTrendDays(uint days);
Sets the query to rank by trend over the indicated days

SetReturnAdditionalPreviews

public bool SetReturnAdditionalPreviews(bool enable);
Should the query return additional previews or just the main

SetReturnChildren

public bool SetReturnChildren(bool enable);
Should the query return child items or just the main

SetReturnKeyValueTags

public bool SetReturnKeyValueTags(bool enable);
Should the query return key value tags

SetReturnLongDescription

public bool SetReturnLongDescription(bool enable);
Should the query return the long description of the item

SetReturnMetadata

public bool SetReturnMetadata(bool enable);
Should the query return metadata

SetReturnOnlyIDs

public bool SetReturnOnlyIDs(bool enable);
Should the query only return item IDs

SetReturnPlaytimeStats

public bool SetReturnPlaytimeStats(uint days);
Over what set of days should paly time stats be returned

SetReturnTotalOnly

public bool SetReturnTotalOnly(bool enable);
Should the query only return the matching count and not item data at all

SetSearchText

public bool SetSearchText(string text);
Sets the search text to be used by the query

SetNextPage

public bool SetNextPage();
Advances the active page forward by 1 if available

SetPreviousPage

public bool SetPreviousPage();
Steps back to the previous page if available

SetPage

public bool SetPage(uint page);
Sets the query to the indicated page

Execute

public bool Execute(UnityAction<UgcQuery> callback);
Executes the given query and registers a callback to catch its results

ReleaseHandle

public void ReleaseHandle();
Releases the query handle, this should be called when done with a query. This is automatically called when the object is disposed.

Dispose

public void Dispose();
Deconstructs the query and frees its handles