Commit 0df9a82a by Carsten Brandt

updated documentation and tests

fixes #5331
parent d4ceeb2d
...@@ -191,7 +191,7 @@ WHERE `id` IN (SELECT `id` FROM `user`) ...@@ -191,7 +191,7 @@ WHERE `id` IN (SELECT `id` FROM `user`)
Another way to use the method is the operand format which is `[operator, operand1, operand2, ...]`. Another way to use the method is the operand format which is `[operator, operand1, operand2, ...]`.
Operator can be one of the following: Operator can be one of the following (see also [[yii\db\QueryInterface::where()]]):
- `and`: the operands should be concatenated together using `AND`. For example, - `and`: the operands should be concatenated together using `AND`. For example,
`['and', 'id=1', 'id=2']` will generate `id=1 AND id=2`. If an operand is an array, `['and', 'id=1', 'id=2']` will generate `id=1 AND id=2`. If an operand is an array,
......
...@@ -116,6 +116,12 @@ interface QueryInterface ...@@ -116,6 +116,12 @@ interface QueryInterface
* `['in', 'id', [1, 2, 3]]` will generate `id IN (1, 2, 3)`. * `['in', 'id', [1, 2, 3]]` will generate `id IN (1, 2, 3)`.
* The method will properly quote the column name and escape values in the range. * The method will properly quote the column name and escape values in the range.
* *
* To create a composite `IN` condition you can use and array for the column name and value, where the values are indexed by the column name:
* `['in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']] ]`.
*
* You may also specify a sub-query that is used to get the values for the `IN`-condition:
* `['in', 'user_id', (new Query())->select('id')->from('users')->where(['active' => 1])]`
*
* - **not in**: similar to the `in` operator except that `IN` is replaced with `NOT IN` in the generated condition. * - **not in**: similar to the `in` operator except that `IN` is replaced with `NOT IN` in the generated condition.
* *
* - **like**: operand 1 should be a column or DB expression, and operand 2 be a string or an array representing * - **like**: operand 1 should be a column or DB expression, and operand 2 be a string or an array representing
...@@ -137,6 +143,12 @@ interface QueryInterface ...@@ -137,6 +143,12 @@ interface QueryInterface
* - **or not like**: similar to the `not like` operator except that `OR` is used to concatenate * - **or not like**: similar to the `not like` operator except that `OR` is used to concatenate
* the `NOT LIKE` predicates. * the `NOT LIKE` predicates.
* *
* - **exists**: operand 1 is a query object that used to build an `EXISTS` condition. For example
* `['exists', (new Query())->select('id')->from('users')->where(['active' => 1])]` will result in the following SQL expression:
* `EXISTS (SELECT "id" FROM "users" WHERE "active"=1)`.
*
* - **not exists**: similar to the `exists` operator except that `EXISTS` is replaced with `NOT EXISTS` in the generated condition.
*
* - Additionally you can specify arbitrary operators as follows: A condition of `['>=', 'id', 10]` will result in the * - Additionally you can specify arbitrary operators as follows: A condition of `['>=', 'id', 10]` will result in the
* following SQL expression: `id >= 10`. * following SQL expression: `id >= 10`.
* *
......
...@@ -171,8 +171,19 @@ class QueryBuilderTest extends DatabaseTestCase ...@@ -171,8 +171,19 @@ class QueryBuilderTest extends DatabaseTestCase
// in // in
[ ['in', 'id', [1, 2, 3]], '"id" IN (:qp0, :qp1, :qp2)', [':qp0' => 1, ':qp1' => 2, ':qp2' => 3] ], [ ['in', 'id', [1, 2, 3]], '"id" IN (:qp0, :qp1, :qp2)', [':qp0' => 1, ':qp1' => 2, ':qp2' => 3] ],
[ ['not in', 'id', [1, 2, 3]], '"id" NOT IN (:qp0, :qp1, :qp2)', [':qp0' => 1, ':qp1' => 2, ':qp2' => 3] ], [ ['not in', 'id', [1, 2, 3]], '"id" NOT IN (:qp0, :qp1, :qp2)', [':qp0' => 1, ':qp1' => 2, ':qp2' => 3] ],
[ ['in', 'id', (new Query())->select('id')->from('users')->where(['active' => 1])], '("id") IN (SELECT "id" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
[ ['not in', 'id', (new Query())->select('id')->from('users')->where(['active' => 1])], '("id") NOT IN (SELECT "id" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
// TODO: exists and not exists // composite in
[ ['in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']]], '("id", "name") IN ((:qp0, :qp1), (:qp2, :qp3))', [':qp0' => 1, ':qp1' => 'foo', ':qp2' => 2, ':qp3' => 'bar'] ],
[ ['not in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']]], '("id", "name") NOT IN ((:qp0, :qp1), (:qp2, :qp3))', [':qp0' => 1, ':qp1' => 'foo', ':qp2' => 2, ':qp3' => 'bar'] ],
[ ['in', ['id', 'name'], (new Query())->select(['id', 'name'])->from('users')->where(['active' => 1])], '("id", "name") IN (SELECT "id", "name" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
[ ['not in', ['id', 'name'], (new Query())->select(['id', 'name'])->from('users')->where(['active' => 1])], '("id", "name") NOT IN (SELECT "id", "name" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
// exists
[ ['exists', (new Query())->select('id')->from('users')->where(['active' => 1])], 'EXISTS (SELECT "id" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
[ ['not exists', (new Query())->select('id')->from('users')->where(['active' => 1])], 'NOT EXISTS (SELECT "id" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
// simple conditions // simple conditions
[ ['=', 'a', 'b'], '"a" = :qp0', [':qp0' => 'b'] ], [ ['=', 'a', 'b'], '"a" = :qp0', [':qp0' => 'b'] ],
...@@ -229,8 +240,6 @@ class QueryBuilderTest extends DatabaseTestCase ...@@ -229,8 +240,6 @@ class QueryBuilderTest extends DatabaseTestCase
[ ['in', 'id', []], '', [] ], [ ['in', 'id', []], '', [] ],
[ ['not in', 'id', []], '', [] ], [ ['not in', 'id', []], '', [] ],
// TODO: exists and not exists
// simple conditions // simple conditions
[ ['=', 'a', ''], '', [] ], [ ['=', 'a', ''], '', [] ],
[ ['>', 'a', ''], '', [] ], [ ['>', 'a', ''], '', [] ],
...@@ -262,8 +271,8 @@ class QueryBuilderTest extends DatabaseTestCase ...@@ -262,8 +271,8 @@ class QueryBuilderTest extends DatabaseTestCase
{ {
$query = (new Query())->where($condition); $query = (new Query())->where($condition);
list($sql, $params) = $this->getQueryBuilder()->build($query); list($sql, $params) = $this->getQueryBuilder()->build($query);
$this->assertEquals($expectedParams, $params);
$this->assertEquals('SELECT *' . (empty($expected) ? '' : ' WHERE ' . $expected), $sql); $this->assertEquals('SELECT *' . (empty($expected) ? '' : ' WHERE ' . $expected), $sql);
$this->assertEquals($expectedParams, $params);
} }
/** /**
...@@ -273,8 +282,8 @@ class QueryBuilderTest extends DatabaseTestCase ...@@ -273,8 +282,8 @@ class QueryBuilderTest extends DatabaseTestCase
{ {
$query = (new Query())->filterWhere($condition); $query = (new Query())->filterWhere($condition);
list($sql, $params) = $this->getQueryBuilder()->build($query); list($sql, $params) = $this->getQueryBuilder()->build($query);
$this->assertEquals($expectedParams, $params);
$this->assertEquals('SELECT *' . (empty($expected) ? '' : ' WHERE ' . $expected), $sql); $this->assertEquals('SELECT *' . (empty($expected) ? '' : ' WHERE ' . $expected), $sql);
$this->assertEquals($expectedParams, $params);
} }
public function testAddDropPrimaryKey() public function testAddDropPrimaryKey()
...@@ -295,30 +304,28 @@ class QueryBuilderTest extends DatabaseTestCase ...@@ -295,30 +304,28 @@ class QueryBuilderTest extends DatabaseTestCase
$this->assertEquals(0, count($tableSchema->primaryKey)); $this->assertEquals(0, count($tableSchema->primaryKey));
} }
/* qiangxue: the following tests are commented because they vary by different DB drivers. need a better test scheme. public function existsParamsProvider()
public function testBuildWhereExists()
{ {
$expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE EXISTS (SELECT `1` FROM `Website` `w`)"; $conditions = [
$expectedQueryParams = null; ['exists', "SELECT `id` FROM `TotalExample` `t` WHERE EXISTS (SELECT `1` FROM `Website` `w`)"],
['not exists', "SELECT `id` FROM `TotalExample` `t` WHERE NOT EXISTS (SELECT `1` FROM `Website` `w`)"]
$subQuery = new Query(); ];
$subQuery->select('1')
->from('Website w');
$query = new Query();
$query->select('id')
->from('TotalExample t')
->where(['exists', $subQuery]);
list($actualQuerySql, $actualQueryParams) = $this->getQueryBuilder()->build($query); // adjust dbms specific escaping
$this->assertEquals($expectedQuerySql, $actualQuerySql); foreach($conditions as $i => $condition) {
$this->assertEquals($expectedQueryParams, $actualQueryParams); if (!in_array($this->driverName, ['mssql', 'mysql', 'sqlite'])) {
$conditions[$i][1] = str_replace('`', '"', $condition[1]);
}
}
return $conditions;
} }
public function testBuildWhereNotExists() /**
* @dataProvider existsParamsProvider
*/
public function testBuildWhereExists($cond, $expectedQuerySql)
{ {
$expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE NOT EXISTS (SELECT `1` FROM `Website` `w`)"; $expectedQueryParams = [];
$expectedQueryParams = null;
$subQuery = new Query(); $subQuery = new Query();
$subQuery->select('1') $subQuery->select('1')
...@@ -327,16 +334,20 @@ class QueryBuilderTest extends DatabaseTestCase ...@@ -327,16 +334,20 @@ class QueryBuilderTest extends DatabaseTestCase
$query = new Query(); $query = new Query();
$query->select('id') $query->select('id')
->from('TotalExample t') ->from('TotalExample t')
->where(['not exists', $subQuery]); ->where([$cond, $subQuery]);
list($actualQuerySql, $actualQueryParams) = $this->getQueryBuilder()->build($query); list($actualQuerySql, $actualQueryParams) = $this->getQueryBuilder()->build($query);
$this->assertEquals($expectedQuerySql, $actualQuerySql); $this->assertEquals($expectedQuerySql, $actualQuerySql);
$this->assertEquals($expectedQueryParams, $actualQueryParams); $this->assertEquals($expectedQueryParams, $actualQueryParams);
} }
public function testBuildWhereExistsWithParameters() public function testBuildWhereExistsWithParameters()
{ {
$expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE (EXISTS (SELECT `1` FROM `Website` `w` WHERE (w.id = t.website_id) AND (w.merchant_id = :merchant_id))) AND (t.some_column = :some_value)"; $expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE (EXISTS (SELECT `1` FROM `Website` `w` WHERE (w.id = t.website_id) AND (w.merchant_id = :merchant_id))) AND (t.some_column = :some_value)";
if (!in_array($this->driverName, ['mssql', 'mysql', 'sqlite'])) {
$expectedQuerySql = str_replace('`', '"', $expectedQuerySql);
}
$expectedQueryParams = [':some_value' => "asd", ':merchant_id' => 6]; $expectedQueryParams = [':some_value' => "asd", ':merchant_id' => 6];
$subQuery = new Query(); $subQuery = new Query();
...@@ -359,6 +370,9 @@ class QueryBuilderTest extends DatabaseTestCase ...@@ -359,6 +370,9 @@ class QueryBuilderTest extends DatabaseTestCase
public function testBuildWhereExistsWithArrayParameters() public function testBuildWhereExistsWithArrayParameters()
{ {
$expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE (EXISTS (SELECT `1` FROM `Website` `w` WHERE (w.id = t.website_id) AND ((`w`.`merchant_id`=:qp0) AND (`w`.`user_id`=:qp1)))) AND (`t`.`some_column`=:qp2)"; $expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE (EXISTS (SELECT `1` FROM `Website` `w` WHERE (w.id = t.website_id) AND ((`w`.`merchant_id`=:qp0) AND (`w`.`user_id`=:qp1)))) AND (`t`.`some_column`=:qp2)";
if (!in_array($this->driverName, ['mssql', 'mysql', 'sqlite'])) {
$expectedQuerySql = str_replace('`', '"', $expectedQuerySql);
}
$expectedQueryParams = [':qp0' => 6, ':qp1' => 210, ':qp2' => 'asd']; $expectedQueryParams = [':qp0' => 6, ':qp1' => 210, ':qp2' => 'asd'];
$subQuery = new Query(); $subQuery = new Query();
...@@ -377,30 +391,32 @@ class QueryBuilderTest extends DatabaseTestCase ...@@ -377,30 +391,32 @@ class QueryBuilderTest extends DatabaseTestCase
$this->assertEquals($expectedQuerySql, $actualQuerySql); $this->assertEquals($expectedQuerySql, $actualQuerySql);
$this->assertEquals($expectedQueryParams, $queryParams); $this->assertEquals($expectedQueryParams, $queryParams);
} }
*/
/**
/* * This test contains three select queries connected with UNION and UNION ALL constructions.
This test contains three select queries connected with UNION and UNION ALL constructions. * It could be useful to use "phpunit --group=db --filter testBuildUnion" command for run it.
It could be useful to use "phpunit --group=db --filter testBuildUnion" command for run it. */
public function testBuildUnion()
public function testBuildUnion() {
{ $expectedQuerySql = "(SELECT `id` FROM `TotalExample` `t1` WHERE (w > 0) AND (x < 2)) UNION ( SELECT `id` FROM `TotalTotalExample` `t2` WHERE w > 5 ) UNION ALL ( SELECT `id` FROM `TotalTotalExample` `t3` WHERE w = 3 )";
$expectedQuerySql = "SELECT `id` FROM `TotalExample` `t1` WHERE (w > 0) AND (x < 2) UNION ( SELECT `id` FROM `TotalTotalExample` `t2` WHERE w > 5 ) UNION ALL ( SELECT `id` FROM `TotalTotalExample` `t3` WHERE w = 3 )"; if (!in_array($this->driverName, ['mssql', 'mysql', 'sqlite'])) {
$query = new Query(); $expectedQuerySql = str_replace('`', '"', $expectedQuerySql);
$secondQuery = new Query(); }
$secondQuery->select('id') $query = new Query();
->from('TotalTotalExample t2') $secondQuery = new Query();
->where('w > 5'); $secondQuery->select('id')
$thirdQuery = new Query(); ->from('TotalTotalExample t2')
$thirdQuery->select('id') ->where('w > 5');
->from('TotalTotalExample t3') $thirdQuery = new Query();
->where('w = 3'); $thirdQuery->select('id')
$query->select('id') ->from('TotalTotalExample t3')
->from('TotalExample t1') ->where('w = 3');
->where(['and', 'w > 0', 'x < 2']) $query->select('id')
->union($secondQuery) ->from('TotalExample t1')
->union($thirdQuery, TRUE); ->where(['and', 'w > 0', 'x < 2'])
list($actualQuerySql, $queryParams) = $this->getQueryBuilder()->build($query); ->union($secondQuery)
$this->assertEquals($expectedQuerySql, $actualQuerySql); ->union($thirdQuery, TRUE);
}*/ list($actualQuerySql, $queryParams) = $this->getQueryBuilder()->build($query);
$this->assertEquals($expectedQuerySql, $actualQuerySql);
}
} }
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment