12.15 Information Functions

Information Functions

Name Description

'BENCHMARK()' Repeatedly execute an expression

'CHARSET()' Return the character set of the argument

'COERCIBILITY()' Return the collation coercibility value of the string argument

'COLLATION()' Return the collation of the string argument

'CONNECTION_ID()' Return the connection ID (thread ID) for the connection

'CURRENT_USER()', The authenticated user name and host name 'CURRENT_USER'

'DATABASE()' Return the default (current) database name

'FOUND_ROWS()' For a SELECT with a LIMIT clause, the number of rows that would be returned were there no LIMIT clause

'LAST_INSERT_ID()' Value of the AUTOINCREMENT column for the last INSERT

'ROW_COUNT()' The number of rows updated

'SCHEMA()' Synonym for DATABASE()

'SESSION_USER()' Synonym for USER()

'SYSTEM_USER()' Synonym for USER()

'USER()' The user name and host name provided by the client

'VERSION()' Return a string that indicates the MySQL server version

'BENCHMARK(COUNT,EXPR)'

The 'BENCHMARK()' function executes the expression EXPR repeatedly COUNT times. It may be used to time how quickly MySQL processes the expression. The result value is '0', or 'NULL' for inappropriate arguments such as a 'NULL' or negative repeat count.

The intended use is from within the *note 'mysql': mysql. client, which reports query execution times:

  mysql> SELECT BENCHMARK(1000000,AES_ENCRYPT('hello','goodbye'));
  +---------------------------------------------------+
  | BENCHMARK(1000000,AES_ENCRYPT('hello','goodbye')) |
  +---------------------------------------------------+
  |                                                 0 |
  +---------------------------------------------------+
  1 row in set (4.74 sec)

The time reported is elapsed time on the client end, not CPU time on the server end. It is advisable to execute 'BENCHMARK()' several times, and to interpret the result with regard to how heavily loaded the server machine is.

'BENCHMARK()' is intended for measuring the runtime performance of scalar expressions, which has some significant implications for the way that you use it and interpret the results:

* Only scalar expressions can be used.  Although the expression
  can be a subquery, it must return a single column and at most
  a single row.  For example, 'BENCHMARK(10, (SELECT * FROM t))'
  fails if the table 't' has more than one column or more than
  one row.

* Executing a 'SELECT EXPR' statement N times differs from
  executing 'SELECT BENCHMARK(N, EXPR)' in terms of the amount
  of overhead involved.  The two have very different execution
  profiles and you should not expect them to take the same
  amount of time.  The former involves the parser, optimizer,
  table locking, and runtime evaluation N times each.  The
  latter involves only runtime evaluation N times, and all the
  other components just once.  Memory structures already
  allocated are reused, and runtime optimizations such as local
  caching of results already evaluated for aggregate functions
  can alter the results.  Use of 'BENCHMARK()' thus measures
  performance of the runtime component by giving more weight to
  that component and removing the 'noise' introduced by the
  network, parser, optimizer, and so forth.

'CHARSET(STR)'

Returns the character set of the string argument.

  mysql> SELECT CHARSET('abc');
          -> 'latin1'
  mysql> SELECT CHARSET(CONVERT('abc' USING utf8));
          -> 'utf8'
  mysql> SELECT CHARSET(USER());
          -> 'utf8'

'COERCIBILITY(STR)'

Returns the collation coercibility value of the string argument.
```
  mysql> SELECT COERCIBILITY('abc' COLLATE latin1_swedish_ci);
          -> 0
  mysql> SELECT COERCIBILITY(USER());
          -> 3
  mysql> SELECT COERCIBILITY('abc');
          -> 4
  mysql> SELECT COERCIBILITY(1000);
          -> 5
```
The return values have the meanings shown in the following table. Lower values have higher precedence.

CoercibilityMeaning Example

'0'

Explicit Value collation with 'COLLATE' clause

'1'

No Concatenation collation of strings with different collations

'2'

Implicit Column collation value, stored routine parameter or local variable

'3'

System 'USER()' constant return value

'4'

Coercible Literal string

'5'

Numeric Numeric or temporal value

'6'

