NewtのAPIで利用できるクエリパラメータを理解して、様々なクエリを実行する

最終更新日:

Table of contents

この記事ではNewtのAPI(Newt CDN APINewt API)で利用できるクエリパラメータを理解して、様々なクエリを実行する方法を紹介します。
URLにクエリパラメータを付与する場合の書き方と、SDK を利用する場合の書き方を説明します。

記事内で使用している主なソフトウェアのバージョン

  • newt-client-js(newt-client-js): 3.2.4

概要

はじめに、NewtのAPI(Newt CDN API・Newt API)で利用可能なクエリと演算子の一覧について説明します。
その後、よくある質問に回答する形で、各クエリの使い方を紹介していきます。
最後に、現状のクエリパラメータではできないことも記載します。

1. 利用可能なクエリ・演算子一覧

1-1. NewtのAPIで利用できるクエリは9種類

まず、NewtのAPI(Newt CDN API・Newt API)で利用できるクエリ一覧について説明します。
NewtのAPIで利用できるクエリには大きく以下の9種類があります。Newt CDN APIもNewt APIも利用できるクエリは共通です。

名前説明
Filters条件に合致するコンテンツのみ取得する
FormatHTML形式のデータを取得するか、テキスト形式のデータを取得するか指定する
Select指定したフィールドの情報のみ取得する
Order指定した順番で取得する
Limit返却されるコンテンツの最大件数を指定する
Skip何件のコンテンツをスキップするか指定する
Depth画像フィールド・ファイルフィールド・参照フィールドで、取得するデータの階層を指定する
Andすべての条件に合致するコンテンツを取得する(複数条件の関係を指定)
Orいずれかの条件に合致するコンテンツを取得する(複数条件の関係を指定)

以下、それぞれについて説明します。
詳細については、Queries のリファレンスに記載があるので、ご確認ください。

1-1-1. Filters

条件に合致するコンテンツのみ取得します。
1-2で利用可能なすべての演算子について説明します。

URLの場合

// 書き方
{field}={value}
// 例
slug=hoge

SDKの場合

// 書き方
query: {
  field: value
}
// 例
query: {
  slug: 'hoge'
}

1-1-2. Format

フィールドタイプがリッチテキストまたはマークダウンの場合、デフォルトではHTML形式のデータが返されます。Formatクエリを利用して、HTML形式のデータを取得するか、テキスト形式のデータを取得するか、指定します。
fmt 演算子を使用して、text の値を指定した場合に、テキスト形式のデータが返却されます。それ以外の場合はHTML形式のデータが返却されます。

URLの場合

// 書き方
{field}[fmt]=text
// 例
body[fmt]=text

SDKの場合

// 書き方
query: {
  field: {
    fmt: 'text'
  }
}
// 例
query: {
  body: {
    fmt: 'text'
  }
}

1-1-3. Select

指定したフィールドの情報のみ取得します。

URLの場合

// 書き方
select={field},{field}
// 例
select=title,slug

SDKの場合

// 書き方
query: {
  select: [field, field]
}
// 例
query: {
  select: ['title', 'slug']
}

1-1-4. Order

指定した順番でコンテンツを取得します。
複数の値を指定した場合、左のものから順にソートされます。降順にしたい場合は - をつけます。

URLの場合

// 書き方
order=-{field},{field}
// 例
order=-priority,_sys.createdAt

SDKの場合

// 書き方
query: {
  order: [-field, field]
}
// 例
query: {
  order: ['-priority', '_sys.createdAt']
}

1-1-5. Limit

返却されるコンテンツの最大件数を指定します。

URLの場合

// 書き方
limit={value}
// 例
limit=10

SDKの場合

// 書き方
query: {
  limit: value
}
// 例
query: {
  limit: 10
}

1-1-6. Skip

何件のコンテンツをスキップするか指定します。

URLの場合

// 書き方
skip={value}
// 例
skip=10

SDKの場合

// 書き方
query: {
  skip: value
}
// 例
query: {
  skip: 10
}

1-1-7. Depth

画像・ファイル・参照フィールドで、取得するデータの階層を指定します。

URLの場合

// 書き方
depth={value}
// 例
depth=2

SDKの場合

// 書き方
query: {
  depth: value
}
// 例
query: {
  depth: 2
}

1-1-8. And

指定したすべての条件を満たすコンテンツを取得します。
URLで記載する時は & で接続します。
SDKで記載する時は query オブジェクトの中にすべての条件を記載します。

URLの場合

// 例: tagの名称がdevelopersであるコンテンツを作成順で取得する
tag=developers&order=_sys.createdAt

SDKの場合

