API Filter path overview

Flow Production Tracking
,
1

Hi,

I haven’t found information about the filter path to provide to a GET request, and I was wondering if there is an overview over the types, or a way to get the correct path.

E.g. with the request below, the path I’m using in the filter is “project.Project.name”.

curl -X GET https://dena901.shotgunstudio.com/api/v1/entity/CustomEntity03\?fields\=\*\&filter\[project.Project.name\]\=$ProjectName \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $AuthToken'

Cheers.

3 Likes
2

Hi @ChristianHelmich,

Here is detail of filtering. Is this you are looking for?

curl -X GET https://yoursite.shotgunstudio.com/api/v1/entity/assets?filter[sg_status_list]=ip&filter[sg_asset_type]=Prop,Character,Environment&filter[shots.Shot.code]=bunny_010_0020 \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

Thanks

Loney

4 Likes
3

Err, thanks but that’s not really what I’m looking for. What I search is the part you put in the filter brackets, e.g. for filter[shots.Shot.code] the shots.Shot.code part.

Is this information I can get from the schema by querying as explained below?
https://developer.shotgunsoftware.com/rest-api/#read-schema-for-all-entities

Cheers.

2 Likes
6

Hey Christian!

If I understand your question correctly, you’re looking for a way to navigate from one entity to another via the filter?

Essentially, the paths that exist do so because of the presence of linked fields on an entity. In your example, it’s easy to get an asset’s project by looking at project.Project.name.

In regards to the notation, here’s a breakdown in case you haven’t grokked it yet:

  1. project: for the entity you’re linking through, its entity field whose name is project. In your case, it’s the Asset field called project.
  2. Project: an entity field can link through multiple kinds of entities (though it doesn’t always), so here we declare what kind of entity we’re looking for. In this case, a Project entity.
  3. name: for the Project entity, we’re looking to filter on its name, and that field is obviously called name.

So your query is asking for all Assets whose Project’s name is $ProjectName.

If you want to construct other linked field queries, you’d need to follow a path of linked entity fields in order to arrive at your destination. If two entities aren’t linked by an entity field, you won’t be able to get from one to the other.

You’re correct that you can infer relationships by reading the schema, but there’s a torrent of information to digest and it can be a little hard to sift through to what you need. Here’s the result of a schema field read for the Asset’s project field:

>>> sg.schema_field_read("Asset",'project')
{'project': {'mandatory': {'editable': False, 'value': False}, 'name': 
{'editable': True, 'value': 'Project'}, 'data_type': {'editable': False, 
'value': 'entity'}, 'entity_type': {'editable': False, 'value': 'Asset'}, 
'custom_metadata': {'editable': True, 'value': ''}, 'editable': 
{'editable': False, 'value': True}, 'ui_value_displayable': 
{'editable': False, 'value': True}, 'visible': {'editable': False, 
'value': True}, 'unique': {'editable': False, 'value': False}, 
'properties': {'default_value': {'editable': False, 'value': None}, 
'summary_default': {'editable': True, 'value': 'none'}, 'valid_types': 
{'editable': True, 'value': ['Project']}}, 'description': 
{'editable': True, 'value': ''}}}

important keys here are data_type and valid_types. data_type should be entity or multi_entity, you can follow those. valid_types will tell you what kind of entities can be linked to that field.

You can also use this ‘dot notation’ in the fields that you request. However, an important caveat: while you can filter through a multi-entity field, you can’t query the field data on a multi-entity field, because we can’t know which entity you’re trying to query through (since there can be many).

for instance, this is valid:

# sg_task_group is an entity field that links to one Group that a Task 
# belongs to
>>> sg.find("Task",
    [['sg_sequence','is_not',None]],
    ['sg_task_group.Group.code'])
[{'type': 'Task', 'id': 9289, 'sg_task_group.Group.code': 'lavagroup'}]

but this is not:

# sg_supervisors is a multi-entity field that can belong 
# to multiple HumanUsers
>>> sg.find("Task",
    [['sg_supervisors','is_not',None]],
    ['sg_supervisors.HumanUser.name'])
[{'type': 'Task', 'id': 9289}]
# we don't get `HumanUser.name` back, because we can't know which 
# 'name' of the potentially multiple supervisors in that field 
# should be returned.

Also, if you want to know a little more about how linked entities work, we have a fantastic series of Producer Training videos, and this one specifically talks about the subject:

I hope this helps!

4 Likes
8

Also, just for clarity, I’m changing the subject line from “REST API Filter path overview” to “API Filter path overview”, since it’s not actually a REST-specific topic :slight_smile:

2 Likes
10

Thanks. This helps a lot.

4 Likes