查詢生成器類別

你可以在 CodeIgniter 中使用查詢生成器類別。這個模式可以讓你使用最少的程式從資料庫中取出、插入及更新資訊。在一些案例中,只需要一兩行程式就可以進行資料庫操作。 CodeIgniter 不需要每個資料表都是它自己的一個類別檔。取而代之,它提供了一個更簡單的介面。

除了簡單,使用查詢生成器功能的主要好處在於,它讓你可以產生獨立於資料庫的應用程式,因為實際上的查詢語法是使用不同資料庫的轉接器來產生的。這也讓你的查詢更安全,因為值會由系統自動跳脫。

Note

如果你傾向自己撰寫查詢,你可以在資料庫設定檔中設定不啟用這個類別,來讓核心資料庫函式庫及轉接器使用較少的資源。

選取資料

以下函式可以讓你建構 SQL SELECT 語句。

$this->db->get()

執行選取查詢並回傳結果。它同時可以用來取得資料表中所有記錄:

$query = $this->db->get('mytable');  // 產生: SELECT * FROM mytable

第二及第三個參數,可以讓你設定查詢的限制及偏移:

$query = $this->db->get('mytable', 10, 20);

// 執行: SELECT * FROM mytable LIMIT 20, 10
// (使用 MySQL 時。其他資料庫的語法稍有不同)

你會注意到,上面的函式被指派給一個叫做 $query 的變數,它可以用來顯示結果:

$query = $this->db->get('mytable');

foreach ($query->result() as $row)
{
        echo $row->title;
}

請參閱 result functions 頁面有關於生成出 result 的完整討論。

$this->db->get_compiled_select()

用來編譯 select 查詢,就像 $this->db->get() 但是沒有 執行 查詢。這個方法只將 SQL 查詢當做字串回傳。

例如:

$sql = $this->db->get_compiled_select('mytable');
echo $sql;

// 印出字串: SELECT * FROM mytable

第二個參數讓你能設定,是否要讓查詢產生器的查詢在編譯之後重設。(預設是會重設,就像使用 $this->db->get() 一樣):

echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE);

// 印出字串: SELECT * FROM mytable LIMIT 20, 10
// (使用 MySQL 時。其他資料庫的語法稍有不同)

echo $this->db->select('title, content, date')->get_compiled_select();

// 印出字串: SELECT title, content, date FROM mytable LIMIT 20, 10

要注意的關鍵是在上面的範例中,第二個查詢並未使用 $this->db->from() ,也沒有傳送資料表名稱作為第一個參數。會出現這個結果,是因為查詢並未執行 $this->db->get() 使得值被重設,或是使用 $this->db->reset_query() 直接將值重設。

$this->db->get_where()

與上面的函式相同,只是它讓你可以加入 “where” 子句作為第二個參數,而非使用 db->where() 函式:

$query = $this->db->get_where('mytable', array('id' => $id), $limit, $offset);

更詳細的資訊,請參閱下面關於 where 函式的說明。

Note

舊的 getwhere() 方法已經被移除而被 get_where() 方法取代

$this->db->select()

讓你可以撰寫查詢中 SELECT 的部份:

$this->db->select('title, content, date');
$query = $this->db->get('mytable');

// 執行: SELECT title, content, date FROM mytable

Note

如果要從資料表中選取所有欄位 (*) ,你不需要使用這個函式。當你忽略, CodeIgniter 會假設你希望選取所有欄位而自動加上 ‘SELECT *’ 。

$this->db->select() 可接受額外的第二個參數。如果你設成 FALSE , CodeIgniter 將不會試著保護欄位及資料表名稱。如果你需要自行組合 select 語句,而自動跳脫欄位名稱可能會破壞它時,這個參數會很有用。

$this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE);
$query = $this->db->get('mytable');

$this->db->select_max()

用來撰寫查詢中 SELECT MAX(field) 的部份。你可以額外包含第二個參數,來重新命名查詢結果中的欄位。

$this->db->select_max('age');
$query = $this->db->get('members');  // 產生: SELECT MAX(age) as age FROM members

$this->db->select_max('age', 'member_age');
$query = $this->db->get('members'); // 產生: SELECT MAX(age) as member_age FROM members

$this->db->select_min()

用來撰寫查詢中 “SELECT MIN(field)” 的部份。跟 select_max() 一樣,可以額外用第二個參數來重新命名查詢結果中的欄位。

$this->db->select_min('age');
$query = $this->db->get('members'); // 產生: SELECT MIN(age) as age FROM members

$this->db->select_avg()

用來撰寫查詢中 “SELECT AVG(field)” 的部份。跟 select_max() 一樣,可以額外用第二個參數來重新命名查詢結果中的欄位。

$this->db->select_avg('age');
$query = $this->db->get('members'); // 產生: SELECT AVG(age) as age FROM members

$this->db->select_sum()

用來撰寫查詢中 “SELECT SUM(field)” 的部份。跟 select_max() 一樣,可以額外用第二個參數來重新命名查詢結果中的欄位。

$this->db->select_sum('age');
$query = $this->db->get('members'); // 產生: SELECT SUM(age) as age FROM members

$this->db->from()

讓你撰寫查詢中 FROM 的部份:

$this->db->select('title, content, date');
$this->db->from('mytable');
$query = $this->db->get();  // 產生: SELECT title, content, date FROM mytable

Note

如同之前的說明,查詢中 FROM 的部份可以在 $this->db->get() 函式中指定,就看你偏好使用哪個方法。

$this->db->join()

讓你撰寫查詢中的 JOIN 部分:

$this->db->select('*');
$this->db->from('blogs');
$this->db->join('comments', 'comments.id = blogs.id');
$query = $this->db->get();

// 產生:
// SELECT * FROM blogs JOIN comments ON comments.id = blogs.id

