UGC Query
Last updated
Last updated
Support us as a and get instant access to all our assets, exclusive tools and assets, escalated support and issue tracking and our gratitude. These articles are made possible by our ... become a sponsor today!
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 which can its self simplify UGC query even further.
As with anything User Generated Content the process of querying records is done in stages. The raw API requires the following steps.
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.
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
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.
We have created a number of Get methods you can use to quickly construct a UgcQuery to meet your needs.
The first form of the Get method can be used with any type of query and simply gets a query ready for you to further modify.
This form of the Get method takes one or more file IDs you would like to get more information on. This can be useful when already have a set of known file IDs such as the users subscribed IDs. You can also pass in a list or array of file IDs you would like to query.
This option lets you create a query that looks for items related to a specific user or account.
Creates a query to get all the published files related to the local user.
The same as calling Get(fileIds) on the set of subscribed files the local user is subscribed to. This is the easiest way to get the details about all the workshop items this user is currently using.
Gets the set of workshop items the local player has played
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.
The number of matched records. This will be 0 untill the query is executed and should not be updated manually.
The number of pages found for this query. This will be 0 until the query is exeucted and should not be updated manually.
This will be populated with the results when the query is executed ... assuming there are results to populate.
Adds a excluded tag to a pending UGC Query. This will only return UGC without the specified tag.
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.
Adds a required tag to a pending UGC Query. This will only return UGC with the specified tag.
Set allow cached response from UGC Query
Set the cloud file name filter value
Sets the query item language
Sets the query match any tag
Sets the query to rank by trend over the indicated days
Should the query return additional previews or just the main
Should the query return child items or just the main
Should the query return key value tags
Should the query return the long description of the item
Should the query return metadata
Should the query only return item IDs
Over what set of days should paly time stats be returned
Should the query only return the matching count and not item data at all
Sets the search text to be used by the query
Advances the active page forward by 1 if available
Steps back to the previous page if available
Sets the query to the indicated page
Executes the given query and registers a callback to catch its results
Releases the query handle, this should be called when done with a query. This is automatically called when the object is disposed.
Deconstructs the query and frees its handles
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 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 field or by calling . When the page is set the existing handle will be released and a new handle created.
This indicates the current page the query is reading. Setting this value calls the method.
See for more info on how to use the items returned.