// 例: tagの名称がdevelopersであるコンテンツを作成順で取得する
query: {
  tag: 'developers',
  order: ['_sys.createdAt']
}

1-1-9. Or

いずれかの条件に合致するコンテンツを取得します。
URLで記載する時は、条件を () で囲み、各条件を ; で区切ります。
SDKで記載する時は query オブジェクトの中に or オブジェクトを作成し、配列で条件を記載します。

URLの場合

// 例: slugがdevelopers、またはtagがdevelopersであるコンテンツを取得する
[or]=(slug=developers;tag=developers)

SDKの場合

// 例: slugがdevelopers、またはtagがdevelopersであるコンテンツを取得する
query: {
  or: [
    {
      slug: 'developers',
    },
    {
      tag: 'developers',
    },
  ],
}

また、OR条件と他の条件をANDで接続することも可能です。

URLの場合

// 例: slugがdevelopers、またはtagがdevelopersであるコンテンツを取得する。かつ作成順で取得する
[or]=(slug=developers;tag=developers)&order=_sys.createdAt

SDKの場合

// 例: slugがdevelopers、またはtagがdevelopersであるコンテンツを取得する。かつ作成順で取得する
query: {
  or: [
    {
      slug: 'developers',
    },
    {
      tag: 'developers',
    },
  ],
  order: ['_sys.createdAt']
}

1-2. Filtersで利用できる演算子は11種類

上記で説明した Filters では、さらに11種類の演算子を利用できます。
Newt CDN APIもNewt APIも利用できる演算子は共通です。

演算子説明
なし指定した値に一致するコンテンツを取得する
ne指定した値に一致するコンテンツを除外する
match指定した値を含むコンテンツを取得する
in指定した要素のどれかに一致するコンテンツを取得する
nin指定した要素のどれかに一致するコンテンツを除外する
all指定した要素のすべてを含むコンテンツを取得する
exists指定したフィールドを持つ(持たない)コンテンツを取得する
gt指定した値より大きいコンテンツを取得する
gte指定した値以上のコンテンツを取得する
lt指定した値未満のコンテンツを取得する
lte指定した値以下のコンテンツを取得する

以下、それぞれについて説明します。
詳細については、Queries のリファレンスに記載があるので、ご確認ください。

1-2-1. 演算子なし

指定した値に一致するコンテンツを取得します。

URLの場合

// 書き方
{field}={value}
// 例
slug=hoge

SDKの場合

// 書き方
query: {
  field: value
}
// 例
query: {
  slug: 'hoge'
}

1-2-2. ne

指定した値に一致するコンテンツを除外します。

URLの場合

// 書き方
{field}[ne]={value}
// 例
slug[ne]=fuga

SDKの場合

// 書き方
query: {
  field: {
    ne: value
  }
}
// 例
query: {
  slug: {
    ne: 'fuga'
  }
}

1-2-3. match

指定した値を含むコンテンツを取得します。

URLの場合

// 書き方
{field}[match]={value}
// 例
body[match]=abc

SDKの場合

// 書き方
query: {
  field: {
    match: value
  }
}
// 例
query: {
  body: {
    match: 'abc'
  }
}

1-2-4. in

指定した要素のどれかに一致するコンテンツを取得します。

URLの場合

// 書き方
{field}[in]={value},{value}
// 例
tag[in]=developers,community

SDKの場合

// 書き方
query: {
  field: {
    in: [value, value]
  }
}
// 例
query: {
  tag: {
    in: ['developers', 'community']
  }
}

1-2-5. nin

指定した要素のどれかに一致するコンテンツを除外します。

URLの場合

// 書き方
{field}[nin]={value},{value}
// 例
tag[nin]=engineer,designer

SDKの場合

// 書き方
query: {
  field: {
    nin: [value, value]
  }
}
// 例
query: {
  tag: {
    nin: ['engineer', 'designer']
  }
}

1-2-6. all

指定した要素のすべてを含むコンテンツを取得します。

URLの場合

// 書き方
{field}[all]={value},{value}
// 例
tag[all]=update,feature

SDKの場合

// 書き方
query: {
  field: {
    all: [value, value]
  }
}
// 例
query: {
  tag: {
    all: ['update', 'feature']
  }
}

1-2-7. exists

指定したフィールドを持つ(持たない)コンテンツを取得します。
trueを指定した場合は該当のフィールドを持つコンテンツを、falseを指定した場合は該当のフィールドを持たないコンテンツを取得します。

URLの場合

// 書き方
{field}[exists]={value}
// 例
custom.description[exists]=true

SDKの場合

// 書き方
query: {
  field: {
    exists: true
  }
}
// 例
query: {
 'custom.description': {
    exists: true
  }
}