如果需要在一個查詢中使用多個 join ,可以多次呼叫這個函式。

如果你需要在查詢中指定 JOIN 的方式,可以透過這個函式的第三個參數來做。可指定的方式有: left, right, outer, inner, left outer, 以及 right outer 。

$this->db->join('comments', 'comments.id = blogs.id', 'left');
// 產生: LEFT JOIN comments ON comments.id = blogs.id

尋找特定的資料

$this->db->where()

這個函式讓你能用四個方法之一來設定 WHERE 子句:

Note

所有傳送給這個函式的值會被自動跳脫,以產生較安全的查詢。

  1. 簡單的 key/value 方法:

    $this->db->where('name', $name); // 產生: WHERE name = 'Joe'
    

    注意,它會幫你加上等號。

    If you use multiple function calls they will be chained together with AND between them:

    如果你多次呼叫這個函式,它會將他們用 AND 串在一起:

    $this->db->where('name', $name);
    $this->db->where('title', $title);
    $this->db->where('status', $status);
    // WHERE name = 'Joe' AND title = 'boss' AND status = 'active'
    
  2. 客製的 key/value 方法:

    You can include an operator in the first parameter in order to control the comparison:

    你可以在第一個參數加上運算子,來控制它比較的方式:

    $this->db->where('name !=', $name);
    $this->db->where('id <', $id); // 產生: WHERE name != 'Joe' AND id < 45
    
  3. 關連陣列方法:

    $array = array('name' => $name, 'title' => $title, 'status' => $status);
    $this->db->where($array);
    // 產生: WHERE name = 'Joe' AND title = 'boss' AND status = 'active'
    

    You can include your own operators using this method as well:

    你同樣可以在這個方法中使用你要的運算子:

    $array = array('name !=' => $name, 'id <' => $id, 'date >' => $date);
    $this->db->where($array);
    
  4. 自定字串:

    你可以手動撰寫自己要的子句:

    $where = "name='Joe' AND status='boss' OR status='active'";
    $this->db->where($where);
    

$this->db->where() 可以接受額外的第三個參數。如果你將它設為 FALSE , CodeIgniter 將嘗試不去保護欄位及資料表名稱。

$this->db->where('MATCH (field) AGAINST ("value")', NULL, FALSE);

$this->db->or_where()

這個函式與前面的相同,只是會將多個實例用 OR 串接起來:

$this->db->where('name !=', $name);
$this->db->or_where('id >', $id);  // 產生: WHERE name != 'Joe' OR id > 50

Note

舊的 orwhere() 方法已經被移除而被 or_where() 方法取代

$this->db->where_in()

產生 WHERE field IN (‘item’, ‘item’) SQL 查詢,如果合適的話就用 AND 來串接

$names = array('Frank', 'Todd', 'James');
$this->db->where_in('username', $names);
// 產生: WHERE username IN ('Frank', 'Todd', 'James')

$this->db->or_where_in()

產生 WHERE field IN (‘item’, ‘item’) SQL 查詢,如果合適的話就用 OR 來串接

$names = array('Frank', 'Todd', 'James');
$this->db->or_where_in('username', $names);
// 產生: OR username IN ('Frank', 'Todd', 'James')

$this->db->where_not_in()

產生 WHERE field NOT IN (‘item’, ‘item’) SQL 查詢,如果合適的話就用 AND 來串接

$names = array('Frank', 'Todd', 'James');
$this->db->where_not_in('username', $names);
// 產生: WHERE username NOT IN ('Frank', 'Todd', 'James')

$this->db->or_where_not_in()

產生 WHERE field NOT IN (‘item’, ‘item’) SQL 查詢,如果合適的話就用 OR 來串接

$names = array('Frank', 'Todd', 'James');
$this->db->or_where_not_in('username', $names);
// 產生: OR username NOT IN ('Frank', 'Todd', 'James')

尋找相似的資料

$this->db->like()

這個方法可以讓你產生 LIKE 子句,在做搜尋時很有用。

Note

所有傳進這個方法的值會被自動跳脫。

  1. 簡單的 key/value 方法:

    $this->db->like('title', 'match');
    // 產生: WHERE `title` LIKE '%match%' ESCAPE '!'
    

    如果你多次呼叫這個方法,它們會使用 AND 來串接:

    $this->db->like('title', 'match');
    $this->db->like('body', 'match');
    // WHERE `title` LIKE '%match%' ESCAPE '!' AND  `body` LIKE '%match% ESCAPE '!'
    

    如果要控制在哪個位置放置萬用字元,你可以使用額外的第三個參數。可使用的參數為 ‘before’, ‘after’ 以及 ‘both’ (預設值)

    $this->db->like('title', 'match', 'before');    // 產生: WHERE `title` LIKE '%match' ESCAPE '!'
    $this->db->like('title', 'match', 'after');     // 產生: WHERE `title` LIKE 'match%' ESCAPE '!'
    $this->db->like('title', 'match', 'both');      // 產生: WHERE `title` LIKE '%match%' ESCAPE '!'
    
  2. 關連陣列方法:

    $array = array('title' => $match, 'page1' => $match, 'page2' => $match);
    $this->db->like($array);
    // WHERE `title` LIKE '%match%' ESCAPE '!' AND  `page1` LIKE '%match%' ESCAPE '!' AND  `page2` LIKE '%match%' ESCAPE '!'
    

$this->db->or_like()

這個與前面的方法相同,只是多個實例會使用 OR 來串接:

$this->db->like('title', 'match'); $this->db->or_like('body', $match);
// WHERE `title` LIKE '%match%' ESCAPE '!' OR  `body` LIKE '%match%' ESCAPE '!'

Note

舊的 orlike() 方法已經被移除而被 or_like() 方法取代

