Laravel 5.3 データベース:クエリビルダ

イントロダクション

データベースクエリビルダはスラスラと書ける(fluent)便利なインターフェイスで、クエリを作成し実行するために使用します。アプリケーションで行われるほとんどのデーターベース操作が可能で、サポートしている全データベースシステムに対し使用できます。

LaravelクエリビルダはアプリケーションをSQLインジェクション攻撃から守るために、PDOパラメーターによるバインディングを使用します。バインドする文字列をクリーンにしてから渡す必要はありません。

結果の取得

全レコードの取得

クエリを書くにはDBファサードのtableメソッドを使います。tableメソッドは指定したテーブルに対するクエリビルダインスタンスを返します。これを使いクエリに制約を加え、最終的な結果を取得するチェーンを繋げます。次に、最終的な結果をgetで取得します。

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
    /**
     * アプリケーションの全ユーザーレコード一覧を表示
     *
     * @return Response
     */
    public function index()
    {
        $users = DB::table('users')->get();

        return view('user.index', ['users' => $users]);
    }
}

getメソッドは、PHPのStdClassオブジェクトのインスタンスを結果として含む、Illuminate\Support\Collectionを返します。各カラムの値は、オブジェクトのプロパティとしてアクセスできます。

foreach ($users as $user) {
    echo $user->name;
}

テーブルから1カラム/1レコード取得

データベーステーブルから1レコードのみ取得する必要がある場合は、firstメソッドを使います。このメソッドはStdClassオブジェクトを返します。

$user = DB::table('users')->where('name', 'John')->first();

echo $user->name;

全カラムは必要ない場合、valueメソッドにより一つの値のみ取得できます。このメソッドはカラムの値を直接返します。

$email = DB::table('users')->where('name', 'John')->value('email');

カラム値をリストで取得

単一カラムの値をコレクションで取得したい場合はpluckメソッドを使います。以下の例では役割名(title)をコレクションで取得しています。

$titles = DB::table('roles')->pluck('title');

foreach ($titles as $title) {
    echo $title;
}

取得コレクションのキーカラムを指定することもできます。

$roles = DB::table('roles')->pluck('title', 'name');

foreach ($roles as $name => $title) {
    echo $title;
}

結果の分割

数千のデータベースレコードを扱う場合はchunkメソッドの使用を考慮してください。このメソッドは一度に小さな「かたまり(chunk)」で結果を取得し、このチャンクは処理のために「クロージャ」に渡されます。このメソッドは数千のレコードを処理するArtisanコマンドを書くときに便利です。usersレコード全体から一度に100レコードずつチャンクを処理する例を見てください。

DB::table('users')->orderBy('id')->chunk(100, function ($users) {
    foreach ($users as $user) {
        //
    }
});

クロージャからfalseを返すとチャンクの処理を中断できます。

DB::table('users')->orderBy('id')->chunk(100, function ($users) {
    // レコードの処理…

    return false;
});

集計

またクエリビルダはcountmaxminavgsumなど多くの集計メソッドを提供しています。クエリを制約した後にこれらのメソッドを使うことも可能です。

$users = DB::table('users')->count();

$price = DB::table('orders')->max('price');

もちろんこれらのメソッドをクエリを構築するために他の節と組み合わせて使用できます。

$price = DB::table('orders')
                ->where('finalized', 1)
                ->avg('price');

SELECT

SELECT節の指定

もちろん、いつもデータベースレコードの全カラムが必要ではないでしょう。クエリのselect節をselectメソッドで指定できます。

$users = DB::table('users')->select('name', 'email as user_email')->get();

distinctメソッドで重複行をまとめた結果を返すように強制できます。

$users = DB::table('users')->distinct()->get();

既にクエリビルダインスタンスがあり、select節にカラムを追加したい場合はaddSelectメソッドを使ってください。

$query = DB::table('users')->select('name');

$users = $query->addSelect('age')->get();

SQL文

たまにクエリの中でSQLを直接使用したいことがあります。このようなSQLでは文字をそのまま埋め込むだけですので、SQLインジェクションをされないように気をつけてください! エスケープなしのSQLを使用する場合はDB::rawメソッドを使用します。

