Newt

無料ではじめる
  • ガイド
  • CDN API・Newt API

利用可能なクエリ

Table of contents

CDN API・Newt APIでは、様々なクエリパラメータを利用できます。
この記事では、利用可能なクエリ・演算子の一覧を紹介します。
また、URLにクエリパラメータを付与する場合の書き方と、SDK を利用する場合の書き方を説明します。

詳細については、以下のリファレンスをご確認ください。

1. 利用可能なクエリは9種類

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

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

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

1-1. Filters

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

URLの場合

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

SDKの場合

// 書き方
query: {
  field: value
}
// 例
query: {
  slug: 'hoge'
}
参照フィールドに対してクエリをかけたい場合、現状では _id に対してのみクエリをかけられる仕様となっております。その他のフィールドに対してクエリをかけることはできません。

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-3. Select

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

URLの場合

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

SDKの場合

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

1-4. Order

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

URLの場合

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

SDKの場合

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

1-5. Limit

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

URLの場合

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

SDKの場合

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

1-6. Skip

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

URLの場合

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

SDKの場合

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

1-7. Depth

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

URLの場合

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

SDKの場合

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

1-8. And

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

URLの場合

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

SDKの場合

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

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']
}

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

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

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

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

2-1. 演算子なし

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

URLの場合

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

SDKの場合

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

2-2. ne

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

URLの場合

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

SDKの場合

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

2-3. match

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

URLの場合

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

SDKの場合

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

2-4. in

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

URLの場合

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

SDKの場合

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

2-5. nin

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

URLの場合

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

SDKの場合

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

2-6. all

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

URLの場合

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

SDKの場合

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

2-7. exists

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

URLの場合

// 書き方
{field}[exists]={value}
// 例
thumbnail[exists]=true

SDKの場合

// 書き方
query: {
  field: {
    exists: true
  }
}
// 例
query: {
 thumbnail: {
    exists: true
  }
}

2-8. gt

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

URLの場合

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

SDKの場合

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

2-9. gte

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

URLの場合

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

SDKの場合

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

2-10. lt

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

URLの場合

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

SDKの場合

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

2-11. lte

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

URLの場合

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

SDKの場合

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

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

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

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

  • 参照フィールド・画像フィールド・ファイルフィールドの_id以外の項目
  • マルチタイプフィールド
  • カスタムフィールドタイプを利用したフィールド

関連ドキュメント

チュートリアル / API

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

ガイド / CDN API・Newt API

SDK

NewtMade in Newt