Simple GraphQL query filter expressions

You can create a simple filter expression for basic filtering.

A simple filter expression is a comma-separated list of one or more of the following:
One or more item types

This filter item is not available for the componentPresentations() query, because this query already has its item type implicitly set to Component Presentation.

This is the string itemTypes: followed by a comma-separated list of item type names in all caps, enclosed in square brackets. An item type name is one of the following: PUBLICATION, PAGE, COMPONENT, KEYWORD or TEMPLATE. Omitting a list of item types means that items of all item types will be queried.

Namespaces

In an items() query, this is the string namespaceIds: followed by a comma-separated list of namespace identifiers, enclosed in square brackets. Only 2 namespace IDs are available: 1, representing Tridion Sites, or 2, representing Tridion Docs. Omitting a list of namespaces means that both namespaces will be queried.

In a componentPresentations() query, this is the string namespaceId: followed by a namespace identifier.

Publications

In an items() query, this is the string publicationIds: followed by a comma-separated list of Publication identifiers, enclosed in square brackets. Publication IDs are not guaranteed to be unique across both products, so you may need to include the namespaceIds filter in order to resolve any ambiguity. Omitting a list of Publications means that all Publications will be queried.

In a componentPresentations() query, this is the string publicationId: followed by a Publication identifier.

Zero or more custom metadata key-value pairs

These are zero or more instances of customMeta: { CUSTOMMETAFILTER } in which CUSTOMMETAFILTER contains at least a key-value pair, like so: key: KEYNAME, value: KEYVALUE, where KEYNAME is the custom metadata property you want to filter on, and KEYVALUE is the value it should be set to.

In addition to the key-value pair itself, you can also add the following:
scope

Before the key-value pair, use scope: to indicate which item should have this Keyword set to this value. By default, the query assumes that you want the key-value pair to be present in the returned item itself. But you can also explicitly set it to Publication, if you are fetching items that are not Publications, to indicate that the Publication containing the item must have the key-value pair, or to ItemInPublication, if you are fetching items that are Publications, to indicate that at least one item within the Publication (not the Publication itself) must have they key-value pair.

valueType

After the key-value pair, you can add valueType: followed by the data type of the value, one of FLOAT, NUMBER or DATE. If left unspecified, valueType defaults to the value STRING.

Zero or more Taxonomy Keywords
These are zero or more instances of one of the following:
  • keyword: { categoryName: CATNAME, key: KEYNAME }
  • keyword: { categoryId: CATID, keywordId: KEYID }

In the first case, the Category and Keyword are identified by name; in the second, by ID (which can be necessary if multiple Keywords (or multiple Categories) have the same name.

A Schema ID or title

You can specify that the items being retrieved must be based on a specific Schema by adding one of the following:

schema: {
  id: SCHEMAID
}

where SCHEMAID is the unique identifier of the Schema on which you want to filter.

schema: {
  title: SCHEMATITLE
}

where SCHEMATITLE is the title (not guaranteed to be unique) of the Schema on which you want to filter.

(If you specify both properties under the same schema property, and the two don't refer to the same Schema, the title attribute is ignored.)

A Component Template (for componentPresentations() query only)
You can specify that the Component Presentations being retrieved must have been rendered using a specific Component Template by adding the following:
template: {id: TEMPLATEID}

where TEMPLATEID is the unique identifier of the Component Template on which you want to filter.

A date range for a Component (for componentPresentations() query only)
You can specify that the Components being rendered as the Component Presentations being retrieved must have been created, updated, first published or most recently published within a specified date range:
dateRange: {type: EVENTTYPE, start: STARTTIMESTAMP, end: ENDTIMESTAMP}
In this complex property, EVENTTYPE is one of the following:
Value for typeDescription
CREATION_DATEThe moment when the Component was created
UPDATED_DATEThe moment when the Component was most recently modified
INITIAL_PUBLISH_DATEThe moment when the Component was first published
LAST_PUBLISH_DATEThe moment when the Component was most recently published

STARTTIMESTAMP and ENDTIMESTAMP are timestamps in the UTC date-time format (ISO 8601).