kintone REST APIでのクエリと文字列の正しい扱い方（パート1：クエリ記法）

1. はじめに

kintone REST APIを使う際に、クエリや返却されたデータを扱う際の文字列（文字列リテラル）の記述に初学者だと混乱することがあります。
クエリ記法の書き方についていくつか記述方法や応用例を解説します。

2. クエリ文字列の基本

kintoneのクエリ文字列は、次のような形で記述します。この例では、特定の名前フィールドに対してクエリを作成しています。

const query = '名前 = "山田太郎"'; 
kintone.api('/k/v1/records', 'GET', { app: kintone.app.getId(), query: query }).then(response => {
    console.log(response.records);
});

クエリ記法

クエリの記述において、特に注意が必要なのは引用符の使い方です。クエリ内の文字列や日付は必ず二重引用符（"）で囲む必要があります。また、テキスト値や日付のフォーマットはkintoneが指定する形式に従う必要があります。このルールを守らないと、クエリ構文エラーが発生する可能性があります。例えば、名前フィールドに対して特定の値を指定する場合、次のように記述します。

const query = '名前 = "山田太郎"';

詳細はリファレンスを確認してみてください！
https://cybozu.dev/ja/kintone/docs/overview/query/

よくしてしまう間違いパターン

混乱をしてしまうのが引用符の扱いです。たとえば次のような間違いが起こりがちです。

• 誤った例

  const query = '名前 = 山田太郎'; // 値を引用符で囲んでいないためエラー
  const queryNumber = '年齢 = "30"'; // 数値に二重引用符をつけたためエラー
  

• 正しい例

  const query = '名前 = "山田太郎"'; // 値を二重引用符で囲む
  const queryNumber = '年齢 = 30'; // 数値には引用符をつけない
  

先述のリファレンスをみて改めておさらいすると良いと思います。

3. 複雑なクエリの組み立て

動的にクエリを組み立てるには？

JSカスタマイズを行っていると実際には、動的にクエリをくみたくなる場合がよくあります。そのケースもみてみましょう。
任意の文字列を動的に組み立てるには、従来のプラス記号を使う方法と、便利なテンプレートリテラルを使う方法があります。それぞれの方法について以下で説明します。

• プラス記号（連結演算子）を使った例
  まずはプラス記号を使った方法です。文字列を手動で結合する従来通りのシンプルなやり方です。

  const name = "山田太郎";
  const queryConcat = '名前 = "' + name + '"';
  kintone.api('/k/v1/records', 'GET', { app: kintone.app.getId(), query: queryConcat 
  }).then(response => {
      console.log(response.records);
  });
  

  この方法では文字列が「+」で結合されます。ただし、書きたいクエリが複雑になるとコードが読みにくくなる傾向にあります。

• テンプレートリテラルを使った例
  次に、テンプレートリテラルを使った方法です。この方法はコードが直感的で読みやすく、特に複雑なクエリの記述に適しています。

  const query = `名前 = "${name}"`;
  kintone.api('/k/v1/records', 'GET', { app: kintone.app.getId(), query: query 
  }).then(response => {
    console.log(response.records);
  });
  

  テンプレートリテラルは比較的新しい書き方ですので、従来はプラス記法で書くのが一般的でしたが、なれるとテンプレートリテラルで書くほうが直感的で可読性が上がるので是非チャレンジしてみてください！

複数条件のクエリ

また、複数の条件を含むクエリや長いクエリを記述する場合は下記のようになります。
テンプレートリテラルで書いてみます。

• 複数条件の組み合わせ

  const name = "山田太郎";
  const status = "完了";
  const query = `名前 = "${name}" and ステータス = "${status}"`;
  kintone.api('/k/v1/records', 'GET', { app: kintone.app.getId(), query: query }).then(response => {
    console.log(response.records);
  });
  

• OR条件を含む場合

  const name = "山田太郎";
  const status = "完了";
  const query = `ステータス = "${status}" or ステータス = "進行中"`;
  kintone.api('/k/v1/records', 'GET', { app: kintone.app.getId(), query: query 
  }).then(response => {
    console.log(response.records);
  });
  

クエリが長い場合の整形方法

複数の条件を結合してクエリを作成する場合、以下のように配列を用いて整理すると管理がしやすくなります。配列に各条件を追加し、最後にjoin(' and ')で結合する方法です。
こういうやり方もある、という程度で理解してください。

const query = [
    `名前 = "山田太郎"`,
    `年齢 >= 30`,
    `ステータス = "完了"`
].join(' and ');
kintone.api('/k/v1/records', 'GET', { app: kintone.app.getId(), query: query }).then(response => {
    console.log(response.records);
});

5. よくあるエラーとその対処法

前述の通り引用符をつけ忘れたりしてしまうとエラーになってしまいます。JSカスタマイズになれないと混乱することもありますが、まずはエラーを切り分けるために送られたクエリが正しいのかを見てみましょう。

下記のように通信時エラーをみるとどのようなクエリを送っているかがわかります。
https://cybozu.dev/ja/id/42b1d7ce01fd5d9b53dbf4df/#methods-list-5

クエリがおかしいとまずコンソールに下記のようにエラーがでます。

ネットワークタブからクエリをみてみましょう。今回は文字列がダブルクォートでくくれていないのがわかります。

6. おわりに

JavaScript自体の引用符の扱い、queryの引用符の扱い、というふうにそれぞれで引用符について理解する必要があるのでややこしいですが、ここらへんは慣れもあるので繰り返し書いていくと理解できるようになるとおもいます。
こまったらぜひこの記事を読み返してみてください。