エンティティ操作

1. `ent` エンティティ操作の紹介

このチュートリアルでは、ent フレームワークでのエンティティ操作を習得するための包括的なガイドを提供します。エンティティの作成、クエリ、更新、削除の完全なプロセスについてカバーし、ent のコア機能に徐々に入り込む初心者に適しています。

3. エンティティ作成操作

3.1 単一エンティティの作成

エンティティの作成はデータ永続化の基本的な操作です。ent フレームワークを使用して単一のエンティティオブジェクトを作成し、データベースに保存する手順は以下の通りです：

まず、エンティティの構造とフィールドを定義します。つまり、schema ファイルでエンティティのモデルを定義します。
ent generate コマンドを実行して、対応するエンティティ操作コードを生成します。
生成された Create メソッドを使用して新しいエンティティを構築し、チェーンされた呼び出しを通じてエンティティのフィールド値を設定します。
最後に Save メソッドを呼び出してエンティティをデータベースに保存します。

以下はユーザーエンティティを作成して保存する方法を示す例です：

package main

import (
    "context"
    "log"
    "entdemo/ent"
)

func main() {
    // データベースの相互作用のためのクライアントインスタンスを作成
    client, err := ent.Open("sqlite3", "file:ent?mode=memory&cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("データベース接続のオープンに失敗しました：%v", err)
    }
    defer client.Close()

    // コンテキストの作成
    ctx := context.Background()
    
    // クライアントを使用してユーザーエンティティを作成
    a8m, err := client.User.
        Create().
        SetName("a8m").
        Save(ctx)
    if err != nil {
        log.Fatalf("ユーザーエンティティの作成に失敗しました：%v", err)
    }

    // エンティティがデータベースに正常に保存されました
    log.Printf("ユーザーエンティティが保存されました：%v", a8m)
}

この例ではまずデータベースクライアント client が作成されます。次に、User.Create メソッドを使用して新しいユーザーの属性を設定し、最後に Save メソッドを呼び出してユーザーをデータベースに保存します。

3.2 バッチエンティティの作成

特定のシナリオでは、データベースの初期化や大量データのインポート操作時など、複数のエンティティを作成する必要がある場合があります。ent フレームワークは、エンティティをバッチで作成する能力を提供し、個々にエンティティを作成し保存するよりも優れたパフォーマンスを提供します。

バッチエンティティの作成手順は以下の通りです：

Create メソッドの代わりに CreateBulk メソッドを使用し、単一の操作で複数のエンティティを作成します。
作成する各エンティティに対して Create を呼び出します。
すべてのエンティティを作成した後、Save メソッドを使用して一括でデータベースにエンティティを保存します。

以下はバッチエンティティの作成の例です：

package main

import (
    "context"
    "log"
    "entdemo/ent"
)

func main() {
    client, err := ent.Open("sqlite3", "file:ent?mode=memory&cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("データベース接続のオープンに失敗しました：%v", err)
    }
    defer client.Close()

    ctx := context.Background()

    // Pet エンティティのバッチ作成
    pets, err := client.Pet.CreateBulk(
        client.Pet.Create().SetName("pedro").SetOwner(a8m),
        client.Pet.Create().SetName("xabi").SetOwner(a8m),
        client.Pet.Create().SetName("layla").SetOwner(a8m),
    ).Save(ctx)
    if err != nil {
        log.Fatalf("Pet エンティティのバッチ作成に失敗しました：%v", err)
    }

    log.Printf("バッチで %d 個の Pet エンティティを作成しました\n", len(pets))
}

この例では、まず client が作成され、その後 CreateBulk メソッドを使用して複数の Pet エンティティが構築され、その名前とオーナーのフィールドが設定されます。Save メソッドを呼び出すと、すべてのエンティティが一度にデータベースに保存され、大量のデータを扱う際のパフォーマンスが向上します。

4. エンティティクエリ操作

4.1 基本的なクエリ

データベースのクエリは情報を取得するための基本的な方法です。entでは、クエリを開始するために Query メソッドが使用されます。以下に基本的なエンティティのクエリの手順と例が示されています：

使用可能な Client インスタンスがあることを確認します。
Client.Query() または Pet.Query() のようなエンティティヘルパーメソッドを使用してクエリを作成します。
必要に応じて Where などのフィルタ条件を追加します。
All メソッドを呼び出してクエリを実行し、結果を取得します。

package main

import (
    "context"
    "log"
    "entdemo/ent"
    "entdemo/ent/user"
)