$this->db->not_like()

這個方法與 like() 相同,只是它會產生 NOT LIKE 語句:

$this->db->not_like('title', 'match');  // WHERE `title` NOT LIKE '%match% ESCAPE '!'

$this->db->or_not_like()

這個方法與 not_like() 相同,只是多個實例會使用 OR 來串接:

$this->db->like('title', 'match');
$this->db->or_not_like('body', 'match');
// WHERE `title` LIKE '%match% OR  `body` NOT LIKE '%match%' ESCAPE '!'

$this->db->group_by()

讓你可以撰寫查詢中 GROUP BY 的部份:

$this->db->group_by("title"); // 產生: GROUP BY title

你也可以用陣列來傳送多個值給它:

$this->db->group_by(array("title", "date"));  // 產生: GROUP BY title, date

Note

舊的 groupby() 方法已經被移除,而被 group_by() 方法取代

$this->db->distinct()

用來在查詢中加入 “DISTINCT” 關鍵字

$this->db->distinct();
$this->db->get('table'); // 產生: SELECT DISTINCT * FROM table

$this->db->having()

讓你可以撰寫查詢中 HAVING 的部份。它有兩種語法,分別使用一個或兩個參數:

$this->db->having('user_id = 45');  // 產生: HAVING user_id = 45
$this->db->having('user_id',  45);  // 產生: HAVING user_id = 45

你也能用陣列來將多個值傳給它:

$this->db->having(array('title =' => 'My Title', 'id <' => $id));
// 產生: HAVING title = 'My Title', id < 45

如果你使用的資料庫 CodeIgniter 會為它的查詢做跳脫,你可使用額外的第三個參數,將它設定為 FALSE 來防止跳脫內容。

$this->db->having('user_id',  45);  // 在一些資料庫例如MySQL會產生: HAVING `user_id` = 45
$this->db->having('user_id',  45, FALSE);  // 產生: HAVING user_id = 45

$this->db->or_having()

與 having() 相同,只是它會使用 OR 來分隔多個子句。

排序查詢結果

$this->db->order_by()

讓你設定 ORDER BY 子句。

第一個參數包含你要用來排序的欄位名稱。

第二個參數讓你設定結果排序的方向,選項有 ASC, DESC 以及 RANDOM

$this->db->order_by('title', 'DESC');
// 產生: ORDER BY `title` DESC

你也可以用第一個參數傳入自定的字串:

$this->db->order_by('title DESC, name ASC');
// 產生: ORDER BY `title` DESC, `name` ASC

或是使用多次函式呼叫來傳入多個需要的欄位。

$this->db->order_by('title', 'DESC');
$this->db->order_by('name', 'ASC');
// 產生: ORDER BY `title` DESC, `name` ASC

如果你選擇 RANDOM 作為排序方向的選項,那第一個參數會被忽略,除非你指定一個數值作為種子。

$this->db->order_by('title', 'RANDOM');
// 產生: ORDER BY RAND()

$this->db->order_by(42, 'RANDOM');
// 產生: ORDER BY RAND(42)

Note

舊的 orderby() 方法已經被移除,而被 order_by() 方法取代

Note

Oracle 目前不支援亂數排序,所以預設會使用 ASC 來取代。

結果的限制或計數

$this->db->limit()

讓你限制查詢所要回傳的列數:

$this->db->limit(10);  // 產生: LIMIT 10

第二個參數讓你可以指定查詢結果的偏移量。

$this->db->limit(10, 20);  // 產生: LIMIT 20, 10 (使用MySQL時。其他資料庫的語法稍有不同)

$this->db->count_all_results()

讓你可以判斷特定 Active Record 查詢的結果列數。查詢可接受查詢生成器所給的限制條件,諸如 where(), or_where(), like(), or_like() 等。例如:

echo $this->db->count_all_results('my_table');  // 產生一個整數,像是 25
$this->db->like('title', 'match');
$this->db->from('my_table');
echo $this->db->count_all_results(); // 產生一個整數,像是 17

不過這個方法也會重置你傳給 select() 的任何欄位值。如果你需要保留它們,可以傳送 FALSE 作為第二個參數:

echo $this->db->count_all_results('my_table', FALSE);

$this->db->count_all()

讓你可以判斷特定資料表中資料的列數。提交資料表名稱作為第一個參數。例如:

echo $this->db->count_all('my_table');  // 產生一個整數,像是 25

查詢分組

查詢分組讓你使用括號在 WHERE 子句中產生不同群組。這讓你可以用複雜的 WHERE 子句來產生查詢。支援巢狀的群組。例如:

$this->db->select('*')->from('my_table')
        ->group_start()
                ->where('a', 'a')
                ->or_group_start()
                        ->where('b', 'b')
                        ->where('c', 'c')
                ->group_end()
        ->group_end()
        ->where('d', 'd')
->get();

// 生成:
// SELECT * FROM (`my_table`) WHERE ( `a` = 'a' OR ( `b` = 'b' AND `c` = 'c' ) ) AND `d` = 'd'

Note

群組需要保持平衡,請確認每個 group_start() 都有相對應的 group_end() 。

$this->db->group_start()

經由在查詢的 WHERE 子句中加入一個左括號,來起始一個新的群組。

$this->db->or_group_start()

經由在查詢的 WHERE 子句中加入一個 OR 以及後面的左括號,來起始一個新的群組。

$this->db->not_group_start()

經由在查詢的 WHERE 子句中加入一個 NOT 以及後面的左括號,來起始一個新的群組。

$this->db->or_not_group_start()

經由在查詢的 WHERE 子句中加入一個 OR NOT 以及後面的左括號,來起始一個新的群組。

$this->db->group_end()

經由在查詢的 WHERE 子句中加入一個右括號,來結束目前的群組。