$users = DB::table('users')
                     ->select(DB::raw('count(*) as user_count, status'))
                     ->where('status', '<>', 1)
                     ->groupBy('status')
                     ->get();

JOIN

INNER JOIN文

さらにクエリビルダはJOIN文を書くためにも使用できます。基本的な"INNER JOIN"を実行するには、クエリビルダインスタンスにjoinメソッドを使ってください。joinメソッドの第1引数は結合したいテーブル名、それ以降の引数にはJOIN時のカラムの制約条件を指定します。もちろん下記のように、一つのクエリで複数のテーブルを結合できます。

$users = DB::table('users')
            ->join('contacts', 'users.id', '=', 'contacts.user_id')
            ->join('orders', 'users.id', '=', 'orders.user_id')
            ->select('users.*', 'contacts.phone', 'orders.price')
            ->get();

LEFT JOIN文

"INNER JOIN"の代わりに"LEFT JOIN"を実行したい場合はleftJoinメソッドを使います。leftJoinメソッドの使い方はjoinメソッドと同じです。

$users = DB::table('users')
            ->leftJoin('posts', 'users.id', '=', 'posts.user_id')
            ->get();

クロスジョイン文

「クロスジョイン」を実行するときは、接合したいテーブル名を指定し、crossJoinメソッドを使ってください。クロスジョインにより、最初のテーブルと指定したテーブルとの、デカルト積を生成します。

$users = DB::table('sizes')
            ->crossJoin('colours')
            ->get();

上級のJOIN文

さらに上級なJOIN節を指定することもできます。そのためにはjoinメソッドの第2引数に「クロージャ」を指定します。その「クロージャ」はJOIN節に制約を指定できるようにするJoinClauseオブジェクトを受け取ります。

DB::table('users')
        ->join('contacts', function ($join) {
            $join->on('users.id', '=', 'contacts.user_id')->orOn(...);
        })
        ->get();

JOINに"where"節を使用したい場合はjoinの中でwhereorWhereを使用して下さい。2つのカラムを比べる代わりに、これらのメソッドは値とカラムを比較します。

DB::table('users')
        ->join('contacts', function ($join) {
            $join->on('users.id', '=', 'contacts.user_id')
                 ->where('contacts.user_id', '>', 5);
        })
        ->get();

UNION

クエリビルダは2つのクエリを結合(union)させる手軽な手法を提供します。たとえば最初にクエリを作成し、その後に2つ目のクエリを結合するためにunionメソッドを使います。

$first = DB::table('users')
            ->whereNull('first_name');

$users = DB::table('users')
            ->whereNull('last_name')
            ->union($first)
            ->get();

Tip!! unionと同じ使い方のunionAllメソッドも使えます。

WHERE節

単純なWHERE節

where節をクエリに追加するには、クエリビルダインスタンスのwhereメソッドを使います。基本的なwhereの呼び出しでは3つの引数を使います。第1引数はカラム名です。第2引数はデータベースがサポートしているオペレーターです。第3引数はカラムに対して比較する値です。

例として、"votes"カラムの値が100と等しいレコードのクエリを見てください。

$users = DB::table('users')->where('votes', '=', 100)->get();

利便性のため、カラムが指定値と等しいかを比べたい場合は、whereメソッドの第2引数に値をそのまま指定できます。

$users = DB::table('users')->where('votes', 100)->get();

もちろん、where文を書くときには、その他いろいろなオペレータも使えます。

$users = DB::table('users')
                ->where('votes', '>=', 100)
                ->get();

$users = DB::table('users')
                ->where('votes', '<>', 100)
                ->get();

$users = DB::table('users')
                ->where('name', 'like', 'T%')
                ->get();

whereに配列で条件を渡すこともできます。

$users = DB::table('users')->where([
    ['status', '=', '1'],
    ['subscribed', '<>', '1'],
])->get();

OR節

WHEREの結合にチェーンでor節をクエリに追加できます。orWhereメソッドはwhereメソッドと同じ引数を受け付けます。

$users = DB::table('users')
                    ->where('votes', '>', 100)
                    ->orWhere('name', 'John')
                    ->get();