Ignorable 'NULL' or an expression derived from 'NULL'

For more information, see *note charset-collation-coercibility::.

'COLLATION(STR)'

Returns the collation of the string argument.

  mysql> SELECT COLLATION('abc');
          -> 'latin1_swedish_ci'
  mysql> SELECT COLLATION(_utf8'abc');
          -> 'utf8_general_ci'

'CONNECTION_ID()'

Returns the connection ID (thread ID) for the connection. Every connection has an ID that is unique among the set of currently connected clients.

The value returned by 'CONNECTION_ID()' is the same type of value as displayed in the 'ID' column of the Information Schema note 'PROCESSLIST': information-schema-processlist-table. table, the 'Id' column of note 'SHOW PROCESSLIST': show-processlist. output, and the 'PROCESSLIST_ID' column of the Performance Schema *note 'threads': performance-schema-threads-table. table.
```
  mysql> SELECT CONNECTION_ID();
          -> 23786
```
Warning:

Changing the session value of the 'pseudo_thread_id' system variable changes the value returned by the 'CONNECTION_ID()' function.
'CURRENT_USER', 'CURRENT_USER()'

Returns the user name and host name combination for the MySQL account that the server used to authenticate the current client. This account determines your access privileges. The return value is a string in the 'utf8' character set.

The value of 'CURRENT_USER()' can differ from the value of 'USER()'.
```
  mysql> SELECT USER();
          -> 'davida@localhost'
  mysql> SELECT * FROM mysql.user;
  ERROR 1044: Access denied for user ''@'localhost' to
  database 'mysql'
  mysql> SELECT CURRENT_USER();
          -> '@localhost'
```
The example illustrates that although the client specified a user name of 'davida' (as indicated by the value of the 'USER()' function), the server authenticated the client using an anonymous user account (as seen by the empty user name part of the 'CURRENT_USER()' value). One way this might occur is that there is no account listed in the grant tables for 'davida'.

Within a stored program or view, 'CURRENT_USER()' returns the account for the user who defined the object (as given by its 'DEFINER' value) unless defined with the 'SQL SECURITY INVOKER' characteristic. In the latter case, 'CURRENT_USER()' returns the object's invoker.

Triggers and events have no option to define the 'SQL SECURITY' characteristic, so for these objects, 'CURRENT_USER()' returns the account for the user who defined the object. To return the invoker, use 'USER()' or 'SESSION_USER()'.

The following statements support use of the 'CURRENT_USER()' function to take the place of the name of (and, possibly, a host for) an affected user or a definer; in such cases, 'CURRENT_USER()' is expanded where and as needed:
```
* *note 'DROP USER': drop-user.

* *note 'RENAME USER': rename-user.

* *note 'GRANT': grant.

* *note 'REVOKE': revoke.

* *note 'CREATE FUNCTION': create-function.

* *note 'CREATE PROCEDURE': create-procedure.

* *note 'CREATE TRIGGER': create-trigger.

* *note 'CREATE EVENT': create-event.

* *note 'CREATE VIEW': create-view.

* *note 'ALTER EVENT': alter-event.

* *note 'ALTER VIEW': alter-view.

* *note 'SET PASSWORD': set-password.
```
For information about the implications that this expansion of 'CURRENT_USER()' has for replication, see *note replication-features-current-user::.
'DATABASE()'

Returns the default (current) database name as a string in the 'utf8' character set. If there is no default database, 'DATABASE()' returns 'NULL'. Within a stored routine, the default database is the database that the routine is associated with, which is not necessarily the same as the database that is the default in the calling context.
```
  mysql> SELECT DATABASE();
          -> 'test'
```
If there is no default database, 'DATABASE()' returns 'NULL'.
'FOUND_ROWS()'

A note 'SELECT': select. statement may include a 'LIMIT' clause to restrict the number of rows the server returns to the client. In some cases, it is desirable to know how many rows the statement would have returned without the 'LIMIT', but without running the statement again. To obtain this row count, include an 'SQL_CALC_FOUND_ROWS' option in the note 'SELECT': select. statement, and then invoke 'FOUND_ROWS()' afterward:
```
  mysql> SELECT SQL_CALC_FOUND_ROWS * FROM TBL_NAME
      -> WHERE id > 100 LIMIT 10;
  mysql> SELECT FOUND_ROWS();
```
The second note 'SELECT': select. returns a number indicating how many rows the first note 'SELECT': select. would have returned had it been written without the 'LIMIT' clause.