插入資料

$this->db->insert()

根據你提供的資料產生插入語句字串,並執行查詢。你可以傳入 陣列物件 作為參數。下面的範例是使用陣列:

$data = array(
        'title' => 'My title',
        'name' => 'My Name',
        'date' => 'My date'
);

$this->db->insert('mytable', $data);
// 產生: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date')

第一個參數包含了資料表的名稱,第二個參數則是一個包含了要存入的值的關連陣列。

下面這個例子則使用物件:

/*
class Myclass {
        public $title = 'My Title';
        public $content = 'My Content';
        public $date = 'My Date';
}
*/

$object = new Myclass;
$this->db->insert('mytable', $object);
// 產生: INSERT INTO mytable (title, content, date) VALUES ('My Title', 'My Content', 'My Date')

第一個參數包含了資料表的名稱,第二個參數則是一個物件。

Note

所有的值都會被自動跳脫以產生較安全的查詢。

$this->db->get_compiled_insert()

就像 $this->db->insert() 一樣編譯出插入的查詢,但是並不 執行 。這個方法只會把產生的 SQL 查詢當做字串回傳。

範例:

$data = array(
        'title' => 'My title',
        'name'  => 'My Name',
        'date'  => 'My date'
);

$sql = $this->db->set($data)->get_compiled_insert('mytable');
echo $sql;

// 產生字串: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date')

第二個參數讓你能設定是否要在執行後重設查詢生成器(預設是會,跟 $this->db->insert() 一樣):

echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE);

// 產生字串: INSERT INTO mytable (title) VALUES ('My Title')

echo $this->db->set('content', 'My Content')->get_compiled_insert();

// 產生字串: INSERT INTO mytable (title, content) VALUES ('My Title', 'My Content')

在上例中要注意的重點在於,第二次查詢並沒有使用 $this->db->from() ,也沒有把資料表名稱當做第一個參數傳入。這樣依舊能運作的原因在於,查詢並未使用 $this->db->insert() 來執行而使得值被重設,也沒有直接使用 $this->db->reset_query() 來重設。

Note

這個方法不適用於批次插入資料。

$this->db->insert_batch()

根據你提供的資料產生插入語句字串,並且執行查詢。你可以傳入一個 陣列 或是 物件 給函式。下面的範例是使用陣列:

$data = array(
        array(
                'title' => 'My title',
                'name' => 'My Name',
                'date' => 'My date'
        ),
        array(
                'title' => 'Another title',
                'name' => 'Another Name',
                'date' => 'Another date'
        )
);

$this->db->insert_batch('mytable', $data);
// 產生: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date'),  ('Another title', 'Another name', 'Another date')

第一個參數包含了資料表名稱,第二個參數則是要插入資料的關聯陣列。

Note

所有的值都會被自動跳脫以產生較安全的查詢。

更新資料

$this->db->replace()

這個方法會執行一個 REPLACE 語句,它基本上是一個標準的 SQL DELETE 加上 INSERT,使用 PRIMARYUNIQUE 鍵來做判斷的因素。 在我們的案例中,它可以讓你不需要呼叫 select(), update(), delete()insert() 等的不同組合來實現複雜的邏輯。

範例:

$data = array(
        'title' => 'My title',
        'name'  => 'My Name',
        'date'  => 'My date'
);

$this->db->replace('table', $data);

// 執行: REPLACE INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date')

在上面的範例中,如果我們假設 title 欄位是主鍵,而一個列的 title 欄位值包含 ‘My title’ ,那這個列會被刪除而用新的資料列取代。

也可以使用 set() 方法,而且就像使用 insert() 時一樣,所有的欄位值會被自動跳脫。

$this->db->set()

這個函式讓你能設定要插入或更新的值。

也可以直接傳送一個資料陣列給插入或更新函數

$this->db->set('name', $name);
$this->db->insert('mytable');  // 產生: INSERT INTO mytable (name) VALUES ('{$name}')

如果多次呼叫函式,它會根據你是要插入或更新來做適當的組合:

$this->db->set('name', $name);
$this->db->set('title', $title);
$this->db->set('status', $status);
$this->db->insert('mytable');

set() 可以接受額外的第三個參數 ($escape) ,將它設定為 FALSE ,可以避免資料被跳脫。為了展示其中的差異,這裡同時使用 escape 參數與不使用 escape 參數來呼叫 set() :

$this->db->set('field', 'field+1', FALSE);
$this->db->insert('mytable'); // 執行: INSERT INTO mytable (field) VALUES (field+1)
$this->db->set('field', 'field+1');
$this->db->insert('mytable'); // 執行: INSERT INTO mytable (field) VALUES ('field+1')

你也可以傳送關連陣列給這個函式:

$array = array(
        'name' => $name,
        'title' => $title,
        'status' => $status
);

$this->db->set($array);
$this->db->insert('mytable');

或是傳送一個物件:

/*
class Myclass {
        public $title = 'My Title';
        public $content = 'My Content';
        public $date = 'My Date';
}
*/

$object = new Myclass;
$this->db->set($object);
$this->db->insert('mytable');

$this->db->update()

根據你傳送的資料產生一個 update 字串並執行查詢。你可以傳送 陣列物件 給函式。這是使用陣列的例子:

$data = array(
        'title' => $title,
        'name' => $name,
        'date' => $date
);

$this->db->where('id', $id);
$this->db->update('mytable', $data);
// 產生:
// UPDATE mytable
// SET title = '{$title}', name = '{$name}', date = '{$date}'
// WHERE id = $id

你也可以提供一個物件:

/*
class Myclass {
        public $title = 'My Title';
        public $content = 'My Content';
        public $date = 'My Date';
}
*/