その他のWHERE節

whereBetween

whereBetweenメソッドはカラムの値が2つの値の間である条件を加えます。

$users = DB::table('users')
                    ->whereBetween('votes', [1, 100])->get();

whereNotBetween

whereNotBetweenメソッドは、カラムの値が2つの値の間ではない条件を加えます。

$users = DB::table('users')
                    ->whereNotBetween('votes', [1, 100])
                    ->get();

whereIn / whereNotIn

whereInメソッドは指定した配列の中にカラムの値が含まれている条件を加えます。

$users = DB::table('users')
                    ->whereIn('id', [1, 2, 3])
                    ->get();

whereNotInメソッドはカラムの値が指定した配列の中に含まれていない条件を加えます。

$users = DB::table('users')
                    ->whereNotIn('id', [1, 2, 3])
                    ->get();

whereNull / whereNotNull

whereNullメソッドは指定したカラムの値がNULLである条件を加えます。

$users = DB::table('users')
                    ->whereNull('updated_at')
                    ->get();

whereNotBetweenメソッドは指定したカラムの値がNULLでない条件を加えます。

$users = DB::table('users')
                    ->whereNotNull('updated_at')
                    ->get();

whereDate / whereMonth / whereDay / whereYear

whereDateメソッドはカラム値を日付と比較する時に使用します。

$users = DB::table('users')
                ->whereDate('created_at', '2016-12-31')
                ->get();

whereMonthメソッドはカラム値と、ある年の指定した月とを比較します。

$users = DB::table('users')
                ->whereMonth('created_at', '12')
                ->get();

whereDayメソッドはカラム値と、ある月の指定した日とを比べます。

$users = DB::table('users')
                ->whereDay('created_at', '31')
                ->get();

whereYearメソッドはカラム値と、指定した年とを比べます。

$users = DB::table('users')
                ->whereYear('created_at', '2016')
                ->get();

whereColumn

whereColumnメソッドは2つのカラムが同値である確認をするのに使います。

$users = DB::table('users')
                ->whereColumn('first_name', 'last_name')
                ->get();

メソッドに比較演算子を追加指定することもできます。

$users = DB::table('users')
                ->whereColumn('updated_at', '>', 'created_at')
                ->get();

whereColumnへ配列により複数の条件を渡すこともできます。各条件はandオペレータでつなげられます。

$users = DB::table('users')
                ->whereColumn([
                    ['first_name', '=', 'last_name'],
                    ['updated_at', '>', 'created_at']
                ])->get();

パラメータのグループ分け

時には、"WHERE EXISTS"節やグループにまとめたパラーメーターのネストのような、上級のWHERE節を作成する必要が起きます。Laravelクエリビルダはこれらもうまく処理できます。手始めに、カッコで制約をまとめる例を見てください。

DB::table('users')
            ->where('name', '=', 'John')
            ->orWhere(function ($query) {
                $query->where('votes', '>', 100)
                      ->where('title', '<>', 'Admin');
            })
            ->get();

ご覧の通り、orWhereメソッドに渡している「クロージャ」が、クエリビルダのグルーピングを指示しています。生成するSQLの括弧内で展開される制約を指定できるように、「クロージャ」はクエリビルダのインスタンスを受け取ります。

select * from users where name = 'John' or (votes > 100 and title <> 'Admin')

Where Exists節

whereExistsメソッドはWHERE EXISTSのSQLを書けるように用意しています。whereExistsメソッドは引数に「クロージャー」を取り、"EXISTS"節の中に置かれるクエリーを定義するためのクエリービルダーを受け取ります。

DB::table('users')
            ->whereExists(function ($query) {
                $query->select(DB::raw(1))
                      ->from('orders')
                      ->whereRaw('orders.user_id = users.id');
            })
            ->get();

上のクエリは以下のSQLを生成します。

select * from users
where exists (
    select 1 from orders where orders.user_id = users.id
)

JSON WHERE節

Laravelはデータベース上のJSONタイプをサポートするカラムに対するクエリに対応しています。現在、MySQL5.7とPostgresに対応しています。JSONカラムをクエリーするには->オペレータを使ってください。

