Global Query Parameters

Most f the Cloud Studio app 📟 API Endpoint operations can be manipulated with the following parameters. It is important to understand them to get the most out of the platform.

Fields

Fields allows you to choose the fields that are returned in the current dataset. This parameter supports dot notation to request nested relational fields. You can also use a wildcard (*) to include all fields at a specific depth.

Get all top-level fields — *.
Get all top-level fields and all second-level relational fields — *.*.

Performance & Size

While the fields wildcard is very useful for debugging purposes, we recommend only requesting specific fields for production use. By only requesting the fields you really need, you can speed up the request, and reduce the overall output size.

Second Level Example

For this example, we'll get all top-level fields and second-level relational fields within images.

http

?*,images.*

First and Second Name Example

For this example, we'll get only the first_name and last_name fields.

http

?first_name,last_name

Third Level Example

For this example, we'll get all top-level and second-level relational fields, and third-level fields within images.thumbnails.

http

?*.*,images.thumbnails.*

Many-To-Any (Union Types)

Seeing that Many-to-Any (M2A) fields have nested data from multiple collections, it's not always safe or wanted to fetch the same field from every related collection. In M2A fields, you can use the following syntax to specify what fields to fetch from which related nested collection type.

Get Many-to-Any fields — ?fields=<m2a-field>:<collection-scope>.<field>.

Many-to-Any Fields Name Example

For this example, we'll have a collection pages with a many-to-any field called sections that points to headings, paragraphs, and videos. We only want to fetch title and level from headings, body from paragraphs and source from videos. We can achieve that by using:

sections.item:headings.title
sections.item:headings.level
sections.item:paragraphs.body
sections.item:videos.source

In GraphQL, this can be achieved using Union Types.

RESTGraphQL

http

GET /items/articles
	?fields[]=title
	&fields[]=sections.item:headings.title
	&fields[]=sections.item:headings.level
	&fields[]=sections.item:paragraphs.body
	&fields[]=sections.item:videos.source

graphql

# Using native GraphQL Union types
query {
	articles {
		sections {
			item {
				... on headings {
					title
					level
				}

				... on paragraphs {
					body
				}

				... on videos {
					source
				}
			}
		}
	}
}

Filter

Filters allows you to search items in a collection that matches the filter's conditions. The filter param follows the Filter Rules spec, which includes additional information on logical operators (AND/OR), nested relational filtering, and dynamic variables.

Filter First Name Example

For this example, we'll retrieve all items where the first name is equal to Robot.

RESTGraphQL

http

?filter[first_name][_eq]=Robot

// or

?filter={ "first_name": { "_eq": "Robot" }}

graphql

query {
	users(filter: { first_name: { _eq: "Robot" } }) {
		id
	}
}

Nested Filters

The above example will filter the top level items based on a condition in the related item. If you're looking to filter the related items themselves, take a look at the deep parameter!

Filtering M2A fields

Because attribute names in GraphQL cannot contain the : character, you will need to replace it with a double underscore. For example, instead of using sections.item:heading in your filter, you will need to use sections.item__heading (see the full example below).

graphql

query {
	articles(
		filter: {
			sections: {
				item__headings: {
					# Instead of: item:headings
					title: { _eq: "Section 1" }
				}
			}
		}
	) {
		id
	}
}

Search

The search parameter allows you to perform a search on all string and text type fields within a collection. It's an easy way to search for an item without creating complex field filters – though it is far less optimized. It only searches the root item's fields, related item fields are not included.

Mention Cloud Example

For this example, we'll find all items that mention Cloud.

RESTGraphQL

http

?search=Cloud

graphql

query {
	articles(search: "Cloud") {
		id
	}
}

Sort

Sorts allows you to sort field(s) by the order of choice. Sorting defaults to ascending, but a minus sign (-) can be used to reverse this to descending order. Fields are prioritized by the order in the parameter. The dot-notation has to be used when sorting with values of nested fields.

Multi Sort Example

For this example, we'll sort our collection 🪣 based on a set of sorting criteria:

Sort by creation date descending — -date_created.
Sort by a "sort" field, followed by publish date descending — sort,-publish_date.
Sort by a "sort" field, followed by a nested author's name — sort,-author.name.

RESTGraphQL

http

?sort=sort,-date_created,author.name

// or

?sort[]=sort
&sort[]=-date_created
&sort[]=-author.name

graphql

query {
	articles(sort: ["sort", "-date_created", "author.name"]) {
		id
	}
}

Limit

Limits allows you to set the maximum number of items that will be returned. The default limit is set to 100.

Get the maximum allowed number of items — -1.

Maximum Items

Depending on the size of your collection, fetching the maximum amount of items may result in degraded performance or timeouts, use with caution.

First 200 Items Example

For this example, we'll get the first 200 items.

RESTGraphQL

http

?limit=200

graphql

query {
	articles(limit: 200) {
		id
	}
}

Offset

Offsets allows you to skip the first n items in the response. Can be used for pagination.

Offset of 100 Example

For this example, we'll get the items 101-200 by providing an offset of 100.

RESTGraphQL

http

?offset=100

graphql

query {
	articles(offset: 100) {
		id
	}
}

Page

An alternative to offset. Page allows you to set offset under the hood by calculating limit * page. Page is 1-indexed.

Get items 1-100 — 1
Get items 101-200 — 2

Second Page Example

For this example, we'll get the second page.

RESTGraphQL

http

?page=2

graphql

query {
	articles(page: 2) {
		id
	}
}

Aggregation & Grouping

Aggregate functions allow you to perform calculations on a set of values, returning a single result.