1-2-8. gt

指定した値より大きいコンテンツを取得します。

URLの場合

// 書き方
{field}[gt]={value}
// 例
_sys.createdAt[gt]=2022

SDKの場合

// 書き方
query: {
  field: {
    gt: value
  }
}
// 例
query: {
  '_sys.createdAt': {
    gt: '2022'
  }
}

1-2-9. gte

指定した値以上のコンテンツを取得します。

URLの場合

// 書き方
{field}[gte]={value}
// 例
_sys.createdAt[gte]=2023

SDKの場合

// 書き方
query: {
  field: {
    gte: value
  }
}
// 例
query: {
  '_sys.createdAt': {
    gte: '2023'
  }
}

1-2-10. lt

指定した値未満のコンテンツを取得します。

URLの場合

// 書き方
{field}[lt]={value}
// 例
_sys.createdAt[lt]=2023

SDKの場合

// 書き方
query: {
  field: {
    lt: value
  }
}
// 例
query: {
  '_sys.createdAt': {
    lt: '2023'
  }
}

1-2-11. lte

指定した値以下のコンテンツを取得します。

URLの場合

// 書き方
{field}[lte]={value}
// 例
_sys.createdAt[lte]=2022

SDKの場合

// 書き方
query: {
  field: {
    lte: value
  }
}
// 例
query: {
  '_sys.createdAt': {
    lte: '2022'
  }
}

2. クエリに関するよくある質問(フィールド別)

2-1. 参照フィールド

特定の参照先を持つコンテンツを取得したい(単数の参照フィールド)

単数の(複数値ではない)参照フィールドを利用している場合の質問です。

質問:
「投稿」モデルと「カテゴリ」モデルを定義しています。
投稿モデルはカテゴリという参照フィールドを定義していて、参照先モデルに「カテゴリ」を指定しています。
特定のカテゴリを持つ投稿を取得したいのですが、どのようなクエリを利用すればいいですか?

参照フィールドは _id の情報を持っているので、あらかじめ_id情報を調べてから演算子なしのFilterを利用します。
例えば_idが 123abc の場合、以下のようになります。

// URLの場合
category=123abc
// SDKの場合
query: {
  category: '123abc'
}
参照先に対してクエリをかけたい場合、現状では _id に対してのみクエリをかけられる仕様となっております。その他のフィールドに対してクエリをかけることはできません。

特定の参照先を含むコンテンツを取得したい(複数値の参照フィールド)

複数値の参照フィールドを利用している場合の質問です。

質問:
「投稿」モデルと「タグ」モデルを定義しています。
投稿モデルはタグという複数値の参照フィールドを定義していて、参照先モデルに「タグ」を指定しています。
いずれかのタグを含む投稿を取得したいのですが、どのようなクエリを利用すればいいですか?

参照フィールドは _id の情報を持っているので、あらかじめ_id情報を調べてからin演算子のFilterを利用します。
例えば_idが 123abc456abc の場合、以下のようになります。

// URLの場合
tags[in]=123abc,456abc
// SDKの場合
query: {
  tags: {
    in: ['123abc', '456abc']
  }
}

また、「いずれかのタグ」ではなく「特定のタグ」を含む投稿を取得したい場合は、演算子なしでの記載も可能です。
(単数の参照フィールドを利用している場合と同じ書き方となります)

// URLの場合
tags=123abc
// SDKの場合
query: {
  tags: '123abc'
}
参照先に対してクエリをかけたい場合、現状では _id に対してのみクエリをかけられる仕様となっております。その他のフィールドに対してクエリをかけることはできません。

_id以外の参照先の情報を取得したい

質問:
「投稿」モデル・「著者」モデル・「部門」モデルを定義しています。
投稿モデルは著者という参照フィールドを定義していて、参照先モデルに「著者」を指定しています。
著者モデルは部門という参照フィールドを定義していて、参照先モデルに「部門」を指定しています。
投稿を取得した時に、著者の情報は表示されますが、部門の情報は_idのみしか返却されません。
部門の名前やその他の情報を取得できないですか?

Depthクエリを利用することで、深い階層の情報も取得できます。
以下のように depth を指定することで、2階層目の情報も取得できます。

// URLの場合
depth=2
// SDKの場合
query: {
  depth: 2
}
現状では depth の最大値は 2 となっております。3 以上の値は指定できません。

2-2. リッチテキストフィールド

HTML形式ではなく、プレーンなテキスト形式で取得したい

