Kintone MCP Server

// src/server/tools/documentation/queryLanguage.js /** * kintoneクエリ言語のドキュメントを取得する関数 * @returns {string} ドキュメント文字列 */ export function getQueryLanguageDocumentation() { return ` # kintoneクエリー記法ドキュメント ## 概要 kintoneでレコードを検索・取得する際に使用するクエリー記法について説明します。 クエリーは「フィールドコード 演算子 値」の形式で記述し、演算子、関数、オプションを組み合わせて柔軟な検索条件を指定できます。 ## 実行前の推奨チェック - **クエリー仕様の確認**: \`search_records\` などの検索系ツールを実行する前に、このガイドでクエリー構文と利用可能な演算子・関数を確認することを推奨します。構文エラーはkintone API側で即座に失敗します。 - **フィールド情報の把握**: 対象アプリのフィールド一覧とフィールドコードを事前に把握するために、\`get_form_fields\` ツールで最新のフォーム設定を取得してください。取得結果の \`properties\` に含まれる各フィールドの \`type\` や \`code\` を参照し、クエリーで使用できる演算子との整合性をチェックすると安全です。 - **テーブル/関連レコードの注意**: \`get_form_fields\` の結果で SUBTABLE（テーブル）やLOOKUP設定が含まれている場合、テーブル内フィールドは \`in\` 演算子の使用が必須である点など、構文上の制約を再確認してください。 - **フィールド更新後の再確認**: アプリの設定を変更した直後は、再度 \`get_form_fields\` を呼び出して最新状態を確認し、キャッシュされた情報に依存しないようにしてください。 ## 基本的な使い方のポイント - **文字列は必ずダブルクォートで囲む**: Customer = "サイボウズ株式会社" - **数値はクォートなしまたはありどちらでも可**: 数値_0 = 10 または 数値_0 = "10" - **複数値はin演算子で括弧内に記述**: Status in ("対応中","未対応") - **テーブル内フィールドは=でなくinを使用**: ResponseDate in ("2022-09-29T05:00:00Z") - **オプションの順序を守る**: order by → limit → offset ## 1. 演算子 ### 基本演算子 | 演算子 | 例 | 説明 | |--------|-----|------| | \`=\` | \`文字列_0 = "テスト"\` | 完全一致 | | \`!=\` | \`文字列_0 != "テスト"\` | 不一致 | | \`>\` | \`数値_0 > 10\` | より大きい | | \`<\` | \`数値_0 < 10\` | より小さい | | \`>=\` | \`数値_0 >= 10\` | 以上 | | \`<=\` | \`数値_0 <= 10\` | 以下 | ### 文字列演算子 | 演算子 | 例 | 説明 | |--------|-----|------| | \`in\` | \`ドロップダウン_0 in ("A", "B")\` | いずれかと一致 | | \`not in\` | \`ドロップダウン_0 not in ("A", "B")\` | いずれとも一致しない | | \`like\` | \`文字列_0 like "テスト"\` | 部分一致（含む） | | \`not like\` | \`文字列_0 not like "テスト"\` | 部分一致しない（含まない） | ### 空値判定演算子 | 演算子 | 例 | 説明 | |--------|-----|------| | \`is\` | \`文字列_複数行_0 is empty\` | フィールドが空（空文字、空白文字、改行文字、タブ文字のみ） | | \`is not\` | \`文字列_複数行_0 is not empty\` | フィールドが空でない | 注記: - \`is empty\` / \`is not empty\` が使用できるのは、フィールドタイプが「文字列（複数行）」または「添付ファイル（FILE）」の場合のみです。現状では、その他のフィールドタイプに対しては \`is empty\` / \`is not empty\` を使用できません。 - 「文字列（1行）」では \`is empty\` / \`is not empty\` は使用できません。「文字列（1行）」が空欄または空欄でないレコードを検索したい場合は \`= ""\` / \`!= ""\` を使用してください。ただし、テーブル内の「文字列（1行）」フィールドに対しては使用できません。 - 日付フィールドや日時フィールドにおいても \`is empty\` / \`is not empty\` は使用できません。これらのフィールドタイプに対して空値で検索したい場合は \`= ""\` / \`!= ""\` を使用してください。ただし、テーブル内フィールドに対しては使用できません。 ### 論理演算子 | 演算子 | 例 | 説明 | |--------|-----|------| | \`and\` | \`数値_0 >= 10 and 数値_0 <= 20\` | 論理積（両方の条件を満たす） | | \`or\` | \`数値_0 < 10 or 数値_0 > 20\` | 論理和（いずれかの条件を満たす） | ### 注意事項 - テーブル内フィールドや関連レコードフィールドでは、\`=\`や\`!=\`の代わりに\`in\`や\`not in\`を使用する必要があります - \`like\`演算子は単語検索であり、添付ファイルフィールドではファイル名とファイル内容が検索対象になります - 添付ファイル（FILE）フィールドでは \`is empty\` / \`is not empty\` により「ファイルの有無」で絞り込み可能です（クエリ式でのレコード検索に限る）。ただし、プロセス管理やアプリアクションの条件、レコード/フィールドのアクセス権の条件では使用できません - 一部の記号は文字列検索で使用できない、あるいは無視される場合があります ## 2. 関数 ### ユーザー関連関数 | 関数名 | 例 | 説明 | |--------|-----|------| | \`LOGINUSER()\` | \`作成者 in (LOGINUSER())\` | APIを実行したユーザー | | \`PRIMARY_ORGANIZATION()\` | \`組織 in (PRIMARY_ORGANIZATION())\` | APIを実行したユーザーの優先する組織 | ### 日時関連関数 | 関数名 | 例 | 説明 | |--------|-----|------| | \`NOW()\` | \`作成日時 = NOW()\` | APIを実行した日時 | | \`TODAY()\` | \`作成日時 = TODAY()\` | APIを実行した日 | | \`YESTERDAY()\` | \`作成日時 = YESTERDAY()\` | APIを実行した日の前日 | | \`TOMORROW()\` | \`日時 = TOMORROW()\` | APIを実行した日の翌日 | ### 期間指定関数 | 関数名 | 例 | 説明 | |--------|-----|------| | \`FROM_TODAY(数字, 期間の単位)\` | \`作成日時 < FROM_TODAY(5, DAYS)\` | APIを実行した日から起算した期間 | 期間の単位： - \`DAYS\`: 日単位 - \`WEEKS\`: 週単位 - \`MONTHS\`: 月単位 - \`YEARS\`: 年単位 ### 週指定関数 | 関数名 | 例 | 説明 | |--------|-----|------| | \`THIS_WEEK(曜日)\` | \`作成日時 = THIS_WEEK()\` | 今週 | | \`LAST_WEEK(曜日)\` | \`作成日時 = LAST_WEEK()\` | 前週 | | \`NEXT_WEEK(曜日)\` | \`日時 = NEXT_WEEK()\` | 翌週 | 曜日の指定（省略可）： - \`SUNDAY\`: 日曜日 - \`MONDAY\`: 月曜日 - \`TUESDAY\`: 火曜日 - \`WEDNESDAY\`: 水曜日 - \`THURSDAY\`: 木曜日 - \`FRIDAY\`: 金曜日 - \`SATURDAY\`: 土曜日 ### 月指定関数 | 関数名 | 例 | 説明 | |--------|-----|------| | \`THIS_MONTH(日付)\` | \`作成日時 = THIS_MONTH()\` | 今月 | | \`LAST_MONTH(日付)\` | \`作成日時 = LAST_MONTH()\` | 前月 | | \`NEXT_MONTH(日付)\` | \`作成日時 = NEXT_MONTH()\` | 翌月 | 日付の指定（省略可）： - \`LAST\`: 月末 - 1～31の数値: 指定日 ### 年指定関数 | 関数名 | 例 | 説明 | |--------|-----|------| | \`THIS_YEAR()\` | \`作成日時 = THIS_YEAR()\` | 今年 | | \`LAST_YEAR()\` | \`作成日時 = LAST_YEAR()\` | 前年 | | \`NEXT_YEAR()\` | \`日時 = NEXT_YEAR()\` | 翌年 | ## 3. オプション ### order by（並び替え） レコードの取得順序を指定します。 **構文**: \`order by フィールドコード 並び順\` **並び順**: - \`asc\`: 昇順 - \`desc\`: 降順 **例**: \`\`\` order by 更新日時 desc order by フィールドコード1 desc, フィールドコード2 asc \`\`\` **注意事項**: - 省略時はレコードIDの降順 - 複数フィールドでの並び替えはカンマ区切りで指定 - ソートで選択できるフィールドには制限があります ### limit（取得件数） 取得するレコード数を指定します。 **構文**: \`limit 数値\` **制限**: 1～500（省略時は100） **例**: \`limit 20\` **重要な注意事項**: - kintoneクエリー構文では、\`limit\`句のみの指定はサポートされていません - 必ず検索条件または\`order by\`句と組み合わせて使用してください - 正しい例: \`$id > 0 limit 10\` または \`order by $id desc limit 10\` - 誤った例: \`limit 10\` （このような指定は無効です） ### offset（取得開始位置） 取得をスキップするレコード数を指定します。 **構文**: \`offset 数値\` **制限**: 0～10,000（省略時は0） **例**: \`offset 30\`（31番目のレコードから取得） ### オプションの記述順序 オプションを使用する場合は、必ず以下の順序で指定してください： 1. order by 2. limit 3. offset ## 4. フィールド別利用可能演算子・関数一覧 ### 数値系フィールド | フィールドタイプ | 利用可能な演算子 | 利用可能な関数 | |----------------|-----------------|---------------| | レコード番号 | \`=\` \`!=\` \`>\` \`<\` \`>=\` \`<=\` \`in\` \`not in\` | なし | | $id | \`=\` \`!=\` \`>\` \`<\` \`>=\` \`<=\` \`in\` \`not in\` | なし | | 数値 | \`=\` \`!=\` \`>\` \`<\` \`>=\` \`<=\` \`in\` \`not in\` | なし | | 計算 | \`=\` \`!=\` \`>\` \`<\` \`>=\` \`<=\` \`in\` \`not in\` | なし | ### 文字列系フィールド | フィールドタイプ | 利用可能な演算子 | 利用可能な関数 | |----------------|-----------------|---------------| | 文字列（1行） | \`=\` \`!=\` \`in\` \`not in\` \`like\` \`not like\` | なし | | リンク | \`=\` \`!=\` \`in\` \`not in\` \`like\` \`not like\` | なし | | 文字列（複数行） | \`like\` \`not like\` \`is empty\` \`is not empty\` | なし | | リッチエディター | \`like\` \`not like\` | なし | ### 選択系フィールド | フィールドタイプ | 利用可能な演算子 | 利用可能な関数 | |----------------|-----------------|---------------| | チェックボックス | \`in\` \`not in\` | なし | | ラジオボタン | \`in\` \`not in\` | なし | | ドロップダウン | \`in\` \`not in\` | なし | | 複数選択 | \`in\` \`not in\` | なし | | ステータス | \`=\` \`!=\` \`in\` \`not in\` | なし | ### 日時系フィールド | フィールドタイプ | 利用可能な演算子 | 利用可能な関数 | |----------------|-----------------|---------------| | 日付 | \`=\` \`!=\` \`>\` \`<\` \`>=\` \`<=\` | 日付関連すべて | | 時刻 | \`=\` \`!=\` \`>\` \`<\` \`>=\` \`<=\` | なし | | 日時 | \`=\` \`!=\` \`>\` \`<\` \`>=\` \`<=\` | 日時関連すべて | ### ユーザー系フィールド | フィールドタイプ | 利用可能な演算子 | 利用可能な関数 | |----------------|-----------------|---------------| | 作成者 | \`in\` \`not in\` | \`LOGINUSER()\` | | 更新者 | \`in\` \`not in\` | \`LOGINUSER()\` | | ユーザー選択 | \`in\` \`not in\` | \`LOGINUSER()\` | | 組織選択 | \`in\` \`not in\` | \`PRIMARY_ORGANIZATION()\` | | グループ選択 | \`in\` \`not in\` | なし | ### その他のフィールド | フィールドタイプ | 利用可能な演算子 | 利用可能な関数 | |----------------|-----------------|---------------| | 添付ファイル | \`like\` \`not like\` \`is empty\` \`is not empty\` | なし | | ルックアップ | ルックアップ元のフィールドタイプと同じ | ルックアップ元のフィールドタイプと同じ | | 関連レコード | 参照するアプリのフィールドタイプと同じ | 参照するアプリのフィールドタイプと同じ | ## 5. エスケープ処理 以下のフィールドの値に\`"\`（ダブルクオート）や\`\\\`（バックスラッシュ）を含む場合、エスケープが必要です： - 文字列（1行） - 文字列（複数行） - リッチエディター - チェックボックス - ラジオボタン - ドロップダウン - 複数選択 - ステータス ### エスケープの例 **ダブルクオートを含む場合**: \`\`\` -- 「sample"1"」をエスケープ Checkbox in ("sample\\"1\\"") \`\`\` **バックスラッシュを含む場合**: \`\`\` -- 「sample\\2\\」をエスケープ Checkbox in ("sample\\\\2\\\\") \`\`\` ## 6. サンプルクエリ ### 文字列（1行）の値を指定する \`\`\` -- 完全一致 Customer = "サイボウズ株式会社" -- 部分一致 Customer like "株式会社" \`\`\` ### 文字列（複数行）の空欄チェック \`\`\` -- フィールドが空欄 Detail is empty -- フィールドが空欄でない Detail is not empty \`\`\` ### 添付ファイルの有無で絞り込む \`\`\` -- 添付ファイルが無いレコード Attachments is empty -- 添付ファイルが1つ以上あるレコード Attachments is not empty \`\`\` ### ドロップダウンの値を指定する \`\`\` -- 複数の値のいずれかに一致 Status in ("対応中","未対応") -- 特定の値を除外 Status not in ("完了") \`\`\` ### 日付フィールドの値を指定する \`\`\` -- 特定の日付 LimitDay = "2022-09-29" -- 日付範囲 LimitDay >= "2022-09-29" and LimitDay <= "2022-10-29" -- 今日より前の期限 LimitDay < TODAY() \`\`\` ### レコード番号フィールドの利用 \`\`\` -- $idを使用したレコード番号の指定 $id = 100 -- 関連レコードのレコード番号 関連レコード一覧のフィールドコード.$id = 100 \`\`\` ### 関連レコードに含まれるフィールドの値を指定する \`\`\` -- 関連レコードのフィールドを条件に使用 Company.Name in ("サイボウズ") and Company.Address like "東京都" \`\`\` ### テーブル内のフィールドの値を取得する \`\`\` -- テーブル内の日時フィールド（in演算子を使用） ResponseDate in ("2022-09-29T05:00:00Z") \`\`\` ### 複数のフィールドや条件の指定 \`\`\` -- AND条件 LimitDay < TODAY() and Status not in ("完了") -- order byを使用した条件の指定 LimitDay < TODAY() and Status not in ("完了") order by LimitDay asc \`\`\` ### 式のグループ化 \`\`\` -- 括弧を使用したグループ化 (QType in ("その他")) or (LimitDay >= "2022-09-29" and LimitDay <= "2022-10-29") \`\`\` ### ソートとページング \`\`\` -- 日付の昇順でソート LimitDay < TODAY() order by LimitDay asc -- 複数フィールドでソート Status not in ("完了") order by Priority desc, LimitDay asc -- ページング（21件目から20件取得） Status = "対応中" order by $id desc limit 20 offset 20 \`\`\` ## 7. ベストプラクティス ### パフォーマンスの最適化 1. \`like\`演算子より\`=\`や\`in\`演算子を優先する 2. 必要なレコード数だけ取得するよう\`limit\`を適切に設定する ### クエリの可読性 1. 複雑な条件は括弧でグループ化する 2. 論理演算子（\`and\`/\`or\`）の優先順位に注意する 3. クエリー文字列内ではフィールドのラベルではなく、フィールドコードを指定する必要があることを常に意識する ### エラー回避 1. 日時フィールドはISO 8601形式で指定する 2. 文字列値は必ずダブルクオートで囲む 3. \`in\`演算子の値は必ず括弧で囲む 4. オプションの記述順序を守る（order by → limit → offset） ### セキュリティ 1. ユーザー入力をクエリに含める場合は必ずエスケープ処理を行う 2. SQLインジェクションのような攻撃を防ぐため、入力値を検証する 3. 権限のないレコードはAPIレベルでフィルタリングされるが、適切なクエリ設計を心がける ## 8. 制限事項とトラブルシューティング ### 制限事項 - \`limit\`の最大値は500、最小値は1 - \`limit\`句のみの指定は無効（検索条件またはorder by句と組み合わせが必要） - \`offset\`の最大値は10000 - 500件を超えるレコードを取得する場合は、複数回のAPIコールが必要 - ソートで使用できるフィールドには制限がある - \`like\`演算子で使用できない記号がある - 「文字列（複数行）」と「添付ファイル（FILE）」に対する \`is empty\` / \`is not empty\` は「レコード検索のクエリ式」でのみ使用可能。プロセス管理・アプリアクションの条件、レコード/フィールドのアクセス権の条件では使用不可 - 「文字列（複数行）」と「添付ファイル（FILE）」以外の全てのフィールドタイプ、例えば「文字列（1行）」では \`is empty\` / \`is not empty\` は使用不可 ### よくあるエラーと対処法 **「Invalid query」エラー** - 原因：クエリの構文が正しくない - 対処：演算子の前後のスペース、引用符の閉じ忘れ、括弧の対応を確認 **「limit句のみの指定」エラー** - 原因：\`limit 10\`のように、limit句のみを指定している - 対処：検索条件またはorder by句と組み合わせる - 例：\`$id > 0 limit 10\` または \`order by $id desc limit 10\` **「Field not found」エラー** - 原因：存在しないフィールドコードを指定 - 対処：フィールドコードのスペルミス、大文字小文字を確認 **「Invalid operator」エラー** - 原因：フィールドタイプに対して使用できない演算子を使用 - 対処：フィールドタイプ別の利用可能演算子一覧を確認 **日時の検索がうまくいかない** - 原因：タイムゾーンの考慮不足 - 対処：日時はUTC形式（末尾にZ）で指定、またはタイムゾーンを明示 **テーブル内フィールドの検索エラー** - 原因：\`=\`演算子を使用している - 対処：\`in\`または\`not in\`演算子を使用 `; }