Parents

GraphQL can significantly enhance the power of your API Integration. To onboard, please reach out to your Account Manager for pricing information.

Parents is a field on the Entity root type that represents the entity's associated parent records. Parents is an array of type Entity, and is specified by passing a char type ID parameter.

{
    entity(id: 10, charTypeId: 3) {
       parents(charTypeId: 4) {
            items {
                 id
                 title
                 template {
                      templateId
                 }
            }
       }   
    }
}

The Parents field is especially powerful because it allows you to traverse a record's hierarchy. You can include multiple Parents fields for each entity to represent different char types, and each Parent Entity can have its own Parents field. Chaining together the Parents fields allows you to traverse an entire record's hierarchy in a single request.

In the example below, we are retrieving a Rights record, it's parent Catalog records, and those Catalog's parent Deal records.

{
    entity(id: 10, charTypeId: 3) {
       parents(charTypeId: 1) {
            items {
                 id
                 title
                 template {
                      templateId
                 }
                 parents(charTypeId: 4) {
                      items {
                           id
                           title
                           template {
                                templateId
                           }
                      }
                 }
            }
       }    
    }
}

Response:

{
    "data": {
        "entity": {
            "parents": {
                "items": [
                    {
                        "id": 100,
                        "title": "Catalog 1",
                        "template": {
                            "templateId": 1
                        }
                        "parents": {
                            "items": [
                                {
                                    "id": 400,
                                    "title": "Deal 1",
                                    "template": {
                                        "templateId": 1
                                    }
                                },
                                {
                                    "id": 401,
                                    "title": "Deal2",
                                    "template": {
                                        "templateId": 2
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "id": 101,
                        "title": "Catalog 2",
                        "template": {
                            "templateId": 2
                        }
                        "parents": {
                            "items": []
                        }
                    }
                ]
            }
        }
    }
}

Aliasing

When using multiple Parents fields for different char types, it is necessary to keep track of what a certain Parents field represents by using an Alias. Adding an alias to a field will rename the response Parents field with the desired alias name.

In the below example, catalog is added as an alias for parent records with char type ID = 1 and deals is added an alias for parent records with a char type ID = 4.

{
    entity(id: 10, charTypeId: 3) {
       catalog: parents(charTypeId: 1) {
            items {
                 id
                 title
                 template {
                      templateId
                 }
            }
       } 
       deals: parents(charTypeId: 4) {
            items {
                 id
                 title
                 template {
                      templateId
                 }
            }
       }    
    }
}

Response:

{
    "data": {
        "entity": {
            "id": 10,
            "title": "Right 1",
            "template": {
                "templateId": 1
            },
            : {
                "items": [
                    {
                        "id": 100,
                        "template": {
                            "templateId": 1
                        },
                        "title": "Catalog 1"
                    },
                    {
                        "id": 101,
                        "template": {
                            "templateId": 2
                        },
                        "title": "Catalog 2"
                    }
                ]
            },
            : {
                "items": [
                    {
                        "id": 200,
                        "template": {
                            "templateId": 1
                        },
                        "title": "Deal 1"
                    },
                    {
                        "id": 201,
                        "template": {
                            "templateId": 2
                        },
                        "title": "Deal 2"
                    }
                ]
            }
        }
    }
}

Paging

To limit response sizes, the Parents field utilizes paging. To page through the children records, use the skip and take parameters:

{
    entity(id: 10, charTypeId: 3) {
       deals: parents(charTypeId: 4, : 10, : 10) {
            items {
                 id
                 title
                 template {
                      templateId
                 }
            }
       }  
    }
}

The default page size is 50.

There are also additional fields in the request that help to identify the total number of Parents records (totalCount), if a previous page exists (hasPreviousPage), and if a next page exists (hasNextPage). hasPreviousPage and hasNextPage are nested in a pageInfo object on the Parents object:

{
    entity(id: 10, charTypeId: 3) {
       deals: parents(charTypeId: 4, skip: 10, take: 2) {
            
            pageInfo {
                 hasPreviousPage
                 hasNextPage
            }
            items {
                 id
                 title
                 template {
                      templateId
                 }
            }
       }  
    }
}

Response:

{
    "data": {
        "entity": {
            "id": 10,
            "title": "Right 1",
            "template": {
                "templateId": 1
            },
            "deals": {
                "totalCount": 24,
                "pageInfo": {
                    "hasPreviousPage": true,
                    "hasNextPage": true
                },
                "items": [
                    {
                        "id": 100,
                        "template": {
                            "templateId": 1
                        },
                        "title": "Deal 1"
                    },
                    {
                        "id": 101,
                        "template": {
                            "templateId": 2
                        },
                        "title": "Deal 2"
                    }
                ]
            }
        }
    }
}

Using these fields and parameters, you can page through the Parents in subsequent requests, using logic similar to:

if (pageInfo.hasNextPage)

skip = skip + take

Filtering

Parents can be filtered by using a special parameter object called where.

{
    entity(id: 10, charTypeId: 1) {
       parents(charTypeId: 4, where: {templateId: {eq: 1}}) {
            items {
                 id
                 title
                 template {
                      templateId
                 }
            }
       }  
    }
}

All of the following Entity fields can be filtered on in the Parents collection:

• title

• templateId

• statusId

• createdBy

• createdDate

• lastUpdatedBy

• lastUpdatedDate

• statusUpdatedBy

• statusUpdatedDate

String Filtering

String fields (title) can be filtered using the following operators:

operator	value type	description	usage
eq	String	exact match	{title: {eq: "Episode 1"}}
neq	String	doesn't match	{title: {neq: "Episode 1"}}
contains	String	substring match	{title: {contains: "Episode"}}
ncontains	String	doesn't contain substring match	{title: {ncontains: "Episode"}}
in	[String]	exact match one of the following	{title: {in: ["Episode 1", "Episode 2"]}}
nin	[String]	doesn't match any of the following	{title: {nin: ["Episode 1", "Episode 2"]}}
startsWith	String	string starts with	{title: {startsWith: "Episode"}}
nstartsWith	String	string doesn't start with	{title: {nstartsWith: "Episode"}}
endsWith	String	string ends with	{title: {endsWith: "Episode"}}
nendsWith	String	string doesn't end with	{title: {nendsWith: "Episode"}}

Comparable Filtering

Field types of bool, int, and DateTime such as templateId, statusId, createdBy, createdDate, lastUpdatedBy, lastUpdatedDate, statusUpdatedBy, statusUpdatedDate can be filtered using the following operators:

operator	value type	description	usage
eq	Int, Bool, DateTime	exact match	{templateId: {eq: 1}}
neq	Int, Bool, DateTime	doesn't match	{templateId: {eq: 1}}
in	[Int], [Bool], [DateTime]	matches one of the following	{templateId: {in: [1,2]}}
nin	[Int], [Bool], [DateTime]	doesn't match any of the following	{statusId: {nin: [1,2,3]}}
gt	Int, Bool, DateTime	greater than	{createdDate: {gt: "2023-06-27T16:07:08.570Z"}}
ngt	Int, Bool, DateTime	not greater than	{createdDate: {gt: "2023-06-27T16:07:08.570Z"}}
gte	Int, Bool, DateTime	greater than or equal	{createdDate: {gte: "2023-06-27T16:07:08.570Z"}}
ngte	Int, Bool, DateTime	not greater than or equal	{createdDate: {ngte: "2023-06-27T16:07:08.570Z"}}
lt	Int, Bool, DateTime	less than	{createdDate: {lt: "2023-06-27T16:07:08.570Z"}}
nlt	Int, Bool, DateTime	not less than	{createdDate: {nlt: "2023-06-27T16:07:08.570Z"}}
lte	Int, Bool, DateTime	less than or equal	{createdDate: {lte: "2023-06-27T16:07:08.570Z"}}
nlte	Int, Bool, DateTime	not less than or equal	{createdDate: {nlte: "2023-06-27T16:07:08.570Z"}}

and / or Filtering

All of the above operators can be combined using the and and or operators:

operator	description	usage
and	all conditions must be true	{ and: [ {lastUpdatedDate: {gt: "2023-06-27T16:07:08.570Z"}}, {templateId: {in: [1,2]}} ] }
or	one condition must be true	{ or: [ {lastUpdatedDate: {gt: "2023-06-27T16:07:08.570Z"}}, {templateId: {in: [1,2]}} ] }

Sorting

To sort the records in the response by a specific field, specify an order parameter:

{
    entity(id: 10, charTypeId: 1) {
       deals: parents(charTypeId: 4, order: [{ lastUpdatedDate: DESC }]) {
            items {
                 id
                 title
                 template {
                      templateId
                 }
            }
       }  
    }
}

You can sort by the following fields:

• id

• title

• createdBy

• createdDate

• lastUpdatedBy

• lastUpdatedDate

• statusUpdatedBy

• statusUpdatedDate

You can sort each of the fields above either ascending using ASC or descending using DESC.

You can also sort on a field and then by another field:

{
    entity(id: 10, charTypeId: 1) {
       deals: parents(charTypeId: 4, order: [{ lastUpdatedDate: DESC }, { id: ASC }]) {
            items {
                 id
                 title
                 template {
                      templateId
                 }
            }
       }  
    }
}