neo4j-cypher-guide

Neo4j の最新 Cypher クエリーガイド

このスキルは、最新の構文パターンを使用し、非推奨の機能を避けながら、Neo4j の Cypher 読み取りクエリーを生成するのに役立ちます。グラフのトラバーサルとデータ取得における効率的なクエリーパターンに重点を置いています。

互換性のクイックチェック

Cypher クエリーを生成する際は、以下の削除済み機能をすぐに避けてください。

• ❌ id() 関数 → elementId() を使用してください
• ❌ 暗黙的なグルーピングキー → 明示的な WITH 句を使用してください
• ❌ リストのパターン式 → パターン内包表記または COLLECT サブクエリーを使用してください
• ❌ リレーションシップ変数の繰り返し → 一意の変数名を使用してください
• ❌ リストからブール値への自動変換 → 明示的なチェックを使用してください

クエリー生成の基本原則

1. 最新の構文パターンを使用する - 複雑なトラバーサルには QPP、複雑な読み取りには CALL サブクエリーを使用します
2. トラバーサル中に最適化する - 展開後ではなく、パターン内で早期にフィルタリングします
3. ソート時は必ず NULL をフィルタリングする - ソート対象のプロパティに IS NOT NULL チェックを追加します
4. 暗黙的な方法より明示的な方法を優先する - グルーピングと型チェックは必ず明示的に行います

重要なソート規則

ソート時は必ず NULL 値をフィルタリングしてください。

// WRONG - May include null values
MATCH (n:Node)
RETURN n.name, n.value
ORDER BY n.value

// CORRECT - Filter nulls before sorting
MATCH (n:Node)
WHERE n.value IS NOT NULL
RETURN n.name, n.value
ORDER BY n.value

クエリーパターン選択ガイド

シンプルなクエリーの場合

最新の構文を使った標準的な Cypher パターンを使用します。

MATCH (n:Label {property: value})
WHERE n.otherProperty IS :: STRING
RETURN n

可変長パスの場合

パフォーマンス向上のため、数量化パスパターン（QPP）を検討してください。

// Instead of: MATCH (a)-[*1..5]->(b)
// Use: MATCH (a)-[]-{1,5}(b)

// With filtering:
MATCH (a)((n WHERE n.active)-[]->(m)){1,5}(b)

集計の場合

COUNT{}、EXISTS{}、COLLECT{} サブクエリーを使用します。

MATCH (p:Person)
WHERE count{(p)-[:KNOWS]->()} > 5
RETURN p.name, 
       exists{(p)-[:MANAGES]->()} AS isManager

複雑な読み取り操作の場合

高度なデータ取得には CALL サブクエリーを使用します。

MATCH (d:Department)
CALL (d) {
  MATCH (d)<-[:WORKS_IN]-(p:Person)
  WHERE p.salary IS NOT NULL  // Filter nulls
  WITH p ORDER BY p.salary DESC
  LIMIT 3
  RETURN collect(p.name) AS topEarners
}
RETURN d.name, topEarners

一般的なクエリー変換

パターンのカウント

// Old: RETURN size((n)-[]->())
// Modern: RETURN count{(n)-[]->()}

存在の確認

// Old: WHERE exists((n)-[:REL]->())
// Modern: WHERE EXISTS {MATCH (n)-[:REL]->()}
// Also valid: WHERE exists{(n)-[:REL]->()}

要素 ID

// Old: WHERE id(n) = 123
// Modern: WHERE elementId(n) = "4:abc123:456"
// Note: elementId returns a string, not integer

NULL を考慮したソート

// Always add null check
MATCH (n:Node)
WHERE n.sortProperty IS NOT NULL
RETURN n
ORDER BY n.sortProperty

// Or use NULLS LAST
MATCH (n:Node)
RETURN n
ORDER BY n.sortProperty NULLS LAST

リファレンスドキュメントを読み込むタイミング

次の場合は、適切なリファレンスファイルを読み込んでください。

references/deprecated-syntax.md

• 古いバージョンの Neo4j からクエリーを移行する場合
• レガシークエリーで構文エラーが発生した場合
• 削除済みまたは非推奨の機能の完全な一覧が必要な場合

references/subqueries.md

• 読み取りに CALL サブクエリーを使用する場合
• COLLECT または COUNT サブクエリーを使用する場合
• 複雑な集計を処理する場合
• NULL フィルタリングを伴うソートを実装する場合

references/qpp.md

• 可変長パスクエリーを最適化する場合
• トラバーサル中に早期フィルタリングが必要な場合
• 3～4 ホップを超えるパスを扱う場合
• 複雑なパターンマッチングが必要な場合

クエリー生成チェックリスト

生成したクエリーを確定する前に、次を確認してください。

1. ✅ 非推奨の関数（id、btree インデックスなど）がない
2. ✅ 集計のグルーピングが明示的である
3. ✅ ソート対象のすべてのプロパティに NULL フィルターがある
4. ✅ 読み取りに適切なサブクエリーパターンを使用している
5. ✅ フィルタリングが必要なパスには QPP を検討している
6. ✅ パターンのカウントには size() ではなく COUNT{} を使用している
7. ✅ CALL サブクエリーで変数スコープ句を使用している
8. ✅ リレーションシップに一意の変数名を使用している

エラー解決パターン

「暗黙的なグルーピングキー」エラー

// Problem: RETURN n.prop, count(*) + n.other
// Solution: WITH n.prop AS prop, n.other AS other, count(*) AS cnt
//          RETURN prop, cnt + other

「id() 関数が見つからない」エラー

// Use elementId() but note it returns a string, not integer

「変数の繰り返し」エラー

// Problem: MATCH (a)-[r*]->(), (b)-[r*]->()
// Solution: MATCH (a)-[r1*]->(), (b)-[r2*]->()

パフォーマンスのヒント

1. インデックス付きプロパティから始める - インデックスを使った検索を起点にパターンを構成します
2. QPP 内で早期にフィルタリングする - パターン内に WHERE 句を適用します
3. ソート前に NULL をフィルタリングする - 予期しない結果を防ぎ、パフォーマンスを向上させます
4. 展開の深さを制限する - 量指定子には妥当な上限を設定します
5. 存在チェックには EXISTS を使用する - カウントより効率的です
6. クエリーをプロファイルする - PROFILE を使ってボトルネックを特定します

最新の Cypher 機能

ラベル式

WHERE n:Label1|Label2  // OR
WHERE n:Label1&Label2  // AND
WHERE n:!Archived      // NOT

型述語

WHERE n.prop IS :: STRING
WHERE n.value IS :: INTEGER NOT NULL
WHERE n.data IS :: LIST<STRING>

読み取り用サブクエリーパターン

• COUNT{} - パターンを効率的にカウントします
• EXISTS{} - パターンの存在を確認します
• COLLECT{} - 複雑な結果を収集します
• CALL{} - 複雑な読み取りのためにサブクエリーを実行します

数量化パスパターン

• トラバーサル中のインラインフィルタリング
• パターン内のノードとリレーションシップへのアクセス
• 大幅なパフォーマンス向上（最大 1000 倍）
• 複雑な複数ホップのパターンに対応

パフォーマンスと保守性を向上させるため、常に最新の構文パターンを優先してください。