Yii 框架資料庫查詢操作完整指南

Yii 框架資料庫查詢操作總覽

在 Yii 框架開發中，資料庫查詢是核心操作之一。本文系統整理了 Yii 1.x 版本中常用的查詢方法，涵蓋原生 SQL 查詢、Active Record 模式、條件構建以及統計查詢等場景，幫助開發者快速掌握各類查詢技巧。

一、使用 CDbCommand 執行原生 SQL

透過 Yii::app()->dbName->createCommand($sql) 可直接執行任意 SQL 語句，dbName 為資料庫連線元件名稱。

1. queryRow() - 查詢單行記錄

$result = Yii::app()->dbName->createCommand($sql)->queryRow();

若有結果，返回一維陣列；無結果則返回 false。適合查詢單筆資料，如使用者詳情、設定值等。

2. queryAll() - 查詢多行記錄

$result = Yii::app()->dbName->createCommand($sql)->queryAll();

返回二維陣列，每個元素為一行記錄的關聯陣列。常用於列表頁、報表資料獲取。

二、Active Record 模式查詢

Active Record 將資料表映射為模型類別，提供物件導向的查詢介面。假設模型類別為 Region、User、Post，對應 models/Region.php 等檔案。

3. findByPk() - 主鍵查詢單筆

$result = Region::model()->findByPk($id);

根據主鍵值 $id 查詢，返回模型物件或 null。

4. findAll() - 條件查詢多筆

$result = Region::model()->findAll($condition, $params);

範例：findAll("username=:name", array(":name"=>$username))
返回二維陣列，第一維元素為模型物件。支援參數綁定防止 SQL 注入。

5. findAllByPk() - 主鍵集合查詢

$admin = User::model()->findAllByPk($postIDs, $condition, $params);

支援單一主鍵或陣列 array(1,2)，可附加額外條件。返回物件陣列。

6. findAllBySql() - 自定 SQL 查詢多筆

$admin = User::model()->findAllBySql($sql, $params);

範例：findAllBySql("select * from admin where username=:name", array(':name'=>'admin'))
返回模型物件陣列，適合複雜關聯查詢。

7. findBySql() - 自定 SQL 查詢單筆

$post = Post::model()->findBySql($sql, $params);

僅返回第一筆結果的模型物件。

8. find() - 通用條件查詢單筆

$row = User::model()->find($condition, $params);

範例：find('username=:name', array(':name'=>'admin'))
或陣列格式：find(array('condition'=>'user_id=:user_id', 'params'=>array(':user_id'=>$uid)))

9. findByAttributes() - 屬性查詢單筆

$admin = User::model()->findByAttributes($attributes, $condition, $params);

以陣列指定多欄位條件：findByAttributes(array('username'=>'admin'))
返回單一模型物件。

10. findAllByAttributes() - 屬性查詢多筆

$admin = User::model()->findAllByAttributes($attributes, $condition, $params);

返回模型物件陣列。

三、使用 CDbCriteria 處理複雜查詢

當查詢條件涉及欄位選取、排序、分頁、關聯等時，建議使用 CDbCriteria：

$criteria = new CDbCriteria;
$criteria->select = 'title';
$criteria->condition = 'postID=:postID';
$criteria->params = array(':postID'=>10);
$post = Post::model()->find($criteria);

更簡潔的陣列寫法：

$post = Post::model()->find(array(
    'select' => 'title',
    'condition' => 'postID=:postID',
    'params' => array(':postID'=>10)
));

四、統計與存在性查詢

1. count() - 條件計數

$n = Post::model()->count($condition, $params);

返回整數。範例：count("username=:name", array(":name"=>$username))

2. countBySql() - SQL 計數

$n = Post::model()->countBySql($sql, $params);

範例：countBySql("select * from admin where username=:name", array(':name'=>'admin'))

3. exists() - 存在性檢查

$exists = Post::model()->exists($condition, $params);

有資料返回 true，否則 false。適合驗證帳號是否存在等場景。