Azure Cosmos DB を使ったデータ操作の基本体験

## 目次
- [はじめに](#はじめに)
- [Azure Cosmos DBについて](#azure-cosmos-dbについて)
  - [概要](#概要)
  - [主な特徴](#主な特徴)
  - [主な用途](#主な用途)
- [実際に導入する](#実際に導入する)
  - [準備](#準備)
  - [Azure Cosmos DB作成方法](#azure-cosmos-db作成方法)
  - [Azure Cosmos DB を使った保存・取得・更新の基本操作](#azure-cosmos-db-を使った保存取得更新の基本操作)
- [まとめ](#まとめ)

## はじめに
こんにちは！TechoesのCです。
前回の記事では、Azure を使ってフロントエンドページを構成・デプロイする方法を体験しました。

今回は、Azure Cosmos DB を利用し、データベースの作成や接続方法、保存・取得の基本的な操作について確認してみました。
これにより、Azure 上で NoSQL データベースを扱う際の基礎的な流れを理解することができます。

なお、記事の都合上、今回は主に データ操作の方法 にフォーカスしており、実際のアプリ連携やコード全体の構成については、今後の記事で取り上げる予定です。

## Azure Cosmos DBについて
### 概要

Azure Cosmos DB は、Azure が提供する スケーラブルな NoSQL データベース で、無料枠を利用することで コストをかけずにデータ管理機能を追加できる のが魅力です。

ここでは、フロントエンドから Cosmos DB にデータを保存・取得・更新 する方法を紹介します。

### 主な特徴
 -  **スキーマレスな NoSQL データベース：** JSON 形式でデータを柔軟に保存・管理
 -  **グローバル分散：** Azure の複数リージョンにデータをレプリケーションし、低レイテンシーを実現
 -  **マルチモデル対応：** SQL、MongoDB、Gremlin（グラフDB）、Cassandra など複数の API を利用可能
 -  **無料プランあり：** 400 RU/s（リクエストユニット）と 50GB のストレージを無料で使用可能

### 主な用途
 -  **フロントエンドアプリのデータ管理：** Web アプリやモバイルアプリでのユーザー情報の保存
 -  **IoT データの収集・分析：** センサーやログデータのリアルタイム処理
 -  **EC・SNS のデータ管理：** ショッピングサイトやソーシャルメディアのユーザデータをスケーラブルに管理
 -  **リアルタイム分析：** 低レイテンシーを活かしたダッシュボードやデータ可視化


## 実際に導入する
### 準備
 -  **Azureアカウント作成**

前回の記事でも説明したように、Azure Cosmos DB を利用するには Azure アカウントが必要 です。

まだアカウントを作成していない場合は、以下の記事を参考に Azure の無料アカウントを作成 してください。

https://qiita.com/i-chini-techoes/items/f94b2fc0dd0e5928a006

アカウントを作成すると、無料で Azure Cosmos DB を利用できるクレジット（$200分）や、無料枠のリソース（400 RU/s、50GB ストレージ）を活用できます。

### Azure Cosmos DB作成方法

**1. Azure Portal で Azure  Cosmos DB を新規作成**

Azure Portal にログイン し、左側のメニューから 「Azure Cosmos DB」 を開きます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/7e03fcbb-6bac-4d50-b34e-64f13d3cd179.png)

「+ 作成」ボタンをクリック し、新しい Cosmos DB を作成します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/221c4a6c-32dc-4e7b-9615-c2573b69953d.png)

「NoSQL」 を選択し、「作成」ボタンをクリック。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/a9da3ee5-442b-4411-9803-978272931e53.png)

**2. Azure Portal で作成した Azure Cosmos DB を開く**
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/096cd4ae-393d-45db-ace2-37b2961a3dce.png)

画面内の各項目に、次の情報を入力します。
| 設定項目  | 設定内容 |
|--------|------|
| サブスクリプション   | Azure subscription 1（選択できるものを指定）   |
| リソース グループ   | 必要なら「新規作成」または既存のものを選択   |
| アカウント名   | 任意の名前   |
| 場所（リージョン）   | 利用可能なリージョンを選択   |
| Availability Zones   | 有効 または 無効（リージョンによって異なる）   |

「容量モード」 の選択肢
 -  「プロビジョニングされたスループット」 → 手動またはオートスケール（一般的に選ばれる）
 -  「Serverless」 → 使用した分だけ課金（スモールプロジェクト向け）

作成完了後、Azure Portal の「リソースに移動」をクリックして、Cosmos DB の管理画面に入る。作成された Cosmos DB は以下のように表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/9b5c0a99-dcc2-43bb-b15b-2d6a4420b7d2.png)

**Azure Cosmos DB のデータ構成**
 
 Azure Cosmos DB では、データは データベース → コンテナー → ドキュメント（JSON） の階層で管理されます。
今回は、データベース（noticedb） を作成し、その中に コンテナー（notices） を追加し、フロントエンドから利用するデータを格納します。
 
まず、Azure Cosmos DB の「データエクスプローラー」に移動し、新しいデータベースを作成します。

 -  [New Database] ボタンをクリック
 -  データベース名を入力（例：noticedb）
 -  スループット設定 は無料枠を使う場合は Autoscale か Serverless を選択
 -  [作成] をクリック してデータベースを作成

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/aee61652-c5ac-40fb-8fdc-d9bd41dc373b.png)

次に、このデータベース内に データを保存するコンテナー を作成します。

 -  [New Container] をクリック
 -  Database を noticedb に設定
 -  コンテナー名（例：notices）を入力
 -  パーティションキー を設定（例：/id）
 -  [OK] をクリック して作成

 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/ca29c930-dccd-40f2-bcb2-7e5a02a73205.png)


作成が完了すると、左側のリストに noticedb の下に notices が表示されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/3f0568f1-a5e5-4432-8818-60f20760537e.png)


次に、データを追加します。

**1. [New Item] をクリック**
 
 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/7a082b72-1474-449f-a3d2-ac7f236df6ca.png)

**2. データを登録する際は、以下のような JSON フォーマットを使用**

Azure Cosmos DB では **データは JSON 形式で管理** されており、新しいアイテムを追加する際も **JSON データを入力する** 形になります。例えば、以下のようなデータを登録できます。

```json
{
  "id": "1740501888207",
  "title": "01",
  "content": "test01",
  "createdAt": "2025-02-25T16:44:48.2027",
  "isDeleted": false,
  "updatedAt": "2025-02-25T16:44:48.2027"
}
 ```
**3.[Save] をクリックしてデータを保存**

 これで、Cosmos DB に notices コンテナーを作成し、フロントエンドで利用するデータを保存する準備ができました。
 
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/422297ac-33a4-47db-abf3-f01f7c026af7.png)