In the absence of the 'SQL_CALC_FOUND_ROWS' option in the most recent successful *note 'SELECT': select. statement, 'FOUND_ROWS()' returns the number of rows in the result set returned by that statement. If the statement includes a 'LIMIT' clause, 'FOUND_ROWS()' returns the number of rows up to the limit. For example, 'FOUND_ROWS()' returns 10 or 60, respectively, if the statement includes 'LIMIT 10' or 'LIMIT 50, 10'.

The row count available through 'FOUND_ROWS()' is transient and not intended to be available past the statement following the 'SELECT SQL_CALC_FOUND_ROWS' statement. If you need to refer to the value later, save it:
```
  mysql> SELECT SQL_CALC_FOUND_ROWS * FROM ... ;
  mysql> SET @rows = FOUND_ROWS();
```
If you are using 'SELECT SQL_CALC_FOUND_ROWS', MySQL must calculate how many rows are in the full result set. However, this is faster than running the query again without 'LIMIT', because the result set need not be sent to the client.

'SQL_CALC_FOUND_ROWS' and 'FOUND_ROWS()' can be useful in situations when you want to restrict the number of rows that a query returns, but also determine the number of rows in the full result set without running the query again. An example is a Web script that presents a paged display containing links to the pages that show other sections of a search result. Using 'FOUND_ROWS()' enables you to determine how many other pages are needed for the rest of the result.

The use of 'SQL_CALC_FOUND_ROWS' and 'FOUND_ROWS()' is more complex for note 'UNION': union. statements than for simple note 'SELECT': select. statements, because 'LIMIT' may occur at multiple places in a note 'UNION': union. It may be applied to individual note 'SELECT': select. statements in the note 'UNION': union, or global to the note 'UNION': union. result as a whole.

The intent of 'SQL_CALC_FOUND_ROWS' for note 'UNION': union. is that it should return the row count that would be returned without a global 'LIMIT'. The conditions for use of 'SQL_CALC_FOUND_ROWS' with note 'UNION': union. are:
```
* The 'SQL_CALC_FOUND_ROWS' keyword must appear in the first
  *note 'SELECT': select. of the *note 'UNION': union.

* The value of 'FOUND_ROWS()' is exact only if *note 'UNION
  ALL': union. is used.  If *note 'UNION': union. without 'ALL'
  is used, duplicate removal occurs and the value of
  'FOUND_ROWS()' is only approximate.

* If no 'LIMIT' is present in the *note 'UNION': union,
  'SQL_CALC_FOUND_ROWS' is ignored and returns the number of
  rows in the temporary table that is created to process the
  *note 'UNION': union.
```
Beyond the cases described here, the behavior of 'FOUND_ROWS()' is undefined (for example, its value following a *note 'SELECT': select. statement that fails with an error).

Important:

'FOUND_ROWS()' is not replicated reliably using statement-based replication. This function is automatically replicated using row-based replication.
'LAST_INSERT_ID()', 'LAST_INSERT_ID(EXPR)'

With no argument, 'LAST_INSERT_ID()' returns a 'BIGINT UNSIGNED' (64-bit) value representing the first automatically generated value successfully inserted for an 'AUTO_INCREMENT' column as a result of the most recently executed *note 'INSERT': insert. statement. The value of 'LAST_INSERT_ID()' remains unchanged if no rows are successfully inserted.

With an argument, 'LAST_INSERT_ID()' returns an unsigned integer.

