Queries

Learn about queries; the way to fetch content from your Cosmic Bucket.

Prerequisite

The following references assume you have already reviewed the methods for fetching Objects and media from your Bucket.

Queries in the browser URL

Object properties

You can compose queries to search by the following Object properties.

ParameterDescription
idObject id
titleObject title
slugObject slug
typeObject type Slug
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)

Media properties

Construct queries to search by the following media properties.

ParameterDescription
idMedia id
nameMedia name
original_nameMedia original name
sizeMedia size
typeMedia type
createdMedia created date
folderMedia folder
metadataMedia metadata (JSON)

Selectors

Use the following selectors to build your queries.

ParameterDescription
$eqMatches values that are equal to a specified value. Default 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.
$allMatches all 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.

Evaluation

ParameterDescription
$regex, $optionsSearch for string, use $options: "i" for case insensitive matches.

Logic Operators

ParameterDescription
$andReturns results that match all of the query conditions.
$notReturns results that do not match the query expression.
$orReturns results that match any of the specified conditions.
$norReturns results that fail to match any of the specified conditions.

Basic examples

The following examples use the NPM module and assume you have an understaning of authentication.

A basic query may be when you want to fetch Objects in a certain type. For example, blog posts:

const query = {
  type: 'posts',
};
await cosmic.objects.find(query);

Let's say you want to fetch only blog posts from a certain category set by a single Object relationship metafield:

const query = {
  type: 'posts',
  category: 'category-object-id', // The category Object id
};
await cosmic.objects.find(query);

You can also use queries to fetch media.

const query = {
  type: 'video/mp4', // fetch all video files
};
await cosmic.media.find(query);

Advanced examples

Let's say you want to fetch products that have a price (Number Metafield) less than 100:

const query = {
  type: 'products',
  'metadata.price': {
    $lt: 100,
  },
};
await cosmic.objects.find(query);

Let's say you want to fetch products that have any of a certain set of tags (select dropdown Metafield):

const query = {
  type: 'products',
  'metadata.tags': {
    $in: ['Clothing', 'Menswear'],
  },
};
await cosmic.objects.find(query);

Let's say you want to fetch products that match a combination of values using the $and logic operator.

const query = {
  type: 'products',
  $and: [
    {
      'metadata.category': 'Tshirt',
    },
    {
      'metadata.price': {
        $lte: 29,
      },
    },
  ],
};
await cosmic.objects.find(query);

Using the $regex method we can create a search feature that searches Objects by title.

const query = {
  type: 'products',
  title: {
    $regex: 'Hoodie',
    $options: 'i', // case insensitive
  },
};
await cosmic.objects.find(query);

More query info