$object = new Myclass;
$this->db->where('id', $id);
$this->db->update('mytable', $object);
// 產生:
// UPDATE mytable
// SET title = '{$title}', name = '{$name}', date = '{$date}'
// WHERE id = $id

Note

所有的值會被自動跳脫以產生較安全的查詢。

你會發現使用 $this->db->where() 讓你可以設定 WHERE 子句。你也可以額外用字串來直接傳送這個資訊給 update 函式:

$this->db->update('mytable', $data, "id = 4");

Or as an array

或是使用一個陣列:

$this->db->update('mytable', $data, array('id' => $id));

你也可以使用前面提到的 $this->db->set() 函式來執行更新。

$this->db->update_batch()

根據你提供的資料產生 update 字串並執行查詢。你也可以傳送一個 陣列 或是 物件 給這個函式。 這是使用陣列的例子:

$data = array(
   array(
      'title' => 'My title' ,
      'name' => 'My Name 2' ,
      'date' => 'My date 2'
   ),
   array(
      'title' => 'Another title' ,
      'name' => 'Another Name 2' ,
      'date' => 'Another date 2'
   )
);

$this->db->update_batch('mytable', $data, 'title');

// 產生:
// UPDATE `mytable` SET `name` = CASE
// WHEN `title` = 'My title' THEN 'My Name 2'
// WHEN `title` = 'Another title' THEN 'Another Name 2'
// ELSE `name` END,
// `date` = CASE
// WHEN `title` = 'My title' THEN 'My date 2'
// WHEN `title` = 'Another title' THEN 'Another date 2'
// ELSE `date` END
// WHERE `title` IN ('My title','Another title')

第一個參數會包含資料表的名稱,第二個參數是一個值的陣列,第三個則是 where 使用的鍵。

Note

所有的值會被自動跳脫以產生較安全的查詢。

Note

由於它運作的天性,在這個方法使用 affected_rows() 不會給你適當的結果。取而代之,使用 update_batch() 來回傳受影響的列數。

$this->db->get_compiled_update()

$this->db->get_compiled_insert() 用幾乎完全一樣的方式運作,只是它會產生 UPDATE SQL 字串而非 INSERT SQL 字串。

請參閱 $this->db->get_compiled_insert() 的文件來取得更多資訊。

Note

這個方法無法在批次更新運作。

刪除資料

$this->db->delete()

產生一個刪除的 SQL 字串並執行查詢。

$this->db->delete('mytable', array('id' => $id));
// 產生:
// DELETE FROM mytable
// WHERE id = $id

第一個參數是資料表名稱,第二個參數是 where 子句。除了傳送資料作為第二個參數,你也可以使用 where() 或是 or_where() 函式:

$this->db->where('id', $id);
$this->db->delete('mytable');

// 產生:
// DELETE FROM mytable
// WHERE id = $id

如果你想要從多個資料表刪除資料,可以傳送一個資料表名稱的陣列給 delete() 。

$tables = array('table1', 'table2', 'table3');
$this->db->where('id', '5');
$this->db->delete($tables);

如果你要把資料表中所有的資料刪除,可以使用 truncate() 函式或是 empty_table() 函式。

$this->db->empty_table()

產生一個刪除的 SQL 字串並執行查詢。

$this->db->empty_table('mytable'); // 產生: DELETE FROM mytable

$this->db->truncate()

產生一個 truncate SQL 字串並執行查詢。

$this->db->from('mytable');
$this->db->truncate();

// 或

$this->db->truncate('mytable');

// 產生:
// TRUNCATE mytable

Note

如果無法使用 TRUNCATE 命令, truncate() 會執行 “DELETE FROM table” 。

$this->db->get_compiled_delete()

運作的方式與 $this->db->get_compiled_insert() 完全一樣,除了它會產生一個 DELETE SQL 字串而不是 INSERT SQL 字串。

請參閱 $this->db->get_compiled_insert() 文件來取得更多資訊。

方法串接

方法串接讓你可以把多個函式接起來使用以簡化語法。請考慮下例:

$query = $this->db->select('title')
                ->where('id', $id)
                ->limit(10, 20)
                ->get('mytable');

查詢生成器快取

雖然不是真的快取,查詢生成器可以儲存(或 “快取” )查詢中的特定部分,讓你可以在程式中重複使用。正常狀態下,當查詢生成器的呼叫完成時,所有儲存起來的資訊會被重置以準備下一次呼叫。使用快取,讓你能防止重置,而簡單地重複使用資訊。

快取的呼叫是累積的。如果你進行兩次快取的 select() 呼叫,然後進行兩次不快取的呼叫,結果會進行四次 select() 呼叫。 有三個快取函式可以使用:

$this->db->start_cache()

必須呼叫這個函式來開始快取。所有正確的查詢生成器的查詢類型(請參閱後面提到的可支援的查詢)會被儲存起來以備接下來的程式使用。

$this->db->stop_cache()

呼叫這個函數能停止快取。

$this->db->flush_cache()

這個函數會刪除所有查詢生成器快取中的項目。

一個快取的範例

這是一個使用範例:

$this->db->start_cache();
$this->db->select('field1');
$this->db->stop_cache();
$this->db->get('tablename');
// 生成: SELECT `field1` FROM (`tablename`)

$this->db->select('field2');
$this->db->get('tablename');
// 生成:  SELECT `field1`, `field2` FROM (`tablename`)

$this->db->flush_cache();
$this->db->select('field2');
$this->db->get('tablename');
// 生成:  SELECT `field2` FROM (`tablename`)

Note

下列語句可以被快取: select, from, join, where, like, group_by, having, order_by

重置查詢生成器

$this->db->reset_query()

重置查詢生成器讓你可以重新開始查詢,而不用先呼叫 $this->db->get() 或 $this->db->insert() 等方法。就像其他執行查詢的方法,這並不會讓你重置使用 查詢生成器快取 快取起來的項目。