For example, after inserting a row that generates an 'AUTO_INCREMENT' value, you can get the value like this:
```
  mysql> SELECT LAST_INSERT_ID();
          -> 195
```
The currently executing statement does not affect the value of 'LAST_INSERT_ID()'. Suppose that you generate an 'AUTO_INCREMENT' value with one statement, and then refer to 'LAST_INSERT_ID()' in a multiple-row *note 'INSERT': insert. statement that inserts rows into a table with its own 'AUTO_INCREMENT' column. The value of 'LAST_INSERT_ID()' remains stable in the second statement; its value for the second and later rows is not affected by the earlier row insertions. (However, if you mix references to 'LAST_INSERT_ID()' and 'LAST_INSERT_ID(EXPR)', the effect is undefined.)

If the previous statement returned an error, the value of 'LAST_INSERT_ID()' is undefined. For transactional tables, if the statement is rolled back due to an error, the value of 'LAST_INSERT_ID()' is left undefined. For manual note 'ROLLBACK': commit, the value of 'LAST_INSERT_ID()' is not restored to that before the transaction; it remains as it was at the point of the note 'ROLLBACK': commit.

Within the body of a stored routine (procedure or function) or a trigger, the value of 'LAST_INSERT_ID()' changes the same way as for statements executed outside the body of these kinds of objects. The effect of a stored routine or trigger upon the value of 'LAST_INSERT_ID()' that is seen by following statements depends on the kind of routine:
```
* If a stored procedure executes statements that change the
  value of 'LAST_INSERT_ID()', the changed value is seen by
  statements that follow the procedure call.

* For stored functions and triggers that change the value, the
  value is restored when the function or trigger ends, so
  statements following them do not see a changed value.
```
The ID that was generated is maintained in the server on a per-connection basis. This means that the value returned by the function to a given client is the first 'AUTO_INCREMENT' value generated for most recent statement affecting an 'AUTO_INCREMENT' column by that client. This value cannot be affected by other clients, even if they generate 'AUTO_INCREMENT' values of their own. This behavior ensures that each client can retrieve its own ID without concern for the activity of other clients, and without the need for locks or transactions.

The value of 'LAST_INSERT_ID()' is not changed if you set the 'AUTO_INCREMENT' column of a row to a non-'magic' value (that is, a value that is not 'NULL' and not '0').

Important:

If you insert multiple rows using a single note 'INSERT': insert. statement, 'LAST_INSERT_ID()' returns the value generated for the first inserted row only. The reason for this is to make it possible to reproduce easily the same note 'INSERT': insert. statement against some other server.

For example:
```
  mysql> USE test;

  mysql> CREATE TABLE t (
         id INT AUTO_INCREMENT NOT NULL PRIMARY KEY,
         name VARCHAR(10) NOT NULL
         );

  mysql> INSERT INTO t VALUES (NULL, 'Bob');

  mysql> SELECT * FROM t;
  +----+------+
  | id | name |
  +----+------+
  |  1 | Bob  |
  +----+------+

  mysql> SELECT LAST_INSERT_ID();
  +------------------+
  | LAST_INSERT_ID() |
  +------------------+
  |                1 |
  +------------------+

  mysql> INSERT INTO t VALUES
         (NULL, 'Mary'), (NULL, 'Jane'), (NULL, 'Lisa');

  mysql> SELECT * FROM t;
  +----+------+
  | id | name |
  +----+------+
  |  1 | Bob  |
  |  2 | Mary |
  |  3 | Jane |
  |  4 | Lisa |
  +----+------+

  mysql> SELECT LAST_INSERT_ID();
  +------------------+
  | LAST_INSERT_ID() |
  +------------------+
  |                2 |
  +------------------+
```
Although the second note 'INSERT': insert. statement inserted three new rows into 't', the ID generated for the first of these rows was '2', and it is this value that is returned by 'LAST_INSERT_ID()' for the following note 'SELECT': select. statement.

