From 4fce5c482f5168886f99d9849848f0b54d256670 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Thu, 11 Dec 2014 17:11:48 +0200 Subject: [ci skip] Update Query Builder docs Close #2512 Related: #3396 --- user_guide_src/source/database/query_builder.rst | 667 ++++++++++++----------- 1 file changed, 337 insertions(+), 330 deletions(-) (limited to 'user_guide_src/source') diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst index 577248b32..030599e31 100644 --- a/user_guide_src/source/database/query_builder.rst +++ b/user_guide_src/source/database/query_builder.rst @@ -40,8 +40,9 @@ The second and third parameters enable you to set a limit and offset clause:: $query = $this->db->get('mytable', 10, 20); - // Produces: SELECT * FROM mytable LIMIT 20, 10 - // (in MySQL. Other databases have slightly different syntax) + + // Executes: SELECT * FROM mytable LIMIT 20, 10 + // (in MySQL. Other databases have slightly different syntax) You'll notice that the above function is assigned to a variable named $query, which can be used to show the results:: @@ -66,18 +67,19 @@ Example:: $sql = $this->db->get_compiled_select('mytable'); echo $sql; - // Produces string: SELECT * FROM mytable + // Prints string: SELECT * FROM mytable The second parameter enables you to set whether or not the query builder query will be reset (by default it will be reset, just like when using `$this->db->get()`):: echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE); - // Produces string: SELECT * FROM mytable LIMIT 20, 10 + + // Prints string: SELECT * FROM mytable LIMIT 20, 10 // (in MySQL. Other databases have slightly different syntax) echo $this->db->select('title, content, date')->get_compiled_select(); - // Produces string: SELECT title, content, date FROM mytable LIMIT 20, 10 + // Prints string: SELECT title, content, date FROM mytable LIMIT 20, 10 The key thing to notice in the above example is that the second query did not utilize **$this->db->from()** and did not pass a table name into the first @@ -102,15 +104,18 @@ Please read the about the where function below for more information. Permits you to write the SELECT portion of your query:: $this->db->select('title, content, date'); - $query = $this->db->get('mytable'); // Produces: SELECT title, content, date FROM mytable + $query = $this->db->get('mytable'); + // Executes: SELECT title, content, date FROM mytable .. note:: If you are selecting all (\*) from a table you do not need to - use this function. When omitted, CodeIgniter assumes you wish to SELECT * + use this function. When omitted, CodeIgniter assumes that you wish + to select all fields and automatically adds 'SELECT *'. -$this->db->select() accepts an optional second parameter. If you set it -to FALSE, CodeIgniter will not try to protect your field or table names -with backticks. This is useful if you need a compound select statement. +``$this->db->select()`` accepts an optional second parameter. If you set it +to FALSE, CodeIgniter will not try to protect your field or table names. +This is useful if you need a compound select statement where automatic +escaping of fields may break them. :: @@ -119,7 +124,7 @@ with backticks. This is useful if you need a compound select statement. **$this->db->select_max()** -Writes a "SELECT MAX(field)" portion for your query. You can optionally +Writes a ``SELECT MAX(field)`` portion for your query. You can optionally include a second parameter to rename the resulting field. :: @@ -232,6 +237,7 @@ methods: // WHERE name = 'Joe' AND title = 'boss' AND status = 'active' #. **Custom key/value method:** + You can include an operator in the first parameter in order to control the comparison: @@ -262,9 +268,8 @@ methods: $this->db->where($where); -$this->db->where() accepts an optional third parameter. If you set it to -FALSE, CodeIgniter will not try to protect your field or table names -with backticks. +``$this->db->where()`` accepts an optional third parameter. If you set it to +FALSE, CodeIgniter will not try to protect your field or table names. :: @@ -1041,496 +1046,498 @@ Class Reference .. class:: CI_DB_query_builder - .. method:: count_all_results([$table = '']) + .. method:: reset_query() - :param string $table: Table name to query - :returns: Number of rows in the query result - :rtype: int + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates a platform-specific query string that counts - all records returned by an Query Builder query. + Resets the current Query Builder state. Useful when you want + to build a query that can be cancelled under certain conditions. - .. method:: dbprefix([$table = '']) + .. method:: start_cache() - :param string $table: The table name to work with - :returns: The modified table name - :rtype: string + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Prepends a database prefix if one exists in configuration + Starts the Query Builder cache. - .. method:: delete([$table = ''[, $where = ''[, $limit = NULL[, $reset_data = TRUE]]]]) + .. method:: stop_cache() - :param mixed $table: The table(s) to delete from; string or array - :param string $where: The where clause - :param string $limit: The limit clause - :param boolean $reset_data: TRUE to reset the query "write" clause - :returns: DB_query_builder instance, FALSE on failure - :rtype: mixed + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Compiles a delete string and runs the query + Stops the Query Builder cache. - .. method:: distinct([$val = TRUE]) + .. method:: flush_cache() - :param boolean $val: Desired value of the "distinct" flag - :returns: DB_query_driver instance - :rtype: object + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Sets a flag which tells the query string compiler to add DISTINCT + Empties the Query Builder cache. - .. method:: empty_table([$table = '']) + .. method:: set_dbprefix([$prefix = '']) - :param string $table: Name of table to empty - :returns: DB_driver instance - :rtype: object + :param string $prefix: The new prefix to use + :returns: The DB prefix in use + :rtype: string - Compiles a delete string and runs "DELETE FROM table" + Sets the database prefix, without having to reconnect. - .. method:: flush_cache() + .. method:: dbprefix([$table = '']) - :rtype: void + :param string $table: The table name to prefix + :returns: The prefixed table name + :rtype: string - Empties the QB cache + Prepends a database prefix, if one exists in configuration. - .. method:: from($from) + .. method:: count_all_results([$table = '']) - :param mixed $from: Can be a string or array - :returns: DB_query_builder instance - :rtype: object + :param string $table: Table name + :returns: Number of rows in the query result + :rtype: int - Generates the FROM portion of the query + Generates a platform-specific query string that counts + all records returned by an Query Builder query. .. method:: get([$table = ''[, $limit = NULL[, $offset = NULL]]]) :param string $table: The table to query - :param string $limit: The limit clause - :param string $offset: The offset clause - :returns: DB_result - :rtype: object - - Compiles the select statement based on the other functions - called and runs the query + :param int $limit: The LIMIT clause + :param int $offset: The OFFSET clause + :returns: CI_DB_result instance (method chaining) + :rtype: CI_DB_result - .. method:: get_compiled_delete([$table = ''[, $reset = TRUE]]) - - :param string $table: Name of the table to delete from - :param boolean $reset: TRUE: reset QB values; FALSE: leave QB values alone - :returns: The SQL string - :rtype: string + Compiles and runs SELECT statement based on the already + called Query Builder methods. - Compiles a delete query string and returns the sql - - .. method:: get_compiled_insert([$table = ''[, $reset = TRUE]]) + .. method:: get_where([$table = ''[, $where = NULL[, $limit = NULL[, $offset = NULL]]]]) - :param string $table: Name of the table to insert into - :param boolean $reset: TRUE: reset QB values; FALSE: leave QB values alone - :returns: The SQL string - :rtype: string + :param mixed $table: The table(s) to fetch data from; string or array + :param string $where: The WHERE clause + :param int $limit: The LIMIT clause + :param int $offset: The OFFSET clause + :returns: CI_DB_result instance (method chaining) + :rtype: CI_DB_result - Compiles an insert query string and returns the sql + Same as ``get()``, but also allows the WHERE to be added directly. - .. method:: get_compiled_select([$table = ''[, $reset = TRUE]]) + .. method:: select([$select = '*'[, $escape = NULL]]) - :param string $table: Name of the table to select from - :param boolean $reset: TRUE: reset QB values; FALSE: leave QB values alone - :returns: The SQL string - :rtype: string + :param string $select: The SELECT portion of a query + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Compiles a select query string and returns the sql + Adds a SELECT clause to a query. - .. method:: get_compiled_update([$table = ''[, $reset = TRUE]]) + .. method:: select_avg([$select = ''[, $alias = '']]) - :param string $table: Name of the table to update - :param boolean $reset: TRUE: reset QB values; FALSE: leave QB values alone - :returns: The SQL string - :rtype: string + :param string $select: Field to compute the average of + :param string $alias: Alias for the resulting value name + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Compiles an update query string and returns the sql + Adds a SELECT AVG(field) clause to a query. - .. method:: get_where([$table = ''[, $where = NULL[, $limit = NULL[, $offset = NULL]]]]) + .. method:: select_max([$select = ''[, $alias = '']]) - :param mixed $table: The table(s) to delete from; string or array - :param string $where: The where clause - :param int $limit: Number of records to return - :param int $offset: Number of records to skip - :returns: DB_result - :rtype: object + :param string $select: Field to compute the maximum of + :param string $alias: Alias for the resulting value name + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Allows the where clause, limit and offset to be added directly + Adds a SELECT MAX(field) clause to a query. - .. method:: group_by($by[, $escape = NULL]) + .. method:: select_min([$select = ''[, $alias = '']]) - :param mixed $by: Field(s) to group by; string or array - :returns: DB_query_builder instance - :rtype: object + :param string $select: Field to compute the minimum of + :param string $alias: Alias for the resulting value name + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Adds a GROUPBY clause to the query + Adds a SELECT MIN(field) clause to a query. - .. method:: group_end() + .. method:: select_sum([$select = ''[, $alias = '']]) - :returns: DB_query_builder instance - :rtype: object + :param string $select: Field to compute the sum of + :param string $alias: Alias for the resulting value name + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Ends a query group + Adds a SELECT SUM(field) clause to a query. - .. method:: group_start([$not = ''[, $type = 'AND ']]) + .. method:: distinct([$val = TRUE]) - :param string $not: (Internal use only) - :param string $type: (Internal use only) - :returns: DB_query_builder instance - :rtype: object + :param bool $val: Desired value of the "distinct" flag + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Starts a query group. + Sets a flag which tells the query builder to add + a DISTINCT clause to the SELECT portion of the query. - .. method:: having($key[, $value = NULL[, $escape = NULL]]) + .. method:: from($from) - :param string $key: Key (string) or associative array of values - :param string $value: Value sought if the key is a string - :param string $escape: TRUE to escape the content - :returns: DB_query_builder instance - :rtype: object + :param mixed $from: Table name(s); string or array + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Separates multiple calls with 'AND'. + Specifies the FROM clause of a query. - .. method:: insert([$table = ''[, $set = NULL[, $escape = NULL]]]) + .. method:: join($table, $cond[, $type = ''[, $escape = NULL]]) - :param string $table: The table to insert data into - :param array $set: An associative array of insert values - :param boolean $table: Whether to escape values and identifiers - :returns: DB_result - :rtype: object + :param string $table: Table name to join + :param string $cond: The JOIN ON condition + :param string $type: The JOIN type + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Compiles an insert string and runs the query + Adds a JOIN clause to a query. - .. method:: insert_batch([$table = ''[, $set = NULL[, $escape = NULL]]]) + .. method:: where($key[, $value = NULL[, $escape = NULL]]) - :param string $table: The table to insert data into - :param array $set: An associative array of insert values + :param mixed $key: Name of field to compare, or associative array + :param mixed $value: If a single key, compared to this value :param boolean $escape: Whether to escape values and identifiers - :returns: Number of rows inserted or FALSE on failure - :rtype: mixed + :returns: DB_query_builder instance + :rtype: object - Compiles batch insert strings and runs the queries + Generates the WHERE portion of the query. + Separates multiple calls with 'AND'. - .. method:: join($table, $cond[, $type = ''[, $escape = NULL]]) + .. method:: or_where($key[, $value = NULL[, $escape = NULL]]) - :param string $table: Name of the table being joined - :param string $cond: The JOIN condition - :param string $type: The JOIN type + :param mixed $key: Name of field to compare, or associative array + :param mixed $value: If a single key, compared to this value :param boolean $escape: Whether to escape values and identifiers :returns: DB_query_builder instance :rtype: object - Generates the JOIN portion of the query + Generates the WHERE portion of the query. + Separates multiple calls with 'OR'. - .. method:: like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) + .. method:: or_where_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) - :param string $field: Name of field to compare - :param string $match: Text portion to match - :param string $side: Position of a match + :param string $key: The field to search + :param array $values: The values searched on :param boolean $escape: Whether to escape values and identifiers :returns: DB_query_builder instance :rtype: object - Generates a %LIKE% portion of the query. - Separates multiple calls with 'AND'. + Generates a WHERE field IN('item', 'item') SQL query, + joined with 'OR' if appropriate. - .. method:: limit($value[, $offset = FALSE]) + .. method:: or_where_not_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) - :param mixed $value: Number of rows to limit the results to, NULL for no limit - :param mixed $offset: Number of rows to skip, FALSE if no offset used + :param string $key: The field to search + :param array $values: The values searched on + :param boolean $escape: Whether to escape values and identifiers :returns: DB_query_builder instance :rtype: object - Specify a limit and offset for the query + Generates a WHERE field NOT IN('item', 'item') SQL query, + joined with 'OR' if appropriate. - .. method:: not_group_start() + .. method:: where_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) + :param string $key: Name of field to examine + :param array $values: Array of target values + :param boolean $escape: Whether to escape values and identifiers :returns: DB_query_builder instance :rtype: object - Starts a query group, but NOTs the group + Generates a WHERE field IN('item', 'item') SQL query, + joined with 'AND' if appropriate. - .. method:: not_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) + .. method:: where_not_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) - :param string $field: Name of field to compare - :param string $match: Text portion to match - :param string $side: Position of a match + :param string $key: Name of field to examine + :param array $values: Array of target values :param boolean $escape: Whether to escape values and identifiers :returns: DB_query_builder instance :rtype: object - Generates a NOT LIKE portion of the query. - Separates multiple calls with 'AND'. + Generates a WHERE field NOT IN('item', 'item') SQL query, + joined with 'AND' if appropriate. - .. method:: offset($offset) + .. method:: group_start() - :param int $offset: Number of rows to skip in a query - :returns: DB_query_builder instance - :rtype: object + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Sets the OFFSET value + Starts a group expression, using ANDs for the conditions inside it. .. method:: or_group_start() - :returns: DB_query_builder instance - :rtype: object + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Starts a query group, but ORs the group + Starts a group expression, using ORs for the conditions inside it. - .. method:: or_having($key[, $value = NULL[, $escape = NULL]]) + .. method:: not_group_start() - :param string $key: Key (string) or associative array of values - :param string $value: Value sought if the key is a string - :param string $escape: TRUE to escape the content - :returns: DB_query_builder instance - :rtype: object + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Separates multiple calls with 'OR'. + Starts a group expression, using AND NOTs for the conditions inside it. - .. method:: or_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) + .. method:: or_not_group_start() - :param string $field: Name of field to compare - :param string $match: Text portion to match - :param string $side: Position of a match - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates a %LIKE% portion of the query. - Separates multiple calls with 'OR'. + Starts a group expression, using OR NOTs for the conditions inside it. - .. method:: or_not_group_start() + .. method:: group_end() :returns: DB_query_builder instance :rtype: object - Starts a query group, but OR NOTs the group + Ends a group expression. - .. method:: or_not_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) + .. method:: like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) - :param string $field: Name of field to compare + :param string $field: Field name :param string $match: Text portion to match - :param string $side: Position of a match - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :param string $side: Which side of the expression to put the '%' wildcard on + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates a NOT LIKE portion of the query. - Separates multiple calls with 'OR'. + Adds a LIKE clause to a query, separating multiple calls with AND. - .. method:: or_where($key[, $value = NULL[, $escape = NULL]]) + .. method:: or_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) - :param mixed $key: Name of field to compare, or associative array - :param mixed $value: If a single key, compared to this value - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :param string $field: Field name + :param string $match: Text portion to match + :param string $side: Which side of the expression to put the '%' wildcard on + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates the WHERE portion of the query. - Separates multiple calls with 'OR'. + Adds a LIKE clause to a query, separating multiple class with OR. - .. method:: or_where_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) + .. method:: not_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) - :param string $key: The field to search - :param array $values: The values searched on - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :param string $field: Field name + :param string $match: Text portion to match + :param string $side: Which side of the expression to put the '%' wildcard on + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates a WHERE field IN('item', 'item') SQL query, - joined with 'OR' if appropriate. + Adds a NOT LIKE clause to a query, separating multiple calls with AND. - .. method:: or_where_not_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) + .. method:: or_not_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) - :param string $key: The field to search - :param array $values: The values searched on - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :param string $field: Field name + :param string $match: Text portion to match + :param string $side: Which side of the expression to put the '%' wildcard on + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates a WHERE field NOT IN('item', 'item') SQL query, - joined with 'OR' if appropriate. + Adds a NOT LIKE clause to a query, separating multiple calls with OR. - .. method:: order_by($orderby[, $direction = ''[, $escape = NULL]]) + .. method:: having($key[, $value = NULL[, $escape = NULL]]) - :param string $orderby: The field to order by - :param string $direction: The order requested - asc, desc or random - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :param mixed $key: Identifier (string) or associative array of field/value pairs + :param string $value: Value sought if $key is an identifier + :param string $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates an ORDER BY clause in the SQL query + Adds a HAVING clause to a query, separating multiple calls with AND. - .. method:: replace([$table = ''[, $set = NULL]]) + .. method:: or_having($key[, $value = NULL[, $escape = NULL]]) - :param string $table: The table to query - :param array $set: Associative array of insert values - :returns: DB_result, FALSE on failure - :rtype: mixed + :param mixed $key: Identifier (string) or associative array of field/value pairs + :param string $value: Value sought if $key is an identifier + :param string $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Compiles an replace into string and runs the query + Adds a HAVING clause to a query, separating multiple calls with OR. - .. method:: reset_query() + .. method:: group_by($by[, $escape = NULL]) - :rtype: void + :param mixed $by: Field(s) to group by; string or array + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Publicly-visible method to reset the QB values. + Adds a GROUP BY clause to a query. - .. method:: select([$select = '*'[, $escape = NULL]]) + .. method:: order_by($orderby[, $direction = ''[, $escape = NULL]]) - :param string $select: Comma-separated list of fields to select - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :param string $orderby: Field to order by + :param string $direction: The order requested - ASC, DESC or random + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates the SELECT portion of the query + Adds an ORDER BY clause to a query. - .. method:: select_avg([$select = ''[, $alias = '']]) + .. method:: limit($value[, $offset = 0]) - :param string $select: Field to compute the average of - :param string $alias: Alias for the resulting value - :returns: DB_query_builder instance - :rtype: object + :param int $value: Number of rows to limit the results to + :param int $offset: Number of rows to skip + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates a SELECT AVG(field) portion of a query + Adds LIMIT and OFFSET clauses to a query. - .. method:: select_max([$select = ''[, $alias = '']]) + .. method:: offset($offset) - :param string $select: Field to compute the maximum of - :param string $alias: Alias for the resulting value - :returns: DB_query_builder instance - :rtype: object + :param int $offset: Number of rows to skip + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates a SELECT MAX(field) portion of a query + Adds an OFFSET clause to a query. - .. method:: select_min([$select = ''[, $alias = '']]) + .. method:: set($key[, $value = ''[, $escape = NULL]]) - :param string $select: Field to compute the minimum of - :param string $alias: Alias for the resulting value - :returns: DB_query_builder instance - :rtype: object + :param mixed $key: Field name, or an array of field/value pairs + :param string $value: Field value, if $key is a single field + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Generates a SELECT MIN(field) portion of a query + Adds field/value pairs to be passed later to ``insert()``, + ``update()`` or ``replace()``. - .. method:: select_sum([$select = ''[, $alias = '']]) + .. method:: insert([$table = ''[, $set = NULL[, $escape = NULL]]]) - :param string $select: Field to compute the sum of - :param string $alias: Alias for the resulting value - :returns: DB_query_builder instance - :rtype: object + :param string $table: Table name + :param array $set: An associative array of field/value pairs + :param bool $escape: Whether to escape values and identifiers + :returns: TRUE on success, FALSE on failure + :rtype: bool - Generates a SELECT SUM(field) portion of a query + Compiles and executes an INSERT statement. - .. method:: set($key[, $value = ''[, $escape = NULL]]) + .. method:: insert_batch([$table = ''[, $set = NULL[, $escape = NULL]]]) - :param mixed $key: The field to be set, or an array of key/value pairs - :param string $value: If a single key, its new value - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :param string $table: Table name + :param array $set: Data to insert + :param bool $escape: Whether to escape values and identifiers + :returns: Number of rows inserted or FALSE on failure + :rtype: mixed - Allows key/value pairs to be set for inserting or updating + Compiles and executes batch INSERT statements. - .. method:: set_dbprefix([$prefix = '']) + .. method:: set_insert_batch($key[, $value = ''[, $escape = NULL]]) - :param string $prefix: The new prefix to use - :returns: The DB prefix in use - :rtype: string + :param mixed $key: Field name or an array of field/value pairs + :param string $value: Field value, if $key is a single field + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - Set's the DB Prefix to something new without needing to reconnect + Adds field/value pairs to be inserted in a table later via ``insert_batch()``. - .. method:: set_insert_batch($key[, $value = ''[, $escape = NULL]]) + .. method:: update([$table = ''[, $set = NULL[, $where = NULL[, $limit = NULL]]]]) - :param mixed $key: The field to be set, or an array of key/value pairs - :param string $value: If a single key, its new value - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :param string $table: Table name + :param array $set: An associative array of field/value pairs + :param string $where: The WHERE clause + :param int $limit: The LIMIT clause + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Compiles and executes an UPDATE statement. - The "set_insert_batch" function. Allows key/value pairs to be set for batch inserts + .. method:: update_batch([$table = ''[, $set = NULL[, $value = NULL]]]) + + :param string $table: Table name + :param array $set: Field name, or an associative array of field/value pairs + :param string $value: Field value, if $set is a single field + :returns: Number of rows updated or FALSE on failure + :rtype: mixed + + Compiles and executes batch UPDATE statements. .. method:: set_update_batch($key[, $value = ''[, $escape = NULL]]) - :param mixed $key: The field to be set, or an array of key/value pairs - :param string $value: If a single key, its new value - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + :param mixed $key: Field name or an array of field/value pairs + :param string $value: Field value, if $key is a single field + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder - The "set_batch_batch" function. Allows key/value pairs to be set for batch batch + Adds field/value pairs to be updated in a table later via ``update_batch()``. - .. method:: start_cache() + .. method:: replace([$table = ''[, $set = NULL]]) - :rtype: void + :param string $table: Table name + :param array $set: An associative array of field/value pairs + :returns: TRUE on success, FALSE on failure + :rtype: bool - Start DB caching + Compiles and executes a REPLACE statement. - .. method:: stop_cache() + .. method:: delete([$table = ''[, $where = ''[, $limit = NULL[, $reset_data = TRUE]]]]) - :rtype: void + :param mixed $table: The table(s) to delete from; string or array + :param string $where: The WHERE clause + :param int $limit: The LIMIT clause + :param bool $reset_data: TRUE to reset the query "write" clause + :returns: CI_DB_query_builder instance (method chaining) or FALSE on failure + :rtype: mixed - Stop DB caching + Compiles and executes a DELETE query. .. method:: truncate([$table = '']) - :param string $table: Name fo the table to truncate - :returns: DB_result - :rtype: object + :param string $table: Table name + :returns: TRUE on success, FALSE on failure + :rtype: bool - Compiles a truncate string and runs the query. - If the database does not support the truncate() command - This function maps to "DELETE FROM table" + Executes a TRUNCATE statement on a table. - .. method:: update([$table = ''[, $set = NULL[, $where = NULL[, $limit = NULL]]]]) + .. note:: If the database platform in use doesn't support TRUNCATE, + a DELETE statement will be used instead. - :param string $table: The table to insert data into - :param array $set: An associative array of insert values - :param string $where: WHERE clause to use - :param string $limit: LIMIT clause to use - :returns: DB_result - :rtype: object + .. method:: empty_table([$table = '']) - Compiles an update string and runs the query. + :param string $table: Table name + :returns: TRUE on success, FALSE on failure + :rtype: bool - .. method:: update_batch([$table = ''[, $set = NULL[, $value = NULL]]]) + Deletes all records from a table via a DELETE statement. - :param string $table: The table to update data in - :param mixed $set: The field to be set, or an array of key/value pairs - :param string $value: If a single key, its new value - :returns: DB_result - :rtype: object + .. method:: get_compiled_select([$table = ''[, $reset = TRUE]]) - Compiles an update string and runs the query. + :param string $table: Table name + :param bool $reset: Whether to reset the current QB values or not + :returns: The compiled SQL statement as a string + :rtype: string - .. method:: where($key[, $value = NULL[, $escape = NULL]]) + Compiles a SELECT statement and returns it as a string. - :param mixed $key: Name of field to compare, or associative array - :param mixed $value: If a single key, compared to this value - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + .. method:: get_compiled_insert([$table = ''[, $reset = TRUE]]) - Generates the WHERE portion of the query. - Separates multiple calls with 'AND'. + :param string $table: Table name + :param bool $reset: Whether to reset the current QB values or not + :returns: The compiled SQL statement as a string + :rtype: string - .. method:: where_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) + Compiles an INSERT statement and returns it as a string. - :param string $key: Name of field to examine - :param array $values: Array of target values - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + .. method:: get_compiled_update([$table = ''[, $reset = TRUE]]) - Generates a WHERE field IN('item', 'item') SQL query, - joined with 'AND' if appropriate. + :param string $table: Table name + :param bool $reset: Whether to reset the current QB values or not + :returns: The compiled SQL statement as a string + :rtype: string - .. method:: where_not_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) + Compiles an UPDATE statement and returns it as a string. - :param string $key: Name of field to examine - :param array $values: Array of target values - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object + .. method:: get_compiled_delete([$table = ''[, $reset = TRUE]]) - Generates a WHERE field NOT IN('item', 'item') SQL query, - joined with 'AND' if appropriate. \ No newline at end of file + :param string $table: Table name + :param bool $reset: Whether to reset the current QB values or not + :returns: The compiled SQL statement as a string + :rtype: string + + Compiles a DELETE statement and returns it as a string. \ No newline at end of file -- cgit v1.2.3-24-g4f1b