Skip to content

Queries

Queries give you powerful NoSQL database-like functionality for content fetching. Use the query parameter to send a valid JSON (stringified) query on the Get Objects endpoint and Get Media list endpoint. See example requests below.

Note
If accessing the endpoint via browser address bar, open and closed curly braces will need to be encoded: %7B and %7D respectively. This encoder tool may help.

Definition

GET $BASE_URL/buckets/${bucket_slug}/objects?read_key=${read_key}&query=${query}

Query Keys

ParameterDescription
idObject Id
titleObject Title
slugObject Slug
contentObject Content
typeObject Type Slug
statusObject Status
localeObject Locale
created_atObject Created at Date
published_atObject Published at Date
modified_atObject Modified at Date
created_byObject Created by user id
modified_byObject Modified by user id
metadata.$keyMetadata value(s)

Query Selectors

ParameterDescription
$eqMatches values that are equal to a specified value. Equivalent to direct key/value query.
$gtMatches values that are greater than a specified value.
$gteMatches values that are greater than or equal to a specified value.
$ltMatches values that are less than a specified value.
$lteMatches values that are less than or equal to a specified value.
$inMatches any of the values specified in an array.
$neMatches all values that are not equal to a specified value.
$ninMatches none of the values specified in an array.
$regex, $optionsSearch for string, use $options: "i" for case insensitive matches

Logic Operators

ParameterDescription
$andReturns Objects that match all conditions
$allEquivalent to $and
$orReturns Objects that match any conditions

Example Queries

Endpoint base path

To keep examples concise, the following base path is used:

endpoint = "$BASE_URL/buckets/${bucket_slug}/objects?read_key=${read_key}&props=title,slug,metadata"

Matches Objects with exact Object Type

curl '$endpoint&query={"type":"posts"}'

Matches Objects with exact title

curl '$endpoint&query={"title":"Post 1"}'

Matches Objects with exact id

curl '$endpoint&query={"id":"valid-object-id"}'

Matches Objects with any ids

curl '$endpoint&query={"id":["valid-object-id-1","valid-object-id-2"]}'

Match Objects with any ids not equal to value

curl '$endpoint&query={"id":{"$ne":"valid-object-id"}}'

Match Objects except with ids in the array of values

curl '$endpoint&query={"id":{"$nin":["valid-object-id-1","valid-object-id-2"]}}'

Match Objects with exact slug

curl '$endpoint&query={"slug":"post-1"}'

Match Objects with string in content. Case insensive with $options.

curl '$endpoint&query={"content":{"$regex":"jamstack","$options":"i"}}'

Match metadata value (Number Metafield)

curl '$endpoint&query={"metadata.price":9.99}'

Match any slug values

curl '$endpoint&query={"$or":[{"slug":"post-1"},{"slug":"post-2"}]}'

Match any metadata values

curl '$endpoint&query={"$or":[{"metadata.grade":"A"},{"metadata.grade":"B"}]}'

Match all metadata values

curl '$endpoint&query={"$and":[{"metadata.grade":"A"},{"metadata.price":{"$lt":10}}]}'

Match greater than or equal to metadata value

curl '$endpoint&query={"metadata.price":{"$gte":9.99}}'

Match exact metadata value (Switch Metafield)

curl '$endpoint&query={"metadata.is_featured":true}'

Match nested JSON metadata value (JSON Metafield)

curl '$endpoint&query={"metadata.json_data":{"is_awesome":true,"other_data":{"nested":"yep"}}}'

Match Single Object Metafield value

curl '$endpoint&query={"metadata.category":"category_id-1"}'

Match not equal to Single Object Metafield value

curl '$endpoint&query={"metadata.category":{"$ne": "category_id-1"}}'

Match all Multiple Object Metafield values

curl '$endpoint&query={"metadata.categories":["category_id-1","category_id-2"]}'

Match any Multiple Object Metafield values

curl '$endpoint&query={"metadata.categories":{"$in":["category_id-1","category_id-2"]}}'

Match doesn't have any Multiple Object Metafield values

curl '$endpoint&query={"metadata.categories":{"$nin":["category_id-1","category_id-2"]}}'

Localization

Match with slug and locale

curl '$endpoint&query={"slug":"home","locale":"en-US"}'

More info

💡

Want more information?
Our queries follow MongoDB methods of comparison and logical operators. See further documentation and more examples in the MongoDB docs.