If you use *note 'INSERT IGNORE': insert. and the row is ignored, the 'LAST_INSERT_ID()' remains unchanged from the current value (or 0 is returned if the connection has not yet performed a successful 'INSERT') and, for non-transactional tables, the 'AUTO_INCREMENT' counter is not incremented. For 'InnoDB' tables, the 'AUTO_INCREMENT' counter is incremented if 'innodb_autoinc_lock_mode' is set to '1' or '2', as demonstrated in the following example:
```
  mysql> USE test;

  mysql> SELECT @@innodb_autoinc_lock_mode;
  +----------------------------+
  | @@innodb_autoinc_lock_mode |
  +----------------------------+
  |                          1 |
  +----------------------------+

  mysql> CREATE TABLE `t` (
         `id` INT(11) NOT NULL AUTO_INCREMENT,
         `val` INT(11) DEFAULT NULL,
         PRIMARY KEY (`id`),
         UNIQUE KEY `i1` (`val`)
         ) ENGINE=InnoDB DEFAULT CHARSET=latin1;

  # Insert two rows

  mysql> INSERT INTO t (val) VALUES (1),(2);

  # With auto_increment_offset=1, the inserted rows
  # result in an AUTO_INCREMENT value of 3

  mysql> SHOW CREATE TABLE t\G
  *************************** 1. row ***************************
         Table: t
  Create Table: CREATE TABLE `t` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `val` int(11) DEFAULT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `i1` (`val`)
  ) ENGINE=InnoDB AUTO_INCREMENT=3 DEFAULT CHARSET=latin1

  # LAST_INSERT_ID() returns the first automatically generated
  # value that is successfully inserted for the AUTO_INCREMENT column

  mysql> SELECT LAST_INSERT_ID();
  +------------------+
  | LAST_INSERT_ID() |
  +------------------+
  |                1 |
  +------------------+

  # The attempted insertion of duplicate rows fail but errors are ignored

  mysql> INSERT IGNORE INTO t (val) VALUES (1),(2);
  Query OK, 0 rows affected (0.00 sec)
  Records: 2  Duplicates: 2  Warnings: 0

  # With innodb_autoinc_lock_mode=1, the AUTO_INCREMENT counter
  # is incremented for the ignored rows

  mysql> SHOW CREATE TABLE t\G
  *************************** 1. row ***************************
         Table: t
  Create Table: CREATE TABLE `t` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `val` int(11) DEFAULT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `i1` (`val`)
  ) ENGINE=InnoDB AUTO_INCREMENT=5 DEFAULT CHARSET=latin1

  # The LAST_INSERT_ID is unchanged because the previous insert was unsuccessful

  mysql> SELECT LAST_INSERT_ID();
  +------------------+
  | LAST_INSERT_ID() |
  +------------------+
  |                1 |
  +------------------+
```
For more information, see *note innodb-auto-increment-handling::.