在你使用查詢生成器產生 SQL (例如: $this->db->get_compiled_select() ),然後又想要進行其他動作(例如執行查詢)的狀況下,這樣會很有用:

// 注意, get_compiled_select 方法的第二個參數是 FALSE
$sql = $this->db->select(array('field1','field2'))
                                ->where('field3',5)
                                ->get_compiled_select('mytable', FALSE);

// ...
// 對 SQL 程式碼做一些瘋狂的事 ... 像是把它加入到 cron script
// 來在稍後執行 ...
// ...

$data = $this->db->get()->result_array();

// 會執行並回傳下列查詢的結果陣列:
// SELECT field1, field1 from mytable where field3 = 5;

Note

在使用查詢生成器的快取功能,又沒有重置查詢的時候重複呼叫 get_compiled_select() ,會使得快取被合併兩次。例如,假設你正在快取一個 select() ,這樣反而會讓你 select 同一個欄位兩次。

類別參考

class CI_DB_query_builder
reset_query()
Returns:CI_DB_query_builder 的實例(方法串接)
Return type:CI_DB_query_builder

重置當前查詢生成器的狀態。當你要建立一個在特定狀況下會取消的查詢時,這個方法很有用。

start_cache()
Returns:CI_DB_query_builder 的實例(方法串接)
Return type:CI_DB_query_builder

開始查詢生成器的快取。

stop_cache()
Returns:CI_DB_query_builder 的實例(方法串接)
Return type:CI_DB_query_builder

停止查詢生成器的快取。

flush_cache()
Returns:CI_DB_query_builder 的實例(方法串接)
Return type:CI_DB_query_builder

清空查詢生成器的快取。

set_dbprefix([$prefix = ''])
Parameters:
  • $prefix (string) – 要使用的新前綴
Returns:

使用中的資料庫前綴

Return type:

string

設定資料庫前綴,此操作無需重新連接到資料庫。

dbprefix([$table = ''])
Parameters:
  • $table (string) – 要加上前綴的資料表名稱
Returns:

已加上前綴的資料表名稱

Return type:

string

Prepends a database prefix, if one exists in configuration. 如果設定中存在已經設定好資料庫前綴,就將它加上。

count_all_results([$table = ''[, $reset = TRUE]])
Parameters:
  • $table (string) – 資料表名稱
  • $reset (bool) – 是否要在執行完畢重設 SELECT 的值
Returns:

查詢結果的列數

Return type:

int

產生一個平台特定的查詢字串,這個查詢字串會用來計算查詢生成器的查詢所回傳的記錄數,然後執行並回傳結果。

get([$table = ''[, $limit = NULL[, $offset = NULL]]])
Parameters:
  • $table (string) – 要查詢的資料表
  • $limit (int) – LIMIT 子句
  • $offset (int) – OFFSET 子句
Returns:

CI_DB_result 的實例(方法串接)

Return type:

CI_DB_result

根據已經呼叫的查詢生成器方法,編譯並執行 SELECT 語句。

get_where([$table = ''[, $where = NULL[, $limit = NULL[, $offset = NULL]]]])
Parameters:
  • $table (mixed) – 要取得資料的資料表(一個或多個),字串或陣列
  • $where (string) – WHERE 子句
  • $limit (int) – LIMIT 子句
  • $offset (int) – OFFSET 子句
Returns:

CI_DB_result 的實例(方法串接)

Return type:

CI_DB_result

get() 相同,但是讓你可以直接加入 WHERE 子句。

select([$select = '*'[, $escape = NULL]])
Parameters:
  • $select (string) – 查詢的 SELECT 部分
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢中加入 SELECT 子句。

select_avg([$select = ''[, $alias = '']])
Parameters:
  • $select (string) – 要計算平均值的欄位
  • $alias (string) – 結果值的欄位別名
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢中加入 SELECT AVG(field) 子句。

select_max([$select = ''[, $alias = '']])
Parameters:
  • $select (string) – 要計算最大值的欄位
  • $alias (string) – 結果值的欄位別名
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢中加入 SELECT MAX(field) 子句。

select_min([$select = ''[, $alias = '']])
Parameters:
  • $select (string) – 要計算最小值的欄位
  • $alias (string) – 結果值的欄位別名
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢中加入 SELECT MIN(field) 子句。

select_sum([$select = ''[, $alias = '']])
Parameters:
  • $select (string) – 要計算總和的欄位
  • $alias (string) – 結果值的欄位別名
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢中加入 SELECT SUM(field) 子句。

distinct([$val = TRUE])
Parameters:
  • $val (bool) – 要使用的 “distinct” 旗標值
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

設定一個旗標,告訴查詢生成器要在查詢的 SELECT 部分加入 DISTINCT 子句。

from($from)
Parameters:
  • $from (mixed) – 字串或陣列,用來指定一個或多個資料表名稱
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

指定查詢的 FROM 子句。

join($table, $cond[, $type = ''[, $escape = NULL]])
Parameters:
  • $table (string) – 要 join 的資料表名稱
  • $cond (string) – JOIN ON 條件
  • $type (string) – JOIN 的類型
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢中加入 JOIN 子句。

where($key[, $value = NULL[, $escape = NULL]])
Parameters:
  • $key (mixed) – 用來比較的欄位名稱,或是一個關連陣列
  • $value (mixed) – 如果 key 是單一欄位名稱,用來指定比較的值
  • $escape (boolean) – 是否要跳脫值及識別字
Returns:

DB_query_builder 的實例

Return type:

object

產生查詢的 WHERE 部分。 多次呼叫時會使用 ‘AND’ 來分隔(串接多個條件)。