func main() {
    client, err := ent.Open("sqlite3", "file:ent?cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("データベース接続のオープンに失敗しました: %v", err)
    }
    defer client.Close()
    ctx := context.Background()

    // 名前が "a8m" のすべてのユーザをクエリします
    users, err := client.User.
        Query().
        Where(user.NameEQ("a8m")).
        All(ctx)
    if err != nil {
        log.Fatalf("ユーザのクエリに失敗しました: %v", err)
    }

    for _, u := range users {
        log.Printf("ユーザが見つかりました: %#v\n", u)
    }
}

この例は、名前が "a8m" のすべてのユーザを見つける方法を示しています。

4.2 ページネーションとソート

ページネーションとソートは、クエリ時によく使用される高度な機能であり、データの出力順序と数量を制御するために使用されます。entを使用してページネーションとソートクエリを実行する方法は以下の通りです：

Limit メソッドを使用して返される結果の最大数を設定します。
Offset メソッドを使用して以前の結果のいくつかをスキップします。
Order メソッドを使用してソートフィールドと方向を指定します。

以下はページネーションとソートクエリの例です：

package main

import (
    "context"
    "log"
    "entdemo/ent"
    "entdemo/ent/pet"
)

func main() {
    client, err := ent.Open("sqlite3", "file:ent?cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("データベース接続のオープンに失敗しました: %v", err)
    }
    defer client.Close()
    ctx := context.Background()

    // 年齢の降順でペットをクエリし、ページネーションする
    pets, err := client.Pet.
        Query().
        Order(ent.Desc(pet.FieldAge)).
        Limit(10).
        Offset(0).
        All(ctx)
    if err != nil {
        log.Fatalf("ペットのクエリに失敗しました: %v", err)
    }

    for _, p := range pets {
        log.Printf("ペットが見つかりました: %#v\n", p)
    }
}

この例は、年齢の降順で並べ替えられた最初のページ、最大10件のペットを取得する方法を示しています。Limit と Offset の値を変更することで、データセット全体をページ送りすることができます。

5.2 条件付きの更新

Entを使用すると、条件に基づいて更新を行うことができます。特定の条件を満たすユーザーのみを更新する例を以下に示します。

// 仮にユーザーの `id` があり、そのユーザーを現在のバージョン `currentVersion` で完了とマークしたいとします

err := client.Todo.
    UpdateOneID(id).          // ユーザーIDによる更新用のビルダーを作成
    SetStatus(todo.StatusDone).
    AddVersion(1).
    Where(
        todo.Version(currentVersion),  // 現在のバージョンが一致する場合にのみ更新操作を実行
    ).
    Exec(ctx)
switch {
case ent.IsNotFound(err):
    fmt.Println("Todoが見つかりません")
case err != nil:
    fmt.Println("更新エラー:", err)
}

条件付きの更新を行う場合、.Where() メソッドを使用する必要があります。これにより、データベース内の現在の値に基づいて更新を実行すべきかどうかを判断でき、データの整合性と信頼性を確保する上で重要です。

6. エンティティの削除操作

6.1 単一エンティティの削除

エンティティの削除もデータベース操作において重要な機能です。Entフレームワークは、削除操作を行うためのシンプルなAPIを提供しています。

以下の例は、指定されたユーザーエンティティを削除する方法を示しています。

err := client.User.
    DeleteOne(a8m).  // ユーザー削除用のビルダーを作成
    Exec(ctx)        // 削除操作を実行
if err != nil {
    log.Fatalf("ユーザーの削除に失敗しました: %v", err)
}

6.2 条件付き削除

更新操作と同様に、特定の条件に基づいて削除操作を行うこともできます。特定の条件を満たすエンティティのみを削除したい場合があります。.Where() メソッドを使用してこれらの条件を定義できます。

// ある特定の日付よりも前に更新されたすべてのファイルを削除したいと仮定します

affected, err := client.File.
    Delete().
    Where(file.UpdatedAtLT(date)).  // ファイルの更新日時が指定された日付よりも前の場合にのみ削除を実行
    Exec(ctx)
if err != nil {
    log.Fatalf("ファイルの削除に失敗しました: %v", err)
}

// この操作は削除操作によって影響を受けたレコード数を返します
fmt.Printf("%d個のファイルが削除されました\n", affected)

条件付きの削除操作を使用することで、データ操作に対する厳密な制御が可能となり、条件を満たすエンティティのみが削除されることを保証します。これにより、データベース操作のセキュリティと信頼性が向上します。

1. ent エンティティ操作の紹介