$users = DB::table('users')
                ->where('options->language', 'en')
                ->get();

$users = DB::table('users')
                ->where('preferences->dining->meal', 'salad')
                ->get();

順序、グループ分け、制限、オフセット

orderBy

orderByメソッドは指定したカラムでクエリ結果をソートします。orderByメソッドの最初の引数はソート対象のカラムで、第2引数はソートの昇順(asc)と降順(desc)をコントロールします。

$users = DB::table('users')
                ->orderBy('name', 'desc')
                ->get();

latest/oldest

latestoldestメソッドにより、データの結果を簡単に整列できます。デフォルトで、結果はcreated_atカラムによりソートされます。ソートキーとしてカラム名を渡すこともできます。

$user = DB::table('users')
                ->latest()
                ->first();

inRandomOrder

inRandomOrderメソッドはクエリ結果をランダムな順番にしたい時に使用します。たとえば、以下のコードはランダムにユーザを一人取得します。

$randomUser = DB::table('users')
                ->inRandomOrder()
                ->first();

groupBy / having / havingRaw

groupByhavingメソッドはクエリ結果をグループにまとめるために使用します。havingメソッドはwhereメソッドと似た使い方です。

$users = DB::table('users')
                ->groupBy('account_id')
                ->having('account_id', '>', 100)
                ->get();

havingRawメソッドはhaveing節の値としてSQL文字列をそのまま指定するために使用します。たとえば2,500ドルより多く売り上げている部門(department)を全部見つけましょう。

$users = DB::table('orders')
                ->select('department', DB::raw('SUM(price) as total_sales'))
                ->groupBy('department')
                ->havingRaw('SUM(price) > 2500')
                ->get();

skip / take

クエリから限られた(LIMIT)数のレコードを受け取ったり、結果から指定した件数を飛ばしたりするには、skiptakeメソッドを使います。

$users = DB::table('users')->skip(10)->take(5)->get();

別の方法として、limitoffsetメソッドも使用できます。

$users = DB::table('users')
                ->offset(10)
                ->limit(5)
                ->get();

条件節

ある条件がtrueの場合の時のみ、クエリへ特定の文を適用したい場合があります。例えば特定の入力値がリクエストに含まれている場合に、where文を適用する場合です。whenメソッドで実現できます。

$role = $request->input('role');

$users = DB::table('users')
                ->when($role, function ($query) use ($role) {
                    return $query->where('role_id', $role);
                })
                ->get();

whenメソッドは、第1引数がtrueの時のみ、指定されたクロージャを実行します。最初の引数がfalseの場合、クロージャを実行しません。

whenメソッドの第3引数に別のクロージャを渡せます。このクロージャは、最初の引数の評価がfalseであると実行されます。この機能をどう使うかを確認するため、クエリのデフォルトソートを設定してみましょう。

$sortBy = null;

$users = DB::table('users')
                ->when($sortBy, function ($query) use ($sortBy) {
                    return $query->orderBy($sortBy);
                }, function ($query) {
                    return $query->orderBy('name');
                })
                ->get();

INSERT

クエリビルダは、データベーステーブルにレコードを挿入するためのinsertメソッドを提供しています。insertメソッドは挿入するカラム名と値の配列を引数に取ります。

DB::table('users')->insert(
    ['email' => 'john@example.com', 'votes' => 0]
);

配列の配列をinsertに渡して呼び出すことで、テーブルにたくさんのレコードを一度にまとめて挿入できます。

DB::table('users')->insert([
    ['email' => 'taylor@example.com', 'votes' => 0],
    ['email' => 'dayle@example.com', 'votes' => 0]
]);

自動増分ID

テーブルが自動増分IDを持っている場合、insertGetIdメソッドを使うとレコードを挿入し、そのレコードのIDを返してくれます。

$id = DB::table('users')->insertGetId(
    ['email' => 'john@example.com', 'votes' => 0]
);

Note: PostgreSQLでinsertGetIdメソッドを使う場合、自動増分カラム名はidである必要があります。他の「シーケンス」からIDを取得したい場合は、insertGetIdメソッドの第2引数にシーケンス名を指定してください。

