原文地址:http://www.yiiframework.com/doc/guide/1.1/en/database.query-builder
不过原文是英文的,Yii的官网没有翻译这一章,自己就尝试着翻译了一下,有很多地方时会按自己的理解写,不一定完全按原文翻译。。。
Yii的查询生成器提供了用面向对象的方式写SQL语句。它允许开发人员使用类的方法和属性来指定一个SQL语句的各个部分。然后,组装成一个有效的SQL语句,可以通过调用DAO数据访问对象的描述方法为进一步执行。以下显示了一个典型的使用查询生成器建立一个select语句:
$user = Yii::app()->db->createCommand() ->select('id, username, profile') ->from('tbl_user u') ->join('tbl_profile p', 'u.id=p.user_id') ->where('id=:id', array(':id'=>$id)) ->queryRow();
当你在应用程序中需要组装SQL语句的程序,或基于一些条件逻辑时,最好使用查询生成器。使用查询生成器的好处主要包括:
它可以建立复杂的SQL语句编程。
它会自引用表名和列名防止SQL保留字和特殊字符的冲突。
它还可以引用参数值和使用参数绑定,这有助于减少SQL注入攻击的风险。
它提供了一定程度的数据库抽象,简化了迁移到不同的数据库平台的成本。
它不强制使用查询生成器。事实上,如果你的查询是简单的,它是更容易和更快的直接写SQL语句。
注:查询生成器不能用于修改现有的查询指定为SQL语句。例如,下面的代码将不能工作:
$command = Yii::app()->db->createCommand('SELECT * FROM tbl_user'); // the following line will NOT append WHERE clause to the above SQL $command->where('id=:id', array(':id'=>$id));
换句话说,不要混合使用普通的SQL和查询生成器。
Yii的查询生成器是从 CDbCommand 提供主要数据库查询类,描述数据访问对象。
开始使用查询生成器,我们创造了 CDbCommand 的一个新实例,
$command = Yii::app()->db->createCommand();
我们使用 Yii::app()->db
来获得数据库连接,然后调用 CDbConnection::createCommand() 创建所需的命令实例。
请注意,将整个SQL语句放入 createcommand() ,叫做数据访问对象,我们需呀把设置它为空。这是因为我们将在下面的解释中使用查询生成器添加SQL语句的各个部分的方法。
数据检索查询是指选择SQL语句。查询生成器提供了一套方法来建立一个SELECT语句的各个部分。因为所有这些方法返回 CDbCommand 的实例,我们可以使用方法链调用他们,如图所示,在本节开头的例子。
AND
operatorOR
operator在下面,我们将解释如何使用这些查询生成器方法。为简单起见,我们假设底层数据库是MySQL。注意:如果你使用的是其他数据库,表/列/值引用的例子可能是不同的。
function select($columns='*')
该select()方法指定一个查询的选择部分。$columns参数指定要选择的列,它可以是一个字符串,用逗号分隔列,或者一个数组的列名称。列的名称可以包含表的前缀和 / 或列别名。该方法将自动引用列名,除非一列包含一些括号(这意味着这个列是一个DB的表达式)。
下面是一些例子:
// SELECT * select() // SELECT `id`, `username` select('id, username') // SELECT `tbl_user`.`id`, `username` AS `name` select('tbl_user.id, username as name') // SELECT `id`, `username` select(array('id', 'username')) // SELECT `id`, count(*) as num select(array('id', 'count(*) as num'))
function selectDistinct($columns)
selectdistinct()方法类似于select(),除了它打开了 DISTINCT
的标志。例如,selectdistinct('id,用户名”)会产生以下SQL:
SELECT DISTINCT `id`, `username`
function from($tables)
from()方法指定来了一个查询的FROM部分。 $tables
参数指定表的选择。这可以是一个字符串,用逗号分隔的表的名称,或表名数组。表的名称可以包含架构前缀(例如公共。tbl_user)和/或表的别名(e.g.tbl_user U)。该方法将自动引用表的名称,除非它包含一些括号(即表是一个给定的子查询或DB的表达式)。
下面是一些例子:
// FROM `tbl_user` from('tbl_user') // FROM `tbl_user` `u`, `public`.`tbl_profile` `p` from('tbl_user u, public.tbl_profile p') // FROM `tbl_user`, `tbl_profile` from(array('tbl_user', 'tbl_profile')) // FROM `tbl_user`, (select * from tbl_profile) p from(array('tbl_user', '(select * from tbl_profile) p'))
function where($conditions, $params=array())
where()方法指定查询的WHERE。$conditions 参数指定查询条件的同时,$params 指定参数绑定到整个查询。$conditions参数可以是一个字符串(例如id = 1)或一个数组中的格式:
array(operator, operand1, operand2, ...)
operator
可以是以下的任何一个:
and
: operands 应该使用 and 连接在一起。例如, array('and', 'id=1', 'id=2')
将产生 id=1 AND id=2 。如果一个操作数是一个数组,它将使用这里描述的相同规则转换成一个字符串。例如,array('and', 'type=1', array('or', 'id=1', 'id=2')) 将生成 type=1 AND (id=1 OR id=2)
。
or
: 类似 and 操作,除了operands 是使用 OR 连接的。
in
: operand 1 应是一个列或 DB 表达式,而 operand 2 是代表值的范围的数组,列或 DB 表达式应在这个数组的范围内。例如,array('in', 'id', array(1,2,3))
将生成 id IN (1,2,3)
。
not in
: 类似 in 操作,除了用 NOT IN 代替 IN 去生成SQL。
like
: operand 1 应是一个列或 DB 表达式,而 operand 2 是代表值的范围的数组,列或 DB 表达式应在这个数组的范围内。例如,array('like', 'name', '%tester%')
会生成 name LIKE '%tester%'
。当规定值的范围为一个数组时,多个 LIKE 生成SQL时会用 AND 连接。例如,array('like', 'name', array('%test%', '%sample%'))
会生成 name LIKE '%test%' AND name LIKE '%sample%'
。
not like
: 类似 like 的操作,除了用 NOT LIKE 代替 LIKE 去生成SQL。
or like
: 类似 like 的操作,除了多个 like 生成 SQL 时用OR连接。
or not like
: 类似 not like 的操作,除了多个 like 生成 SQL 时用OR连接。
下面是一些例子,使用的地方:
// WHERE id=1 or id=2 where('id=1 or id=2') // WHERE id=:id1 or id=:id2 where('id=:id1 or id=:id2', array(':id1'=>1, ':id2'=>2)) // WHERE id=1 OR id=2 where(array('or', 'id=1', 'id=2')) // WHERE id=1 AND (type=2 OR type=3) where(array('and', 'id=1', array('or', 'type=2', 'type=3'))) // WHERE `id` IN (1, 2) where(array('in', 'id', array(1, 2)) // WHERE `id` NOT IN (1, 2) where(array('not in', 'id', array(1,2))) // WHERE `name` LIKE '%Qiang%' where(array('like', 'name', '%Qiang%')) // WHERE `name` LIKE '%Qiang' AND `name` LIKE '%Xue' where(array('like', 'name', array('%Qiang', '%Xue'))) // WHERE `name` LIKE '%Qiang' OR `name` LIKE '%Xue' where(array('or like', 'name', array('%Qiang', '%Xue'))) // WHERE `name` NOT LIKE '%Qiang%' where(array('not like', 'name', '%Qiang%')) // WHERE `name` NOT LIKE '%Qiang%' OR `name` NOT LIKE '%Xue%' where(array('or not like', 'name', array('%Qiang%', '%Xue%')))
请注意,当操作者含有like时,我们必须明确指定的通配符(如%和_)的模式。如果参数是从用户的输入,我们也应该使用下面的代码转义特殊字符,以防止他们被当作通配符:
$keyword=$_GET['q']; // escape % and _ characters $keyword=strtr($keyword, array('%'=>'\%', '_'=>'\_')); $command->where(array('like', 'title', '%'.$keyword.'%'));
function andWhere($conditions, $params=array())
用 and 的方式添加到WHERE的条件中。此方法的行为几乎是 where() 相同,除了它只是添加条件不能取代它。在 where() 文档中有该方法参数的详细信息。
function orWhere($conditions, $params=array())
用 or 的方式添加到WHERE的条件中。此方法的行为几乎是 where() 相同,除了它只是添加条件不能取代它。在 where() 文档中有该方法参数的详细信息。
function order($columns)
order() 方法指定查询的ORDER BY部分。$columns
参数指定列进行排序,这可以是一个包含用逗号分隔列和order的方向(ASC 或
DESC
)的字符串,或者一个列和order的方向的数组。列名称可以包含表前缀。该方法将自动引用列名,除非一列包含一些括号(即给出一个 DB 表达式)。
下面是一些例子:
// ORDER BY `name`, `id` DESC order('name, id desc') // ORDER BY `tbl_profile`.`name`, `id` DESC order(array('tbl_profile.name', 'id desc'))
function limit($limit, $offset=null) function offset($offset)
limit()和offset()方法指定查询的 LIMIT
和 OFFSET
部分。请注意,某些DBMS不支持 LIMIT
和 OFFSET
语法。在这种情况下,查询生成器将改写整个SQL语句来模拟 LIMIT
和 OFFSET 的
功能。
下面是一些例子:
// LIMIT 10 取前10条 limit(10) // LIMIT 10 OFFSET 20 取到第21~30条 limit(10, 20) // OFFSET 20 去掉前20条后剩下的数据 offset(20)
function join($table, $conditions, $params=array()) function leftJoin($table, $conditions, $params=array()) function rightJoin($table, $conditions, $params=array()) function crossJoin($table) function naturalJoin($table)
join()方法及其变种指定如何与其他表连接,使用内部联接,左外连接,右外部联接,交叉连接,或自然连接。 $table
参数指定要加入哪个表。表名可以包含数据库的前缀和 / 或别名。该方法将引用表名,除非它包含一个插入语,即一个DB表达式或子查询。 $conditions
参数指定连接条件。它的语法与where() 相同。$params
参数指定绑定到整个查询的参数。
值得注意的是,它不像其他的查询生成器方法,每次调用一个join方法都会追加到SQL中。
下面是一些例子:
// JOIN `tbl_profile` ON user_id=id join('tbl_profile', 'user_id=id') // LEFT JOIN `pub`.`tbl_profile` `p` ON p.user_id=id AND type=1 leftJoin('pub.tbl_profile p', 'p.user_id=id AND type=:type', array(':type'=>1))
function group($columns)
group() 方法指定查询的GROUP BY。 $columns
参数指定列进行分组,它可以是一个用逗号分隔的列的字符串,或者一个列的数组。列名称可以包含表前缀。该方法将自动引用列名,除非一列包含一些括号(即是一个 DB 表达式)。
下面是一些例子:
// GROUP BY `name`, `id` group('name, id') // GROUP BY `tbl_profile`.`name`, `id` group(array('tbl_profile.name', 'id'))
function having($conditions, $params=array())
having() 方法指定查询的 HAVING。它的使用方式与 where() 相同。
下面是一些例子:
// HAVING id=1 or id=2 having('id=1 or id=2') // HAVING id=1 OR id=2 having(array('or', 'id=1', 'id=2'))
function union($sql)
union() 方法指定查询 UNION。它使用UNION操作附加到现有的SQL上。调用union()多次将现有的SQL附加多个表。
下面是一些例子:
// UNION (select * from tbl_profile) union('select * from tbl_profile')
调用上面查询生成器的方法来建立一个查询后,我们可以调用DAO方法数据访问对象执行查询。例如,我们可以调用 CDbCommand::queryRow() 获得连续的结果,或者使用 CDbCommand::queryAll() 立刻得到所有行。
例子:
$users = Yii::app()->db->createCommand() ->select('*') ->from('tbl_user') ->queryAll();
除了执行查询生成器的查询,我们也可以获取相应的SQL语句。这可以通过调用 CDbCommand::getText() 获得。
$sql = Yii::app()->db->createCommand() ->select('*') ->from('tbl_user') ->text;
如果有任何参数必须绑定到查询的,他们可以通过 CDbCommand::params 的属性绑定。
有时,使用方法链来建立一个查询可能不是最佳的选择。Yii的查询生成器允许使用对简单象属性赋值的方式去建立查询。特别是,每个查询生成器的方法都有一个具有相同名称的属性。给属性赋值相当于调用相应的方法。例如,下面两个语句是等价的,假设$command
代表 CDbCommand 对象:
$command->select(array('id', 'username')); $command->select = array('id', 'username');
此外, CDbConnection::createCommand() 方法可以把一个数组作为参数。数组中的键值对将被用来初始化创建的 CDbCommand 实例的属性。这意味着,我们可以使用下面的代码来建立一个查询:
$row = Yii::app()->db->createCommand(array( 'select' => array('id', 'username'), 'from' => 'tbl_user', 'where' => 'id=:id', 'params' => array(':id'=>1), ))->queryRow();
一个 CDbCommand 实例可以重复使用多次建立几个查询。建立一个新的查询之前,需要调用 CDbCommand::reset() 方法以清理前面的查询。例子:
$command = Yii::app()->db->createCommand(); $users = $command->select('*')->from('tbl_users')->queryAll(); $command->reset(); // clean up the previous query $posts = $command->select('*')->from('tbl_posts')->queryAll();
数据操作查询是指SQL语句插入,更新和删除数据库表中的数据。对应于这些查询,查询生成器分别提供了插入,更新和删除的方法。不同于上面介绍 SELECT 的查询方法,这些数据操作查询方法将建立一个完整的SQL语句,并立即执行。
下面描述了这些数据操作查询方法。
function insert($table, $columns)
insert()方法的建立和执行一条 INSERT SQL 语句。 $table
参数指定要插入的表,而键值对数组 $columns
指定要插入的列的值。该方法将转义表名,并且将与绑定参数结合使用。
下面是一个例子:
// build and execute the following SQL: // INSERT INTO `tbl_user` (`name`, `email`) VALUES (:name, :email) $command->insert('tbl_user', array( 'name'=>'Tester', 'email'=>'[email protected]', ));
function update($table, $columns, $conditions='', $params=array())
update()方法的建立和执行一个SQL更新语句。 $table
参数指定要更新的表; $columns
是键值对的数组,用于指定要更新的列值的;$conditions
和 $params
像where()一样,指定 UPDATE 语句中的 WHERE 子句。该方法将转义表名,并且将与要更新的值的参数结合使用。
下面是一个例子:
// build and execute the following SQL: // UPDATE `tbl_user` SET `name`=:name WHERE id=:id $command->update('tbl_user', array( 'name'=>'Tester', ), 'id=:id', array(':id'=>1));
function delete($table, $conditions='', $params=array())
delete()方法的建立和执行一个SQL删除语句。 $table
参数指定要删除数据的表;$conditions
和$params
像where()一样,指定 DELETE
语句中的 WHERE 子句。该方法将正确转义表名。
下面是一个例子:
// build and execute the following SQL: // DELETE FROM `tbl_user` WHERE id=:id $command->delete('tbl_user', 'id=:id', array(':id'=>1));
除了正常的数据检索和操作查询,查询生成器提供了一套用于可以操纵数据库的构建和执行SQL查询的方法。它支持以下操作:
Info: 虽然在不同的数据库管理系统中SQL语句操作数据库的模式有很大的不同,但查询生成器试图提供一个统一的接口,用于构建这些查询。这简化了数据库迁移从一个数据库管理系统到另一个任务。
查询生成器中引入了一组可以在定义表的列中使用抽象数据类型。与物理数据类型不同,物理数据类型有具体独特的DBMS而且在不同的DBMS中有很大的不同,抽象数据类型都是独立的DBMS。当抽象数据类型在定义表的列中使用时,查询生成器将其转换成相应的物理数据类型。
下面的抽象数据类型由查询生成器的支持。
pk
: 一个通用的主键类型,将被转换成 int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY
for MySQL;string
: 字符串类型,将被转换成 varchar(255)
for MySQL;text
: 文本型(长字符串),将被转换成 text
for MySQL;integer
: 整数类型,将被转换成 int(11)
for MySQL;float
: 浮点数类型,将被转换成 float
for MySQL;decimal
: 十进制数类型,将被转换成 decimal
for MySQL;datetime
: datetime类型,将被转换成 datetime
for MySQL;timestamp
: 时间戳类型,将被转换成 timestamp
for MySQL;time
: 时间类型,将被转换成 time
for MySQL;date
: 日期类型,将被转换成 date
for MySQL;binary
: 二进制数据类型,将被转换成 blob
for MySQL;boolean
: 布尔类型,将被转换成 tinyint(1)
for MySQL;money
: 金钱/货币型,将被转换成 decimal(19,4)
for MySQL. 自1.1.8版本开始此类型可以使用。function createTable($table, $columns, $options=null)
createTable() 方法构建和执行一条创建表的SQL语句。$table
参数指定要创建的表的名称。 $columns
参数指定在新表中的列。他们必须被指定为名称类型的键值对(e.g. 'username'=>'string'
)。 $options
参数指定应附加到生成的SQL上的任何额外的SQL片段。查询生成器将正确的引用的表名以及列名。
当指定一个列的定义时,可以使用如上所述的抽象数据类型。查询生成器会根据当前使用的数据库管理系统的抽象数据类型转换成相应的物理数据类型。例如,string 类型将被转换为MySQL的 varchar(255)。
一个列定义还可以包含非抽象数据类型或规格。他们将没有任何改变的被放置在生成的SQL中。例如,point
不是一个抽象数据类型,如果用在列定义,它会出现在生成的SQL中,而且 string NOT NULL
将被转换varchar(255) NOT NULL(即只有抽象类型的字符串转换)。
下面是一个例子,显示了如何创建一个表:
// CREATE TABLE `tbl_user` ( // `id` int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, // `username` varchar(255) NOT NULL, // `location` point // ) ENGINE=InnoDB createTable('tbl_user', array( 'id' => 'pk', 'username' => 'string NOT NULL', 'location' => 'point', ), 'ENGINE=InnoDB')
function renameTable($table, $newName)
renameTable() 方法创建和执行一条重命名表名的SQL语句。 $table 参数
指定要重命名的表的名称。 $newName
参数指定表的新名称。查询生成器将正确引用的表名。
下面是一个示例,演示了如何重命名表:
// RENAME TABLE `tbl_users` TO `tbl_user` renameTable('tbl_users', 'tbl_user')
function dropTable($table)
dropTable() 方法创建和执行一条删除表的SQL语句。在$table
参数指定要删除的表的名称。查询生成器会正确地引用的表名。
下面是一个示例展示如何删除一个表:
// DROP TABLE `tbl_user` dropTable('tbl_user')
function truncateTable($table)
truncateTable() 方法建立和执行一条清空表数据的SQL语句。 $table 参数
指定清空的表名。查询生成器会正确地引用的表名。
下面是一个示例显示如何清空表:
// TRUNCATE TABLE `tbl_user` truncateTable('tbl_user')
function addColumn($table, $column, $type)
addColumn() 方法创建并执行一条添加一个表的新列的SQL语句。 $table 参数
指定新列将被添加到的表的名称。 $column
参数指定新列的名称。 $type
指定新列的定义。列定义中可以包含抽象数据类型,如 "createTable"小节中的描述。查询生成器将正确的引用的表名以及列名。
下面是一个示例,演示如何添加一个表的列:
// ALTER TABLE `tbl_user` ADD `email` varchar(255) NOT NULL addColumn('tbl_user', 'email', 'string NOT NULL')
function dropColumn($table, $column)
dropColumn() 方法创建和执行一条删除表列的SQL语句。 $table 参数
指定要被删除的列所属的表名。 $column
参数指定要被删除的列名。查询生成器将正确地引用的表名以及列名。
下面是一个示例展示如何删除一个表列:
// ALTER TABLE `tbl_user` DROP COLUMN `location` dropColumn('tbl_user', 'location')
function renameColumn($table, $name, $newName)
renameColumn() 方法创建和执行一条重命名列的SQL语句。 $table 参数
指定要重命名的列所属的表的名称。 $name
参数指定的旧列名。 $newName
指定新的列名。查询生成器将正确地引用的表名以及列名。
下面是一个示例,展示了如何重命名表列:
// ALTER TABLE `tbl_users` CHANGE `name` `username` varchar(255) NOT NULL renameColumn('tbl_user', 'name', 'username')
function alterColumn($table, $column, $type)
alterColumn() 方法创建和执行一条修改表列的SQL语句。 $table 参数
指定要被改变的列所属的表的名称。 $column
参数指定被改变的列的名称。$type
指定列的新定义。列定义中可以包含抽象数据类型,如 "createTable"小节中的描述。查询生成器将正确的引用的表名以及列名。
下面是一个示例,展示了如何更改一个表列:
// ALTER TABLE `tbl_user` CHANGE `username` `username` varchar(255) NOT NULL alterColumn('tbl_user', 'username', 'string NOT NULL')
function addForeignKey($name, $table, $columns, $refTable, $refColumns, $delete=null, $update=null)
addForeignKey() 方法创建和执行一条添加一个外键约束SQL语句。 $name
参数指定外键的名称。 $table
和 $columns
参数指定外键的表名和列名。如果有多个列,他们应该用逗号字符分隔。 $refTable
和 $refColumns
参数指定表名和列名的外键引用。 $delete
和 $update
参数指定 SQL语句中的 ON DELETE 和ON UPDATE选项。大多数的DBMS都支持这些选项:RESTRICT
, CASCADE
, NO ACTION
, SET DEFAULT
, SET NULL
. 。查询生成器会正确地引用表名,索引名和列名。
下面是一个示例,演示如何添加一个外键约束:
// ALTER TABLE `tbl_profile` ADD CONSTRAINT `fk_profile_user_id` // FOREIGN KEY (`user_id`) REFERENCES `tbl_user` (`id`) // ON DELETE CASCADE ON UPDATE CASCADE addForeignKey('fk_profile_user_id', 'tbl_profile', 'user_id', 'tbl_user', 'id', 'CASCADE', 'CASCADE')
function dropForeignKey($name, $table)
dropForeignKey() 方法创建和执行一条删除一个外键约束的SQL语句。 $name
参数指定的要删除的外键约束的名称。 $table
参数指定外键所属的表的名称。查询生成器将正确地引用的表名以及约束名称。
下面是一个示例,显示了如何删除外键约束:
// ALTER TABLE `tbl_profile` DROP FOREIGN KEY `fk_profile_user_id` dropForeignKey('fk_profile_user_id', 'tbl_profile')
function createIndex($name, $table, $column, $unique=false)
createIndex() 方法构建和执行一条创建索引的SQL语句。 $name
参数指定要创建的索引的名称。$table
参数指定索引所属的表的名称。$column
参数指定要索引的列的名称。 $unique 参数
指定是否创建一个唯一索引。如果索引由多个列,则必须用逗号将它们隔开。查询生成器会正确地引用表名,索引名和列名。
下面是一个示例,显示了如何创建索引:
// CREATE INDEX `idx_username` ON `tbl_user` (`username`) createIndex('idx_username', 'tbl_user', 'username')
function dropIndex($name, $table)
dropIndex() 方法创建和执行一条删除索引的SQL语句。 $name
参数指定要删除的索引的名称。$table
参数指定索引所属的表的名称。查询生成器将正确地引用的表名以及索引名称。
下面是一个示例,显示了如何删除索引:
// DROP INDEX `idx_username` ON `tbl_user` dropIndex('idx_username', 'tbl_user')
终于翻译完了~~~