From 6ebceb439ceddd02925a8424e3ccb6d368b9a92d Mon Sep 17 00:00:00 2001 From: James L Parry Date: Thu, 4 Dec 2014 06:23:14 -0800 Subject: User Guide - consolidate table & field metadata pages Signed-off-by:James L Parry --- user_guide_src/source/database/fields.rst | 80 ---------------- user_guide_src/source/database/index.rst | 3 +- user_guide_src/source/database/metadata.rst | 130 ++++++++++++++++++++++++++ user_guide_src/source/database/table_data.rst | 31 ------ 4 files changed, 131 insertions(+), 113 deletions(-) delete mode 100644 user_guide_src/source/database/fields.rst create mode 100644 user_guide_src/source/database/metadata.rst delete mode 100644 user_guide_src/source/database/table_data.rst (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/fields.rst b/user_guide_src/source/database/fields.rst deleted file mode 100644 index b706ace7d..000000000 --- a/user_guide_src/source/database/fields.rst +++ /dev/null @@ -1,80 +0,0 @@ -########## -Field Data -########## - -$this->db->list_fields() -========================= - -Returns an array containing the field names. This query can be called -two ways: - -1. You can supply the table name and call it from the $this->db-> -object:: - - $fields = $this->db->list_fields('table_name'); - - foreach ($fields as $field) - { - echo $field; - } - -2. You can gather the field names associated with any query you run by -calling the function from your query result object:: - - $query = $this->db->query('SELECT * FROM some_table'); - - foreach ($query->list_fields() as $field) - { - echo $field; - } - -$this->db->field_exists() -========================== - -Sometimes it's helpful to know whether a particular field exists before -performing an action. Returns a boolean TRUE/FALSE. Usage example:: - - if ($this->db->field_exists('field_name', 'table_name')) - { - // some code... - } - -.. note:: Replace *field_name* with the name of the column you are looking - for, and replace *table_name* with the name of the table you are - looking for. - -$this->db->field_data() -======================== - -Returns an array of objects containing field information. - -Sometimes it's helpful to gather the field names or other metadata, like -the column type, max length, etc. - -.. note:: Not all databases provide meta-data. - -Usage example:: - - $fields = $this->db->field_data('table_name'); - - foreach ($fields as $field) - { - echo $field->name; - echo $field->type; - echo $field->max_length; - echo $field->primary_key; - } - -If you have run a query already you can use the result object instead of -supplying the table name:: - - $query = $this->db->query("YOUR QUERY"); - $fields = $query->field_data(); - -The following data is available from this function if supported by your -database: - -- name - column name -- max_length - maximum length of the column -- primary_key - 1 if the column is a primary key -- type - the type of the column \ No newline at end of file diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index cfd624238..4612daf9d 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -17,8 +17,7 @@ patterns. The database functions offer clear, simple syntax. Query Helper Functions Query Builder Class Transactions - Table MetaData - Field MetaData + Getting MetaData Custom Function Calls Query Caching Database Manipulation with Database Forge diff --git a/user_guide_src/source/database/metadata.rst b/user_guide_src/source/database/metadata.rst new file mode 100644 index 000000000..b8be809b6 --- /dev/null +++ b/user_guide_src/source/database/metadata.rst @@ -0,0 +1,130 @@ +################# +Database Metadata +################# + +************** +Table MetaData +************** + +These functions let you fetch table information. + +List the Tables in Your Database +================================ + +**$this->db->list_tables();** + +Returns an array containing the names of all the tables in the database +you are currently connected to. Example:: + + $tables = $this->db->list_tables(); + + foreach ($tables as $table) + { + echo $table; + } + + +Determine If a Table Exists +=========================== + +**$this->db->table_exists();** + +Sometimes it's helpful to know whether a particular table exists before +running an operation on it. Returns a boolean TRUE/FALSE. Usage example:: + + if ($this->db->table_exists('table_name')) + { + // some code... + } + +.. note:: Replace *table_name* with the name of the table you are looking for. + + +************** +Field MetaData +************** + +List the Fields in a Table +========================== + +**$this->db->list_fields()** + +Returns an array containing the field names. This query can be called +two ways: + +1. You can supply the table name and call it from the $this->db-> +object:: + + $fields = $this->db->list_fields('table_name'); + + foreach ($fields as $field) + { + echo $field; + } + +2. You can gather the field names associated with any query you run by +calling the function from your query result object:: + + $query = $this->db->query('SELECT * FROM some_table'); + + foreach ($query->list_fields() as $field) + { + echo $field; + } + + +Determine If a Field is Present in a Table +========================================== + +**$this->db->field_exists()** + +Sometimes it's helpful to know whether a particular field exists before +performing an action. Returns a boolean TRUE/FALSE. Usage example:: + + if ($this->db->field_exists('field_name', 'table_name')) + { + // some code... + } + +.. note:: Replace *field_name* with the name of the column you are looking + for, and replace *table_name* with the name of the table you are + looking for. + + +Retrieve Field Metadata +======================= + +**$this->db->field_data()** + +Returns an array of objects containing field information. + +Sometimes it's helpful to gather the field names or other metadata, like +the column type, max length, etc. + +.. note:: Not all databases provide meta-data. + +Usage example:: + + $fields = $this->db->field_data('table_name'); + + foreach ($fields as $field) + { + echo $field->name; + echo $field->type; + echo $field->max_length; + echo $field->primary_key; + } + +If you have run a query already you can use the result object instead of +supplying the table name:: + + $query = $this->db->query("YOUR QUERY"); + $fields = $query->field_data(); + +The following data is available from this function if supported by your +database: + +- name - column name +- max_length - maximum length of the column +- primary_key - 1 if the column is a primary key +- type - the type of the column diff --git a/user_guide_src/source/database/table_data.rst b/user_guide_src/source/database/table_data.rst deleted file mode 100644 index 744a05154..000000000 --- a/user_guide_src/source/database/table_data.rst +++ /dev/null @@ -1,31 +0,0 @@ -########## -Table Data -########## - -These functions let you fetch table information. - -$this->db->list_tables(); -========================== - -Returns an array containing the names of all the tables in the database -you are currently connected to. Example:: - - $tables = $this->db->list_tables(); - - foreach ($tables as $table) - { - echo $table; - } - -$this->db->table_exists(); -=========================== - -Sometimes it's helpful to know whether a particular table exists before -running an operation on it. Returns a boolean TRUE/FALSE. Usage example:: - - if ($this->db->table_exists('table_name')) - { - // some code... - } - -.. note:: Replace *table_name* with the name of the table you are looking for. -- cgit v1.2.3-24-g4f1b From b906149a2e6b4d607294b12d4a690ed3af84eed0 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Thu, 4 Dec 2014 16:33:24 +0200 Subject: DB forge/utilities polishing (docs) following #3375, #3378 --- user_guide_src/source/database/forge.rst | 111 ++++++++++++--------------- user_guide_src/source/database/utilities.rst | 75 +++++++++--------- 2 files changed, 88 insertions(+), 98 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst index 371397d26..59a6591b7 100644 --- a/user_guide_src/source/database/forge.rst +++ b/user_guide_src/source/database/forge.rst @@ -185,7 +185,6 @@ below is for MySQL. // gives KEY `blog_name_blog_label` (`blog_name`, `blog_label`) - Creating a table ================ @@ -242,7 +241,6 @@ Executes a TABLE rename // gives ALTER TABLE old_table_name RENAME TO new_table_name - **************** Modifying Tables **************** @@ -318,104 +316,93 @@ change the name you can add a "name" key into the field defining array. Class Reference *************** -.. class:: DB_forge - - .. method:: __construct(&$db) - - :param object $db: Database object - :returns: DB_forge object for the specified database - :rtype: DB_forge - - Initializes a database forge. +.. class:: CI_DB_forge - .. method:: add_column($table = '', $field = array(), $_after = NULL) + .. method:: add_column($table[, $field = array()[, $_after = NULL]]) - :param string $table: Table name - :param array $field: Column definitions + :param string $table: Table name to add the column to + :param array $field: Column definition(s) :param string $_after: Column for AFTER clause (deprecated) - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :returns: TRUE on success, FALSE on failure + :rtype: bool - Add a column to a table. Usage: See `Adding a Column to a Table`_. + Adds a column to a table. Usage: See `Adding a Column to a Table`_. - .. method:: add_field($field = '') + .. method:: add_field($field) - :param array $field: Field to add - :returns: DB_forge instance - :rtype: object + :param array $field: Field definition to add + :returns: CI_DB_forge instance (method chaining) + :rtype: CI_DB_forge - Add a field to the set that will be used to create a table. Usage: See `Adding fields`_. + Adds a field to the set that will be used to create a table. Usage: See `Adding fields`_. - .. method:: add_key($key = '', $primary = FALSE) + .. method:: add_key($key[, $primary = FALSE]) :param array $key: Name of a key field - :param boolean $primary: TRUE if this key is to be a primary key - :returns: DB_forge instance - :rtype: object + :param bool $primary: Set to TRUE if it should be a primary key or a regular one + :returns: CI_DB_forge instance (method chaining) + :rtype: CI_DB_forge - Specify a key field to be used to create a table. Usage: See `Adding Keys`_. + Adds a key to the set that will be used to create a table. Usage: See `Adding Keys`_. .. method:: create_database($db_name) :param string $db_name: Name of the database to create - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :returns: TRUE on success, FALSE on failure + :rtype: bool - Create a new database. Usage: See `Creating and Dropping Databases`_. + Creates a new database. Usage: See `Creating and Dropping Databases`_. - .. method:: create_table($table = '', $if_not_exists = FALSE, array $attributes = array()) + .. method:: create_table($table[, $if_not_exists = FALSE[, array $attributes = array()]]) :param string $table: Name of the table to create - :param string $if_not_exists: TRUE to add an 'IF NOT EXISTS' clause - :param string $attributes: Associative array of table attributes - :returns: DB_driver on success, FALSE on failure - :rtype: mixed + :param string $if_not_exists: Set to TRUE to add an 'IF NOT EXISTS' clause + :param string $attributes: An associative array of table attributes + :returns: TRUE on success, FALSE on failure + :rtype: bool - Create a new table. Usage: See `Creating a table`_. + Creates a new table. Usage: See `Creating a table`_. - .. method:: drop_column($table = '', $column_name = '') + .. method:: drop_column($table, $column_name) :param string $table: Table name - :param array $column_name: Column to drop - :returns: DB_driver on success, FALSE on failure - :rtype: mixed + :param array $column_name: The column name to drop + :returns: TRUE on success, FALSE on failure + :rtype: bool - Drop a column from a table. Usage: See `Dropping a Column From a Table`_. + Drops a column from a table. Usage: See `Dropping a Column From a Table`_. .. method:: drop_database($db_name) :param string $db_name: Name of the database to drop - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :returns: TRUE on success, FALSE on failure + :rtype: bool - Drop a database. Usage: See `Creating and Dropping Databases`_. + Drops a database. Usage: See `Creating and Dropping Databases`_. - .. method:: drop_table($table_name, $if_exists = FALSE) + .. method:: drop_table($table_name[, $if_exists = FALSE]) - :param string $table: Name of the table to create - :param string $if_exists: TRUE to add an 'IF EXISTS' clause - :returns: DB_driver on success, FALSE on failure - :rtype: mixed + :param string $table: Name of the table to drop + :param string $if_exists: Set to TRUE to add an 'IF EXISTS' clause + :returns: TRUE on success, FALSE on failure + :rtype: bool - Drop a table. Usage: See `Dropping a table`_. + Drops a table. Usage: See `Dropping a table`_. - .. method:: modify_column($table = '', $field = array()) + .. method:: modify_column($table, $field) :param string $table: Table name - :param array $field: Column definitions - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :param array $field: Column definition(s) + :returns: TRUE on success, FALSE on failure + :rtype: bool - Modify a column in a table. Usage: See `Modifying a Column in a Table`_. + Modifies a table column. Usage: See `Modifying a Column in a Table`_. .. method:: rename_table($table_name, $new_table_name) - :param string $table: Name of the table + :param string $table: Current of the table :param string $new_table_name: New name of the table - :returns: DB_driver on success, FALSE on failure - :rtype: mixed - - Rename a table. Usage: See `Renaming a table`_. - - + :returns: TRUE on success, FALSE on failure + :rtype: bool + Renames a table. Usage: See `Renaming a table`_. \ No newline at end of file diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index d15cef06d..0d8137dd7 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -9,7 +9,6 @@ database. :local: :depth: 2 - ****************************** Initializing the Utility Class ****************************** @@ -248,66 +247,70 @@ Preference Default Value Options Descript Class Reference *************** -.. class:: DB_utility +.. class:: CI_DB_utility - .. method:: backup($params) + .. method:: backup([$params = array()]) - :param array $params: associative array of backup preferences + :param array $params: An associative array of options :returns: void - :rtype: void - - Perform a database backup, per user preferences + :rtype: void - .. method:: csv_from_results($query, $delim = ',', $newline = "\n", $enclosure = '"') - - :param object $query: DB_result with data to backup - :param string $delim: Delimniter character for the CSV file, default is ',' - :param string $newline: Character to use for newlines, default is "\n" - :param string $enclosure: Delimiter used for enclosure, default is '"' - :returns: The generated CSV file as a string - :rtype: string + Perform a database backup, per user preferences. .. method:: database_exists($database_name) - :param string $database_name: name of the database to check for + :param string $database_name: Database name :returns: TRUE if the database exists, FALSE otherwise - :rtype: boolean + :rtype: bool - Check for the existence of a database + Check for the existence of a database. .. method:: list_databases() :returns: Array of database names found - :rtype: array + :rtype: array - Retrieve all the database names + Retrieve a list of all the database names. .. method:: optimize_database() - :returns: Array of optimization messages, FALSE on failure - :rtype: array + :returns: Array of optimization messages or FALSE on failure + :rtype: array - Optimizes a database + Optimizes the database. .. method:: optimize_table($table_name) - :param string $table_name: Name of the table to optimize - :returns: Array of optimization messages, FALSE on failure - :rtype: array + :param string $table_name: Name of the table to optimize + :returns: Array of optimization messages or FALSE on failure + :rtype: array - Optimizes a database table + Optimizes a database table. .. method:: repair_table($table_name) - :param string $table_name: Name of the table to repair - :returns: Array of repair messages, FALSE on failure - :rtype: array + :param string $table_name: Name of the table to repair + :returns: Array of repair messages or FALSE on failure + :rtype: array + + Repairs a database table. + + .. method:: csv_from_results($query[, $delim = ','[, $newline = "\n"[, $enclosure = '"']]]) + + :param object $query: A database result object + :param string $delim: The CSV field delimiter to use + :param string $newline: The newline character to use + :param string $enclosure: The enclosure delimiter to use + :returns: The generated CSV file as a string + :rtype: string + + Translates a database result object into a CSV document. - Repairs a database table + .. method:: xml_from_results($query[, $params = array()]) - .. method:: xml_from_results($query, $params) + :param object $query: A database result object + :param array $params: An associative array of preferences + :returns: The generated XML document as a string + :rtype: string - :param object $query: DB_result with data to backup - :param array $params: Associative array of preferences - :returns: The generated XML document as a string - :rtype: string + Translates a database result object into an XML document. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 151621923b52c9392976de43e546f0349a604f06 Mon Sep 17 00:00:00 2001 From: James L Parry Date: Fri, 5 Dec 2014 23:40:47 -0800 Subject: User Guide - generating query results Added class reference subsection to the "Generating query results" page in the Database Reference section of the User Guide. Signed-off-by:James L Parry --- user_guide_src/source/database/results.rst | 185 ++++++++++++++++++++++++++++- 1 file changed, 184 insertions(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index e06985130..eba04099c 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -4,6 +4,10 @@ Generating Query Results There are several ways to generate query results: +.. contents:: + :local: + :depth: 2 + ************* Result Arrays ************* @@ -238,4 +242,183 @@ TRUE on success or FALSE on failure. $row = $query->unbuffered_row(); .. note:: Not all database drivers support this feature and will return FALSE. - Most notably - you won't be able to use it with PDO. \ No newline at end of file + Most notably - you won't be able to use it with PDO. + +*************** +Class Reference +*************** + +.. class:: CI_DB_result + + .. method:: custom_result_object($class_name) + + :param string $class_name: Class name for the results + :returns: Array of objects of type $class_name + :rtype: array of $class_name + + Return the query results as an array of the specified class. + + .. method:: custom_row_object($n, $type) + + :param int $n: Index of the results row to return + :param string $class_name: Class name for the results + :returns: Object of type $type + :rtype: $type + + Return a specific row from the query results as an object of + the specified class. + + .. method:: data_seek($n = 0) + + :param int $n: Index of the results row to be returned next + :returns: TRUE on success, FALSE otherwise + :rtype: bool + + Moves the internal results row pointer to the desired offset. + Usage: see `Result Helper Methods`_. + + .. method:: field_data() + + :returns: Array of objects containing field meta-data. + :rtype: array + + Generates an array of objects containing field meta-data. + + .. method:: first_row($type = 'object') + + :param string $type: Type of result requested - array, object, or class name + :returns: First row of result set + :rtype: mixed + + Returns the "first" row, as an array, generic object, or + object of a specific class + + .. method:: free_result() + + :rtype: void + + Free the result. + Usage: see `Result Helper Methods`_. + + .. method:: last_row($type = 'object') + + :param string $type: Type of result requested - array, object, or class name + :returns: Last row of result set + :rtype: mixed + + Returns the "last" row, as an array, generic object, or + object of a specific class + + .. method:: list_fields() + + :returns: Array of column names + :rtype: array + + Fetch Field Names + + .. method:: next_row($type = 'object') + + :param string $type: Type of result requested - array, object, or class name + :returns: "Next" row of result set, NULL if there isn't one + :rtype: mixed + + Returns the "next" row, as an array, generic object, or + object of a specific class + + .. method:: num_fields() + + :returns: Number of fields in the result set + :rtype: integer + + Number of fields in the result set. + Usage: see `Result Helper Methods`_. + + .. method:: num_rows() + + :returns: Number of rows in the result set + :rtype: integer + + Number of rows in the result set. + Usage: see `Result Helper Methods`_. + + .. method:: previous_row($type = 'object') + + :param string $type: Type of result requested - array, object, or class name + :returns: "Previous" row of result set, NULL if there isn't one + :rtype: mixed + + Returns the "previous" row, as an array, generic object, or + object of a specific class + + .. method:: result($type = 'object') + + :param string $type: Type of result requested - array, object, or class name + :returns: Query results as the specified type + :rtype: mixed + + Query result. Acts as a wrapper function for the result_array, + result_object and custom_result_object methods. + Usage: see `Result Arrays`_. + + .. method:: result_array() + + :returns: Query results as an associative array + :rtype: array + + Returns the query results as an array of rows, where each + row is itself an associative array. + Usage: see `Result Arrays`_. + + .. method:: result_object() + + :returns: Query results as an array of objects + :rtype: array + + Returns the query results as an array of rows, where each + row is an object + + .. method:: row($n = 0, $type = 'object') + + :param integer $n: Index of the query results row to be returned + :param string $type: Type of result requested - array, object, or class name + :returns: Requested row of result set + :rtype: mixed + + Wrapper for result_row_array, result_row_object, and + custom_row_object. + Usage: see `Result Rows`_. + + .. method:: row_array($n = 0) + + :param integer $n: Index of the query results row to be returned + :returns: Requested row of result set + :rtype: array + + Returns requested result row as an associative array. + Usage: see `Result Rows`_. + + .. method:: row_object($n = 0) + + :param integer $n: Index of the query results row to be returned + :returns: Requested row of result set + :rtype: object + + Returns requested result row as an object + + .. method:: set_row($key, $value = NULL) + + :param mixed $key: Column index or array of key/value pairs + :param mixed $value: Result to assign to a column if the key is an index + :rtype: void + + Assigns an item into a particular column slot + + .. method:: unbuffered_row($type = 'object') + + :param string $type: Type of result requested - array, object, or class name + :returns: Requested row of result set + :rtype: mixed + + Fetches the next result row and returns it in the requested + form. + Usage: see `Result Rows`_. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 2269947359d309fad381ce943c344efebab206c7 Mon Sep 17 00:00:00 2001 From: James L Parry Date: Sat, 6 Dec 2014 00:55:16 -0800 Subject: User Guide - generating query results Added attributes to the class reference. Signed-off-by:James L Parry --- user_guide_src/source/database/results.rst | 32 ++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index eba04099c..33b19270e 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -250,6 +250,38 @@ Class Reference .. class:: CI_DB_result + .. attribute:: $conn_id + + Connection ID + + .. attribute:: $result_id + + Result ID + + .. attribute:: $result_array = array() + + Result Array + + .. attribute:: $result_object = array() + + Result Object + + .. attribute:: $custom_result_object = array() + + Custom Result Object + + .. attribute:: $current_row = 0 + + Current Row index + + .. attribute:: $num_rows + + Number of rows + + .. attribute:: $row_data + + Row data + .. method:: custom_result_object($class_name) :param string $class_name: Class name for the results -- cgit v1.2.3-24-g4f1b From 141288d1fb32c11d28ea46f06eedafff76e795c4 Mon Sep 17 00:00:00 2001 From: James L Parry Date: Sat, 6 Dec 2014 01:45:12 -0800 Subject: User Guide - query builder Removed API stuff from the query builder page. Added a new API reference page. Updated the index to include the API ref in the TOC. Started on the API reference page. Signed-off-by:James L Parry --- user_guide_src/source/database/index.rst | 1 + user_guide_src/source/database/query_builder.rst | 178 +++++---------------- .../source/database/query_builder_reference.rst | 23 +++ 3 files changed, 63 insertions(+), 139 deletions(-) create mode 100644 user_guide_src/source/database/query_builder_reference.rst (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index 4612daf9d..14a871aed 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -16,6 +16,7 @@ patterns. The database functions offer clear, simple syntax. Generating Query Results Query Helper Functions Query Builder Class + Query Builder API Transactions Getting MetaData Custom Function Calls diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst index 3203ff103..701c489d6 100644 --- a/user_guide_src/source/database/query_builder.rst +++ b/user_guide_src/source/database/query_builder.rst @@ -23,14 +23,17 @@ system. :local: :depth: 1 +.. note:: This page describes how to use the Query Builder class. + API reference information is found on the + `Query Builder API `_ page. + ************** Selecting Data ************** The following functions allow you to build SQL **SELECT** statements. -$this->db->get() ----------------- +**$this->db->get()** Runs the selection query and returns the result. Can be used by itself to retrieve all records from a table:: @@ -57,11 +60,7 @@ $query, which can be used to show the results:: Please visit the :doc:`result functions ` page for a full discussion regarding result generation. -:returns: DB_Result for a successful "read", - TRUE for a successful "write", FALSE if an error - -$this->db->get_compiled_select() --------------------------------- +**$this->db->get_compiled_select()** Compiles the selection query just like **$this->db->get()** but does not *run* the query. This method simply returns the SQL query as a string. @@ -90,10 +89,7 @@ parameter. The reason for this outcome is because the query has not been executed using **$this->db->get()** which resets values or reset directly using **$this->db->reset_query()**. -:returns: The SQL select string - -$this->db->get_where() ----------------------- +**$this->db->get_where()** Identical to the above function except that it permits you to add a "where" clause in the second parameter, instead of using the db->where() @@ -105,11 +101,7 @@ Please read the about the where function below for more information. .. note:: get_where() was formerly known as getwhere(), which has been removed -:returns: DB_Result for a successful "read", - TRUE for a successful "write", FALSE if an error - -$this->db->select() -------------------- +**$this->db->select()** Permits you to write the SELECT portion of your query:: @@ -129,10 +121,7 @@ with backticks. This is useful if you need a compound select statement. $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); $query = $this->db->get('mytable'); -:returns: The query builder object - -$this->db->select_max() ------------------------ +**$this->db->select_max()** Writes a "SELECT MAX(field)" portion for your query. You can optionally include a second parameter to rename the resulting field. @@ -181,11 +170,7 @@ the resulting field. $this->db->select_sum('age'); $query = $this->db->get('members'); // Produces: SELECT SUM(age) as age FROM members -:returns: The query builder object - - -$this->db->from() ------------------ +**$this->db->from()** Permits you to write the FROM portion of your query:: @@ -196,10 +181,7 @@ Permits you to write the FROM portion of your query:: .. note:: As shown earlier, the FROM portion of your query can be specified in the $this->db->get() function, so use whichever method you prefer. -:returns: The query builder object - -$this->db->join() ------------------ +**$this->db->join()** Permits you to write the JOIN portion of your query:: @@ -223,14 +205,11 @@ outer, and right outer. $this->db->join('comments', 'comments.id = blogs.id', 'left'); // Produces: LEFT JOIN comments ON comments.id = blogs.id -:returns: The query builder object - ************************* Looking for Specific Data ************************* -$this->db->where() ------------------- +**$this->db->where()** This function enables you to set **WHERE** clauses using one of four methods: @@ -306,10 +285,7 @@ instances are joined by OR:: .. note:: or_where() was formerly known as orwhere(), which has been removed. -:returns: The query builder object - -$this->db->where_in() ---------------------- +**$this->db->where_in()** Generates a WHERE field IN ('item', 'item') SQL query joined with AND if appropriate @@ -332,10 +308,7 @@ appropriate $this->db->or_where_in('username', $names); // Produces: OR username IN ('Frank', 'Todd', 'James') -:returns: The query builder object - -$this->db->where_not_in() -------------------------- +**$this->db->where_not_in()** Generates a WHERE field NOT IN ('item', 'item') SQL query joined with AND if appropriate @@ -358,15 +331,11 @@ if appropriate $this->db->or_where_not_in('username', $names); // Produces: OR username NOT IN ('Frank', 'Todd', 'James') -:returns: The query builder object - - ************************ Looking for Similar Data ************************ -$this->db->like() ------------------ +**$this->db->like()** This method enables you to generate **LIKE** clauses, useful for doing searches. @@ -432,10 +401,7 @@ instances are joined by OR:: $this->db->or_not_like('body', 'match'); // WHERE `title` LIKE '%match% OR `body` NOT LIKE '%match%' ESCAPE '!' -:returns: The query builder object - -$this->db->group_by() ---------------------- +**$this->db->group_by()** Permits you to write the GROUP BY portion of your query:: @@ -448,10 +414,7 @@ You can also pass an array of multiple values as well:: .. note:: group_by() was formerly known as groupby(), which has been removed. -:returns: The query builder object - -$this->db->distinct() ---------------------- +**$this->db->distinct()** Adds the "DISTINCT" keyword to a query @@ -460,10 +423,7 @@ Adds the "DISTINCT" keyword to a query $this->db->distinct(); $this->db->get('table'); // Produces: SELECT DISTINCT * FROM table -:returns: The query builder object - -$this->db->having() -------------------- +**$this->db->having()** Permits you to write the HAVING portion of your query. There are 2 possible syntaxes, 1 argument or 2:: @@ -491,14 +451,11 @@ setting it to FALSE. Identical to having(), only separates multiple clauses with "OR". -:returns: The query builder object - **************** Ordering results **************** -$this->db->order_by() ---------------------- +**$this->db->order_by()** Lets you set an ORDER BY clause. @@ -542,14 +499,11 @@ be ignored, unless you specify a numeric seed value. .. note:: Random ordering is not currently supported in Oracle and will default to ASC instead. -:returns: The query builder object - **************************** Limiting or Counting Results **************************** -$this->db->limit() ------------------- +**$this->db->limit()** Lets you limit the number of rows you would like returned by the query:: @@ -561,10 +515,7 @@ The second parameter lets you set a result offset. $this->db->limit(10, 20); // Produces: LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) -:returns: The query builder object - -$this->db->count_all_results() ------------------------------- +**$this->db->count_all_results()** Permits you to determine the number of rows in a particular Active Record query. Queries will accept Query Builder restrictors such as @@ -575,18 +526,13 @@ where(), or_where(), like(), or_like(), etc. Example:: $this->db->from('my_table'); echo $this->db->count_all_results(); // Produces an integer, like 17 -:returns: Count of all the records returned by a query - -$this->db->count_all() ----------------------- +**$this->db->count_all()** Permits you to determine the number of rows in a particular table. Submit the table name in the first parameter. Example:: echo $this->db->count_all('my_table'); // Produces an integer, like 25 -:returns: Count of all the records in the specified table - ************** Query grouping ************** @@ -630,14 +576,11 @@ Starts a new group by adding an opening parenthesis to the WHERE clause of the q Ends the current group by adding an closing parenthesis to the WHERE clause of the query. -:returns: The query builder object - ************** Inserting Data ************** -$this->db->insert() -------------------- +**$this->db->insert()** Generates an insert string based on the data you supply, and runs the query. You can either pass an **array** or an **object** to the @@ -674,12 +617,9 @@ object. .. note:: All values are escaped automatically producing safer queries. -:returns: DB_Query on success, FALSE on failure - -$this->db->get_compiled_insert() --------------------------------- +**$this->db->get_compiled_insert()** -Compiles the insertion query just like `$this->db->insert()`_ but does not +Compiles the insertion query just like $this->db->insert() but does not *run* the query. This method simply returns the SQL query as a string. Example:: @@ -696,7 +636,7 @@ Example:: // Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') The second parameter enables you to set whether or not the query builder query -will be reset (by default it will be--just like `$this->db->insert()`_):: +will be reset (by default it will be--just like $this->db->insert()):: echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE); @@ -714,10 +654,7 @@ using `$this->db->insert()` which resets values or reset directly using .. note:: This method doesn't work for batched inserts. -:returns: The SQL insert string - -$this->db->insert_batch() -------------------------- +**$this->db->insert_batch()** Generates an insert string based on the data you supply, and runs the query. You can either pass an **array** or an **object** to the @@ -744,14 +681,11 @@ associative array of values. .. note:: All values are escaped automatically producing safer queries. -:returns: Count of the number of records inserted on success, FALSE on failure - ************* Updating Data ************* -$this->db->replace() --------------------- +**$this->db->replace()** This method executes a REPLACE statement, which is basically the SQL standard for (optional) DELETE + INSERT, using *PRIMARY* and *UNIQUE* @@ -779,10 +713,7 @@ will be deleted with our new row data replacing it. Usage of the ``set()`` method is also allowed and all fields are automatically escaped, just like with ``insert()``. -:returns: DB_query object on success, FALSE on failure - -$this->db->set() ----------------- +**$this->db->set()** This function enables you to set values for inserts or updates. @@ -840,10 +771,7 @@ Or an object:: $this->db->set($object); $this->db->insert('mytable'); -:returns: The query builder object - -$this->db->update() -------------------- +**$this->db->update()** Generates an update string and runs the query based on the data you supply. You can pass an **array** or an **object** to the function. Here @@ -889,10 +817,7 @@ Or as an array:: You may also use the $this->db->set() function described above when performing updates. -:returns: DB_query object on success, FALSE on failure - -$this->db->update_batch() -------------------------- +**$this->db->update_batch()** Generates an update string based on the data you supply, and runs the query. You can either pass an **array** or an **object** to the function. @@ -933,10 +858,7 @@ array of values, the third parameter is the where key. due to the very nature of how it works. Instead, ``update_batch()`` returns the number of rows affected. -:returns: Count of the number of records affected on success, FALSE on failure - -$this->db->get_compiled_update() --------------------------------- +**$this->db->get_compiled_update()** This works exactly the same way as ``$this->db->get_compiled_insert()`` except that it produces an UPDATE SQL string instead of an INSERT SQL string. @@ -945,14 +867,11 @@ For more information view documentation for `$this->db->get_compiled_insert()`. .. note:: This method doesn't work for batched updates. -:returns: The SQL update string - ************* Deleting Data ************* -$this->db->delete() -------------------- +**$this->db->delete()** Generates a delete SQL string and runs the query. @@ -985,21 +904,14 @@ delete data from more than 1 table. If you want to delete all data from a table, you can use the truncate() function, or empty_table(). -:returns: DB_Query on success, FALSE on failure - -$this->db->empty_table() ------------------------- +**$this->db->empty_table()** Generates a delete SQL string and runs the query.:: $this->db->empty_table('mytable'); // Produces: DELETE FROM mytable -:returns: DB_Query on success, FALSE on failure - - -$this->db->truncate() ---------------------- +**$this->db->truncate()** Generates a truncate SQL string and runs the query. @@ -1018,19 +930,12 @@ Generates a truncate SQL string and runs the query. .. note:: If the TRUNCATE command isn't available, truncate() will execute as "DELETE FROM table". -:returns: DB_Query on success, FALSE on failure - -$this->db->get_compiled_delete() --------------------------------- +**$this->db->get_compiled_delete()** This works exactly the same way as ``$this->db->get_compiled_insert()`` except that it produces a DELETE SQL string instead of an INSERT SQL string. -For more information view documentation for `$this->db->get_compiled_insert()`_. - -:returns: The SQL delete string - - +For more information view documentation for $this->db->get_compiled_insert(). *************** Method Chaining @@ -1074,8 +979,6 @@ This function can be called to stop caching. This function deletes all items from the Query Builder cache. -:returns: void - An example of caching --------------------- @@ -1105,8 +1008,7 @@ Here's a usage example:: Resetting Query Builder *********************** -$this->db->reset_query() ------------------------- +**$this->db->reset_query()** Resetting Query Builder allows you to start fresh with your query without executing it first using a method like $this->db->get() or $this->db->insert(). @@ -1135,6 +1037,4 @@ run the query:: .. note:: Double calls to ``get_compiled_select()`` while you're using the Query Builder Caching functionality and NOT resetting your queries will results in the cache being merged twice. That in turn will - i.e. if you're caching a ``select()`` - select the same field twice. - -:returns: void + i.e. if you're caching a ``select()`` - select the same field twice. \ No newline at end of file diff --git a/user_guide_src/source/database/query_builder_reference.rst b/user_guide_src/source/database/query_builder_reference.rst new file mode 100644 index 000000000..f20a1e70d --- /dev/null +++ b/user_guide_src/source/database/query_builder_reference.rst @@ -0,0 +1,23 @@ +################# +Query Builder API +################# + +.. note:: This page provides a complete API reference for the Query Builder + class. For information on how to use the class, see the + `Query Builder Class `_ page. + +*************** +Class Reference +*************** + +.. class:: CI_DB_query_builder + + .. method:: count_all_results($table = '') + + :param string $table: Table name to query + :returns: Number of rows in the query result + :rtype: int + + Generates a platform-specific query string that counts + all records returned by an Query Builder query. + -- cgit v1.2.3-24-g4f1b From 82f5d7cf02bab8f76914f34dfc49dfedb245923e Mon Sep 17 00:00:00 2001 From: James L Parry Date: Sat, 6 Dec 2014 03:02:51 -0800 Subject: User Guide - query builder Fleshing out the API reference Signed-off-by:James L Parry --- .../source/database/query_builder_reference.rst | 217 +++++++++++++++++++++ 1 file changed, 217 insertions(+) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/query_builder_reference.rst b/user_guide_src/source/database/query_builder_reference.rst index f20a1e70d..7c379ae84 100644 --- a/user_guide_src/source/database/query_builder_reference.rst +++ b/user_guide_src/source/database/query_builder_reference.rst @@ -21,3 +21,220 @@ Class Reference Generates a platform-specific query string that counts all records returned by an Query Builder query. + .. method:: dbprefix($table = '') + + :param string $table: The table name to work with + :returns: The modified table name + :rtype: string + + Prepends a database prefix if one exists in configuration + + .. method:: delete($table = '', $where = '', $limit = NULL, $reset_data = TRUE) + + :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 + + Compiles a delete string and runs the query + + .. method:: distinct($val = TRUE) + + :param boolean $val: Desired value of the "distinct" flag + :returns: DB_query_driver instance + :rtype: object + + Sets a flag which tells the query string compiler to add DISTINCT + + .. method:: empty_table($table = '') + + :param string $table: Name of table to empty + :returns: DB_driver instance + :rtype: object + + Compiles a delete string and runs "DELETE FROM table" + + .. method:: flush_cache() + + :rtype: void + + Empties the QB cache + + .. method:: from($from) + + :param mixed $from: Can be a string or array + :returns: DB_query_builder instance + :rtype: object + + Generates the FROM portion of the 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 + + .. 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 a delete query string and returns the sql + + .. method:: get_compiled_insert($table = '', $reset = TRUE) + + :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 + + Compiles an insert query string and returns the sql + + .. method:: get_compiled_select($table = '', $reset = TRUE) + + :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 + + Compiles a select query string and returns the sql + + .. method:: get_compiled_update($table = '', $reset = TRUE) + + :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 + + Compiles an update query string and returns the sql + + .. method:: get_where($table = '', $where = NULL, $limit = NULL, $offset = NULL) + + :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 + + Allows the where clause, limit and offset to be added directly + + .. method:: group_by($by, $escape = NULL) + + :param mixed $by: Field(s) to group by; string or array + :returns: DB_query_builder instance + :rtype: object + + Adds a GROUPBY clause to the query + + .. method:: group_end() + + :returns: DB_query_builder instance + :rtype: object + + Ends a query group + + .. method:: group_start($not = '', $type = 'AND ') + + :param string $not: (Internal use only) + :param string $type: (Internal use only) + :returns: DB_query_builder instance + :rtype: object + + Starts a query group. + + .. method:: having($key, $value = NULL, $escape = NULL) + + :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 + + Separates multiple calls with 'AND'. + + .. method:: insert($table = '', $set = NULL, $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 + + Compiles an insert string and runs the query + + .. method:: insert_batch($table = '', $set = NULL, $escape = NULL) + + :param string $table: The table to insert data into + :param array $set: An associative array of insert values + :param boolean $escape: Whether to escape values and identifiers + :returns: Number of rows inserted or FALSE on failure + :rtype: mixed + + Compiles batch insert strings and runs the queries + + .. method:: join($table, $cond, $type = '', $escape = NULL) + + :param string $table: Name of the table being joined + :param string $cond: The JOIN condition + :param string $type: The JOIN type + :param boolean $escape: Whether to escape values and identifiers + :returns: DB_query_builder instance + :rtype: object + + Generates the JOIN portion of the query + + .. method:: like($field, $match = '', $side = 'both', $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 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'. + + .. method:: limit($value, $offset = FALSE) + + :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 + :returns: DB_query_builder instance + :rtype: object + + Specify a limit and offset for the query + + .. method:: x + + :param string $x: x + :returns: x + :rtype: x + + x + + .. method:: x + + :param string $x: x + :returns: x + :rtype: x + + x + + .. method:: x + + :param string $x: x + :returns: x + :rtype: x + + x + -- cgit v1.2.3-24-g4f1b From 4103d0c5f8edf17e5698fb3eebec12396e714878 Mon Sep 17 00:00:00 2001 From: James L Parry Date: Sat, 6 Dec 2014 08:51:06 -0800 Subject: User Guide - query builder Fleshing out the API reference Signed-off-by:James L Parry --- .../source/database/query_builder_reference.rst | 297 +++++++++++++++++++-- 1 file changed, 282 insertions(+), 15 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/query_builder_reference.rst b/user_guide_src/source/database/query_builder_reference.rst index 7c379ae84..21b15431a 100644 --- a/user_guide_src/source/database/query_builder_reference.rst +++ b/user_guide_src/source/database/query_builder_reference.rst @@ -214,27 +214,294 @@ Class Reference Specify a limit and offset for the query - .. method:: x + .. method:: not_group_start() - :param string $x: x - :returns: x - :rtype: x + :returns: DB_query_builder instance + :rtype: object + + Starts a query group, but NOTs the group + + .. method:: not_like($field, $match = '', $side = 'both', $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 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'. + + .. method:: offset($offset) + + :param int $offset: Number of rows to skip in a query + :returns: DB_query_builder instance + :rtype: object + + Sets the OFFSET value + + .. method:: or_group_start() + + :returns: DB_query_builder instance + :rtype: object + + Starts a query group, but ORs the group + + .. method:: or_having($key, $value = NULL, $escape = NULL) + + :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 + + Separates multiple calls with 'OR'. + + .. method:: or_like($field, $match = '', $side = 'both', $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 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 'OR'. + + .. method:: or_not_group_start() + + :returns: DB_query_builder instance + :rtype: object + + Starts a query group, but OR NOTs the group + + .. method:: or_not_like($field, $match = '', $side = 'both', $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 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 'OR'. + + .. method:: or_where($key, $value = NULL, $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 + + Generates the WHERE portion of the query. + Separates multiple calls with 'OR'. + + .. method:: or_where_in($key = NULL, $values = NULL, $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 + + Generates a WHERE field IN('item', 'item') SQL query, + joined with 'OR' if appropriate. + + .. method:: or_where_not_in($key = NULL, $values = NULL, $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 + + Generates a WHERE field NOT IN('item', 'item') SQL query, + joined with 'OR' if appropriate. + + .. method:: order_by($orderby, $direction = '', $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 + + Generates an ORDER BY clause in the SQL query + + .. method:: replace($table = '', $set = NULL) + + :param string $table: The table to query + :param array $set: Associative array of insert values + :returns: DB_result, FALSE on failure + :rtype: mixed + + Compiles an replace into string and runs the query + + .. method:: reset_query() + + :rtype: void + + Publicly-visible method to reset the QB values. + + .. method:: select($select = '*', $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 + + Generates the SELECT portion of the query + + .. method:: select_avg($select = '', $alias = '') + + :param string $select: Field to compute the average of + :param string $alias: Alias for the resulting value + :returns: DB_query_builder instance + :rtype: object + + Generates a SELECT AVG(field) portion of a query + + .. method:: select_max($select = '', $alias = '') + + :param string $select: Field to compute the maximum of + :param string $alias: Alias for the resulting value + :returns: DB_query_builder instance + :rtype: object + + Generates a SELECT MAX(field) portion of a query + + .. method:: select_min($select = '', $alias = '') + + :param string $select: Field to compute the minimum of + :param string $alias: Alias for the resulting value + :returns: DB_query_builder instance + :rtype: object + + Generates a SELECT MIN(field) portion of a query + + .. method:: select_sum($select = '', $alias = '') + + :param string $select: Field to compute the sum of + :param string $alias: Alias for the resulting value + :returns: DB_query_builder instance + :rtype: object + + Generates a SELECT SUM(field) portion of a query + + .. method:: set($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 + + Allows key/value pairs to be set for inserting or updating + + .. method:: set_dbprefix($prefix = '') + + :param string $prefix: The new prefix to use + :returns: The DB prefix in use + :rtype: string + + Set's the DB Prefix to something new without needing to reconnect + + .. method:: set_insert_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 - x + The "set_insert_batch" function. Allows key/value pairs to be set for batch inserts - .. method:: x + .. method:: set_update_batch($key, $value = '', $escape = NULL) - :param string $x: x - :returns: x - :rtype: x + :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 + + The "set_batch_batch" function. Allows key/value pairs to be set for batch batch + + .. method:: start_cache() + + :rtype: void + + Start DB caching + + .. method:: stop_cache() + + :rtype: void - x + Stop DB caching + + .. method:: truncate($table = '') + + :param string $table: Name fo the table to truncate + :returns: DB_result + :rtype: object + + Compiles a truncate string and runs the query. + If the database does not support the truncate() command + This function maps to "DELETE FROM table" + + .. method:: update($table = '', $set = NULL, $where = NULL, $limit = NULL) + + :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:: x + Compiles an update string and runs the query. - :param string $x: x - :returns: x - :rtype: x + .. method:: update_batch($table = '', $set = NULL, $value = NULL) - x + :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 + + Compiles an update string and runs the query. + + .. method:: where($key, $value = NULL, $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 + + Generates the WHERE portion of the query. + Separates multiple calls with 'AND'. + + .. 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 + + Generates a WHERE field IN('item', 'item') SQL query, + joined with 'AND' if appropriate. + + .. method:: where_not_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 + Generates a WHERE field NOT IN('item', 'item') SQL query, + joined with 'AND' if appropriate. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 8b875cedfa63a06420b9908c3266daddf3a6a706 Mon Sep 17 00:00:00 2001 From: James L Parry Date: Mon, 8 Dec 2014 03:00:31 -0800 Subject: User Guide - query results Removed attributes from class reference. Added square brackets for optional parameters. Signed-off-by:James L Parry --- user_guide_src/source/database/results.rst | 54 ++++++------------------------ 1 file changed, 11 insertions(+), 43 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 33b19270e..044360ebb 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -250,38 +250,6 @@ Class Reference .. class:: CI_DB_result - .. attribute:: $conn_id - - Connection ID - - .. attribute:: $result_id - - Result ID - - .. attribute:: $result_array = array() - - Result Array - - .. attribute:: $result_object = array() - - Result Object - - .. attribute:: $custom_result_object = array() - - Custom Result Object - - .. attribute:: $current_row = 0 - - Current Row index - - .. attribute:: $num_rows - - Number of rows - - .. attribute:: $row_data - - Row data - .. method:: custom_result_object($class_name) :param string $class_name: Class name for the results @@ -300,7 +268,7 @@ Class Reference Return a specific row from the query results as an object of the specified class. - .. method:: data_seek($n = 0) + .. method:: data_seek([$n = 0]) :param int $n: Index of the results row to be returned next :returns: TRUE on success, FALSE otherwise @@ -316,7 +284,7 @@ Class Reference Generates an array of objects containing field meta-data. - .. method:: first_row($type = 'object') + .. method:: first_row([$type = 'object']) :param string $type: Type of result requested - array, object, or class name :returns: First row of result set @@ -332,7 +300,7 @@ Class Reference Free the result. Usage: see `Result Helper Methods`_. - .. method:: last_row($type = 'object') + .. method:: last_row([$type = 'object']) :param string $type: Type of result requested - array, object, or class name :returns: Last row of result set @@ -348,7 +316,7 @@ Class Reference Fetch Field Names - .. method:: next_row($type = 'object') + .. method:: next_row([$type = 'object']) :param string $type: Type of result requested - array, object, or class name :returns: "Next" row of result set, NULL if there isn't one @@ -373,7 +341,7 @@ Class Reference Number of rows in the result set. Usage: see `Result Helper Methods`_. - .. method:: previous_row($type = 'object') + .. method:: previous_row([$type = 'object']) :param string $type: Type of result requested - array, object, or class name :returns: "Previous" row of result set, NULL if there isn't one @@ -382,7 +350,7 @@ Class Reference Returns the "previous" row, as an array, generic object, or object of a specific class - .. method:: result($type = 'object') + .. method:: result([$type = 'object']) :param string $type: Type of result requested - array, object, or class name :returns: Query results as the specified type @@ -409,7 +377,7 @@ Class Reference Returns the query results as an array of rows, where each row is an object - .. method:: row($n = 0, $type = 'object') + .. method:: row([$n = 0[, $type = 'object']]) :param integer $n: Index of the query results row to be returned :param string $type: Type of result requested - array, object, or class name @@ -420,7 +388,7 @@ Class Reference custom_row_object. Usage: see `Result Rows`_. - .. method:: row_array($n = 0) + .. method:: row_array([$n = 0]) :param integer $n: Index of the query results row to be returned :returns: Requested row of result set @@ -429,7 +397,7 @@ Class Reference Returns requested result row as an associative array. Usage: see `Result Rows`_. - .. method:: row_object($n = 0) + .. method:: row_object([$n = 0]) :param integer $n: Index of the query results row to be returned :returns: Requested row of result set @@ -437,7 +405,7 @@ Class Reference Returns requested result row as an object - .. method:: set_row($key, $value = NULL) + .. method:: set_row($key[, $value = NULL]) :param mixed $key: Column index or array of key/value pairs :param mixed $value: Result to assign to a column if the key is an index @@ -445,7 +413,7 @@ Class Reference Assigns an item into a particular column slot - .. method:: unbuffered_row($type = 'object') + .. method:: unbuffered_row([$type = 'object']) :param string $type: Type of result requested - array, object, or class name :returns: Requested row of result set -- cgit v1.2.3-24-g4f1b From 7381711c721eee5bcf4fa20d7d62c96e5e44390e Mon Sep 17 00:00:00 2001 From: James L Parry Date: Mon, 8 Dec 2014 03:09:29 -0800 Subject: User Guide - query builder Integrated API reference with the regular query builder page. Added square brackets for optional parameters. Signed-off-by:James L Parry --- user_guide_src/source/database/index.rst | 1 - user_guide_src/source/database/query_builder.rst | 506 +++++++++++++++++++- .../source/database/query_builder_reference.rst | 507 --------------------- 3 files changed, 501 insertions(+), 513 deletions(-) delete mode 100644 user_guide_src/source/database/query_builder_reference.rst (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index 14a871aed..4612daf9d 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -16,7 +16,6 @@ patterns. The database functions offer clear, simple syntax. Generating Query Results Query Helper Functions Query Builder Class - Query Builder API Transactions Getting MetaData Custom Function Calls diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst index 701c489d6..577248b32 100644 --- a/user_guide_src/source/database/query_builder.rst +++ b/user_guide_src/source/database/query_builder.rst @@ -23,10 +23,6 @@ system. :local: :depth: 1 -.. note:: This page describes how to use the Query Builder class. - API reference information is found on the - `Query Builder API `_ page. - ************** Selecting Data ************** @@ -1037,4 +1033,504 @@ run the query:: .. note:: Double calls to ``get_compiled_select()`` while you're using the Query Builder Caching functionality and NOT resetting your queries will results in the cache being merged twice. That in turn will - i.e. if you're caching a ``select()`` - select the same field twice. \ No newline at end of file + i.e. if you're caching a ``select()`` - select the same field twice. + +*************** +Class Reference +*************** + +.. class:: CI_DB_query_builder + + .. method:: count_all_results([$table = '']) + + :param string $table: Table name to query + :returns: Number of rows in the query result + :rtype: int + + Generates a platform-specific query string that counts + all records returned by an Query Builder query. + + .. method:: dbprefix([$table = '']) + + :param string $table: The table name to work with + :returns: The modified table name + :rtype: string + + Prepends a database prefix if one exists in configuration + + .. method:: delete([$table = ''[, $where = ''[, $limit = NULL[, $reset_data = TRUE]]]]) + + :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 + + Compiles a delete string and runs the query + + .. method:: distinct([$val = TRUE]) + + :param boolean $val: Desired value of the "distinct" flag + :returns: DB_query_driver instance + :rtype: object + + Sets a flag which tells the query string compiler to add DISTINCT + + .. method:: empty_table([$table = '']) + + :param string $table: Name of table to empty + :returns: DB_driver instance + :rtype: object + + Compiles a delete string and runs "DELETE FROM table" + + .. method:: flush_cache() + + :rtype: void + + Empties the QB cache + + .. method:: from($from) + + :param mixed $from: Can be a string or array + :returns: DB_query_builder instance + :rtype: object + + Generates the FROM portion of the 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 + + .. 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 a delete query string and returns the sql + + .. method:: get_compiled_insert([$table = ''[, $reset = TRUE]]) + + :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 + + Compiles an insert query string and returns the sql + + .. method:: get_compiled_select([$table = ''[, $reset = TRUE]]) + + :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 + + Compiles a select query string and returns the sql + + .. method:: get_compiled_update([$table = ''[, $reset = TRUE]]) + + :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 + + Compiles an update query string and returns the sql + + .. method:: get_where([$table = ''[, $where = NULL[, $limit = NULL[, $offset = NULL]]]]) + + :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 + + Allows the where clause, limit and offset to be added directly + + .. method:: group_by($by[, $escape = NULL]) + + :param mixed $by: Field(s) to group by; string or array + :returns: DB_query_builder instance + :rtype: object + + Adds a GROUPBY clause to the query + + .. method:: group_end() + + :returns: DB_query_builder instance + :rtype: object + + Ends a query group + + .. method:: group_start([$not = ''[, $type = 'AND ']]) + + :param string $not: (Internal use only) + :param string $type: (Internal use only) + :returns: DB_query_builder instance + :rtype: object + + Starts a query group. + + .. method:: having($key[, $value = NULL[, $escape = NULL]]) + + :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 + + Separates multiple calls with 'AND'. + + .. method:: insert([$table = ''[, $set = NULL[, $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 + + Compiles an insert string and runs the query + + .. method:: insert_batch([$table = ''[, $set = NULL[, $escape = NULL]]]) + + :param string $table: The table to insert data into + :param array $set: An associative array of insert values + :param boolean $escape: Whether to escape values and identifiers + :returns: Number of rows inserted or FALSE on failure + :rtype: mixed + + Compiles batch insert strings and runs the queries + + .. method:: join($table, $cond[, $type = ''[, $escape = NULL]]) + + :param string $table: Name of the table being joined + :param string $cond: The JOIN condition + :param string $type: The JOIN type + :param boolean $escape: Whether to escape values and identifiers + :returns: DB_query_builder instance + :rtype: object + + Generates the JOIN portion of the query + + .. method:: like($field[, $match = ''[, $side = 'both'[, $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 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'. + + .. method:: limit($value[, $offset = FALSE]) + + :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 + :returns: DB_query_builder instance + :rtype: object + + Specify a limit and offset for the query + + .. method:: not_group_start() + + :returns: DB_query_builder instance + :rtype: object + + Starts a query group, but NOTs the group + + .. method:: not_like($field[, $match = ''[, $side = 'both'[, $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 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'. + + .. method:: offset($offset) + + :param int $offset: Number of rows to skip in a query + :returns: DB_query_builder instance + :rtype: object + + Sets the OFFSET value + + .. method:: or_group_start() + + :returns: DB_query_builder instance + :rtype: object + + Starts a query group, but ORs the group + + .. method:: or_having($key[, $value = NULL[, $escape = NULL]]) + + :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 + + Separates multiple calls with 'OR'. + + .. method:: or_like($field[, $match = ''[, $side = 'both'[, $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 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 'OR'. + + .. method:: or_not_group_start() + + :returns: DB_query_builder instance + :rtype: object + + Starts a query group, but OR NOTs the group + + .. method:: or_not_like($field[, $match = ''[, $side = 'both'[, $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 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 'OR'. + + .. method:: or_where($key[, $value = NULL[, $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 + + Generates the WHERE portion of the query. + Separates multiple calls with 'OR'. + + .. method:: or_where_in([$key = NULL[, $values = NULL[, $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 + + Generates a WHERE field IN('item', 'item') SQL query, + joined with 'OR' if appropriate. + + .. method:: or_where_not_in([$key = NULL[, $values = NULL[, $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 + + Generates a WHERE field NOT IN('item', 'item') SQL query, + joined with 'OR' if appropriate. + + .. method:: order_by($orderby[, $direction = ''[, $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 + + Generates an ORDER BY clause in the SQL query + + .. method:: replace([$table = ''[, $set = NULL]]) + + :param string $table: The table to query + :param array $set: Associative array of insert values + :returns: DB_result, FALSE on failure + :rtype: mixed + + Compiles an replace into string and runs the query + + .. method:: reset_query() + + :rtype: void + + Publicly-visible method to reset the QB values. + + .. method:: select([$select = '*'[, $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 + + Generates the SELECT portion of the query + + .. method:: select_avg([$select = ''[, $alias = '']]) + + :param string $select: Field to compute the average of + :param string $alias: Alias for the resulting value + :returns: DB_query_builder instance + :rtype: object + + Generates a SELECT AVG(field) portion of a query + + .. method:: select_max([$select = ''[, $alias = '']]) + + :param string $select: Field to compute the maximum of + :param string $alias: Alias for the resulting value + :returns: DB_query_builder instance + :rtype: object + + Generates a SELECT MAX(field) portion of a query + + .. method:: select_min([$select = ''[, $alias = '']]) + + :param string $select: Field to compute the minimum of + :param string $alias: Alias for the resulting value + :returns: DB_query_builder instance + :rtype: object + + Generates a SELECT MIN(field) portion of a query + + .. method:: select_sum([$select = ''[, $alias = '']]) + + :param string $select: Field to compute the sum of + :param string $alias: Alias for the resulting value + :returns: DB_query_builder instance + :rtype: object + + Generates a SELECT SUM(field) portion of a query + + .. method:: set($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 + + Allows key/value pairs to be set for inserting or updating + + .. method:: set_dbprefix([$prefix = '']) + + :param string $prefix: The new prefix to use + :returns: The DB prefix in use + :rtype: string + + Set's the DB Prefix to something new without needing to reconnect + + .. method:: set_insert_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 + + The "set_insert_batch" function. Allows key/value pairs to be set for batch inserts + + .. 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 + + The "set_batch_batch" function. Allows key/value pairs to be set for batch batch + + .. method:: start_cache() + + :rtype: void + + Start DB caching + + .. method:: stop_cache() + + :rtype: void + + Stop DB caching + + .. method:: truncate([$table = '']) + + :param string $table: Name fo the table to truncate + :returns: DB_result + :rtype: object + + Compiles a truncate string and runs the query. + If the database does not support the truncate() command + This function maps to "DELETE FROM table" + + .. method:: update([$table = ''[, $set = NULL[, $where = NULL[, $limit = NULL]]]]) + + :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 + + Compiles an update string and runs the query. + + .. method:: update_batch([$table = ''[, $set = NULL[, $value = NULL]]]) + + :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 + + Compiles an update string and runs the query. + + .. method:: where($key[, $value = NULL[, $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 + + Generates the WHERE portion of the query. + Separates multiple calls with 'AND'. + + .. 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 + + Generates a WHERE field IN('item', 'item') SQL query, + joined with 'AND' if appropriate. + + .. method:: where_not_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 + + Generates a WHERE field NOT IN('item', 'item') SQL query, + joined with 'AND' if appropriate. \ No newline at end of file diff --git a/user_guide_src/source/database/query_builder_reference.rst b/user_guide_src/source/database/query_builder_reference.rst deleted file mode 100644 index 21b15431a..000000000 --- a/user_guide_src/source/database/query_builder_reference.rst +++ /dev/null @@ -1,507 +0,0 @@ -################# -Query Builder API -################# - -.. note:: This page provides a complete API reference for the Query Builder - class. For information on how to use the class, see the - `Query Builder Class `_ page. - -*************** -Class Reference -*************** - -.. class:: CI_DB_query_builder - - .. method:: count_all_results($table = '') - - :param string $table: Table name to query - :returns: Number of rows in the query result - :rtype: int - - Generates a platform-specific query string that counts - all records returned by an Query Builder query. - - .. method:: dbprefix($table = '') - - :param string $table: The table name to work with - :returns: The modified table name - :rtype: string - - Prepends a database prefix if one exists in configuration - - .. method:: delete($table = '', $where = '', $limit = NULL, $reset_data = TRUE) - - :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 - - Compiles a delete string and runs the query - - .. method:: distinct($val = TRUE) - - :param boolean $val: Desired value of the "distinct" flag - :returns: DB_query_driver instance - :rtype: object - - Sets a flag which tells the query string compiler to add DISTINCT - - .. method:: empty_table($table = '') - - :param string $table: Name of table to empty - :returns: DB_driver instance - :rtype: object - - Compiles a delete string and runs "DELETE FROM table" - - .. method:: flush_cache() - - :rtype: void - - Empties the QB cache - - .. method:: from($from) - - :param mixed $from: Can be a string or array - :returns: DB_query_builder instance - :rtype: object - - Generates the FROM portion of the 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 - - .. 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 a delete query string and returns the sql - - .. method:: get_compiled_insert($table = '', $reset = TRUE) - - :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 - - Compiles an insert query string and returns the sql - - .. method:: get_compiled_select($table = '', $reset = TRUE) - - :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 - - Compiles a select query string and returns the sql - - .. method:: get_compiled_update($table = '', $reset = TRUE) - - :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 - - Compiles an update query string and returns the sql - - .. method:: get_where($table = '', $where = NULL, $limit = NULL, $offset = NULL) - - :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 - - Allows the where clause, limit and offset to be added directly - - .. method:: group_by($by, $escape = NULL) - - :param mixed $by: Field(s) to group by; string or array - :returns: DB_query_builder instance - :rtype: object - - Adds a GROUPBY clause to the query - - .. method:: group_end() - - :returns: DB_query_builder instance - :rtype: object - - Ends a query group - - .. method:: group_start($not = '', $type = 'AND ') - - :param string $not: (Internal use only) - :param string $type: (Internal use only) - :returns: DB_query_builder instance - :rtype: object - - Starts a query group. - - .. method:: having($key, $value = NULL, $escape = NULL) - - :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 - - Separates multiple calls with 'AND'. - - .. method:: insert($table = '', $set = NULL, $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 - - Compiles an insert string and runs the query - - .. method:: insert_batch($table = '', $set = NULL, $escape = NULL) - - :param string $table: The table to insert data into - :param array $set: An associative array of insert values - :param boolean $escape: Whether to escape values and identifiers - :returns: Number of rows inserted or FALSE on failure - :rtype: mixed - - Compiles batch insert strings and runs the queries - - .. method:: join($table, $cond, $type = '', $escape = NULL) - - :param string $table: Name of the table being joined - :param string $cond: The JOIN condition - :param string $type: The JOIN type - :param boolean $escape: Whether to escape values and identifiers - :returns: DB_query_builder instance - :rtype: object - - Generates the JOIN portion of the query - - .. method:: like($field, $match = '', $side = 'both', $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 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'. - - .. method:: limit($value, $offset = FALSE) - - :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 - :returns: DB_query_builder instance - :rtype: object - - Specify a limit and offset for the query - - .. method:: not_group_start() - - :returns: DB_query_builder instance - :rtype: object - - Starts a query group, but NOTs the group - - .. method:: not_like($field, $match = '', $side = 'both', $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 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'. - - .. method:: offset($offset) - - :param int $offset: Number of rows to skip in a query - :returns: DB_query_builder instance - :rtype: object - - Sets the OFFSET value - - .. method:: or_group_start() - - :returns: DB_query_builder instance - :rtype: object - - Starts a query group, but ORs the group - - .. method:: or_having($key, $value = NULL, $escape = NULL) - - :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 - - Separates multiple calls with 'OR'. - - .. method:: or_like($field, $match = '', $side = 'both', $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 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 'OR'. - - .. method:: or_not_group_start() - - :returns: DB_query_builder instance - :rtype: object - - Starts a query group, but OR NOTs the group - - .. method:: or_not_like($field, $match = '', $side = 'both', $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 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 'OR'. - - .. method:: or_where($key, $value = NULL, $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 - - Generates the WHERE portion of the query. - Separates multiple calls with 'OR'. - - .. method:: or_where_in($key = NULL, $values = NULL, $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 - - Generates a WHERE field IN('item', 'item') SQL query, - joined with 'OR' if appropriate. - - .. method:: or_where_not_in($key = NULL, $values = NULL, $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 - - Generates a WHERE field NOT IN('item', 'item') SQL query, - joined with 'OR' if appropriate. - - .. method:: order_by($orderby, $direction = '', $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 - - Generates an ORDER BY clause in the SQL query - - .. method:: replace($table = '', $set = NULL) - - :param string $table: The table to query - :param array $set: Associative array of insert values - :returns: DB_result, FALSE on failure - :rtype: mixed - - Compiles an replace into string and runs the query - - .. method:: reset_query() - - :rtype: void - - Publicly-visible method to reset the QB values. - - .. method:: select($select = '*', $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 - - Generates the SELECT portion of the query - - .. method:: select_avg($select = '', $alias = '') - - :param string $select: Field to compute the average of - :param string $alias: Alias for the resulting value - :returns: DB_query_builder instance - :rtype: object - - Generates a SELECT AVG(field) portion of a query - - .. method:: select_max($select = '', $alias = '') - - :param string $select: Field to compute the maximum of - :param string $alias: Alias for the resulting value - :returns: DB_query_builder instance - :rtype: object - - Generates a SELECT MAX(field) portion of a query - - .. method:: select_min($select = '', $alias = '') - - :param string $select: Field to compute the minimum of - :param string $alias: Alias for the resulting value - :returns: DB_query_builder instance - :rtype: object - - Generates a SELECT MIN(field) portion of a query - - .. method:: select_sum($select = '', $alias = '') - - :param string $select: Field to compute the sum of - :param string $alias: Alias for the resulting value - :returns: DB_query_builder instance - :rtype: object - - Generates a SELECT SUM(field) portion of a query - - .. method:: set($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 - - Allows key/value pairs to be set for inserting or updating - - .. method:: set_dbprefix($prefix = '') - - :param string $prefix: The new prefix to use - :returns: The DB prefix in use - :rtype: string - - Set's the DB Prefix to something new without needing to reconnect - - .. method:: set_insert_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 - - The "set_insert_batch" function. Allows key/value pairs to be set for batch inserts - - .. 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 - - The "set_batch_batch" function. Allows key/value pairs to be set for batch batch - - .. method:: start_cache() - - :rtype: void - - Start DB caching - - .. method:: stop_cache() - - :rtype: void - - Stop DB caching - - .. method:: truncate($table = '') - - :param string $table: Name fo the table to truncate - :returns: DB_result - :rtype: object - - Compiles a truncate string and runs the query. - If the database does not support the truncate() command - This function maps to "DELETE FROM table" - - .. method:: update($table = '', $set = NULL, $where = NULL, $limit = NULL) - - :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 - - Compiles an update string and runs the query. - - .. method:: update_batch($table = '', $set = NULL, $value = NULL) - - :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 - - Compiles an update string and runs the query. - - .. method:: where($key, $value = NULL, $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 - - Generates the WHERE portion of the query. - Separates multiple calls with 'AND'. - - .. 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 - - Generates a WHERE field IN('item', 'item') SQL query, - joined with 'AND' if appropriate. - - .. method:: where_not_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 - - Generates a WHERE field NOT IN('item', 'item') SQL query, - joined with 'AND' if appropriate. \ No newline at end of file -- cgit v1.2.3-24-g4f1b 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/database') 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 From ab0034bb8a72fc397609ff541182a1819580d761 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Thu, 11 Dec 2014 18:31:51 +0200 Subject: [ci skip] Update DB result docs Related: #3395 --- user_guide_src/source/database/results.rst | 276 +++++++++++++++-------------- 1 file changed, 143 insertions(+), 133 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 044360ebb..ae81998c7 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -12,8 +12,7 @@ There are several ways to generate query results: Result Arrays ************* -result() -======== +**result()** This method returns the query result as an array of **objects**, or **an empty array** on failure. Typically you'll use this in a foreach @@ -28,7 +27,7 @@ loop, like this:: echo $row->body; } -The above method is an alias of result_object(). +The above method is an alias of ``result_object()``. If you run queries that might **not** produce a result, you are encouraged to test the result first:: @@ -54,12 +53,11 @@ instantiate for each result object (note: this class must be loaded) foreach ($query->result('User') as $user) { - echo $user->name; // call attributes - echo $user->reverse_name(); // or methods defined on the 'User' class + echo $user->name; // access attributes + echo $user->reverse_name(); // or methods defined on the 'User' class } -result_array() -=============== +**result_array()** This method returns the query result as a pure array, or an empty array when no result is produced. Typically you'll use this in a foreach @@ -78,8 +76,7 @@ loop, like this:: Result Rows *********** -row() -===== +**row()** This method returns a single result row. If your query has more than one row, it returns only the first row. The result is returned as an @@ -107,13 +104,12 @@ to instantiate the row with:: $query = $this->db->query("SELECT * FROM users LIMIT 1;"); $query->row(0, 'User'); - echo $row->name; // call attributes + echo $row->name; // access attributes echo $row->reverse_name(); // or methods defined on the 'User' class -row_array() -=========== +**row_array()** -Identical to the above row() method, except it returns an array. +Identical to the above ``row()`` method, except it returns an array. Example:: $query = $this->db->query("YOUR QUERY"); @@ -148,11 +144,11 @@ parameter: | **$row = $query->next_row('array')** | **$row = $query->previous_row('array')** -.. note:: all the methods above will load the whole result into memory - (prefetching) use unbuffered_row() for processing large result sets. +.. note:: All the methods above will load the whole result into memory + (prefetching). Use ``unbuffered_row()`` for processing large + result sets. -unbuffered_row() -================ +**unbuffered_row()** This method returns a single result row without prefetching the whole result in memory as ``row()`` does. If your query has more than one row, @@ -180,7 +176,7 @@ the returned value's type:: Result Helper Methods ********************* -**$query->num_rows()** +**num_rows()** The number of rows returned by the query. Note: In this example, $query is the variable that the query result object is assigned to:: @@ -189,13 +185,12 @@ is the variable that the query result object is assigned to:: echo $query->num_rows(); -.. note:: - Not all database drivers have a native way of getting the total +.. note:: Not all database drivers have a native way of getting the total number of rows for a result set. When this is the case, all of - the data is prefetched and count() is manually called on the - resulting array in order to achieve the same methodality. + the data is prefetched and ``count()`` is manually called on the + resulting array in order to achieve the same result. -**$query->num_fields()** +**num_fields()** The number of FIELDS (columns) returned by the query. Make sure to call the method using your query result object:: @@ -204,13 +199,14 @@ the method using your query result object:: echo $query->num_fields(); -**$query->free_result()** +**free_result()** It frees the memory associated with the result and deletes the result resource ID. Normally PHP frees its memory automatically at the end of script execution. However, if you are running a lot of queries in a particular script you might want to free the result after each query -result has been generated in order to cut down on memory consumptions. +result has been generated in order to cut down on memory consumption. + Example:: $query = $this->db->query('SELECT title FROM my_table'); @@ -219,6 +215,7 @@ Example:: { echo $row->title; } + $query->free_result(); // The $query result object will no longer be available $query2 = $this->db->query('SELECT name FROM some_table'); @@ -250,175 +247,188 @@ Class Reference .. class:: CI_DB_result - .. method:: custom_result_object($class_name) - - :param string $class_name: Class name for the results - :returns: Array of objects of type $class_name - :rtype: array of $class_name + .. method:: result([$type = 'object']) - Return the query results as an array of the specified class. + :param string $type: Type of requested results - array, object, or class name + :returns: Array containing the fetched rows + :rtype: array - .. method:: custom_row_object($n, $type) + A wrapper for the ``result_array()``, ``result_object()`` + and ``custom_result_object()`` methods. - :param int $n: Index of the results row to return - :param string $class_name: Class name for the results - :returns: Object of type $type - :rtype: $type + Usage: see `Result Arrays`_. - Return a specific row from the query results as an object of - the specified class. + .. method:: result_array() - .. method:: data_seek([$n = 0]) + :returns: Array containing the fetched rows + :rtype: array - :param int $n: Index of the results row to be returned next - :returns: TRUE on success, FALSE otherwise - :rtype: bool + Returns the query results as an array of rows, where each + row is itself an associative array. - Moves the internal results row pointer to the desired offset. - Usage: see `Result Helper Methods`_. + Usage: see `Result Arrays`_. - .. method:: field_data() + .. method:: result_object() - :returns: Array of objects containing field meta-data. + :returns: Array containing the fetched rows :rtype: array - Generates an array of objects containing field meta-data. + Returns the query results as an array of rows, where each + row is an object of type ``stdClass``. - .. method:: first_row([$type = 'object']) + Usage: see `Result Arrays`_. - :param string $type: Type of result requested - array, object, or class name - :returns: First row of result set - :rtype: mixed + .. method:: custom_result_object($class_name) - Returns the "first" row, as an array, generic object, or - object of a specific class + :param string $class_name: Class name for the resulting rows + :returns: Array containing the fetched rows + :rtype: array - .. method:: free_result() + Returns the query results as an array of rows, where each + row is an instance of the specified class. - :rtype: void + .. method:: row([$n = 0[, $type = 'object']]) - Free the result. - Usage: see `Result Helper Methods`_. + :param int $n: Index of the query results row to be returned + :param string $type: Type of the requested result - array, object, or class name + :returns: The requested row or NULL if it doesn't exist + :rtype: mixed - .. method:: last_row([$type = 'object']) + A wrapper for the ``row_array()``, ``row_object() and + ``custom_row_object()`` methods. + + Usage: see `Result Rows`_. - :param string $type: Type of result requested - array, object, or class name - :returns: Last row of result set + .. method:: unbuffered_row([$type = 'object']) + + :param string $type: Type of the requested result - array, object, or class name + :returns: Next row from the result set or NULL if it doesn't exist :rtype: mixed - Returns the "last" row, as an array, generic object, or - object of a specific class + Fetches the next result row and returns it in the + requested form. - .. method:: list_fields() + Usage: see `Result Rows`_. - :returns: Array of column names + .. method:: row_array([$n = 0]) + + :param int $n: Index of the query results row to be returned + :returns: The requested row or NULL if it doesn't exist :rtype: array - Fetch Field Names + Returns the requested result row as an associative array. - .. method:: next_row([$type = 'object']) + Usage: see `Result Rows`_. - :param string $type: Type of result requested - array, object, or class name - :returns: "Next" row of result set, NULL if there isn't one - :rtype: mixed + .. method:: row_object([$n = 0]) - Returns the "next" row, as an array, generic object, or - object of a specific class + :param int $n: Index of the query results row to be returned + :returns: The requested row or NULL if it doesn't exist + :rtype: stdClass - .. method:: num_fields() + Returns the requested result row as an object of type + ``stdClass``. - :returns: Number of fields in the result set - :rtype: integer + Usage: see `Result Rows`_. - Number of fields in the result set. - Usage: see `Result Helper Methods`_. + .. method:: custom_row_object($n, $type) - .. method:: num_rows() + :param int $n: Index of the results row to return + :param string $class_name: Class name for the resulting row + :returns: The requested row or NULL if it doesn't exist + :rtype: $type - :returns: Number of rows in the result set - :rtype: integer + Returns the requested result row as an instance of the + requested class. - Number of rows in the result set. - Usage: see `Result Helper Methods`_. + .. method:: data_seek([$n = 0]) - .. method:: previous_row([$type = 'object']) + :param int $n: Index of the results row to be returned next + :returns: TRUE on success, FALSE on failure + :rtype: bool - :param string $type: Type of result requested - array, object, or class name - :returns: "Previous" row of result set, NULL if there isn't one - :rtype: mixed + Moves the internal results row pointer to the desired offset. - Returns the "previous" row, as an array, generic object, or - object of a specific class + Usage: see `Result Helper Methods`_. - .. method:: result([$type = 'object']) + .. method:: set_row($key[, $value = NULL]) + + :param mixed $key: Column name or array of key/value pairs + :param mixed $value: Value to assign to the column, $key is a single field name + :rtype: void + + Assigns a value to a particular column. + + .. method:: next_row([$type = 'object']) - :param string $type: Type of result requested - array, object, or class name - :returns: Query results as the specified type + :param string $type: Type of the requested result - array, object, or class name + :returns: Next row of result set, or NULL if it doesn't exist :rtype: mixed - Query result. Acts as a wrapper function for the result_array, - result_object and custom_result_object methods. - Usage: see `Result Arrays`_. + Returns the next row from the result set. - .. method:: result_array() + .. method:: previous_row([$type = 'object']) - :returns: Query results as an associative array - :rtype: array + :param string $type: Type of the requested result - array, object, or class name + :returns: Previous row of result set, or NULL if it doesn't exist + :rtype: mixed - Returns the query results as an array of rows, where each - row is itself an associative array. - Usage: see `Result Arrays`_. + Returns the previous row from the result set. - .. method:: result_object() + .. method:: first_row([$type = 'object']) - :returns: Query results as an array of objects - :rtype: array + :param string $type: Type of the requested result - array, object, or class name + :returns: First row of result set, or NULL if it doesn't exist + :rtype: mixed - Returns the query results as an array of rows, where each - row is an object + Returns the first row from the result set. - .. method:: row([$n = 0[, $type = 'object']]) + .. method:: last_row([$type = 'object']) - :param integer $n: Index of the query results row to be returned - :param string $type: Type of result requested - array, object, or class name - :returns: Requested row of result set + :param string $type: Type of the requested result - array, object, or class name + :returns: Last row of result set, or NULL if it doesn't exist :rtype: mixed - Wrapper for result_row_array, result_row_object, and - custom_row_object. - Usage: see `Result Rows`_. + Returns the last row from the result set. - .. method:: row_array([$n = 0]) + .. method:: num_rows() - :param integer $n: Index of the query results row to be returned - :returns: Requested row of result set - :rtype: array + :returns: Number of rows in the result set + :rtype: int - Returns requested result row as an associative array. - Usage: see `Result Rows`_. + Returns the number of rows in the result set. - .. method:: row_object([$n = 0]) + Usage: see `Result Helper Methods`_. - :param integer $n: Index of the query results row to be returned - :returns: Requested row of result set - :rtype: object + .. method:: num_fields() - Returns requested result row as an object + :returns: Number of fields in the result set + :rtype: int - .. method:: set_row($key[, $value = NULL]) + Returns the number of fields in the result set. + + Usage: see `Result Helper Methods`_. + + .. method:: field_data() + + :returns: Array containing field meta-data + :rtype: array + + Generates an array of ``stdClass`` objects containing + field meta-data. + + .. method:: free_result() - :param mixed $key: Column index or array of key/value pairs - :param mixed $value: Result to assign to a column if the key is an index :rtype: void - Assigns an item into a particular column slot + Frees a result set. - .. method:: unbuffered_row([$type = 'object']) + Usage: see `Result Helper Methods`_. - :param string $type: Type of result requested - array, object, or class name - :returns: Requested row of result set - :rtype: mixed + .. method:: list_fields() + + :returns: Array of column names + :rtype: array - Fetches the next result row and returns it in the requested - form. - Usage: see `Result Rows`_. \ No newline at end of file + Returns an array containing the field names in the + result set. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From d31a4e64aea57b24306484737a374a7f31b8b983 Mon Sep 17 00:00:00 2001 From: David Wosnitza Date: Fri, 12 Dec 2014 16:35:35 +0100 Subject: fixed indentation/linkref errors Signed-off-by: David Wosnitza --- user_guide_src/source/database/query_builder.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst index 030599e31..b06396e96 100644 --- a/user_guide_src/source/database/query_builder.rst +++ b/user_guide_src/source/database/query_builder.rst @@ -2,8 +2,8 @@ Query Builder Class ################### -CodeIgniter gives you access to a Query Builder class. This pattern -allows information to be retrieved, inserted, and updated in your +CodeIgniter gives you access to a Query Builder class. This pattern +allows information to be retrieved, inserted, and updated in your database with minimal scripting. In some cases only one or two lines of code are necessary to perform a database action. CodeIgniter does not require that each database table be its own class @@ -110,10 +110,10 @@ Permits you to write the SELECT portion of your query:: .. note:: If you are selecting all (\*) from a table you do not need to use this function. When omitted, CodeIgniter assumes that you wish - to select all fields and automatically adds 'SELECT *'. + 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. +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. @@ -1097,7 +1097,7 @@ Class Reference :returns: Number of rows in the query result :rtype: int - Generates a platform-specific query string that counts + Generates a platform-specific query string that counts all records returned by an Query Builder query. .. method:: get([$table = ''[, $limit = NULL[, $offset = NULL]]]) @@ -1540,4 +1540,4 @@ Class Reference :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 + Compiles a DELETE statement and returns it as a string. -- cgit v1.2.3-24-g4f1b From 7830173a28dc8e3959ea9a78a334ad10c668f13f Mon Sep 17 00:00:00 2001 From: James L Parry Date: Tue, 16 Dec 2014 02:14:52 -0800 Subject: User Guide - DB Driver Reference First stab at DB driver reference. Methods are listed in order encountered in the source file. Parameter or return types in DB_driver updated as needed, and reflected here. TOC entry added to bottom of database index page. Signed-off-by:James L Parry --- .../source/database/db_driver_reference.rst | 407 +++++++++++++++++++++ user_guide_src/source/database/index.rst | 3 +- 2 files changed, 409 insertions(+), 1 deletion(-) create mode 100644 user_guide_src/source/database/db_driver_reference.rst (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/db_driver_reference.rst b/user_guide_src/source/database/db_driver_reference.rst new file mode 100644 index 000000000..872077a7e --- /dev/null +++ b/user_guide_src/source/database/db_driver_reference.rst @@ -0,0 +1,407 @@ +################### +DB Driver Reference +################### + +This is the platform-independent base DB implementation class. +This class will not be called directly. Rather, the adapter +class for the specific database will extend and instantiate it. + +The how-to material for this has been split over several articles. +This article is intended to be a reference for them. + +.. class:: CI_DB_driver + + .. method:: initialize() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Initialize Database Settings; + establish a connection to the database. + + .. method:: db_pconnect() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Establish a persistent database connection + + .. method:: reconnect() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Keep / reestablish the db connection if no queries have been + sent for a length of time exceeding the server's idle timeout. + + This is only available in drivers that support it. + + .. method:: db_select() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Select database + + .. method:: db_set_charset($charset) + + :param string $charset: Character set name + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Set client character set + + .. method:: platform() + + :returns: Platform name + :rtype: string + + The name of the platform in use (mysql, mssql, etc...) + + .. method:: version() + + :returns: The version of the database being used. + :rtype: string + + Database version number + + .. method:: query($sql[, $binds = FALSE[, $return_object = NULL]]]) + + :param string $sql: The SQL statement to execute + :param array $binds: An array of binding data + :param bool $return_object: Character set name + :returns: True on "update" success, DB_result object on "query" success, FALSE on failure + :rtype: mixed + + Execute the query + + Accepts an SQL string as input and returns a result object + upon + successful execution of a "read" type query. Returns boolean + TRUE + upon successful execution of a "write" type query. + Returns boolean + FALSE upon failure, and if the $db_debug variable is set + to TRUE + will raise an error. + + .. method:: load_rdriver() + + :returns: The DB_result object appropriate for the driver in use + :rtype: DB_result + + Load the result drivers + + .. method:: simple_query($sql) + + :param string $sql: The SQL statement to execute + :returns: True on "update" success, DB_result object on "query" success, FALSE on failure + :rtype: mixed + + Simple Query + + This is a simplified version of the query() function. Internally + we only use it when running transaction commands since they do + not require all the features of the main query() function. + + .. method:: trans_off() + + :rtype: void + + Disable Transactions. + + This permits transactions to be disabled at run-time. + + .. method:: trans_strict([$mode = TRUE]) + + :param boolean $mode: TRUE for strict mode + :rtype: void + + Enable/disable Transaction Strict Mode. + + When strict mode is enabled, if you are running multiple + groups of + transactions, if one group fails all groups will be rolled back. + If strict mode is disabled, each group is treated autonomously, + meaning + a failure of one group will not affect any others. + + .. method:: trans_start([$test_mode = FALSE[) + + :param boolean $test_mode: TRUE for testing mode + :rtype: void + + Start Transaction. + + .. method:: trans_complete() + + :rtype: void + + Complete Transaction. + + .. method:: trans_status() + + :returns: TRUE if the transaction succeeded, FALSE if it failed + :rtype: boolean + + Lets you retrieve the transaction flag to determine if it + has failed. + + .. method:: compile_binds($sql, $binds) + + :param string $sql: The SQL statement + :param array $binds: An array of binding data + :returns: The updated SQL statement + :rtype: string + + Compile Bindings + + .. method:: is_write_type($sql) + + :param string $sql: The SQL statement + :returns: TRUE if the SQL statement is a "write" type of statement + :rtype: boolean + + Determines if a query is a "write" type. + + .. method:: elapsed_time([$decimals = 6]) + + :param int $decimals: The number of decimal places + :returns: The aggregate query elapsed time, in microseconds + :rtype: string + + Calculate the aggregate query elapsed time. + + .. method:: total_queries() + + :returns: The total number of queries + :rtype: int + + Returns the total number of queries. + + .. method:: last_query() + + :returns: The last query executed + :rtype: string + + Returns the last query that was executed. + + .. method:: escape($str) + + :param string $str: The string to work with + :returns: The escaped string + :rtype: mixed + + "Smart" Escape String. + + Escapes data based on type. + Sets boolean and null types + + .. method:: escape_str($str[, $like = FALSE]) + + :param mixed $str: The string or array of strings to work with + :param boolean $like: Whether or not the string will be used in a LIKE condition + :returns: The escaped string(s) + :rtype: mixed + + Escape String. + + .. method:: escape_like_str($str) + + :param mixed $str: The string or array of strings to work with + :returns: The escaped string(s) + :rtype: mixed + + Escape LIKE String. + + Calls the individual driver for platform + specific escaping for LIKE conditions. + + .. method:: primary([$table = '']) + + :param string $table: The table name + :returns: The primary key name, FALSE if none + :rtype: mixed + + Primary. + + Retrieves the primary key. It assumes that the row in the first + position is the primary key. + + .. method:: count_all([$table = '']) + + :param string $table: The table name + :returns: Record count for specified table + :rtype: int + + "Count All" query. + + Generates a platform-specific query string that counts + all records in + the specified database. + + .. method:: list_tables([$constrain_by_prefix = FALSE]) + + :param boolean $constrain_by_prefix: TRUE to constrain the tables considered + :returns: Array of table names, FALSE if the operation is unsupported + :rtype: mixed + + Returns an array of table names. + + .. method:: table_exists($table_name) + + :param string $table_name: The table name + :returns: TRUE if that table exists + :rtype: boolean + + Determine if a particular table exists. + + .. method:: list_fields([$table = '']) + + :param string $table: The table name + :returns: Array of field names, FALSE if the table doesn't exist or the operation is un-supported + :rtype: mixed + + Fetch Field Names. + + .. method:: field_exists($field_name, $table_name) + + :param string $table_name: The table name + :param string $field_name: The field name + :returns: TRUE if that field exists in that table + :rtype: boolean + + Determine if a particular field exists. + + .. method:: field_data([$table = '']) + + :param string $table: The table name + :returns: Object with field data, FALSE if no table given + :rtype: mixed + + Returns an object with field data. + + .. method:: escape_identifiers($item) + + :param mixed $item: The item or array of items to escape + :returns: The item(s), escaped + :rtype: mixed + + Escape the SQL Identifiers. + + This function escapes column and table names + + .. method:: insert_string($table, $data) + + :param string $table: The table upon which the query will be performed + :param array $data: an associative array of data key/values + :returns: The SQL insert string + :rtype: string + + Generate an insert string. + + .. method:: update_string($table, $data, $where) + + :param string $table: The table upon which the query will be performed + :param array $data: an associative array of data key/values + :param mixed $where: the "where" statement + :returns: The SQL update string + :rtype: string + + Generate an update string. + + .. method:: call_function($function) + + :param string $function: Function name + :returns: The function result + :rtype: string + + Enables a native PHP function to be run, using a platform + agnostic wrapper. + + .. method:: cache_set_path([$path = '']) + + :param string $path: the path to the cache directory + :rtype: void + + Set Cache Directory Path. + + .. method:: cache_on() + + :returns: cache_on value + :rtype: boolean + + Enable Query Caching. + + .. method:: cache_off() + + :returns: cache_on value + :rtype: boolean + + Disable Query Caching. + + .. method:: cache_delete([$segment_one = ''[, $segment_two = '']]) + + :param string $segment_one: first URI segment + :param string $segment_two: second URI segment + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Delete the cache files associated with a particular URI + + .. method:: cache_delete_all() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Delete All cache files + + .. method:: close() + + :rtype: void + + Close DB Connection + + .. method:: display_error([$error = ''[, $swap = ''[, $native = FALSE]]]) + + :param string $error: the error message + :param string $swap: any "swap" values + :param boolean $native: whether to localize the message + :returns: sends the application/views/errors/error_db.php template + :rtype: string + + Display an error message + + .. method:: protect_identifiers($item[, $prefix_single = FALSE[, $protect_identifiers = NULL[, $field_exists = TRUE]]]) + + :param string $item: the item + :param boolean $prefix_single: whether to use a single prefix + :param boolean $protect_identifiers: whether to protect identifiers + :param boolean $field_exists: whether the supplied item does not contain a field name. + :returns: the modified item + :rtype: string + + Protect Identifiers. + + This function is used extensively by the Query Builder class, + and by + a couple functions in this class. + It takes a column or table name (optionally with an alias) + and inserts + the table prefix onto it. Some logic is necessary in order + to deal with + column names that include the path. Consider a query like this:: + + SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table + + Or a query with aliasing:: + + SELECT m.member_id, m.member_name FROM members AS m + + Since the column name can include up to four segments + (host, DB, table, column) + or also have an alias prefix, we need to do a bit of work + to figure this out and + insert the table prefix (if it exists) in the proper position, + and escape only + the correct identifiers. \ No newline at end of file diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index 4612daf9d..2fb50f9be 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -21,4 +21,5 @@ patterns. The database functions offer clear, simple syntax. Custom Function Calls Query Caching Database Manipulation with Database Forge - Database Utilities Class \ No newline at end of file + Database Utilities Class + Database Driver Reference \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 0d3fde261bd538dd5f9468a407db74a066bc11a4 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 5 Jan 2015 16:56:41 +0200 Subject: Polish changes following PR #3416 --- .../source/database/db_driver_reference.rst | 381 +++++++++++---------- 1 file changed, 197 insertions(+), 184 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/db_driver_reference.rst b/user_guide_src/source/database/db_driver_reference.rst index 872077a7e..7bee555c8 100644 --- a/user_guide_src/source/database/db_driver_reference.rst +++ b/user_guide_src/source/database/db_driver_reference.rst @@ -9,129 +9,140 @@ class for the specific database will extend and instantiate it. The how-to material for this has been split over several articles. This article is intended to be a reference for them. +.. important:: Not all methods are supported by all database drivers, + some of them may fail (and return FALSE) if the underlying + driver does not support them. + .. class:: CI_DB_driver .. method:: initialize() :returns: TRUE on success, FALSE on failure - :rtype: boolean + :rtype: bool + + Initialize database settings, establish a connection to + the database. + + .. method:: db_connect($persistent = TRUE) + + :param bool $persistent: Whether to establish a persistent connection or a regular one + :returns: Database connection resource/object or FALSE on failure + :rtype: mixed + + Establish a connection with the database. - Initialize Database Settings; - establish a connection to the database. + .. note:: The returned value depends on the underlying + driver in use. For example, a ``mysqli`` instance + will be returned with the 'mysqli' driver. .. method:: db_pconnect() - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :returns: Database connection resource/object or FALSE on failure + :rtype: mixed + + Establish a persistent connection with the database. - Establish a persistent database connection + .. note:: This method is just an alias for ``db_connect(TRUE)``. .. method:: reconnect() :returns: TRUE on success, FALSE on failure - :rtype: boolean + :rtype: bool - Keep / reestablish the db connection if no queries have been - sent for a length of time exceeding the server's idle timeout. + Keep / reestablish the database connection if no queries + have been sent for a length of time exceeding the + server's idle timeout. - This is only available in drivers that support it. - - .. method:: db_select() + .. method:: db_select([$database = '']) + :param string $database: Database name :returns: TRUE on success, FALSE on failure - :rtype: boolean + :rtype: bool - Select database + Select / switch the current database. .. method:: db_set_charset($charset) :param string $charset: Character set name :returns: TRUE on success, FALSE on failure - :rtype: boolean + :rtype: bool - Set client character set + Set client character set. .. method:: platform() :returns: Platform name :rtype: string - The name of the platform in use (mysql, mssql, etc...) + The name of the platform in use (mysql, mssql, etc...). .. method:: version() - :returns: The version of the database being used. + :returns: The version of the database being used :rtype: string - Database version number + Database version number. .. method:: query($sql[, $binds = FALSE[, $return_object = NULL]]]) :param string $sql: The SQL statement to execute :param array $binds: An array of binding data - :param bool $return_object: Character set name - :returns: True on "update" success, DB_result object on "query" success, FALSE on failure + :param bool $return_object: Whether to return a result object or not + :returns: TRUE for successful "write-type" queries, CI_DB_result instance (method chaining) on "query" success, FALSE on failure :rtype: mixed - Execute the query + Execute an SQL query. - Accepts an SQL string as input and returns a result object - upon - successful execution of a "read" type query. Returns boolean - TRUE - upon successful execution of a "write" type query. - Returns boolean - FALSE upon failure, and if the $db_debug variable is set - to TRUE - will raise an error. + Accepts an SQL string as input and returns a result object + upon successful execution of a "read" type query. - .. method:: load_rdriver() + Returns: - :returns: The DB_result object appropriate for the driver in use - :rtype: DB_result + - Boolean TRUE upon successful execution of a "write type" queries + - Boolean FALSE upon failure + - ``CI_DB_result`` object for "read type" queries - Load the result drivers + .. note: If 'db_debug' setting is set to TRUE, an error + page will be displayed instead of returning FALSE + on failures and script execution will stop. .. method:: simple_query($sql) :param string $sql: The SQL statement to execute - :returns: True on "update" success, DB_result object on "query" success, FALSE on failure + :returns: Whatever the underlying driver's "query" function returns :rtype: mixed - Simple Query - - This is a simplified version of the query() function. Internally - we only use it when running transaction commands since they do - not require all the features of the main query() function. + A simplified version of the ``query()`` method, appropriate + for use when you don't need to get a result object or to + just send a query to the database and not care for the result. - .. method:: trans_off() + .. method:: trans_strict([$mode = TRUE]) + :param bool $mode: Strict mode flag :rtype: void - Disable Transactions. + Enable/disable transaction "strict" mode. - This permits transactions to be disabled at run-time. + When strict mode is enabled, if you are running multiple + groups of transactions and one group fails, all groups + will be rolled back. - .. method:: trans_strict([$mode = TRUE]) + If strict mode is disabled, each group is treated + autonomously, meaning a failure of one group will not + affect any others. - :param boolean $mode: TRUE for strict mode - :rtype: void + .. method:: trans_off() - Enable/disable Transaction Strict Mode. + :rtype: void - When strict mode is enabled, if you are running multiple - groups of - transactions, if one group fails all groups will be rolled back. - If strict mode is disabled, each group is treated autonomously, - meaning - a failure of one group will not affect any others. + Disables transactions at run-time. - .. method:: trans_start([$test_mode = FALSE[) + .. method:: trans_start([$test_mode = FALSE]) - :param boolean $test_mode: TRUE for testing mode + :param bool $test_mode: Test mode flag :rtype: void - Start Transaction. + Start a transaction. .. method:: trans_complete() @@ -141,11 +152,11 @@ This article is intended to be a reference for them. .. method:: trans_status() - :returns: TRUE if the transaction succeeded, FALSE if it failed - :rtype: boolean + :returns: TRUE if the transaction succeeded, FALSE if it failed + :rtype: bool - Lets you retrieve the transaction flag to determine if it - has failed. + Lets you retrieve the transaction status flag to + determine if it has failed. .. method:: compile_binds($sql, $binds) @@ -154,15 +165,16 @@ This article is intended to be a reference for them. :returns: The updated SQL statement :rtype: string - Compile Bindings + Compiles an SQL query with the bind values passed for it. .. method:: is_write_type($sql) :param string $sql: The SQL statement - :returns: TRUE if the SQL statement is a "write" type of statement - :rtype: boolean + :returns: TRUE if the SQL statement is of "write type", FALSE if not + :rtype: bool - Determines if a query is a "write" type. + Determines if a query is of a "write" type (such as + INSERT, UPDATE, DELETE) or "read" type (i.e. SELECT). .. method:: elapsed_time([$decimals = 6]) @@ -174,10 +186,11 @@ This article is intended to be a reference for them. .. method:: total_queries() - :returns: The total number of queries + :returns: The total number of queries executed :rtype: int - Returns the total number of queries. + Returns the total number of queries that have been + executed so far. .. method:: last_query() @@ -188,220 +201,220 @@ This article is intended to be a reference for them. .. method:: escape($str) - :param string $str: The string to work with - :returns: The escaped string + :param mixed $str: The value to escape, or an array of multiple ones + :returns: The escaped value(s) :rtype: mixed - "Smart" Escape String. - - Escapes data based on type. - Sets boolean and null types + Escapes input data based on type, including boolean and + NULLs. .. method:: escape_str($str[, $like = FALSE]) - :param mixed $str: The string or array of strings to work with - :param boolean $like: Whether or not the string will be used in a LIKE condition + :param mixed $str: A string value or array of multiple ones + :param bool $like: Whether or not the string will be used in a LIKE condition :returns: The escaped string(s) :rtype: mixed - Escape String. + Escapes string values. + + .. warning:: The returned strings do NOT include quotes + around them. .. method:: escape_like_str($str) - :param mixed $str: The string or array of strings to work with - :returns: The escaped string(s) + :param mixed $str: A string value or array of multiple ones + :returns: The escaped string(s) :rtype: mixed - Escape LIKE String. - - Calls the individual driver for platform - specific escaping for LIKE conditions. + Escape LIKE strings. - .. method:: primary([$table = '']) + Similar to ``escape_str()``, but will also escape the ``%`` + and ``_`` wildcard characters, so that they don't cause + false-positives in LIKE conditions. - :param string $table: The table name - :returns: The primary key name, FALSE if none - :rtype: mixed + .. method:: primary($table) - Primary. - - Retrieves the primary key. It assumes that the row in the first - position is the primary key. + :param string $table: Table name + :returns: The primary key name, FALSE if none + :rtype: string + + Retrieves the primary key of a table. + + .. note:: If the database platform does not support primary + key detection, the first column name may be assumed + as the primary key. .. method:: count_all([$table = '']) - :param string $table: The table name - :returns: Record count for specified table + :param string $table: Table name + :returns: Row count for the specified table :rtype: int - "Count All" query. - - Generates a platform-specific query string that counts - all records in - the specified database. + Returns the total number of rows in a table, or 0 if no + table was provided. .. method:: list_tables([$constrain_by_prefix = FALSE]) - :param boolean $constrain_by_prefix: TRUE to constrain the tables considered - :returns: Array of table names, FALSE if the operation is unsupported - :rtype: mixed + :param bool $constrain_by_prefix: TRUE to match table names by the configured dbprefix + :returns: Array of table names or FALSE on failure + :rtype: array - Returns an array of table names. + Gets a list of the tables in the current database. .. method:: table_exists($table_name) :param string $table_name: The table name - :returns: TRUE if that table exists - :rtype: boolean + :returns: TRUE if that table exists, FALSE if not + :rtype: bool Determine if a particular table exists. - .. method:: list_fields([$table = '']) + .. method:: list_fields($table) :param string $table: The table name - :returns: Array of field names, FALSE if the table doesn't exist or the operation is un-supported - :rtype: mixed + :returns: Array of field names or FALSE on failure + :rtype: array - Fetch Field Names. + Gets a list of the field names in a table. .. method:: field_exists($field_name, $table_name) :param string $table_name: The table name - :param string $field_name: The field name - :returns: TRUE if that field exists in that table - :rtype: boolean + :param string $field_name: The field name + :returns: TRUE if that field exists in that table, FALSE if not + :rtype: bool Determine if a particular field exists. - .. method:: field_data([$table = '']) + .. method:: field_data($table) :param string $table: The table name - :returns: Object with field data, FALSE if no table given - :rtype: mixed + :returns: Array of field data items or FALSE on failure + :rtype: array - Returns an object with field data. + Gets a list containing field data about a table. .. method:: escape_identifiers($item) :param mixed $item: The item or array of items to escape - :returns: The item(s), escaped + :returns: The input item(s), escaped :rtype: mixed - Escape the SQL Identifiers. - - This function escapes column and table names + Escape SQL identifiers, such as column, table and names. .. method:: insert_string($table, $data) - :param string $table: The table upon which the query will be performed - :param array $data: an associative array of data key/values - :returns: The SQL insert string + :param string $table: The target table + :param array $data: An associative array of key/value pairs + :returns: The SQL INSERT statement, as a string :rtype: string - Generate an insert string. + Generate an INSERT statement string. .. method:: update_string($table, $data, $where) - :param string $table: The table upon which the query will be performed - :param array $data: an associative array of data key/values - :param mixed $where: the "where" statement - :returns: The SQL update string + :param string $table: The target table + :param array $data: An associative array of key/value pairs + :param mixed $where: The WHERE statement conditions + :returns: The SQL UPDATE statement, as a string :rtype: string - Generate an update string. + Generate an UPDATE statement string. .. method:: call_function($function) :param string $function: Function name - :returns: The function result + :returns: The function result :rtype: string - Enables a native PHP function to be run, using a platform - agnostic wrapper. + Runs a native PHP function , using a platform agnostic + wrapper. .. method:: cache_set_path([$path = '']) - :param string $path: the path to the cache directory - :rtype: void + :param string $path: Path to the cache directory + :rtype: void - Set Cache Directory Path. + Sets the directory path to use for caching storage. .. method:: cache_on() - :returns: cache_on value - :rtype: boolean + :returns: TRUE if caching is on, FALSE if not + :rtype: bool - Enable Query Caching. + Enable database results caching. .. method:: cache_off() - :returns: cache_on value - :rtype: boolean + :returns: TRUE if caching is on, FALSE if not + :rtype: bool - Disable Query Caching. + Disable database results caching. .. method:: cache_delete([$segment_one = ''[, $segment_two = '']]) - :param string $segment_one: first URI segment - :param string $segment_two: second URI segment - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :param string $segment_one: First URI segment + :param string $segment_two: Second URI segment + :returns: TRUE on success, FALSE on failure + :rtype: bool - Delete the cache files associated with a particular URI + Delete the cache files associated with a particular URI. .. method:: cache_delete_all() - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :returns: TRUE on success, FALSE on failure + :rtype: bool - Delete All cache files + Delete all cache files. .. method:: close() - :rtype: void + :rtype: void - Close DB Connection + Close the DB Connection. .. method:: display_error([$error = ''[, $swap = ''[, $native = FALSE]]]) - :param string $error: the error message - :param string $swap: any "swap" values - :param boolean $native: whether to localize the message - :returns: sends the application/views/errors/error_db.php template + :param string $error: The error message + :param string $swap: Any "swap" values + :param bool $native: Whether to localize the message + :rtype: void + + :returns: Displays the DB error screensends the application/views/errors/error_db.php template :rtype: string - Display an error message + Display an error message and stop script execution. + + The message is displayed using the + *application/views/errors/error_db.php* template. .. method:: protect_identifiers($item[, $prefix_single = FALSE[, $protect_identifiers = NULL[, $field_exists = TRUE]]]) - :param string $item: the item - :param boolean $prefix_single: whether to use a single prefix - :param boolean $protect_identifiers: whether to protect identifiers - :param boolean $field_exists: whether the supplied item does not contain a field name. - :returns: the modified item - :rtype: string + :param string $item: The item to work with + :param bool $prefix_single: Whether to apply the dbprefix even if the input item is a single identifier + :param bool $protect_identifiers: Whether to quote identifiers + :param bool $field_exists: Whether the supplied item contains a field name or not + :returns: The modified item + :rtype: string + + Takes a column or table name (optionally with an alias) + and applies the configured *dbprefix* to it. + + Some logic is necessary in order to deal with + column names that include the path. + + Consider a query like this:: + + SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table + + Or a query with aliasing:: + + SELECT m.member_id, m.member_name FROM members AS m + + Since the column name can include up to four segments + (host, DB, table, column) or also have an alias prefix, + we need to do a bit of work to figure this out and + insert the table prefix (if it exists) in the proper + position, and escape only the correct identifiers. - Protect Identifiers. - - This function is used extensively by the Query Builder class, - and by - a couple functions in this class. - It takes a column or table name (optionally with an alias) - and inserts - the table prefix onto it. Some logic is necessary in order - to deal with - column names that include the path. Consider a query like this:: - - SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table - - Or a query with aliasing:: - - SELECT m.member_id, m.member_name FROM members AS m - - Since the column name can include up to four segments - (host, DB, table, column) - or also have an alias prefix, we need to do a bit of work - to figure this out and - insert the table prefix (if it exists) in the proper position, - and escape only - the correct identifiers. \ No newline at end of file + This method is used extensively by the Query Builder class. \ No newline at end of file -- cgit v1.2.3-24-g4f1b