変更要約: DP-420 第2章を新規作成（ドメイン1後半: SDK クライアント接続(gateway vs direct/シングルトン/エミュレーター/優先リージョン/429・一時エラーのリトライ)、SQL クエリとデータアクセス(配列・ネスト・集計・サブクエリ・関数/ポイント操作 vs クエリ/パッチ/Transactional Batch/Bulk/ETag 楽観的同時実行/一貫性上書き・セッショントークン/ページネーション・継続トークン/クエリメトリクス)、サーバーサイド JS(ストアドプロシージャ=論理パーティション内 ACID/プリ・ポストトリガー/UDF)）。
2.1SDK クライアント接続
Azure Cosmos DB SDK の接続モード（ゲートウェイ vs ダイレクト）、クライアントのシングルトン、エミュレーターでのオフライン開発、接続エラー処理、リージョン指定、SDK ロギングを理解します。
アプリは Azure Cosmos DB SDK（.NET/Java 等）でデータにアクセスします。接続の仕方とクライアントの扱いが、レイテンシ・スループット・コストに直結します。
2.1.1接続モードとシングルトン
接続モード は 2 つ＝ゲートウェイ（gateway） は HTTPS（443）でゲートウェイ経由、ファイアウォール越えが容易で接続数が少ないが遅延はやや大きい。ダイレクト（direct） は TCP でレプリカに直接つなぎ、低遅延・高スループットで本番に推奨される（より多くのポート/接続が必要）。CosmosClient はアプリ全体で 1 つ（シングルトン） として再利用する＝接続/メタデータのキャッシュが効き、リクエストごとに生成すると性能が劣化し接続を浪費する。
2.1.2エミュレーター・リージョン・エラー処理
Cosmos DB エミュレーター はローカルでサービスを模擬し、クラウド課金なしでオフライン開発/テストができる。グローバル分散では SDK に 優先リージョン（ApplicationPreferredRegions） を指定し、近いリージョンから読み、障害時に次のリージョンへフェイルオーバーさせる。一時エラー（transient）と 429（レート制限） は SDK の組み込みリトライ（再試行ポリシー）で処理するのが基本で、429 では Retry-After に従って待ってから再試行する。SDK ロギングを有効にして診断する。
決め手：「低遅延・高スループットの本番」＝ダイレクトモード。「ファイアウォール越え・接続を絞る」＝ゲートウェイ。CosmosClient はシングルトンで再利用。オフライン開発＝エミュレーター。「近いリージョンから読む/フェイルオーバー」＝優先リージョン。429/一時エラー＝SDK リトライ。
混同に注意：
①ダイレクト（性能・要ポート開放）とゲートウェイ（容易・遅延大）を取り違えない。
②CosmosClient をリクエストごとに生成しない（シングルトン）。
③429 は SDK リトライで吸収＝アプリで握り潰さず Retry-After に従う。
④優先リージョン未設定だと書き込みリージョンに固定され遅延が増えうる。
2.1.3この節のまとめ
- 接続モード＝ダイレクト(低遅延・本番) / ゲートウェイ(ファイアウォール越え容易)、CosmosClient はシングルトン
- エミュレーターでオフライン開発、優先リージョンで近接読み取り/フェイルオーバー
- 429/一時エラーは SDK のリトライで処理（Retry-After に従う）
進捗の記録にはログインが必要です。
理解度チェック
（軽い確認用）Q1. 本番アプリで最も低い遅延と高いスループットで Cosmos DB に接続したい。最適な接続モードはどれですか？
Q2. CosmosClient のインスタンス管理として正しいのはどれですか？
Q3. クラウド課金なしでローカルに Cosmos DB を模擬し、オフラインで開発/テストしたい。最適なのはどれですか？
Q4. プロビジョニング RU を超過して 429 が返るとき、SDK 利用アプリの正しい対処はどれですか？
Q5. グローバル分散環境で、アプリに最も近いリージョンから読み取り障害時に次へフェイルオーバーさせたい。最適なのはどれですか？