次は、このデータをフロントエンドから保存・取得・更新する方法 について説明していきます！ 

### Azure Cosmos DB を使った保存・取得・更新の基本操作
ここでは、実際にフロントエンドから Azure Cosmos DB のデータを更新 する流れを紹介します。

Azure Cosmos DB は **NoSQL** のため、MySQL などのリレーショナルデータベースとは異なり、API を通じてデータを **保存・取得・更新** するのが一般的です。
データの更新も SQL の **UPDATE** 文のように単純ではなく、**データを取得→編集→上書き** という流れになります。

**1. Azure Cosmos DB に接続するための情報取得**
フロントエンドやバックエンドから Azure Cosmos DB にアクセスするためには、以下の情報が必要です。

これらの情報は Azure Portal の Azure Cosmos DB の管理画面にある 「キー」タブ で確認できます。

**必要な情報**
| 項目 | 説明 | 確認場所 |
|------|------|---------|
| **URI（エンドポイント）** | API で Azure Cosmos DB にアクセスするための URL | Azure Portal > Cosmos DB > 「キー」タブ |
| **プライマリキー（Primary Key）** | 認証用のキー。バックエンドからアクセスする際に使用 | Azure Portal > Azure Cosmos DB > 「キー」タブ |
| **データベース ID** | データを保存するデータベース名 | Azure Portal > Azure Cosmos DB > 「データ エクスプローラー」 |
| **コンテナー ID** | テーブルに相当するコンテナー名 | Azure Portal > Azure Cosmos DB > 「データ エクスプローラー」 |

**「キー」タブの確認方法**
1. **Azure Portal にログイン**
2. **Azure Cosmos DB の管理画面 を開く**
3. **「キー」タブ を選択**
4. **URI とプライマリキー を取得**

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3565778/39d2c082-01e4-4544-8027-1dca1b619074.png)

この情報を元に、次のコードのように Azure Cosmos DB に接続します。

```javascript
const { CosmosClient } = require("@azure/cosmos");

const endpoint = "https://your-cosmosdb.documents.azure.com:443/";
const key = "your-primary-key";
const client = new CosmosClient({ endpoint, key });

const database = client.database("your-database");
const container = database.container("your-container");
 ```
 