質問:
「投稿」モデルを定義していて、「body」というリッチテキストフィールドを定義しています。
一覧表示を行う時に、本文の抜粋を表示しようと考えているのですが、
HTML形式ではなく、プレーンなテキスト形式でbodyデータを取得する方法はありますか?

Formatクエリを利用することで、テキスト形式でデータを取得できます。

// URLの場合
body[fmt]=text
// SDKの場合
query: {
  body: {
    fmt: 'text'
  }
}

2-3. マークダウンフィールド

HTML形式ではなく、マークダウン形式のテキストで取得したい

質問:
「投稿」モデルを定義していて、「description」というマークダウンフィールドを定義しています。
HTML形式ではなく、マークダウン形式のままdescriptionデータを取得する方法はありますか?

Formatクエリを利用することで、マークダウン形式のテキストデータを取得できます。

// URLの場合
description[fmt]=text
// SDKの場合
query: {
  description: {
    fmt: 'text'
  }
}

2-4. _sysフィールド

指定した年に公開されたコンテンツのみを取得したい

質問:
「投稿」モデルを定義しています。
2023年に公開された投稿を取得したいのですが、どのようなクエリを利用すればいいですか?

CDN APIを利用している場合、_sys.createdAt に初めて公開された日時の情報がISO形式で入ります。
gte演算子・lt演算子のFilterを利用します。

// URLの場合
_sys.createdAt[gte]=2023&_sys.createdAt[lt]=2024
// SDKの場合
query: {
  '_sys.createdAt': {
    gte: '2023',
    lt: '2024'
  }
}

指定した月に公開されたコンテンツのみを取得したい

質問:
「投稿」モデルを定義しています。
2023年3月に公開された投稿を取得したいのですが、どのようなクエリを利用すればいいですか?

CDN APIを利用している場合、_sys.createdAt に初めて公開された日時の情報がISO形式で入ります。
gte演算子・lt演算子のFilterを利用します。

// URLの場合
_sys.createdAt[gte]=2023-03&_sys.createdAt[lt]=2023-04
// SDKの場合
query: {
  '_sys.createdAt': {
    gte: '2023-03',
    lt: '2023-04'
  }
}

2-5. 日付フィールド

指定した年に公開されたコンテンツのみを取得したい

質問:
「イベント」モデルを定義していて、「date」という日付フィールドを定義しています。
2023年の日付が入力されているイベントを取得したいのですが、どのようなクエリを利用すればいいですか?

gte演算子・lt演算子のFilterを利用します。

// URLの場合
date[gte]=2023&date[lt]=2024
// SDKの場合
query: {
  date: {
    gte: '2023',
    lt: '2024'
  }
}

指定した月に公開されたコンテンツのみを取得したい

質問:
「イベント」モデルを定義していて、「date」という日付フィールドを定義しています。
2023年3月の日付が入力されているイベントを取得したいのですが、どのようなクエリを利用すればいいですか?

gte演算子・lt演算子のFilterを利用します。

// URLの場合
date[gte]=2023-03&date[lt]=2023-04
// SDKの場合
query: {
  date: {
    gte: '2023-03',
    lt: '2023-04'
  }
}

3. クエリに関するよくある質問(ユースケース別)

3-1. コンテンツの並び替え

データの降順で取得したい

質問:
コンテンツの更新日に応じて、日付が新しいものから順番に表示したいです。
コンテンツを降順で取得する方法はありますか?

CDN APIを利用している場合、_sys.updatedAt に公開中のコンテンツを更新した日時が入ります。
Orderクエリを利用して、降順にしたい場合は - をつけます。

// URLの場合
order=-_sys.updatedAt
// SDKの場合
query: {
  order: ['-_sys.updatedAt']
}

カスタムオーダーの順番で取得したい

質問:
管理画面でコンテンツを手動で並び替えました。
コンテンツを並び替えた順番の通りに取得する方法はありますか?

_sys.customOrder に手動並び替えを行った際の順序値が入ります。
降順で取得すると、管理画面の通りに取得できます。

// URLの場合
order=-_sys.customOrder
// SDKの場合
query: {
  order: ['-_sys.customOrder']
}

3-2. 検索

複数フィールドのどこかにキーワードが含まれるコンテンツを取得したい

質問:
「投稿」モデルを定義していて、「title」・「body」というフィールドを定義しています。
どちらかのフィールドに特定のキーワードを含むコンテンツを取得したいのですが、
どのようなクエリを利用すればいいですか?

Orクエリを利用することで、いずれかの条件に合致するコンテンツを取得できます。

// URLの場合
[or]=(title[match]=hoge;body[match]=hoge)
// SDKの場合
query: {
  or: [
    {
      title: {
        match: 'hoge'
      }
    },
    {
      body: {
        match: 'hoge'
      }
    },
  ],
}

