---
title: Filter検索のパラメータ
category: api
weight: 1
---

ここでは検索機能を利用する方法を解説します。

## 基本

検索はFilter queryという機能を利用します。Filter queryはSQLに似た記述で検索条件を指定できます。

たとえばtimestampというフィールドについて、2021年06月01日から6月30日までのデータを検索する場合には次のように指定します。

```
?filter=%28timestamp+%3E%3D+%222021-06-01+00%3A00%22+AND+timestamp+%3C%3D+%222021-06-30+23%3A59%22%29
```

この `filter` パラメータは次のような内容をURLエンコードしたものです。

```
?filter=(timestamp >= "2021-06-01 00:00" AND timestamp <= "2021-06-30 23:59")
```

## filterパラメータについて

filterパラメータは基本的に次のような形で構成されます。

`(カラム) (オペレータ) (値)`

- カラムはデータで定義したものを指定します。上記例では `timestamp` になります。
- オペレータはカラムと値をつなぐものです。たとえば `=` や `>=` などになります（[後述](#オペレータについて)）。
- 値は検索条件値になります。文字列や数字が利用できます。

### 相対日付モードについて

今日や昨日、何時間前といった相対的に日時を扱って検索するモードを用意しています。基本形は次のようになります。

`(カラム) (オペレータ):relatively (値)`

カラムやオペレータについては、通常のfilterパラメータと同じです（一部利用できないオペレータがあります）。たとえば次のように検索することで、今日のデータだけを取得できます。

`timestamp >=:relatively "today"`

指定できるオペレータと値については[相対日付モードで指定できるオペレータと値](#相対日付モードで指定できるオペレータと値)を参照してください。

### オペレータについて

Filter queryで利用できるオペレータは次の通りです。

| オペレータ | 意味 | 例 | 備考 |
|-----------|-----------|-----------|-----------|
| =         | `カラム` が `値` である | topics_id = 1 | `=` の代わりに `eq` も利用可能です |
| !=        | `カラム` が `値` ではない | ext_col_01 != "" | `!=` の代わりに `ne` も利用可能です |
| <         | `カラム` が `値` より小さい | inst_ymdhi < "2020-08-01" | `<` の代わりに `lt` も利用可能です |
| <=        | `カラム` が `値` 以下である | inst_ymdhi <= "2020-08-01" | `<=` の代わりに `lte` も利用可能です |
| >         | `カラム` が `値` より大きい | topics_group_id > 2 | `>` の代わりに `gt` も利用可能です |
| >=        | `カラム` が `値` 以上である | topics_group_id >= 2 | `>=` の代わりに `gte` も利用可能です |
| in        | `カラム` に `値` のいずれかが含まれる | ext_col_01 in ["A", "B", "C"]  | 値は配列である必要があります |
| nin       | `カラム` に `値` のいずれも含まれない | ext_col_01 nin ["A", "B", "C"] | 値は配列である必要があります |
| all       | `カラム` に `値` すべてが含まれる | secure_level all [1, 2] | 値は配列である必要があります |
| nall      | `カラム` に `値` すべてが含まれない | secure_level nall [1, 2] | 値は配列である必要があります |
| contains  | `カラム` に `値` が含まれる        | subject contains "foo" | 大文字小文字を区別します |
| icontains | `カラム` に `値` が含まれる        | subject icontains "foo" | 大文字小文字を区別しません |
| ncontains | `カラム` に `値` が含まれない      | subject ncontains "bar" | 大文字小文字を区別します |
| nicontains | `カラム` に `値` が含まれない    | subject nicontains "bar" | 大文字小文字を区別しません |
| startswith | `カラム` が `値` ではじまる       | subject startswith "foo" | 大文字小文字を区別します |
| istartswith | `カラム` が `値` ではじまる      | subject istartswith "foo" | 大文字小文字を区別しません |
| nstartswith | `カラム` が `値` ではじまらない  | subject nstartswith "foo" | 大文字小文字を区別します |
| nistartswith | `カラム` が `値` ではじまらない  | subject nistartswith "foo" | 大文字小文字を区別しません |
| endswith    | `カラム` が `値` で終わる       | subject endswith "foo"      | 大文字小文字を区別します |
| iendswith   | `カラム` が `値` で終わる       | subject iendswith "foo"      | 大文字小文字を区別しません |
| nendswith    | `カラム` が `値` で終わらない   | subject nendswith "foo"      | 大文字小文字を区別します |
| niendswith   | `カラム` が `値` で終わらない   | subject niendswith "foo"      | 大文字小文字を区別しません |

### オペレータの連結について

複数の条件を指定する場合には `AND` と `OR` が利用できます。

| オペレータ | 意味 | 例 |
|-----------|-----------|-----------|
| AND | `条件1` と `条件2` にマッチする | topics_id eq 1 AND subject eq foo |
| OR  | `条件1` と `条件2` のいずれかにマッチする | topics_id eq 1 OR subject eq foo |

### 他の記法

他に括弧などの記法が用意されています。

| オペレータ | 意味 | 例 |
|-----------|-----------|-----------|
| ()        | 条件の優先順位付け | topics_id eq 1 AND (subject eq foo OR subject eq bar) |
| []        | 値の配列化        | topics_id in [1, 2, 3] |
| ,         | 値の配列区切り文字 | topics_id in [1, 2, 3] |

### 値について

| 種類 | フォーマット |  例 | 備考 |
|------|------|------|------|
| 整数 | `%d`   | topics_id eq 1 |               |
| 数値 | `%f`   | topics_id > 1.00 |              |
| 日付 | `"Y-m-d"` | inst_ymdhi < "2020-08-01" |          |
| 時間 | `"H:m:s"`<br />`"H:m"` | post_time > "12:30:00"<br />"H:m" post_time > "12:30"|           |
| 日時 | `"Y-m-d H:i"`<br />`"Y-m-d H:i:s"`<br />`"Y-m-d H:i:s O"` | update_ymdhi < "2020-08-01 12:00"<br />update_ymdhi < "2020-08-01 12:00:00"<br />update_ymdhi < "2020-08-01 12:00:00 +0900" |           |
| 日付 + 時間 | `"Y/m/d H:i:s"`       |  ymd_time > "2021/09/30 12:30:00" |コンテンツ定義の「投稿時間も設定する」フィールドで、「有効にする」にチェックが入っている場合のみ利用できます。<br/>参考:[コンテンツ定義編集](/ja/docs/management/content-structure-topics-group/#項目説明-1) |
| 空文字 | `""`   |  ext_col_01 eq "" |           |
| 空配列| `:empty`   |  ext_col_01 eq :empty | 複数選択で選択なしをフィルタする場合はこちらをご利用ください。<br/>タグで選択なしをフィルタする場合は[:R()検索](/ja/docs/reference/r-filter/#topicslistのapiでタグが設定されていないコンテンツを取得)をご利用ください。|
| 文字列 | `"%s"`<br />`%s`       |  subject eq "TITLE"<br />subject eq TITLE |ダブルクオート `"` で囲んだ場合は日付/時刻/日時を除いて文字列として扱われます。<br />ダブルクオートがない場合、他の型と一致せず、かつ空白や特殊文字がない場合は文字列として扱われます。 |

### 相対日付モードで指定できるオペレータと値

#### 相対日付モードで指定できるオペレータ

相対日付モードで指定できるオペレータは次の通りです。

| オペレータ | 意味 | 例 |
|-----------|-----------|-----------|
| =:relatively | 値に一致する    | timestamp =:relatively "today" |
| !=:relatively | 値に一致しない | timestamp !=:relatively "today" |
| >:relatively | 値より大きい    | timestamp >:relatively "-9 hours" |
| >=:relatively | 値以上         | timestamp >=:relatively "-10 hours" |
| <:relatively | 値より小さい    | timestamp <:relatively "1 week" |
| <=:relatively | 値以下         | timestamp <=:relatively "last Monday" |

#### 相対日付モードで指定できる値

相対日付モードは[PHPのstrtotime関数](https://www.php.net/manual/ja/function.strtotime.php)互換となっています。strtotime関数で利用できる指定方式が指定可能です。

利用できる書式は次の通りです（[PHP: 相対的な書式 - Manual](https://www.php.net/manual/ja/datetime.formats.relative.php)からの転載です）。

| シンボル | 書式 |
|---------|---------|
| dayname | 'sunday' \| 'monday' \| 'tuesday' \| 'wednesday' \| 'thursday' \| 'friday' \| 'saturday' \| 'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat' |
| daytext | 'weekday' \| 'weekdays' |
| number  | [+-]?[0-9]+ |
| ordinal | 'first' \| 'second' \| 'third' \| 'fourth' \| 'fifth' \| 'sixth' \| 'seventh' \| 'eighth' \| 'ninth' \| 'tenth' \| 'eleventh' \| 'twelfth' \| 'next' \| 'last' \| 'previous' \| 'this' |
| reltext | 'next' \| 'last' \| 'previous' \| 'this' |
| space   | [ \t]+ |
| unit    | (('sec' \| 'second' \| 'min' \| 'minute' \| 'hour' \| 'day' \| 'fortnight' \| 'forthnight' \| 'month' \| 'year') 's'?) \| 'weeks' \| daytext |

入力例は次の通りです。

| 書式 | 説明 | 例 |
|------|------|------|
| 'yesterday' | 昨日の00:00:00 | "yesterday 14:00" |
| 'midnight' | 時刻を00:00:00にします |   |
| 'today' | 時刻を00:00:00にします |   |
| 'now' | 今 |   |
| 'noon' | 時刻を12:00:00にします | "yesterday noon" |
| 'tomorrow' | 明日の00:00:00 |   |
| 'back of' hour | 指定された時の15分後 | "back of 7pm", "back of 15" |
| 'front of' hour | 指定された時の15分前 | "front of 5am", "front of 23" |
| 'first day of' | 現在月の最初の日にします。 この書式に続けて月名を指定する使いかたが最適です。 | "first day of January 2008" |
| 'last day of' | 現在月の最後の日にします。 この書式に続いて月名を指定する使いかたが最適です。 | "last day of next month" |
| ordinal space dayname space 'of' | 現在月のx番目の曜日を計算します。 | "first sat of July 2008" |
| 'last' space dayname space 'of' | 現在月の 最後の 曜日を計算します。 | "last sat of July 2008" |
| number space? (unit \| 'week') | 値を数値で指定するような、相対的な時間指定を処理します。 | "+5 weeks", "12 day", "-7 weekdays" |
| ordinal space unit | 値を英単語で指定するような、相対的な時間指定を処理します。 | "fifth day", "second month" |
| 'ago' | 直前に指定された相対的な時間指定について、正負反転します。 | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago" |
| dayname | 現在からみて次にやってくる、指定された曜日にします。 | "Monday" |
| reltext space 'week' | 特別な書式 "weekday + last/this/next week" を処理します。 | "Monday next week" |

### エスケープについて

Filter クエリ内では、特定の文字をそのまま検索条件として利用するために  
**エスケープ処理** が必要になります。  
特に **ダブルクオート (`"`)** と **バックスラッシュ (`\`)** は、クエリ構文に影響するため注意してください。

#### 文字列指定時のルール

- 文字列は原則として **ダブルクオート `"` で囲みます**
- 値の中にダブルクオートを含めたい場合は `\"` としてエスケープします
- バックスラッシュ自体を 1 文字として扱う場合は `\\` と記述します

#### エスケープが必要な文字

| 文字 | 用途 | エスケープ方法 | 記述例 |
|------|------|----------------|--------|
| `"`  | 文字列の区切り | `\"` | `subject eq "He said \"Hello\""` |
| `\`  | エスケープ文字 | `\\` | `path eq "C:\\data\\file.txt"` |


### :File()検索
画像の有無を元に検索を実行します。

検索の対象となる項目は以下の通りです。
- 画像(Kurocofilesにアップロード)
- ファイル(Kurocofilesにアップロード)
- ファイル(GCSにアップロード)
- ファイル(S3にアップロード)

Filterの指定例
- ext_1にファイルが存在する：`:File(exists(ext_1))`
- ext_1にファイルが存在しない：`:File(nexists(ext_1))`

:::caution
:File()による検索はコンテンツの拡張項目が`ext_1`のサイトで有効になっています。  
拡張項目のレスポンスが`ext_col_01`の形式のサイトでは動作しませんのでご注意ください。
:::

### :R()検索  
関連情報に紐づけられたコンテンツやタグの情報を条件に検索を実行できます。  
詳しい使い方は以下を参考にしてください。

:::info
- [関連しているデータを条件にしたfilter機能](/ja/docs/reference/r-filter/)
:::

### :D()検索  
地図の項目を基に、指定した位置からの距離を条件に検索できます。
詳しい使い方は以下を参考にしてください。

:::info
- [位置情報による並び替え](/ja/docs/reference/order-by-location/#filterクエリとの併用)
:::

## order_queryパラメータについて

order_query パラメータは、結果の並び順を指定するために使用します。  
このパラメータは、エンドポイントのパラメータまたはクエリパラメータとして、`フィールド名=(昇順 or 降順)` の形式で指定してください。

###  昇順

昇順（最初が小さいデータ、徐々に大きくなる）はASCになります。  
例：`/rcms-api/1/topics?order_query=topics_id=ASC`

###  降順

降順（最初が大きいデータ、徐々に小さくなる）はDESCになります。  
例：`/rcms-api/1/topics?order_query=topics_id=DESC`

## その他のパラメータについて

その他、検索実行時に指定できるパラメータは次の通りです。

| パラメータ名 | 意味 | 例 |
|-------------|-------------|-------------|
| pageID      | 何ページ目を返すかの指定 | pageID=1 |
| perPage     | 1ページあたりの結果件数 | perPage=20 |
| filter_lang | 絞り込みに利用する言語  | filter_lang=en |
| _lang       | レスポンスするコンテンツの言語 | _lang=en  |