If EXPR is given as an argument to 'LAST_INSERT_ID()', the value of the argument is returned by the function and is remembered as the next value to be returned by 'LAST_INSERT_ID()'. This can be used to simulate sequences:
1. Create a table to hold the sequence counter and initialize it:
```
   mysql> CREATE TABLE sequence (id INT NOT NULL);
   mysql> INSERT INTO sequence VALUES (0);
```
2. Use the table to generate sequence numbers like this:
```
   mysql> UPDATE sequence SET id=LAST_INSERT_ID(id+1);
   mysql> SELECT LAST_INSERT_ID();
```
  The note 'UPDATE': update. statement increments the sequence counter and causes the next call to 'LAST_INSERT_ID()' to return the updated value. The note 'SELECT': select. statement retrieves that value. The 'mysql_insert_id()' (https://dev.mysql.com/doc/c-api/5.7/en/mysql-insert-id.html) C API function can also be used to get the value. See mysql_insert_id() (https://dev.mysql.com/doc/c-api/5.7/en/mysql-insert-id.html).
You can generate sequences without calling 'LAST_INSERT_ID()', but the utility of using the function this way is that the ID value is maintained in the server as the last automatically generated value. It is multi-user safe because multiple clients can issue the note 'UPDATE': update. statement and get their own sequence value with the note 'SELECT': select. statement (or 'mysql_insert_id()' (https://dev.mysql.com/doc/c-api/5.7/en/mysql-insert-id.html)), without affecting or being affected by other clients that generate their own sequence values.

Note that 'mysql_insert_id()' (https://dev.mysql.com/doc/c-api/5.7/en/mysql-insert-id.html) is only updated after note 'INSERT': insert. and note 'UPDATE': update. statements, so you cannot use the C API function to retrieve the value for 'LAST_INSERT_ID(EXPR)' after executing other SQL statements like note 'SELECT': select. or note 'SET': set-variable.
'ROW_COUNT()'

'ROW_COUNT()' returns a value as follows:
```
* DDL statements: 0.  This applies to statements such as *note
  'CREATE TABLE': create-table. or *note 'DROP TABLE':
  drop-table.

* DML statements other than *note 'SELECT': select.: The number
  of affected rows.  This applies to statements such as *note
  'UPDATE': update, *note 'INSERT': insert, or *note 'DELETE':
  delete. (as before), but now also to statements such as *note
  'ALTER TABLE': alter-table. and *note 'LOAD DATA': load-data.

* *note 'SELECT': select.: -1 if the statement returns a result
  set, or the number of rows 'affected' if it does not.  For
  example, for 'SELECT * FROM t1', 'ROW_COUNT()' returns -1.
  For 'SELECT * FROM t1 INTO OUTFILE 'FILE_NAME'', 'ROW_COUNT()'
  returns the number of rows written to the file.

* *note 'SIGNAL': signal. statements: 0.
```
For note 'UPDATE': update. statements, the affected-rows value by default is the number of rows actually changed. If you specify the 'CLIENT_FOUND_ROWS' flag to 'mysql_real_connect()' (https://dev.mysql.com/doc/c-api/5.7/en/mysql-real-connect.html) when connecting to note 'mysqld': mysqld, the affected-rows value is the number of rows 'found'; that is, matched by the 'WHERE' clause.

For *note 'REPLACE': replace. statements, the affected-rows value is 2 if the new row replaced an old row, because in this case, one row was inserted after the duplicate was deleted.

For *note 'INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. statements, the affected-rows value per row is 1 if the row is inserted as a new row, 2 if an existing row is updated, and 0 if an existing row is set to its current values. If you specify the 'CLIENT_FOUND_ROWS' flag, the affected-rows value is 1 (not 0) if an existing row is set to its current values.

The 'ROW_COUNT()' value is similar to the value from the 'mysql_affected_rows()' (https://dev.mysql.com/doc/c-api/5.7/en/mysql-affected-rows.html) C API function and the row count that the *note 'mysql': mysql. client displays following statement execution.
```
  mysql> INSERT INTO t VALUES(1),(2),(3);
  Query OK, 3 rows affected (0.00 sec)
  Records: 3  Duplicates: 0  Warnings: 0

  mysql> SELECT ROW_COUNT();
  +-------------+
  | ROW_COUNT() |
  +-------------+
  |           3 |
  +-------------+
  1 row in set (0.00 sec)

  mysql> DELETE FROM t WHERE i IN(1,2);
  Query OK, 2 rows affected (0.00 sec)

  mysql> SELECT ROW_COUNT();
  +-------------+
  | ROW_COUNT() |
  +-------------+
  |           2 |
  +-------------+
  1 row in set (0.00 sec)
```
Important:

'ROW_COUNT()' is not replicated reliably using statement-based replication. This function is automatically replicated using row-based replication.
'SCHEMA()'

This function is a synonym for 'DATABASE()'.
'SESSION_USER()'

'SESSION_USER()' is a synonym for 'USER()'.
'SYSTEM_USER()'

'SYSTEM_USER()' is a synonym for 'USER()'.
'USER()'

Returns the current MySQL user name and host name as a string in the 'utf8' character set.
```
  mysql> SELECT USER();
          -> 'davida@localhost'
```
The value indicates the user name you specified when connecting to the server, and the client host from which you connected. The value can be different from that of 'CURRENT_USER()'.
'VERSION()'

Returns a string that indicates the MySQL server version. The string uses the 'utf8' character set. The value might have a suffix in addition to the version number. See the description of the 'version' system variable in *note server-system-variables::.

This function is unsafe for statement-based replication. A warning is logged if you use this function when 'binlog_format' is set to 'STATEMENT'.
```
  mysql> SELECT VERSION();
          -> '5.7.44-standard'
```

File: manual.info.tmp, Node: spatial-analysis-functions, Next: json-functions, Prev: information-functions, Up: functions