The following aggregation functions are available in the Cloud Studio app 📟:

Name	Description
`count`	Counts how many items there are
`countDistinct`	Counts how many unique items there are
`sum`	Adds together the values in the given field
`sumDistinct`	Adds together the unique values in the given field
`avg`	Get the average value of the given field
`avgDistinct`	Get the average value of the unique values in the given field
`min`	Return the lowest value in the field
`max`	Return the highest value in the field
`countAll`	Equivalent to `?aggregate[count]=*` (GraphQL only)

Count Items Example

For this example, we'll count the items of the collection 🪣.

RESTGraphQL

http

?aggregate[count]=*

graphql

query {
	articles_aggregated {
		countAll
	}
}

Grouping

By default, the above aggregation functions run on the whole dataset. To allow for more flexible reporting, you can combine the above aggregation with grouping. Grouping allows for running the aggregation functions based on a shared value. This allows for things like "Average rating per month" or "Total sales of items in the jeans category".

The groupBy query allows for grouping on multiple fields simultaneously. Combined with the Functions, this allows for aggregate reporting per year-month-date.

Multi Group Aggregation Example

For this example, we'll group our collection 🪣 by both the author and the publishing date to count the number of views and comments per author per month.

RESTGraphQL

http

?aggregate[count]=views,comments
&groupBy[]=author
&groupBy[]=year(publish_date)

graphql

query {
	articles_aggregated(groupBy: ["author", "year(publish_date)"]) {
		group
		count {
			views
			comments
		}
	}
}

Deep

Deep allows you to set any of the other query parameters on a nested relational dataset.

Deep Limit Example

For this example, we'll apply a query parameter on the nested relational field comments by retrieving three related articles with only one top rated comment nested.

json

{
	"related_articles": {
		"_limit": 3,
		"comments": {
			"_sort": "rating",
			"_limit": 1
		}
	}
}

RESTGraphQL

http

// For this example we'll use the `deep` query to apply a query on the `language_code` nested field.

?deep[translations][_filter][languages_code][_eq]=en-US

// or

?deep={ "translations": { "_filter": { "languages_code": { "_eq": "en-US" }}}}

graphql

# There is natively supported for deep queries in GraphQL. 
# For this example we'll apply a query on the `name` nested field.
query {
	members {
		favorite_games(filter: { name: { _eq: "Mariokart 8" } }) {
			id
			featured_image {
				filename_disk
			}
		}
	}
}

Aliases

Aliases allow you rename fields on the fly, and request the same nested data set multiple times using different filters.

Nested fields

It is only possible to alias same level fields.: Alias for nested fields, f.e. field.nested, will not work.

Dutch Translation Alias Example

For this example, we'll provide an alias for dutch translations which are annotated with the nl-NL language code.

RESTGraphQL

http

?alias[all_translations]=translations
&alias[dutch_translations]=translations
&deep[dutch_translations][_filter][code][_eq]=nl-NL

graphql

# There is natively supported for aliases in GraphQL. 
query {
	articles {
		dutch_translations: translations(filter: { code: { _eq: "nl-NL" } }) {
			id
		}

		all_translations: translations {
			id
		}
	}
}

Export

Exports allow you to export collections 🪣 to a file of choice.

Export to a .csv file — ?export=csv
Export to a .json file — ?export=json
Export to a .xml file — ?export=xml
Export to a .yaml file — ?export=yaml

Export CSV Example

For this example, we'll export the collection 🪣 to a csv file.

RESTGraphQL

http

?export=csv

graphql

# There is no support for exporting to a file in GraphQL.

Functions

Functions allow for "live" modification of values stored in a field. Functions can be used in any query parameter you'd normally supply a field key, including fields, aggregation, and filter.

Functions can be used by wrapping the field key in a JavaScript like syntax, i.e. timestamp -> year(timestamp).

DateTime Functions

Filter	Description
`year`	Extract the year from a datetime/date/timestamp field
`month`	Extract the month from a datetime/date/timestamp field
`week`	Extract the week from a datetime/date/timestamp field
`day`	Extract the day from a datetime/date/timestamp field
`weekday`	Extract the weekday from a datetime/date/timestamp field
`hour`	Extract the hour from a datetime/date/timestamp field
`minute`	Extract the minute from a datetime/date/timestamp field
`second`	Extract the second from a datetime/date/timestamp field

Array Functions

Filter	Description
`count`	Extract the number of items from a JSON array or relational field

GraphQL

Names aren't allowed to include any special characters in GraphQL, preventing the () syntax from being used.

As an alternative, the above functions can be used by appending _func at the end of the field name, and using the function name as the nested field.

Match Year 2021 Example

For this example, we'll extract the year from the date_published field and see if it is equal to 2021.

RESTGraphQL

http

?fields=id,title,weekday(date_published)
&filter[year(date_published)][_eq]=2021

graphql

query {
	articles(filter: { date_published_func: { year: { _eq: 2021 } } }) {
		id
		title
		date_published_func {
			weekday
		}
	}
}

Global Query Parameters ​

Fields ​

Many-To-Any (Union Types) ​

Filter ​

Search ​

Sort ​

Limit ​

Offset ​

Page ​

Aggregation & Grouping ​

Grouping ​

Deep ​

Aliases ​

Export ​

Functions ​

DateTime Functions ​

Array Functions ​

Global Query Parameters

Fields

Many-To-Any (Union Types)

Filter

Search

Sort

Limit

Offset

Page

Aggregation & Grouping

Grouping

Deep

Aliases

Export

Functions

DateTime Functions

Array Functions