or_where($key[, $value = NULL[, $escape = NULL]])
Parameters:
  • $key (mixed) – 用來比較的欄位名稱,或是一個關連陣列
  • $value (mixed) – 如果 key 是單一欄位名稱,用來指定比較的值
  • $escape (boolean) – 是否要跳脫值及識別字
Returns:

DB_query_builder 的實例

Return type:

object

產生查詢的 WHERE 部分。 多次呼叫時會使用 ‘OR’ 來分隔(串接多個條件)。

or_where_in([$key = NULL[, $values = NULL[, $escape = NULL]]])
Parameters:
  • $key (string) – 要搜尋的欄位
  • $values (array) – 用來搜尋的值
  • $escape (boolean) – 是否要跳脫值及識別字
Returns:

DB_query_builder 的實例

Return type:

object

產生一個 WHERE field IN(‘item’, ‘item’) SQL 查詢, 合適的話以 ‘OR’ 串接。

or_where_not_in([$key = NULL[, $values = NULL[, $escape = NULL]]])
Parameters:
  • $key (string) – 要搜尋的欄位
  • $values (array) – 用來搜尋的值
  • $escape (boolean) – 是否要跳脫識別字
Returns:

DB_query_builder 的實例

Return type:

object

產生一個 WHERE field NOT IN(‘item’, ‘item’) SQL 查詢, 合適的話以 ‘OR’ 串接。

where_in([$key = NULL[, $values = NULL[, $escape = NULL]]])
Parameters:
  • $key (string) – 要檢查的欄位名稱
  • $values (array) – 目標值的陣列
  • $escape (boolean) – 是否要跳脫識別字
Returns:

DB_query_builder 的實例

Return type:

object

產生一個 WHERE field IN(‘item’, ‘item’) SQL 查詢, 合適的話以 ‘AND’ 串接。

where_not_in([$key = NULL[, $values = NULL[, $escape = NULL]]])
Parameters:
  • $key (string) – 要檢查的欄位名稱
  • $values (array) – 目標值的陣列
  • $escape (boolean) – 是否要跳脫識別字
Returns:

DB_query_builder 的實例

Return type:

object

產生一個 WHERE field NOT IN(‘item’, ‘item’) SQL 查詢, 合適的話以 ‘AND’ 串接。

group_start()
Returns:CI_DB_query_builder 的實例(方法串接)
Return type:CI_DB_query_builder

開始一段群組表達式,使用 AND 作為內部條件。

or_group_start()
Returns:CI_DB_query_builder 的實例(方法串接)
Return type:CI_DB_query_builder

開始一段群組表達式,使用 OR 作為內部條件。

not_group_start()
Returns:CI_DB_query_builder 的實例(方法串接)
Return type:CI_DB_query_builder

開始一段群組表達式,使用 NOT 作為內部條件。

or_not_group_start()
Returns:CI_DB_query_builder 的實例(方法串接)
Return type:CI_DB_query_builder

開始一段群組表達式,使用 OR NOT 作為內部條件。

group_end()
Returns:DB_query_builder 的實例
Return type:object

結束一段群組表達式。

like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]])
Parameters:
  • $field (string) – 欄位名稱
  • $match (string) – 要匹配的文字部分
  • $side (string) – 要在敘述的哪一側加上 ‘%’ 萬用字元
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 LIKE 子句,多次呼叫時會使用 AND 來分隔(串接多個條件)。

or_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]])
Parameters:
  • $field (string) – 欄位名稱
  • $match (string) – 要匹配的文字部分
  • $side (string) – 要在敘述的哪一側加上 ‘%’ 萬用字元
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 LIKE 子句,多次呼叫時會使用 OR 來分隔(串接多個條件)。

not_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]])
Parameters:
  • $field (string) – 欄位名稱
  • $match (string) – 要匹配的文字部分
  • $side (string) – 要在敘述的哪一側加上 ‘%’ 萬用字元
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 NOT LIKE 子句,多次呼叫時會使用 AND 來分隔(串接多個條件)。

or_not_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]])
Parameters:
  • $field (string) – 欄位名稱
  • $match (string) – 要匹配的文字部分
  • $side (string) – 要在敘述的哪一側加上 ‘%’ 萬用字元
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 NOT LIKE 子句,多次呼叫時會使用 OR 來分隔(串接多個條件)。

having($key[, $value = NULL[, $escape = NULL]])
Parameters:
  • $key (mixed) – 識別字(字串)或是由欄位 / 值對構成的關聯陣列
  • $value (string) – 如果 $key 是識別字,這是要搜尋的值
  • $escape (string) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 HAVING 子句,多次呼叫時會使用 AND 來分隔(串接多個條件)。

or_having($key[, $value = NULL[, $escape = NULL]])
Parameters:
  • $key (mixed) – 識別字(字串)或是由欄位/值對構成的關聯陣列
  • $value (string) – 如果 $key 是識別字,這是要搜尋的值
  • $escape (string) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 HAVING 子句,多次呼叫時會使用 OR 來分隔(串接多個條件)。

group_by($by[, $escape = NULL])
Parameters:
  • $by (mixed) – 要 group by 的欄位,字串或陣列(多個欄位時)
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 GROUP BY 子句。

order_by($orderby[, $direction = ''[, $escape = NULL]])
Parameters:
  • $orderby (string) – 要排序的欄位
  • $direction (string) – 指定的排序方式: ASC, DESC 或 random
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 ORDER BY 子句。

limit($value[, $offset = 0])
Parameters:
  • $value (int) – 要限制的結果列數
  • $offset (int) – 要跳過的列數
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 LIMIT 與 OFFSET 子句。

offset($offset)
Parameters:
  • $offset (int) – 要跳過的列數
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

在查詢加入 OFFSET 子句。