**2. Cosmos DB（NoSQL） にデータを保存・取得**

Cosmos DB は NoSQL の JSON データベース であり、一般的な MySQL とは異なり スキーマレス でデータを保存できます。
ここでは、フロントエンドから Cosmos DB にデータを保存・取得する方法 を説明します。

**データ保存**
Azure Cosmos DB は MySQL のように `INSERT INTO` を使わず、**JSON データをオブジェクトとしてそのまま送信** する形式になります。

📝 **データ保存のサンプルコード**

```javascript
const { CosmosClient } = require("@azure/cosmos");

const endpoint = "https://your-cosmosdb.documents.azure.com:443/";
const key = "your-primary-key";
const databaseId = "your-database";
const containerId = "your-container";

// Cosmos DB クライアントの作成
const client = new CosmosClient({ endpoint, key });
const container = client.database(databaseId).container(containerId);

// 保存するデータ
const newItem = {
  id: "1001",
  title: "新しいお知らせ",
  content: "Cosmos DB にデータを保存しました。",
  createdAt: new Date().toISOString()
};

// データを追加
async function addItem() {
  const { resource } = await container.items.create(newItem);
  console.log("保存完了：", resource);
}

addItem();

 ```
**✅ポイント**
- **SQL の `UPDATE` 文を使用**
- **特定のカラム のみ更新可能**
- **`WHERE` 句 で条件指定**
---
**データ取得**
Azure Cosmos DB では SELECT * FROM のような SQL ライクなクエリも利用できます。

📝 **データ取得のサンプルコード**
```javascript
async function getItems() {
    const querySpec = {
        query: "SELECT * FROM c WHERE c.id = @id",
        parameters: [{ name: "@id", value: "1001" }]
    };

    const { resources } = await container.items.query(querySpec).fetchAll();
    console.log("取得したデータ:", resources);
}

getItems();
 ```
 
**✅ポイント**
- **SQL 風のクエリ でデータを取得**
- **`WHERE` を使って特定の id のみ取得も可能**

---
**データの更新**
Azure Cosmos DB では UPDATE という概念がなく、データを取得して編集し、上書きする 形で更新を行います。

📝 **データ取得のサンプルコード**
```javascript
async function updateItem(id, newTitle, newContent) {
    const { resource: item } = await container.item(id, id).read(); // 既存データを取得
    item.title = newTitle;
    item.content = newContent;
    await container.item(id, id).replace(item); // 上書き保存
}
 ```
 
**✅ポイント**
- **データ全体を取得して上書きするのが基本**
- **更新時も JSON オブジェクトとして扱うため、スキーマレスで自由度が高い**
---
Azure Cosmos DB のデータ保存・取得・更新の方法は、通常の SQL データベースとは異なります。以下の表に違いをまとめました。
| 操作        | Cosmos DB (NoSQL) | 通常の SQL データベース |
|------------|------------------|----------------------|
| **データ保存** | `items.create(data)` を使用し、JSON をそのまま保存 | `INSERT INTO` 文を使用 |
| **データ取得** | `container.items.query(SQL).fetchAll()` を使用 | `SELECT` 文を使用 |
| **データ更新** | `container.item(id).replace(data)` を使用し、取得→編集→上書き | `UPDATE` 文で特定カラムを更新 |
| **データ削除** | `container.item(id).delete()` を使用 | `DELETE` 文を使用 |
| **スキーマ** | スキーマレス（JSON 形式で自由に構造変更可能） | 固定スキーマ（テーブル定義が必要） |
| **クエリ** | SQL ライクな `SELECT * FROM c WHERE c.id = 'xxx'` | 標準 SQL (`SELECT * FROM table WHERE id = 'xxx'`) |
| **トランザクション** | 単一のドキュメント単位で処理 | トランザクションをサポート |



✅ **ポイント**
- **Cosmos DB は NoSQL なので JSON ベースの操作が基本**
- **データ更新は `UPDATE` ではなく、取得→編集→上書き**
- **SQL のようなクエリが使えるが、RDB とは異なる設計が必要**
## まとめ

今回は、Azure Cosmos DB を使って、データベースの作成から接続、そして基本的なデータ操作までを一通り試してみました。
保存や取得といった処理がどのように行えるのか、そして構成の考え方なども含めて、実際に触れてみることで理解が深まりました。

なお、コード全体の構成や応用的な使い方については、別の記事であらためてまとめる予定です。
まずは「使ってみる」ことを目的とした内容として、今後 Azure のサービスと連携する際の一つの参考になれば幸いです。