UPDATE

もちろん、データベースへレコードを挿入するだけでなく、存在しているレコードをupdateメソッドで更新することもできます。updateメソッドはinsertメソッドと同様に、更新対象のカラムのカラム名と値の配列を引数に受け取ります。更新するクエリをwhere節を使って制約することもできます。

DB::table('users')
            ->where('id', 1)
            ->update(['votes' => 1]);

JSONカラムの更新

JSONカラムを更新する場合、JSONオブジェクトの中の適切なキーへアクセスするために、->記法を使ってください。JSONカラムをサポートしているデータベースでのみ、このオペレータをサポートしています。

DB::table('users')
            ->where('id', 1)
            ->update(['options->enabled' => true]);

増減分

クエリビルダは指定したカラムの値を増やしたり、減らしたりするのに便利なメソッドも用意しています。これはシンプルな短縮記法で、update分で書くのに比べるとより記述的であり、簡潔なインターフェイスを提供しています。

両方のメソッドともに、最小1つ、更新したいカラムを引数に取ります。オプションの第2引数はそのカラムの増減値を指定します。

DB::table('users')->increment('votes');

DB::table('users')->increment('votes', 5);

DB::table('users')->decrement('votes');

DB::table('users')->decrement('votes', 5);

さらに増減操作と一緒に更新する追加のカラムを指定することもできます。

DB::table('users')->increment('votes', 1, ['name' => 'John']);

DELETE

クエリビルダはdeleteメソッドで、テーブルからレコードを削除するためにも使用できます。 deleteメソッドを呼び出す前にwhere節を追加し、delete文を制約することもできます。

DB::table('users')->delete();

DB::table('users')->where('votes', '>', 100)->delete();

全レコードを削除し、自動増分のIDを0にリセットするためにテーブルをTRUNCATEしたい場合は、truncateメソッドを使います。

DB::table('users')->truncate();

悲観的ロック

クエリビルダは、SELECT文で「悲観的ロック」を行うための機能をいくつか持っています。SELECT文を実行する間「共有ロック」をかけたい場合は、sharedLockメソッドをクエリに指定して下さい。共有ロックはトランザクションがコミットされるまで、SELECTしている行が更新されることを防ぎます。

DB::table('users')->where('votes', '>', 100)->sharedLock()->get();

もしくはlockForUpdateメソッドが使えます。占有ロックをかけることで、レコードを更新したりSELECTするために他の共有ロックが行われるのを防ぎます。

DB::table('users')->where('votes', '>', 100)->lockForUpdate()->get();

ドキュメント章別ページ

開発環境
ビューとテンプレート
Artisanコンソール
公式パッケージ

ヘッダー項目移動

注目:アイコン:ページ内リンク設置(リンクがないヘッダーへの移動では、リンクがある以前のヘッダーのハッシュをURLへ付加します。

移動

クリックで即時移動します。

バージョン

設定

適用ボタンクリック後に、全項目まとめて適用されます。

カラーテーマ
和文指定 Pagination
和文指定 Scaffold
Largeスクリーン表示幅
インデント
本文フォント
コードフォント
フォント適用確認

フォントの指定フィールドから、フォーカスが外れると、当ブロックの内容に反映されます。EnglishのDisplayもPreviewしてください。

フォント設定時、表示に不具合が出た場合、当サイトのクッキーを削除してください。

バックスラッシュを含むインライン\Code\Blockの例です。

以下はコードブロックの例です。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザに関連する電話レコードを取得
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

設定を保存する前に、表示が乱れないか必ず確認してください。CSSによるフォントファミリー指定の知識がない場合は、フォントを変更しないほうが良いでしょう。

キーボード・ショートカット

オープン操作

PDC

ページ(章)移動の左オフキャンバスオープン

HA

ヘッダー移動モーダルオープン

MS

移動/設定の右オフキャンバスオープン

ヘッダー移動

T

最初のヘッダーへ移動

E

最後のヘッダーへ移動

NJ

次ヘッダー(H2〜H4)へ移動

BK

前ヘッダー(H2〜H4)へ移動

その他

?

このヘルプページ表示
閉じる