より複雑な検索を実行したい場合は、AlgoliaとNext.jsを利用して、高度な全文検索を実現する のチュートリアルもご確認ください。

3-3. ページネーション

指定した箇所から指定した件数だけ取得したい

質問:
ページネーションの実装を考えています。
例えば41番目のコンテンツから50番目のコンテンツまで取得する場合、
どのようなクエリを利用すればいいですか?

Skipクエリで、何件のコンテンツをスキップするか指定できます。
Limitクエリで、返却されるコンテンツの最大件数を指定できます。
「41番目のコンテンツから50番目のコンテンツまで取得する」という指定は「40個のコンテンツをスキップし、10個のコンテンツを取得する」と言い換えて指定します。

// URLの場合
skip=40&limit=10
// SDKの場合
query: {
  skip: 40,
  limit: 10
}

3-4. 前後の記事

あるコンテンツの次のコンテンツを取得したい

質問:
「投稿」モデルを定義しています。
記事詳細ページから次の記事に遷移することを考えているのですが、
あるコンテンツの次のコンテンツを取得する場合、
どのようなクエリを利用すればいいですか?

Orderクエリと、gt演算子(lt演算子)のFilterを使います。
SDKの場合は getFirstContent メソッドを使うことで便利に取得できます。
どちらの場合も、以下のステップで考えます。

  • 現在のコンテンツと比べて、どの値がより大きい(小さい)のか明確にする
  • gt演算子(lt演算子)を利用して、上記の条件を表現する
  • 該当のコンテンツが先頭に来るよう並び順を考えて、Orderクエリで表現する

ここでは、公開日の降順で記事を並べていると想定します。1つ次の記事として、公開日が1つ古いものを取得する場合の方法を示します。以下のように考えます。

  • 現在のコンテンツと比べて _sys.createdAt が1つ古い(小さい)コンテンツを取得したい
  • 上記はlt演算子で表現できそう
  • 1つ古いコンテンツが先頭に来るには、「公開日の降順」=「-_sys.createdAt」で並べると良さそう
// URLの場合
_sys.createdAt[lt]=2023-04-06T00:18:26.810Z&order=-_sys.createdAt&limit=1
// SDKの場合
client.getFirstContent({
  (省略)
  query: {
    '_sys.createdAt': {
        lt: article._sys.createdAt, // articleは現在の記事の情報が入っているとする
    },
    order: ['-_sys.createdAt'],
  },
})

あるコンテンツの前のコンテンツを取得したい

質問:
「投稿」モデルを定義しています。
記事詳細ページから前の記事に遷移することを考えているのですが、
あるコンテンツの前のコンテンツを取得する場合、
どのようなクエリを利用すればいいですか?

Orderクエリと、lt演算子(gt演算子)のFilterを使います。
SDKの場合は getFirstContent メソッドを使うことで便利に取得できます。
どちらの場合も、以下のステップで考えます。

  • 現在のコンテンツと比べて、どの値がより小さい(大きい)のか明確にする
  • lt演算子(gt演算子)を利用して、上記の条件を表現する
  • 該当のコンテンツが先頭に来るよう並び順を考えて、Orderクエリで表現する

ここでは、公開日の降順で記事を並べていると想定します。1つ前の記事として、公開日が1つ新しいものを取得する場合の方法を示します。以下のように考えます。

  • 現在のコンテンツと比べて _sys.createdAt が1つ新しい(大きい)コンテンツを取得したい
  • 上記はgt演算子で表現できそう
  • 1つ新しいコンテンツが先頭に来るには、「公開日の昇順」=「_sys.createdAt」で並べると良さそう
// URLの場合
_sys.createdAt[gt]=2023-04-06T00:18:26.810Z&order=_sys.createdAt&limit=1
// SDKの場合
client.getFirstContent({
  (省略)
  query: {
    '_sys.createdAt': {
        gt: article._sys.createdAt, // articleは現在の記事の情報が入っているとする
    },
    order: ['_sys.createdAt'],
  },
})

4. クエリパラメータの仕様上の制限

クエリをかけられないもの

以下に対しては、Filtersによる絞り込み・Formatによる取得形式の変更・Selectによる取得情報の制限・Orderによる並び順の指定は行えません。ご注意ください。

  • 参照フィールド・画像フィールド・ファイルフィールドの_id以外の項目
  • マルチタイプフィールド

以上で、NewtのAPIで利用できるクエリパラメータの紹介を終わります。
クエリパラメータを利用することで、取得形式を柔軟に変更できるので、ぜひお試しください。

NewtMade in Newt