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

この記事ではNewtのAPI（Newt CDN API・Newt 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 条件に合致するコンテンツのみ取得する
Format HTML形式のデータを取得するか、テキスト形式のデータを取得するか指定する
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が 123abc と 456abc の場合、以下のようになります。

// 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による取得形式の変更・Orderによる並び順の指定は行えません。ご注意ください。

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

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

Newt Made in Newt