set($key[, $value = ''[, $escape = NULL]])
Parameters:
  • $key (mixed) – 欄位名稱,或是由欄位 / 值對構成的陣列
  • $value (string) – 如果 $key 是單一欄位,就是欄位要指定的值
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

加入稍後會被傳給 insert() , update()replace() 的欄位 / 值對。

insert([$table = ''[, $set = NULL[, $escape = NULL]]])
Parameters:
  • $table (string) – 資料表名稱
  • $set (array) – 欄位 / 值對構成的關聯陣列
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

成功時回傳 TRUE ,失敗時回傳 FALSE

Return type:

bool

編譯並執行 INSERT 語句。

insert_batch($table[, $set = NULL[, $escape = NULL[, $batch_size = 100]]])
Parameters:
  • $table (string) – 資料表名稱
  • $set (array) – 要插入的資料
  • $escape (bool) – 是否要跳脫值及識別字
  • $batch_size (int) – 一次插入的資料行數
Returns:

成功時回傳插入列數,失敗時回傳 FALSE

Return type:

mixed

編譯並執行批次的 INSERT 語句。

Note

當提供的資料行數超過 $batch_size ,數個 INSERT 查詢將被執行,每一次嘗試插入最多 $batch_size 行。

set_insert_batch($key[, $value = ''[, $escape = NULL]])
Parameters:
  • $key (mixed) – 欄位名稱或是由欄位 / 值對構成的陣列
  • $value (string) – 如果 $key 是單一欄位,指定欄位要設定的值
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

加入稍後會透過 insert_batch() 插入到資料表的欄位 / 值對。

update([$table = ''[, $set = NULL[, $where = NULL[, $limit = NULL]]]])
Parameters:
  • $table (string) – 資料表名稱
  • $set (array) – 由欄位 / 值對構成的關聯陣列
  • $where (string) – WHERE 子句
  • $limit (int) – LIMIT 子句
Returns:

成功時回傳 TRUE ,失敗時回傳 FALSE

Return type:

bool

編譯並執行 UPDATE 語句。

update_batch($table[, $set = NULL[, $value = NULL[, $batch_size = 100]]])
Parameters:
  • $table (string) – 資料表名稱
  • $set (array) – 欄位名稱或由欄位 / 值對構成的關聯陣列
  • $value (string) – 如果 $set 是單一欄位,指定欄位要設定的值
  • $batch_size (int) – Count of conditions to group in a single query
Returns:

成功時回傳更新列數,失敗時回傳 FALSE

Return type:

mixed

編譯並執行批次 UPDATE 語句。

Note

When more than $batch_size field/value pairs are provided, multiple queries will be executed, each handling up to $batch_size field/value pairs.

set_update_batch($key[, $value = ''[, $escape = NULL]])
Parameters:
  • $key (mixed) – 欄位名稱或由欄位 / 值對構成的陣列
  • $value (string) – 如果 $key 是單一欄位,指定欄位要設定的值
  • $escape (bool) – 是否要跳脫值及識別字
Returns:

CI_DB_query_builder 的實例(方法串接)

Return type:

CI_DB_query_builder

加入稍後會透過 update_batch() 更新到資料表的欄位 / 值對。

replace([$table = ''[, $set = NULL]])
Parameters:
  • $table (string) – 資料表名稱
  • $set (array) – 由欄位 / 值對構成的關聯陣列
Returns:

成功時回傳 TRUE ,失敗時回傳 FALSE

Return type:

bool

編譯並執行 REPLACE 語句。

delete([$table = ''[, $where = ''[, $limit = NULL[, $reset_data = TRUE]]]])
Parameters:
  • $table (mixed) – 要刪除的資料表,字串或陣列(多個資料表)
  • $where (string) – WHERE 子句
  • $limit (int) – LIMIT 子句
  • $reset_data (bool) – TRUE to reset the query “write” clause
Returns:

成功時回傳 CI_DB_query_builder 的實例(方法串接),失敗時回傳 FALSE

Return type:

mixed

編譯並執行 DELETE 查詢。

truncate([$table = ''])
Parameters:
  • $table (string) – 資料表名稱
Returns:

成功時回傳 TRUE ,失敗時回傳 FALSE

Return type:

bool

在資料表執行 TRUNCATE 語句。

Note

如果資料庫平台不支援 TRUNCATE,會使用 DELETE 語句來替代。

empty_table([$table = ''])
Parameters:
  • $table (string) – 資料表名稱
Returns:

成功時回傳 TRUE ,失敗時回傳 FALSE

Return type:

bool

透過 DELETE 語句將資料表中所有記錄刪除。

get_compiled_select([$table = ''[, $reset = TRUE]])
Parameters:
  • $table (string) – 資料表名稱
  • $reset (bool) – 是否要重置當前查詢生成器的值
Returns:

編譯好的 SQL 語句字串

Return type:

string

編譯 SELECT 語句並作為字串回傳。

get_compiled_insert([$table = ''[, $reset = TRUE]])
Parameters:
  • $table (string) – 資料表名稱
  • $reset (bool) – 是否要重置當前查詢生成器的值
Returns:

編譯好的 SQL 語句字串

Return type:

string

編譯 INSERT 語句並作為字串回傳。

get_compiled_update([$table = ''[, $reset = TRUE]])
Parameters:
  • $table (string) – 資料表名稱
  • $reset (bool) – 是否要重置當前查詢生成器的值
Returns:

編譯好的 SQL 語句字串

Return type:

string

編譯 UPDATE 語句並作為字串回傳。

get_compiled_delete([$table = ''[, $reset = TRUE]])
Parameters:
  • $table (string) – 資料表名稱
  • $reset (bool) – 是否要重置當前查詢生成器的值
Returns:

編譯好的 SQL 語句字串

Return type:

string

編譯 DELETE 語句並作為字串回傳。