{
"topics": [
{
"keywords": null,
"description": [
{
"para": "\n BIT data type\n \n\n \n data type\n BIT\n \n\n BIT[(M)]"
},
{
"para": "A bit-value type. M indicates the\n number of bits per value, from 1 to 64. The default is 1 if\n M is omitted."
}
],
"id": "BIT",
"syntax": []
},
{
"keywords": [
"BOOLEAN",
"BOOL",
"ZEROFILL",
"UNSIGNED",
"INT1"
],
"description": [
{
"para": "\n TINYINT data type\n \n\n \n data type\n TINYINT\n \n\n TINYINT[(M)]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "A very small integer. The signed range is\n -128 to 127. The\n unsigned range is 0 to\n 255."
}
],
"id": "TINYINT",
"syntax": []
},
{
"keywords": [
"BOOL"
],
"description": [
{
"para": "\n BOOLEAN data type\n \n\n \n BOOL data type\n \n\n \n data type\n BOOLEAN\n \n\n \n data type\n BOOL\n \n\n BOOL,\n BOOLEAN"
},
{
"para": "These types are synonyms for\n TINYINT(1). A value of zero\n is considered false. Nonzero values are considered true:"
},
{
"programlisting": ">\nmysql> SELECT IF(0, 'true', 'false');\n+------------------------+\n| IF(0, 'true', 'false') |\n+------------------------+\n| false |\n+------------------------+\n\nmysql> SELECT IF(1, 'true', 'false');\n+------------------------+\n| IF(1, 'true', 'false') |\n+------------------------+\n| true |\n+------------------------+\n\nmysql> SELECT IF(2, 'true', 'false');\n+------------------------+\n| IF(2, 'true', 'false') |\n+------------------------+\n| true |\n+------------------------+"
},
{
"para": "However, the values TRUE and\n FALSE are merely aliases for\n 1 and 0, respectively,\n as shown here:"
},
{
"programlisting": ">\nmysql> SELECT IF(0 = FALSE, 'true', 'false');\n+--------------------------------+\n| IF(0 = FALSE, 'true', 'false') |\n+--------------------------------+\n| true |\n+--------------------------------+\n\nmysql> SELECT IF(1 = TRUE, 'true', 'false');\n+-------------------------------+\n| IF(1 = TRUE, 'true', 'false') |\n+-------------------------------+\n| true |\n+-------------------------------+\n\nmysql> SELECT IF(2 = TRUE, 'true', 'false');\n+-------------------------------+\n| IF(2 = TRUE, 'true', 'false') |\n+-------------------------------+\n| false |\n+-------------------------------+\n\nmysql> SELECT IF(2 = FALSE, 'true', 'false');\n+--------------------------------+\n| IF(2 = FALSE, 'true', 'false') |\n+--------------------------------+\n| false |\n+--------------------------------+"
},
{
"para": "The last two statements display the results shown because\n 2 is equal to neither\n 1 nor 0."
}
],
"id": "BOOLEAN",
"syntax": []
},
{
"keywords": [
"INT2"
],
"description": [
{
"para": "\n SMALLINT data type\n \n\n \n data type\n SMALLINT\n \n\n SMALLINT[(M)]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "A small integer. The signed range is\n -32768 to 32767. The\n unsigned range is 0 to\n 65535."
}
],
"id": "SMALLINT",
"syntax": []
},
{
"keywords": [
"INT3",
"MIDDLEINT"
],
"description": [
{
"para": "\n MEDIUMINT data type\n \n\n \n data type\n MEDIUMINT\n \n\n MEDIUMINT[(M)]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "A medium-sized integer. The signed range is\n -8388608 to 8388607.\n The unsigned range is 0 to\n 16777215."
}
],
"id": "MEDIUMINT",
"syntax": []
},
{
"keywords": [
"INT4",
"UNSIGNED",
"ZEROFILL",
"INTEGER"
],
"description": [
{
"para": "\n INT data type\n \n\n \n data type\n INT\n \n\n INT[(M)]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "A normal-size integer. The signed range is\n -2147483648 to\n 2147483647. The unsigned range is\n 0 to 4294967295."
}
],
"id": "INT",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n INTEGER data type\n \n\n \n data type\n INTEGER\n \n\n INTEGER[(M)]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "This type is a synonym for\n INT."
}
],
"id": "INTEGER",
"syntax": []
},
{
"keywords": [
"UNSIGNED",
"ZEROFILL",
"INT8"
],
"description": [
{
"para": "\n BIGINT data type\n \n\n \n data type\n BIGINT\n \n\n \n SERIAL\n \n\n BIGINT[(M)]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "A large integer. The signed range is\n -9223372036854775808 to\n 9223372036854775807. The unsigned range\n is 0 to\n 18446744073709551615."
},
{
"para": "SERIAL is an alias for BIGINT\n UNSIGNED NOT NULL AUTO_INCREMENT UNIQUE."
}
],
"id": "BIGINT",
"syntax": []
},
{
"keywords": [
"ZEROFILL",
"UNSIGNED",
"NUMERIC",
"DEC",
"FIXED"
],
"description": [
{
"para": "\n DECIMAL data type\n \n\n \n data type\n DECIMAL\n \n\n DECIMAL[(M[,D])]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "A packed exact fixed-point number.\n M is the total number of digits\n (the precision) and D is the\n number of digits after the decimal point (the scale). The\n decimal point and (for negative numbers) the\n - sign are not counted in\n M. If\n D is 0, values have no decimal\n point or fractional part. The maximum number of digits\n (M) for\n DECIMAL is 65. The maximum\n number of supported decimals (D)\n is 30. If D is omitted, the\n default is 0. If M is omitted,\n the default is 10."
},
{
"para": "UNSIGNED, if specified, disallows\n negative values. As of MySQL 8.0.17, the\n UNSIGNED attribute is deprecated for\n columns of type DECIMAL (and\n any synonyms) and support for it will be removed in a future\n MySQL version. Consider using a simple\n CHECK constraint instead for such\n columns."
},
{
"para": "All basic calculations (+, -, *, /) with\n DECIMAL columns are done with\n a precision of 65 digits."
}
],
"id": "DECIMAL",
"syntax": []
},
{
"keywords": [
"DECIMAL"
],
"description": [
{
"para": "\n DEC data type\n \n\n \n NUMERIC data type\n \n\n \n FIXED data type\n \n\n \n data type\n DEC\n \n\n \n data type\n NUMERIC\n \n\n \n data type\n FIXED\n \n\n DEC[(M[,D])]\n [UNSIGNED] [ZEROFILL],\n NUMERIC[(M[,D])]\n [UNSIGNED] [ZEROFILL],\n FIXED[(M[,D])]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "These types are synonyms for\n DECIMAL. The\n FIXED synonym is available\n for compatibility with other database systems."
}
],
"id": "DEC",
"syntax": []
},
{
"keywords": [
"UNSIGNED",
"ZEROFILL",
"FLOAT4"
],
"description": [
{
"para": "\n FLOAT data type\n \n\n \n data type\n FLOAT\n \n\n FLOAT[(M,D)]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "A small (single-precision) floating-point number.\n Permissible values are -3.402823466E+38\n to -1.175494351E-38,\n 0, and 1.175494351E-38\n to 3.402823466E+38. These are the\n theoretical limits, based on the IEEE standard. The actual\n range might be slightly smaller depending on your hardware\n or operating system."
},
{
"para": "M is the total number of digits\n and D is the number of digits\n following the decimal point. If M\n and D are omitted, values are\n stored to the limits permitted by the hardware. A\n single-precision floating-point number is accurate to\n approximately 7 decimal places."
},
{
"para": "FLOAT(M,D)\n is a nonstandard MySQL extension. As of MySQL 8.0.17, this\n syntax is deprecated and support for it will be removed in a\n future MySQL version."
},
{
"para": "UNSIGNED, if specified, disallows\n negative values. As of MySQL 8.0.17, the\n UNSIGNED attribute is deprecated for\n columns of type FLOAT (and\n any synonyms) and support for it will be removed in a future\n MySQL version. Consider using a simple\n CHECK constraint instead for such\n columns."
},
{
"para": "Using FLOAT might give you\n some unexpected problems because all calculations in MySQL\n are done with double precision. See\n ."
}
],
"id": "FLOAT",
"syntax": []
},
{
"keywords": [
"FLOAT8",
"UNSIGNED",
"ZEROFILL",
"PRECISION",
"REAL"
],
"description": [
{
"para": "\n DOUBLE data type\n \n\n \n FLOAT data type\n \n\n \n data type\n DOUBLE\n \n\n \n data type\n FLOAT\n \n\n DOUBLE[(M,D)]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "A normal-size (double-precision) floating-point number.\n Permissible values are\n -1.7976931348623157E+308 to\n -2.2250738585072014E-308,\n 0, and\n 2.2250738585072014E-308 to\n 1.7976931348623157E+308. These are the\n theoretical limits, based on the IEEE standard. The actual\n range might be slightly smaller depending on your hardware\n or operating system."
},
{
"para": "M is the total number of digits\n and D is the number of digits\n following the decimal point. If M\n and D are omitted, values are\n stored to the limits permitted by the hardware. A\n double-precision floating-point number is accurate to\n approximately 15 decimal places."
},
{
"para": "DOUBLE(M,D)\n is a nonstandard MySQL extension. As of MySQL 8.0.17, this\n syntax is deprecated and support for it will be removed in a\n future MySQL version."
},
{
"para": "UNSIGNED, if specified, disallows\n negative values. As of MySQL 8.0.17, the\n UNSIGNED attribute is deprecated for\n columns of type DOUBLE (and\n any synonyms) and support for it will be removed in a future\n MySQL version. Consider using a simple\n CHECK constraint instead for such\n columns."
}
],
"id": "DOUBLE",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n DOUBLE PRECISION data type\n \n\n \n REAL data type\n \n\n \n data type\n DOUBLE PRECISION\n \n\n \n data type\n REAL\n \n\n DOUBLE\n PRECISION[(M,D)]\n [UNSIGNED] [ZEROFILL],\n REAL[(M,D)]\n [UNSIGNED] [ZEROFILL]"
},
{
"para": "These types are synonyms for\n DOUBLE. Exception: If the\n REAL_AS_FLOAT SQL mode is\n enabled, REAL is a synonym\n for FLOAT rather than\n DOUBLE."
}
],
"id": "DOUBLE PRECISION",
"syntax": []
},
{
"keywords": [
"DATE"
],
"description": [
{
"para": "\n DATE data type\n \n\n \n data type\n DATE\n \n\n DATE"
},
{
"para": "A date. The supported range is\n '1000-01-01' to\n '9999-12-31'. MySQL displays\n DATE values in\n 'YYYY-MM-DD' format, but permits\n assignment of values to DATE\n columns using either strings or numbers."
}
],
"id": "DATE",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n DATETIME data type\n \n\n \n data type\n DATETIME\n \n\n DATETIME[(fsp)]"
},
{
"para": "A date and time combination. The supported range is\n '1000-01-01 00:00:00.000000' to\n '9999-12-31 23:59:59.999999'. MySQL\n displays DATETIME values in\n 'YYYY-MM-DD\n hh:mm:ss[.fraction]'\n format, but permits assignment of values to\n DATETIME columns using either\n strings or numbers."
},
{
"para": "An optional fsp value in the\n range from 0 to 6 may be given to specify fractional seconds\n precision. A value of 0 signifies that there is no\n fractional part. If omitted, the default precision is 0."
},
{
"para": "Automatic initialization and updating to the current date\n and time for DATETIME columns\n can be specified using DEFAULT and\n ON UPDATE column definition clauses, as\n described in ."
}
],
"id": "DATETIME",
"syntax": []
},
{
"keywords": [
"TIMESTAMP"
],
"description": [
{
"para": "\n TIMESTAMP data type\n \n\n \n data type\n TIMESTAMP\n \n\n TIMESTAMP[(fsp)]"
},
{
"para": "A timestamp. The range is '1970-01-01\n 00:00:01.000000' UTC to '2038-01-19\n 03:14:07.999999' UTC.\n TIMESTAMP values are stored\n as the number of seconds since the epoch\n ('1970-01-01 00:00:00' UTC). A\n TIMESTAMP cannot represent\n the value '1970-01-01 00:00:00' because\n that is equivalent to 0 seconds from the epoch and the value\n 0 is reserved for representing '0000-00-00\n 00:00:00', the zero\n TIMESTAMP value."
},
{
"para": "An optional fsp value in the\n range from 0 to 6 may be given to specify fractional seconds\n precision. A value of 0 signifies that there is no\n fractional part. If omitted, the default precision is 0."
},
{
"para": "The way the server handles TIMESTAMP\n definitions depends on the value of the\n explicit_defaults_for_timestamp\n system variable (see\n )."
},
{
"para": "If\n explicit_defaults_for_timestamp\n is enabled, there is no automatic assignment of the\n DEFAULT CURRENT_TIMESTAMP or ON\n UPDATE CURRENT_TIMESTAMP attributes to any\n TIMESTAMP column. They must\n be included explicitly in the column definition. Also, any\n TIMESTAMP not explicitly\n declared as NOT NULL permits\n NULL values."
},
{
"para": "If\n explicit_defaults_for_timestamp\n is disabled, the server handles TIMESTAMP\n as follows:"
},
{
"para": "Unless specified otherwise, the first\n TIMESTAMP column in a table\n is defined to be automatically set to the date and time of\n the most recent modification if not explicitly assigned a\n value. This makes TIMESTAMP\n useful for recording the timestamp of an\n INSERT or\n UPDATE operation. You can\n also set any TIMESTAMP column\n to the current date and time by assigning it a\n NULL value, unless it has been defined\n with the NULL attribute to permit\n NULL values."
},
{
"para": "Automatic initialization and updating to the current date\n and time can be specified using DEFAULT\n CURRENT_TIMESTAMP and ON UPDATE\n CURRENT_TIMESTAMP column definition clauses. By\n default, the first TIMESTAMP\n column has these properties, as previously noted. However,\n any TIMESTAMP column in a\n table can be defined to have these properties."
}
],
"id": "TIMESTAMP",
"syntax": []
},
{
"keywords": [
"TIME"
],
"description": [
{
"para": "\n TIME data type\n \n\n \n data type\n TIME\n \n\n TIME[(fsp)]"
},
{
"para": "A time. The range is '-838:59:59.000000'\n to '838:59:59.000000'. MySQL displays\n TIME values in\n 'hh:mm:ss[.fraction]'\n format, but permits assignment of values to\n TIME columns using either\n strings or numbers."
},
{
"para": "An optional fsp value in the\n range from 0 to 6 may be given to specify fractional seconds\n precision. A value of 0 signifies that there is no\n fractional part. If omitted, the default precision is 0."
}
],
"id": "TIME",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n YEAR data type\n \n\n \n data type\n YEAR\n \n\n YEAR[(4)]"
},
{
"para": "A year in 4-digit format. MySQL displays\n YEAR values in\n YYYY format, but permits assignment of\n values to YEAR columns using\n either strings or numbers. Values display as\n 1901 to 2155, or\n 0000."
},
{
"para": "For additional information about\n YEAR display format and\n interpretation of input values, see ."
}
],
"id": "YEAR data type",
"syntax": []
},
{
"keywords": [
"NATIONAL",
"CHARACTER",
"NCHAR"
],
"description": [
{
"para": "\n CHAR data type\n \n\n \n NATIONAL CHAR data type\n \n\n \n NCHAR data type\n \n\n \n CHARACTER data type\n \n\n \n data type\n CHAR\n \n\n \n data type\n NATIONAL CHAR\n \n\n \n data type\n NCHAR\n \n\n \n data type\n CHARACTER\n \n\n [NATIONAL] CHAR[(M)]\n [CHARACTER SET charset_name]\n [COLLATE\n collation_name]"
},
{
"para": "A fixed-length string that is always right-padded with\n spaces to the specified length when stored.\n M represents the column length in\n characters. The range of M is 0\n to 255. If M is omitted, the\n length is 1."
}
],
"id": "CHAR",
"syntax": []
},
{
"keywords": [
"CHAR",
"BYTE"
],
"description": [
{
"para": "The CHAR BYTE data type is an\n alias for the BINARY data\n type. This is a compatibility feature."
}
],
"id": "CHAR BYTE",
"syntax": []
},
{
"keywords": [
"NATIONAL",
"VARYING",
"CHARACTER",
"VARCHARACTER",
"NVARCHAR"
],
"description": [
{
"para": "\n VARCHAR data type\n \n\n \n CHARACTER VARYING data type\n \n\n \n CHAR VARYING data type\n \n\n \n VARCHARACTER data type\n \n\n \n NATIONAL VARCHAR data type\n \n\n \n NVARCHAR data type\n \n\n \n data type\n VARCHAR\n \n\n \n data type\n CHARACTER VARYING\n \n\n \n data type\n CHAR VARYING\n \n\n \n data type\n VARCHARACTER\n \n\n \n data type\n NATIONAL VARCHAR\n \n\n \n data type\n NVARCHAR\n \n\n [NATIONAL] VARCHAR(M)\n [CHARACTER SET charset_name]\n [COLLATE\n collation_name]"
},
{
"para": "A variable-length string. M\n represents the maximum column length in characters. The\n range of M is 0 to 65,535. The\n effective maximum length of a\n VARCHAR is subject to the\n maximum row size (65,535 bytes, which is shared among all\n columns) and the character set used. For example,\n utf8 characters can require up to three\n bytes per character, so a\n VARCHAR column that uses the\n utf8 character set can be declared to be\n a maximum of 21,844 characters. See\n ."
},
{
"para": "MySQL stores VARCHAR values\n as a 1-byte or 2-byte length prefix plus data. The length\n prefix indicates the number of bytes in the value. A\n VARCHAR column uses one\n length byte if values require no more than 255 bytes, two\n length bytes if values may require more than 255 bytes."
},
{
"para": "VARCHAR is shorthand for\n CHARACTER VARYING.\n NATIONAL VARCHAR is the\n standard SQL way to define that a\n VARCHAR column should use\n some predefined character set. MySQL uses\n utf8 as this predefined character set.\n .\n NVARCHAR is shorthand for\n NATIONAL VARCHAR."
}
],
"id": "VARCHAR",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n BINARY data type\n \n\n \n data type\n BINARY\n \n\n BINARY[(M)]"
},
{
"para": "The BINARY type is similar to\n the CHAR type, but stores\n binary byte strings rather than nonbinary character strings.\n An optional length M represents\n the column length in bytes. If omitted,\n M defaults to 1."
}
],
"id": "BINARY",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n VARBINARY data type\n \n\n \n data type\n VARBINARY\n \n\n VARBINARY(M)"
},
{
"para": "The VARBINARY type is similar\n to the VARCHAR type, but\n stores binary byte strings rather than nonbinary character\n strings. M represents the maximum\n column length in bytes."
}
],
"id": "VARBINARY",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n TINYBLOB data type\n \n\n \n data type\n TINYBLOB\n \n\n TINYBLOB"
},
{
"para": "A BLOB column with a maximum\n length of 255 (28 minus 1)\n bytes. Each TINYBLOB value is\n stored using a 1-byte length prefix that indicates the\n number of bytes in the value."
}
],
"id": "TINYBLOB",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n TINYTEXT data type\n \n\n \n data type\n TINYTEXT\n \n\n TINYTEXT\n [CHARACTER SET charset_name]\n [COLLATE\n collation_name]"
},
{
"para": "A TEXT column with a maximum\n length of 255 (28 minus 1)\n characters. The effective maximum length is less if the\n value contains multibyte characters. Each\n TINYTEXT value is stored\n using a 1-byte length prefix that indicates the number of\n bytes in the value."
}
],
"id": "TINYTEXT",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n BLOB data type\n \n\n \n data type\n BLOB\n \n\n BLOB[(M)]"
},
{
"para": "A BLOB column with a maximum\n length of 65,535 (216 minus 1)\n bytes. Each BLOB value is\n stored using a 2-byte length prefix that indicates the\n number of bytes in the value."
},
{
"para": "An optional length M can be given\n for this type. If this is done, MySQL creates the column as\n the smallest BLOB type large\n enough to hold values M bytes\n long."
}
],
"id": "BLOB",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n TEXT data type\n \n\n \n data type\n TEXT\n \n\n TEXT[(M)]\n [CHARACTER SET charset_name]\n [COLLATE\n collation_name]"
},
{
"para": "A TEXT column with a maximum\n length of 65,535 (216 minus 1)\n characters. The effective maximum length is less if the\n value contains multibyte characters. Each\n TEXT value is stored using a\n 2-byte length prefix that indicates the number of bytes in\n the value."
},
{
"para": "An optional length M can be given\n for this type. If this is done, MySQL creates the column as\n the smallest TEXT type large\n enough to hold values M\n characters long."
}
],
"id": "TEXT",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n MEDIUMBLOB data type\n \n\n \n data type\n MEDIUMBLOB\n \n\n MEDIUMBLOB"
},
{
"para": "A BLOB column with a maximum\n length of 16,777,215 (224 minus\n 1) bytes. Each MEDIUMBLOB\n value is stored using a 3-byte length prefix that indicates\n the number of bytes in the value."
}
],
"id": "MEDIUMBLOB",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n MEDIUMTEXT data type\n \n\n \n data type\n MEDIUMTEXT\n \n\n MEDIUMTEXT\n [CHARACTER SET charset_name]\n [COLLATE\n collation_name]"
},
{
"para": "A TEXT column with a maximum\n length of 16,777,215 (224 minus\n 1) characters. The effective maximum length is less if the\n value contains multibyte characters. Each\n MEDIUMTEXT value is stored\n using a 3-byte length prefix that indicates the number of\n bytes in the value."
}
],
"id": "MEDIUMTEXT",
"syntax": []
},
{
"keywords": [
"LONG",
"LONGBINARY"
],
"description": [
{
"para": "\n LONGBLOB data type\n \n\n \n data type\n LONGBLOB\n \n\n LONGBLOB"
},
{
"para": "A BLOB column with a maximum\n length of 4,294,967,295 or 4GB\n (232 minus 1) bytes. The\n effective maximum length of\n LONGBLOB columns depends on\n the configured maximum packet size in the client/server\n protocol and available memory. Each\n LONGBLOB value is stored\n using a 4-byte length prefix that indicates the number of\n bytes in the value."
}
],
"id": "LONGBLOB",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n LONGTEXT data type\n \n\n \n data type\n LONGTEXT\n \n\n LONGTEXT\n [CHARACTER SET charset_name]\n [COLLATE\n collation_name]"
},
{
"para": "A TEXT column with a maximum\n length of 4,294,967,295 or 4GB\n (232 minus 1) characters. The\n effective maximum length is less if the value contains\n multibyte characters. The effective maximum length of\n LONGTEXT\n columns also depends on the configured maximum packet size\n in the client/server protocol and available memory. Each\n LONGTEXT\n value is stored using a 4-byte length prefix that indicates\n the number of bytes in the value."
}
],
"id": "LONGTEXT",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n ENUM data type\n \n\n \n data type\n ENUM\n \n\n ENUM('value1','value2',...)\n [CHARACTER SET charset_name]\n [COLLATE\n collation_name]"
},
{
"para": "An enumeration. A string object that can have only one\n value, chosen from the list of values\n 'value1',\n 'value2',\n ..., NULL or the\n special '' error value.\n ENUM values are represented\n internally as integers."
},
{
"para": "An ENUM column can have a\n maximum of 65,535 distinct elements."
},
{
"para": "The maximum supported length of an individual\n ENUM element is\n M <= 255 and\n (M x\n w) <= 1020, where\n M is the element literal length and\n w is the number of bytes required\n for the maximum-length character in the character set."
}
],
"id": "ENUM",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n SET data type\n \n\n \n data type\n SET\n \n\n SET('value1','value2',...)\n [CHARACTER SET charset_name]\n [COLLATE\n collation_name]"
},
{
"para": "A set. A string object that can have zero or more values,\n each of which must be chosen from the list of values\n 'value1',\n 'value2',\n ...SET\n values are represented internally as integers."
},
{
"para": "A SET column can have a\n maximum of 64 distinct members."
},
{
"para": "The maximum supported length of an individual\n SET element is\n M <= 255 and\n (M x\n w) <= 1020, where\n M is the element literal length and\n w is the number of bytes required\n for the maximum-length character in the character set."
}
],
"id": "SET data type",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "A BLOB is a binary large object that can hold\n a variable amount of data. The four BLOB\n types are TINYBLOB, BLOB,\n MEDIUMBLOB, and LONGBLOB.\n These differ only in the maximum length of the values they can\n hold. The four TEXT types are\n TINYTEXT, TEXT,\n MEDIUMTEXT, and LONGTEXT.\n These correspond to the four BLOB types and\n have the same maximum lengths and storage requirements. See\n ."
}
],
"id": "BLOB data type",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "Geometry is the base class. It is an\n abstract class. The instantiable subclasses of\n Geometry are restricted to zero-, one-, and\n two-dimensional geometric objects that exist in\n two-dimensional coordinate space. All instantiable geometry\n classes are defined so that valid instances of a geometry\n class are topologically closed (that is, all defined\n geometries include their boundary)."
},
{
"para": "The base Geometry class has subclasses for\n Point, Curve,\n Surface, and\n GeometryCollection:"
},
{
"itemizedlist": [
[
{
"para": "Point represents zero-dimensional\n objects."
}
],
[
{
"para": "Curve represents one-dimensional\n objects, and has subclass LineString,\n with sub-subclasses Line and\n LinearRing."
}
],
[
{
"para": "Surface is designed for two-dimensional\n objects and has subclass Polygon."
}
],
[
{
"para": "GeometryCollection has specialized\n zero-, one-, and two-dimensional collection classes named\n MultiPoint,\n MultiLineString, and\n MultiPolygon for modeling geometries\n corresponding to collections of Points,\n LineStrings, and\n Polygons, respectively.\n MultiCurve and\n MultiSurface are introduced as abstract\n superclasses that generalize the collection interfaces to\n handle Curves and\n Surfaces."
}
]
]
},
{
"para": "Geometry, Curve,\n Surface, MultiCurve, and\n MultiSurface are defined as noninstantiable\n classes. They define a common set of methods for their\n subclasses and are included for extensibility."
},
{
"para": "Point, LineString,\n Polygon,\n GeometryCollection,\n MultiPoint,\n MultiLineString, and\n MultiPolygon are instantiable classes."
}
],
"id": "Geometry hierarchy",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "Its MBR (minimum bounding\n rectangle), or envelope. This is the bounding geometry,\n formed by the minimum and maximum (X,Y) coordinates:"
}
],
"id": "MBR definition",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "MySQL provides a standard way of creating spatial columns for\n geometry types, for example, with CREATE\n TABLE or ALTER TABLE.\n Spatial columns are supported for\n MyISAM,\n InnoDB,\n NDB, and\n ARCHIVE tables. See also the notes\n about spatial indexes under\n ."
},
{
"para": "Columns with a spatial data type can have an SRID attribute, to\n explicitly indicate the spatial reference system (SRS) for\n values stored in the column. For implications of an\n SRID-restricted column, see\n ."
}
],
"id": "Spatial columns",
"syntax": []
},
{
"keywords": [
"INDEX",
"TABLE",
"ALTER",
"CREATE",
"ADD",
"KEY"
],
"description": [
{
"para": "For InnoDB and MyISAM\n tables, MySQL can create spatial indexes using syntax similar to\n that for creating regular indexes, but using the\n SPATIAL keyword. Columns in spatial indexes\n must be declared NOT NULL. The following\n examples demonstrate how to create spatial indexes:"
},
{
"itemizedlist": [
[
{
"para": "With CREATE TABLE:"
},
{
"programlisting": ">\nCREATE TABLE geom (g GEOMETRY NOT NULL SRID 4326, SPATIAL INDEX(g));"
}
],
[
{
"para": "With ALTER TABLE:"
},
{
"programlisting": ">\nCREATE TABLE geom (g GEOMETRY NOT NULL SRID 4326);\nALTER TABLE geom ADD SPATIAL INDEX(g);"
}
],
[
{
"para": "With CREATE INDEX:"
},
{
"programlisting": ">\nCREATE TABLE geom (g GEOMETRY NOT NULL SRID 4326);\nCREATE SPATIAL INDEX g ON geom (g);"
}
]
]
},
{
"para": "SPATIAL INDEX creates an R-tree index. For\n storage engines that support nonspatial indexing of spatial\n columns, the engine creates a B-tree index. A B-tree index on\n spatial values is useful for exact-value lookups, but not for\n range scans."
},
{
"para": "The optimizer can use spatial indexes defined on columns that\n are SRID-restricted. For more information, see\n , and\n ."
},
{
"para": "For more information on indexing spatial columns, see\n ."
},
{
"para": "To drop spatial indexes, use ALTER\n TABLE or DROP INDEX:"
},
{
"itemizedlist": [
[
{
"para": "With ALTER TABLE:"
},
{
"programlisting": ">\nALTER TABLE geom DROP INDEX g;"
}
],
[
{
"para": "With DROP INDEX:"
},
{
"programlisting": ">\nDROP INDEX g ON geom;"
}
]
]
},
{
"para": "Example: Suppose that a table geom contains\n more than 32,000 geometries, which are stored in the column\n g of type GEOMETRY. The\n table also has an AUTO_INCREMENT column\n fid for storing object ID values."
}
],
"id": "SPATIAL indexes",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n = (equal)\n \n\n \n equal (=)\n \n\n ="
},
{
"para": "Equal:"
}
],
"id": "=",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "NULL-safe equal. This operator performs\n an equality comparison like the\n = operator,\n but returns 1 rather than\n NULL if both operands are\n NULL, and 0 rather\n than NULL if one operand is\n NULL."
},
{
"para": "The\n <=>\n operator is equivalent to the standard SQL IS NOT\n DISTINCT FROM operator."
}
],
"id": "<=>",
"syntax": [
{
"para": "\n NULL\n testing for null\n \n\n \n <=> (equal to)\n \n\n <=>"
}
]
},
{
"keywords": [
"<>"
],
"description": [
{
"para": "Not equal:"
}
],
"id": "!=",
"syntax": [
{
"para": "\n <> (not equal)\n \n\n \n not equal (<>)\n \n\n \n != (not equal)\n \n\n \n not equal (!=)\n \n\n <>,\n !="
}
]
},
{
"keywords": null,
"description": [
{
"para": "Less than or equal:"
}
],
"id": "<=",
"syntax": [
{
"para": "\n <= (less than or equal)\n \n\n \n less than or equal (<=)\n \n\n <="
}
]
},
{
"keywords": null,
"description": [
{
"para": "Less than:"
}
],
"id": "<",
"syntax": [
{
"para": "\n < (less than)\n \n\n \n less than (<)\n \n\n <"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Greater than or equal:"
}
],
"id": ">=",
"syntax": [
{
"para": "\n >= (greater than or equal)\n \n\n \n greater than or equal (>=)\n \n\n >="
}
]
},
{
"keywords": null,
"description": [
{
"para": "Greater than:"
}
],
"id": ">",
"syntax": [
{
"para": "\n > (greater than)\n \n\n \n greater than (>)\n \n\n >"
}
]
},
{
"keywords": [
"BETWEEN",
"AND"
],
"description": [
{
"para": "If expr is greater than or equal\n to min and\n expr is less than or equal to\n max,\n BETWEEN returns\n 1, otherwise it returns\n 0. This is equivalent to the expression\n (min <=\n expr AND\n expr <=\n max) if all the\n arguments are of the same type. Otherwise type conversion\n takes place according to the rules described in\n , but applied to all the\n three arguments."
}
],
"id": "BETWEEN AND",
"syntax": [
{
"para": "\n BETWEEN ... AND\n \n\n expr\n BETWEEN min AND\n max"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is the same as NOT\n (expr BETWEEN\n min AND\n max)."
}
],
"id": "NOT BETWEEN",
"syntax": [
{
"para": "\n NOT BETWEEN\n \n\n expr\n NOT BETWEEN min AND\n max"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the first non-NULL value in the\n list, or NULL if there are no\n non-NULL values."
},
{
"para": "The return type of COALESCE()\n is the aggregated type of the argument types."
}
],
"id": "COALESCE",
"syntax": [
{
"para": "\n NULL\n testing for null\n \n\n \n COALESCE()\n \n\n COALESCE(value,...)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "With two or more arguments, returns the largest\n (maximum-valued) argument. The arguments are compared using\n the same rules as for\n LEAST()."
}
],
"id": "GREATEST",
"syntax": [
{
"para": "\n GREATEST()\n \n\n GREATEST(value1,value2,...)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns 1 (true) if\n expr is equal to any of the\n values in the IN() list, else returns\n 0 (false)."
},
{
"para": "Type conversion takes place according to the rules described\n in , applied to all the\n arguments. If no type conversion is needed for the values in\n the IN() list, they are all\n non-JSON constants of the same type, and\n expr can be compared to each of\n them as a value of the same type (possibly after type\n conversion), an optimization takes place. The values the\n list are sorted and the search for\n expr is done using a binary\n search, which makes the IN() operation\n very quick."
}
],
"id": "IN",
"syntax": [
{
"para": "\n IN()\n \n\n expr\n IN (value,...)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is the same as NOT\n (expr IN\n (value,...))."
}
],
"id": "NOT IN",
"syntax": [
{
"para": "\n NOT IN\n \n\n expr\n NOT IN (value,...)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns 0 if N\n < N1, 1 if\n N <\n N2 and so on or\n -1 if N is\n NULL. All arguments are treated as\n integers. It is required that N1\n < N2 <\n N3 < ...\n < Nn for this function to work\n correctly. This is because a binary search is used (very\n fast)."
}
],
"id": "INTERVAL",
"syntax": [
{
"para": "\n INTERVAL()\n \n\n INTERVAL(N,N1,N2,N3,...)"
}
]
},
{
"keywords": [
"IS"
],
"description": [
{
"para": "Tests a value against a boolean value, where\n boolean_value can be\n TRUE, FALSE, or\n UNKNOWN."
}
],
"id": "IS",
"syntax": [
{
"para": "\n TRUE\n testing for\n \n\n \n FALSE\n testing for\n \n\n \n UNKNOWN\n testing for\n \n\n \n IS boolean_value\n \n\n IS\n boolean_value"
}
]
},
{
"keywords": [
"IS",
"NOT"
],
"description": [
{
"para": "Tests a value against a boolean value, where\n boolean_value can be\n TRUE, FALSE, or\n UNKNOWN."
}
],
"id": "IS NOT",
"syntax": [
{
"para": "\n TRUE\n testing for\n \n\n \n FALSE\n testing for\n \n\n \n UNKNOWN\n testing for\n \n\n \n IS NOT boolean_value\n \n\n IS NOT\n boolean_value"
}
]
},
{
"keywords": [
"IS",
"NULL"
],
"description": [
{
"para": "Tests whether a value is NULL."
}
],
"id": "IS NULL",
"syntax": [
{
"para": "\n NULL\n testing for null\n \n\n \n IS NULL\n \n\n IS NULL"
}
]
},
{
"keywords": [
"IS",
"NOT",
"NULL"
],
"description": [
{
"para": "Tests whether a value is not NULL."
}
],
"id": "IS NOT NULL",
"syntax": [
{
"para": "\n NULL\n testing for null\n \n\n \n IS NOT NULL\n \n\n IS NOT NULL"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If expr is\n NULL,\n ISNULL() returns\n 1, otherwise it returns\n 0."
}
],
"id": "ISNULL",
"syntax": [
{
"para": "\n ISNULL()\n \n\n ISNULL(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "With two or more arguments, returns the smallest\n (minimum-valued) argument. The arguments are compared using\n the following rules:"
},
{
"itemizedlist": [
[
{
"para": "If any argument is NULL, the result\n is NULL. No comparison is needed."
}
],
[
{
"para": "If all arguments are integer-valued, they are compared\n as integers."
}
],
[
{
"para": "If at least one argument is double precision, they are\n compared as double-precision values. Otherwise, if at\n least one argument is a\n DECIMAL value, they are\n compared as DECIMAL\n values."
}
],
[
{
"para": "If the arguments comprise a mix of numbers and strings,\n they are compared as strings."
}
],
[
{
"para": "If any argument is a nonbinary (character) string, the\n arguments are compared as nonbinary strings."
}
],
[
{
"para": "In all other cases, the arguments are compared as binary\n strings."
}
]
]
},
{
"para": "The return type of LEAST() is\n the aggregated type of the comparison argument types."
}
],
"id": "LEAST",
"syntax": [
{
"para": "\n LEAST()\n \n\n LEAST(value1,value2,...)"
}
]
},
{
"keywords": [
"NOT"
],
"description": [
{
"para": "Logical NOT. Evaluates to 1 if the\n operand is 0, to 0 if\n the operand is nonzero, and NOT NULL\n returns NULL."
}
],
"id": "!",
"syntax": [
{
"para": "\n NOT\n logical\n \n\n \n ! (logical NOT)\n \n\n NOT,\n !"
}
]
},
{
"keywords": [
"AND"
],
"description": [
{
"para": "Logical AND. Evaluates to 1 if all\n operands are nonzero and not NULL, to\n 0 if one or more operands are\n 0, otherwise NULL is\n returned."
}
],
"id": "AND",
"syntax": [
{
"para": "\n AND\n logical\n \n\n \n && (logical AND)\n \n\n AND,\n &&"
}
]
},
{
"keywords": [
"OR"
],
"description": [
{
"para": "Logical OR. When both operands are\n non-NULL, the result is\n 1 if any operand is nonzero, and\n 0 otherwise. With a\n NULL operand, the result is\n 1 if the other operand is nonzero, and\n NULL otherwise. If both operands are\n NULL, the result is\n NULL."
}
],
"id": "OR",
"syntax": [
{
"para": "\n OR\n logical\n \n\n \n || (logical OR)\n \n\n OR,\n ||"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Logical XOR. Returns NULL if either\n operand is NULL. For\n non-NULL operands, evaluates to\n 1 if an odd number of operands is\n nonzero, otherwise 0 is returned."
}
],
"id": "XOR",
"syntax": [
{
"para": "\n XOR\n logical\n \n\n XOR"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Assignment operator. Causes the user variable on the left\n hand side of the operator to take on the value to its right.\n The value on the right hand side may be a literal value,\n another variable storing a value, or any legal expression\n that yields a scalar value, including the result of a query\n (provided that this value is a scalar value). You can\n perform multiple assignments in the same\n SET\n statement. You can perform multiple assignments in the same\n statement."
},
{
"para": "Unlike\n =, the\n :=\n operator is never interpreted as a comparison operator. This\n means you can use\n := in\n any valid SQL statement (not just in\n SET\n statements) to assign a value to a variable."
}
],
"id": "assign-value",
"syntax": [
{
"para": "\n := (assignment operator)\n \n\n \n assignment operator\n :=\n \n\n :="
}
]
},
{
"keywords": null,
"description": [
{
"para": "This operator is used to perform value assignments in two\n cases, described in the next two paragraphs."
},
{
"para": "Within a\n SET\n statement, = is treated as an assignment\n operator that causes the user variable on the left hand side\n of the operator to take on the value to its right. (In other\n words, when used in a\n SET\n statement, = is treated identically to\n :=.)\n The value on the right hand side may be a literal value,\n another variable storing a value, or any legal expression\n that yields a scalar value, including the result of a query\n (provided that this value is a scalar value). You can\n perform multiple assignments in the same\n SET\n statement."
},
{
"para": "In the SET clause of an\n UPDATE statement,\n = also acts as an assignment operator; in\n this case, however, it causes the column named on the left\n hand side of the operator to assume the value given to the\n right, provided any WHERE conditions that\n are part of the UPDATE are\n met. You can make multiple assignments in the same\n SET clause of an\n UPDATE statement."
},
{
"para": "In any other context, = is treated as a\n comparison operator."
}
],
"id": "assign-equal",
"syntax": [
{
"para": "\n = (assignment operator)\n \n\n \n assignment operator\n =\n \n\n \n SET statement\n assignment operator\n \n\n ="
}
]
},
{
"keywords": [
"CASE",
"WHEN",
"THEN",
"ELSE",
"END"
],
"description": [
{
"para": "The first CASE syntax returns the\n result for the first\n value=compare_value\n comparison that is true. The second syntax returns the result\n for the first condition that is true. If no comparison or\n condition is true, the result after ELSE is\n returned, or NULL if there is no\n ELSE part."
},
{
"para": "The return type of a CASE\n expression result is the aggregated type of all result values:"
},
{
"itemizedlist": [
[
{
"para": "If all types are numeric, the aggregated type is also\n numeric:"
},
{
"itemizedlist": [
[
{
"para": "If at least one argument is double precision, the\n result is double precision."
}
],
[
{
"para": "Otherwise, if at least one argument is\n DECIMAL, the result is\n DECIMAL."
}
],
[
{
"para": "Otherwise, the result is an integer type (with one\n exception):"
},
{
"itemizedlist": [
[
{
"para": "If all integer types are all signed or all\n unsigned, the result is the same sign and the\n precision is the highest of all specified integer\n types (that is,\n TINYINT,\n SMALLINT,\n MEDIUMINT,\n INT, or\n BIGINT)."
}
],
[
{
"para": "If there is a combination of signed and unsigned\n integer types, the result is signed and the\n precision may be higher. For example, if the types\n are signed INT and\n unsigned INT, the\n result is signed\n BIGINT."
}
],
[
{
"para": "The exception is unsigned\n BIGINT combined\n with any signed integer type. The result is\n DECIMAL with\n sufficient precision and scale 0."
}
]
]
}
]
]
}
],
[
{
"para": "If all types are BIT, the\n result is BIT. Otherwise,\n BIT arguments are treated\n similar to BIGINT."
}
],
[
{
"para": "If all types are YEAR, the\n result is YEAR. Otherwise,\n YEAR arguments are treated similar to\n INT."
}
],
[
{
"para": "If all types are character string\n (CHAR or\n VARCHAR), the result is\n VARCHAR with maximum length\n determined by the longest character length of the\n operands."
}
],
[
{
"para": "If all types are character or binary string, the result is\n VARBINARY."
}
],
[
{
"para": "SET and\n ENUM are treated similar to\n VARCHAR; the result is\n VARCHAR."
}
],
[
{
"para": "If all types are JSON, the\n result is JSON."
}
],
[
{
"para": "If all types are temporal, the result is temporal:"
},
{
"itemizedlist": [
[
{
"para": "If all temporal types are\n DATE,\n TIME, or\n TIMESTAMP, the result\n is DATE,\n TIME, or\n TIMESTAMP,\n respectively."
}
],
[
{
"para": "Otherwise, for a mix of temporal types, the result is\n DATETIME."
}
]
]
}
],
[
{
"para": "If all types are GEOMETRY, the result\n is GEOMETRY."
}
],
[
{
"para": "If any type is BLOB, the\n result is BLOB."
}
],
[
{
"para": "For all other type combinations, the result is\n VARCHAR."
}
],
[
{
"para": "Literal NULL operands are ignored for\n type aggregation."
}
]
]
}
],
"id": "CASE operator",
"syntax": [
{
"para": "\n CASE\n \n\n CASE\n value WHEN\n [compare_value] THEN\n result [WHEN\n [compare_value] THEN\n result ...] [ELSE\n result] END"
},
{
"para": "CASE WHEN\n [condition] THEN\n result [WHEN\n [condition] THEN\n result ...] [ELSE\n result] END"
}
]
},
{
"keywords": [
"IF"
],
"description": [
{
"para": "If expr1 is TRUE\n (expr1 <>\n 0 and expr1\n <> NULL), IF()\n returns expr2. Otherwise, it\n returns expr3."
},
{
"para": "If only one of expr2 or\n expr3 is explicitly\n NULL, the result type of the\n IF() function is the type of\n the non-NULL expression."
},
{
"para": "The default return type of IF()\n (which may matter when it is stored into a temporary table) is\n calculated as follows:"
},
{
"itemizedlist": [
[
{
"para": "If expr2 or\n expr3 produce a string, the\n result is a string."
},
{
"para": "If expr2 and\n expr3 are both strings, the\n result is case-sensitive if either string is case\n sensitive."
}
],
[
{
"para": "If expr2 or\n expr3 produce a floating-point\n value, the result is a floating-point value."
}
],
[
{
"para": "If expr2 or\n expr3 produce an integer, the\n result is an integer."
}
]
]
}
],
"id": "IF function",
"syntax": [
{
"para": "\n IF()\n \n\n IF(expr1,expr2,expr3)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If expr1 is not\n NULL,\n IFNULL() returns\n expr1; otherwise it returns\n expr2."
}
],
"id": "IFNULL",
"syntax": [
{
"para": "\n NULL\n testing for null\n \n\n \n IFNULL()\n \n\n IFNULL(expr1,expr2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns NULL if\n expr1 =\n expr2 is true, otherwise\n returns expr1. This is the same as\n CASE WHEN\n expr1 =\n expr2 THEN NULL ELSE\n expr1 END."
},
{
"para": "The return value has the same type as the first argument."
}
],
"id": "NULLIF",
"syntax": [
{
"para": "\n NULLIF()\n \n\n NULLIF(expr1,expr2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the numeric value of the leftmost character of the\n string str. Returns\n 0 if str is the\n empty string. Returns NULL if\n str is NULL.\n ASCII() works for 8-bit\n characters."
}
],
"id": "ASCII",
"syntax": [
{
"para": "\n ASCII()\n \n\n ASCII(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string representation of the binary value of\n N, where\n N is a longlong\n (BIGINT) number. This is\n equivalent to\n CONV(N,10,2).\n Returns NULL if\n N is NULL."
}
],
"id": "BIN",
"syntax": [
{
"para": "\n BIN()\n \n\n BIN(N)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the length of the string\n str in bits."
}
],
"id": "BIT_LENGTH",
"syntax": [
{
"para": "\n BIT_LENGTH()\n \n\n BIT_LENGTH(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "By default, CHAR() returns a\n binary string. To produce a string in a given character set,\n use the optional USING clause:"
},
{
"programlisting": ">\nmysql> SELECT CHARSET(CHAR(X'65')), CHARSET(CHAR(X'65' USING utf8));\n+----------------------+---------------------------------+\n| CHARSET(CHAR(X'65')) | CHARSET(CHAR(X'65' USING utf8)) |\n+----------------------+---------------------------------+\n| binary | utf8 |\n+----------------------+---------------------------------+"
},
{
"para": "If USING is given and the result string is\n illegal for the given character set, a warning is issued.\n Also, if strict SQL mode is enabled, the result from\n CHAR() becomes\n NULL."
}
],
"id": "CHAR function",
"syntax": [
{
"para": "\n CHAR()\n \n\n CHAR(N,...\n [USING charset_name])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the length of the string\n str, measured in characters. A\n multibyte character counts as a single character. This means\n that for a string containing five 2-byte characters,\n LENGTH() returns\n 10, whereas\n CHAR_LENGTH() returns\n 5."
}
],
"id": "CHAR_LENGTH",
"syntax": [
{
"para": "\n CHAR_LENGTH()\n \n\n CHAR_LENGTH(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "CHARACTER_LENGTH() is a synonym\n for CHAR_LENGTH()."
}
],
"id": "CHARACTER_LENGTH",
"syntax": [
{
"para": "\n CHARACTER_LENGTH()\n \n\n CHARACTER_LENGTH(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string that results from concatenating the\n arguments. May have one or more arguments. If all arguments\n are nonbinary strings, the result is a nonbinary string. If\n the arguments include any binary strings, the result is a\n binary string. A numeric argument is converted to its\n equivalent nonbinary string form."
},
{
"para": "CONCAT() returns\n NULL if any argument is\n NULL."
}
],
"id": "CONCAT",
"syntax": [
{
"para": "\n CONCAT()\n \n\n \n string concatenation\n \n\n \n concatenation\n string\n \n\n CONCAT(str1,str2,...)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "CONCAT_WS() stands for\n Concatenate With Separator and is a special form of\n CONCAT(). The first argument is\n the separator for the rest of the arguments. The separator is\n added between the strings to be concatenated. The separator\n can be a string, as can the rest of the arguments. If the\n separator is NULL, the result is\n NULL."
}
],
"id": "CONCAT_WS",
"syntax": [
{
"para": "\n CONCAT_WS()\n \n\n CONCAT_WS(separator,str1,str2,...)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "ELT() returns the\n Nth element of the list of strings:\n str1 if\n N = 1,\n str2 if\n N = 2, and so\n on. Returns NULL if\n N is less than 1\n or greater than the number of arguments.\n ELT() is the complement of\n FIELD()."
}
],
"id": "ELT",
"syntax": [
{
"para": "\n ELT()\n \n\n ELT(N,str1,str2,str3,...)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string such that for every bit set in the value\n bits, you get an\n on string and for every bit not set\n in the value, you get an off\n string. Bits in bits are examined\n from right to left (from low-order to high-order bits).\n Strings are added to the result from left to right, separated\n by the separator string (the\n default being the comma character ,). The\n number of bits examined is given by\n number_of_bits, which has a default\n of 64 if not specified.\n number_of_bits is silently clipped\n to 64 if larger than 64. It is treated as an unsigned integer,\n so a value of minus1 is effectively the same as 64."
}
],
"id": "EXPORT_SET",
"syntax": [
{
"para": "\n EXPORT_SET()\n \n\n EXPORT_SET(bits,on,off[,separator[,number_of_bits]])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the index (position) of str\n in the str1,\n str2,\n str3, ... list.\n Returns 0 if str\n is not found."
},
{
"para": "If all arguments to FIELD() are\n strings, all arguments are compared as strings. If all\n arguments are numbers, they are compared as numbers.\n Otherwise, the arguments are compared as double."
},
{
"para": "If str is NULL,\n the return value is 0 because\n NULL fails equality comparison with any\n value. FIELD() is the\n complement of ELT()."
}
],
"id": "FIELD",
"syntax": [
{
"para": "\n FIELD()\n \n\n FIELD(str,str1,str2,str3,...)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a value in the range of 1 to\n N if the string\n str is in the string list\n strlist consisting of\n N substrings. A string list is a\n string composed of substrings separated by\n , characters. If the first argument is a\n constant string and the second is a column of type\n SET, the\n FIND_IN_SET() function is\n optimized to use bit arithmetic. Returns 0\n if str is not in\n strlist or if\n strlist is the empty string.\n Returns NULL if either argument is\n NULL. This function does not work properly\n if the first argument contains a comma (,)\n character."
}
],
"id": "FIND_IN_SET",
"syntax": [
{
"para": "\n FIND_IN_SET()\n \n\n FIND_IN_SET(str,strlist)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Formats the number X to a format\n like '#,###,###.##', rounded to\n D decimal places, and returns the\n result as a string. If D is\n 0, the result has no decimal point or\n fractional part."
},
{
"para": "The optional third parameter enables a locale to be specified\n to be used for the result number's decimal point, thousands\n separator, and grouping between separators. Permissible locale\n values are the same as the legal values for the\n lc_time_names system variable\n (see ). If no locale is\n specified, the default is 'en_US'."
}
],
"id": "FORMAT",
"syntax": [
{
"para": "\n FORMAT()\n \n\n FORMAT(X,D[,locale])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Takes a string encoded with the base-64 encoded rules used by\n TO_BASE64() and returns the\n decoded result as a binary string. The result is\n NULL if the argument is\n NULL or not a valid base-64 string. See the\n description of TO_BASE64() for\n details about the encoding and decoding rules."
}
],
"id": "FROM_BASE64",
"syntax": [
{
"para": "\n FROM_BASE64()\n \n\n FROM_BASE64(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "For a string argument str,\n HEX() returns a hexadecimal\n string representation of str where\n each byte of each character in str\n is converted to two hexadecimal digits. (Multibyte characters\n therefore become more than two digits.) The inverse of this\n operation is performed by the\n UNHEX() function."
},
{
"para": "For a numeric argument N,\n HEX() returns a hexadecimal\n string representation of the value of\n N treated as a longlong\n (BIGINT) number. This is\n equivalent to\n CONV(N,10,16).\n The inverse of this operation is performed by\n CONV(HEX(N),16,10)."
}
],
"id": "HEX",
"syntax": [
{
"para": "\n HEX()\n \n\n HEX(str),\n HEX(N)"
}
]
},
{
"keywords": [
"INSERT"
],
"description": [
{
"para": "Returns the string str, with the\n substring beginning at position pos\n and len characters long replaced by\n the string newstr. Returns the\n original string if pos is not\n within the length of the string. Replaces the rest of the\n string from position pos if\n len is not within the length of the\n rest of the string. Returns NULL if any\n argument is NULL."
}
],
"id": "INSERT function",
"syntax": [
{
"para": "\n INSERT()\n \n\n INSERT(str,pos,len,newstr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the position of the first occurrence of substring\n substr in string\n str. This is the same as the\n two-argument form of LOCATE(),\n except that the order of the arguments is reversed."
}
],
"id": "INSTR",
"syntax": [
{
"para": "\n INSTR()\n \n\n INSTR(str,substr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "LCASE() is a synonym for\n LOWER()."
}
],
"id": "LCASE",
"syntax": [
{
"para": "\n LCASE()\n \n\n LCASE(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the leftmost len characters\n from the string str, or\n NULL if any argument is\n NULL."
}
],
"id": "LEFT",
"syntax": [
{
"para": "\n LEFT()\n \n\n LEFT(str,len)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the length of the string\n str, measured in bytes. A multibyte\n character counts as multiple bytes. This means that for a\n string containing five 2-byte characters,\n LENGTH() returns\n 10, whereas\n CHAR_LENGTH() returns\n 5."
}
],
"id": "LENGTH",
"syntax": [
{
"para": "\n LENGTH()\n \n\n LENGTH(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Reads the file and returns the file contents as a string. To\n use this function, the file must be located on the server\n host, you must specify the full path name to the file, and you\n must have the FILE privilege.\n The file must be readable by the server and its size less than\n max_allowed_packet bytes. If\n the secure_file_priv system\n variable is set to a nonempty directory name, the file to be\n loaded must be located in that directory. (Prior to MySQL\n 8.0.17, the file must be readable by all, not just readable by\n the server.)"
},
{
"para": "If the file does not exist or cannot be read because one of\n the preceding conditions is not satisfied, the function\n returns NULL."
},
{
"para": "The character_set_filesystem\n system variable controls interpretation of file names that are\n given as literal strings."
}
],
"id": "LOAD_FILE",
"syntax": [
{
"para": "\n FILE\n \n\n \n LOAD_FILE()\n \n\n LOAD_FILE(file_name)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "The first syntax returns the position of the first occurrence\n of substring substr in string\n str. The second syntax returns the\n position of the first occurrence of substring\n substr in string\n str, starting at position\n pos. Returns 0\n if substr is not in\n str. Returns\n NULL if any argument is\n NULL."
}
],
"id": "LOCATE",
"syntax": [
{
"para": "\n LOCATE()\n \n\n LOCATE(substr,str),\n LOCATE(substr,str,pos)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string str with all\n characters changed to lowercase according to the current\n character set mapping. The default is\n utf8mb4."
},
{
"programlisting": ">\nmysql> SELECT LOWER('QUADRATICALLY');\n -> 'quadratically'"
},
{
"para": "LOWER() (and\n UPPER()) are ineffective when\n applied to binary strings\n (BINARY,\n VARBINARY,\n BLOB). To perform lettercase\n conversion, convert the string to a nonbinary string:"
},
{
"programlisting": ">\nmysql> SET @str = BINARY 'New York';\nmysql> SELECT LOWER(@str), LOWER(CONVERT(@str USING utf8mb4));\n+-------------+------------------------------------+\n| LOWER(@str) | LOWER(CONVERT(@str USING utf8mb4)) |\n+-------------+------------------------------------+\n| New York | new york |\n+-------------+------------------------------------+"
},
{
"para": "For collations of Unicode character sets,\n LOWER() and\n UPPER() work according to the\n Unicode Collation Algorithm (UCA) version in the collation\n name, if there is one, and UCA 4.0.0 if no version is\n specified. For example, utf8mb4_0900_ai_ci\n and utf8_unicode_520_ci work according to\n UCA 9.0.0 and 5.2.0, respectively, whereas\n utf8_unicode_ci works according to UCA\n 4.0.0. See ."
}
],
"id": "LOWER",
"syntax": [
{
"para": "\n LOWER()\n \n\n LOWER(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string str, left-padded\n with the string padstr to a length\n of len characters. If\n str is longer than\n len, the return value is shortened\n to len characters."
}
],
"id": "LPAD",
"syntax": [
{
"para": "\n LPAD()\n \n\n LPAD(str,len,padstr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string str with leading\n space characters removed."
}
],
"id": "LTRIM",
"syntax": [
{
"para": "\n LTRIM()\n \n\n LTRIM(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a set value (a string containing substrings separated\n by , characters) consisting of the strings\n that have the corresponding bit in\n bits set.\n str1 corresponds to bit 0,\n str2 to bit 1, and so on.\n NULL values in\n str1,\n str2, ... are\n not appended to the result."
}
],
"id": "MAKE_SET",
"syntax": [
{
"para": "\n MAKE_SET()\n \n\n MAKE_SET(bits,str1,str2,...)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "MID(str,pos,len)\n is a synonym for\n SUBSTRING(str,pos,len)."
}
],
"id": "MID",
"syntax": [
{
"para": "\n MID()\n \n\n MID(str,pos,len)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string representation of the octal value of\n N, where\n N is a longlong\n (BIGINT) number. This is\n equivalent to\n CONV(N,10,8).\n Returns NULL if\n N is NULL."
}
],
"id": "OCT",
"syntax": [
{
"para": "\n OCT()\n \n\n OCT(N)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "OCTET_LENGTH() is a synonym for\n LENGTH()."
}
],
"id": "OCTET_LENGTH",
"syntax": [
{
"para": "\n OCTET_LENGTH()\n \n\n OCTET_LENGTH(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If the leftmost character of the string\n str is a multibyte character,\n returns the code for that character, calculated from the\n numeric values of its constituent bytes using this formula:"
},
{
"programlisting": ">\n (1st byte code)\n+ (2nd byte code * 256)\n+ (3rd byte code * 256^2) ..."
},
{
"para": "If the leftmost character is not a multibyte character,\n ORD() returns the same value as\n the ASCII() function."
}
],
"id": "ORD",
"syntax": [
{
"para": "\n ORD()\n \n\n ORD(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "POSITION(substr\n IN str) is a synonym for\n LOCATE(substr,str)."
}
],
"id": "POSITION",
"syntax": [
{
"para": "\n POSITION()\n \n\n POSITION(substr\n IN str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Quotes a string to produce a result that can be used as a\n properly escaped data value in an SQL statement. The string is\n returned enclosed by single quotation marks and with each\n instance of backslash (\\), single quote\n ('), ASCII NUL, and\n Control+Z preceded by a backslash. If the argument is\n NULL, the return value is the word\n NULL without enclosing single quotation marks."
}
],
"id": "QUOTE",
"syntax": [
{
"para": "\n QUOTE()\n \n\n QUOTE(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string consisting of the string\n str repeated\n count times. If\n count is less than 1, returns an\n empty string. Returns NULL if\n str or\n count are NULL."
}
],
"id": "REPEAT function",
"syntax": [
{
"para": "\n REPEAT()\n \n\n REPEAT(str,count)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string str with all\n occurrences of the string from_str\n replaced by the string to_str.\n REPLACE() performs a\n case-sensitive match when searching for\n from_str."
}
],
"id": "REPLACE function",
"syntax": [
{
"para": "\n REPLACE()\n \n\n REPLACE(str,from_str,to_str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string str with the\n order of the characters reversed."
}
],
"id": "REVERSE",
"syntax": [
{
"para": "\n REVERSE()\n \n\n REVERSE(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the rightmost len\n characters from the string str, or\n NULL if any argument is\n NULL."
}
],
"id": "RIGHT",
"syntax": [
{
"para": "\n RIGHT()\n \n\n RIGHT(str,len)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string str,\n right-padded with the string padstr\n to a length of len characters. If\n str is longer than\n len, the return value is shortened\n to len characters."
}
],
"id": "RPAD",
"syntax": [
{
"para": "\n RPAD()\n \n\n RPAD(str,len,padstr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string str with\n trailing space characters removed."
}
],
"id": "RTRIM",
"syntax": [
{
"para": "\n RTRIM()\n \n\n RTRIM(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a soundex string from str.\n Two strings that sound almost the same should have identical\n soundex strings. A standard soundex string is four characters\n long, but the SOUNDEX()\n function returns an arbitrarily long string. You can use\n SUBSTRING() on the result to\n get a standard soundex string. All nonalphabetic characters in\n str are ignored. All international\n alphabetic characters outside the A-Z range are treated as\n vowels."
},
{
"itemizedlist": [
[
{
"para": "This function, as currently implemented, is intended to\n work well with strings that are in the English language\n only. Strings in other languages may not produce reliable\n results."
}
],
[
{
"para": "This function is not guaranteed to provide consistent\n results with strings that use multibyte character sets,\n including utf-8. See Bug #22638 for\n more information."
}
]
]
}
],
"id": "SOUNDEX",
"syntax": [
{
"para": "\n SOUNDEX()\n \n\n SOUNDEX(str)"
}
]
},
{
"keywords": [
"SOUNDS",
"LIKE"
],
"description": [
{
"para": "This is the same as\n SOUNDEX(expr1)\n = SOUNDEX(expr2)."
}
],
"id": "SOUNDS LIKE",
"syntax": [
{
"para": "\n SOUNDS LIKE\n \n\n expr1\n SOUNDS LIKE expr2"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string consisting of N\n space characters."
}
],
"id": "SPACE",
"syntax": [
{
"para": "\n SPACE()\n \n\n SPACE(N)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "SUBSTR() is a synonym for\n SUBSTRING()."
}
],
"id": "SUBSTR",
"syntax": [
{
"para": "\n SUBSTR()\n \n\n SUBSTR(str,pos),\n SUBSTR(str\n FROM pos),\n SUBSTR(str,pos,len),\n SUBSTR(str\n FROM pos FOR\n len)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "The forms without a len argument\n return a substring from string str\n starting at position pos. The forms\n with a len argument return a\n substring len characters long from\n string str, starting at position\n pos. The forms that use\n FROM are standard SQL syntax. It is also\n possible to use a negative value for\n pos. In this case, the beginning of\n the substring is pos characters\n from the end of the string, rather than the beginning. A\n negative value may be used for pos\n in any of the forms of this function. A value of 0 for\n pos returns an empty string."
},
{
"para": "For all forms of SUBSTRING(),\n the position of the first character in the string from which\n the substring is to be extracted is reckoned as\n 1."
}
],
"id": "SUBSTRING",
"syntax": [
{
"para": "\n SUBSTRING()\n \n\n SUBSTRING(str,pos),\n SUBSTRING(str\n FROM pos),\n SUBSTRING(str,pos,len),\n SUBSTRING(str\n FROM pos FOR\n len)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the substring from string\n str before\n count occurrences of the delimiter\n delim. If\n count is positive, everything to\n the left of the final delimiter (counting from the left) is\n returned. If count is negative,\n everything to the right of the final delimiter (counting from\n the right) is returned.\n SUBSTRING_INDEX() performs a\n case-sensitive match when searching for\n delim."
}
],
"id": "SUBSTRING_INDEX",
"syntax": [
{
"para": "\n SUBSTRING_INDEX()\n \n\n SUBSTRING_INDEX(str,delim,count)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Converts the string argument to base-64 encoded form and\n returns the result as a character string with the connection\n character set and collation. If the argument is not a string,\n it is converted to a string before conversion takes place. The\n result is NULL if the argument is\n NULL. Base-64 encoded strings can be\n decoded using the FROM_BASE64()\n function."
}
],
"id": "TO_BASE64",
"syntax": [
{
"para": "\n TO_BASE64()\n \n\n TO_BASE64(str)"
}
]
},
{
"keywords": [
"BOTH",
"LEADING",
"TRAILING",
"FROM"
],
"description": [
{
"para": "Returns the string str with all\n remstr prefixes or suffixes\n removed. If none of the specifiers BOTH,\n LEADING, or TRAILING is\n given, BOTH is assumed.\n remstr is optional and, if not\n specified, spaces are removed."
}
],
"id": "TRIM",
"syntax": [
{
"para": "\n TRIM()\n \n\n TRIM([{BOTH | LEADING | TRAILING}\n [remstr] FROM]\n str),\n TRIM([remstr\n FROM] str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "UCASE() is a synonym for\n UPPER()."
}
],
"id": "UCASE",
"syntax": [
{
"para": "\n UCASE()\n \n\n UCASE(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "For a string argument str,\n UNHEX(str)\n interprets each pair of characters in the argument as a\n hexadecimal number and converts it to the byte represented by\n the number. The return value is a binary string."
}
],
"id": "UNHEX",
"syntax": [
{
"para": "\n UNHEX()\n \n\n UNHEX(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string str with all\n characters changed to uppercase according to the current\n character set mapping. The default is\n utf8mb4."
},
{
"programlisting": ">\nmysql> SELECT UPPER('Hej');\n -> 'HEJ'"
},
{
"para": "See the description of LOWER()\n for information that also applies to\n UPPER(). This included\n information about how to perform lettercase conversion of\n binary strings (BINARY,\n VARBINARY,\n BLOB) for which these functions\n are ineffective, and information about case folding for\n Unicode character sets."
}
],
"id": "UPPER",
"syntax": [
{
"para": "\n UPPER()\n \n\n UPPER(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function returns the weight string for the input string.\n The return value is a binary string that represents the\n comparison and sorting value of the string. It has these\n properties:"
},
{
"itemizedlist": [
[
{
"para": "If\n WEIGHT_STRING(str1)\n =\n WEIGHT_STRING(str2),\n then str1 =\n str2\n (str1 and\n str2 are considered equal)"
}
],
[
{
"para": "If\n WEIGHT_STRING(str1)\n <\n WEIGHT_STRING(str2),\n then str1 <\n str2\n (str1 sorts before\n str2)"
}
]
]
},
{
"para": "WEIGHT_STRING() is a debugging\n function intended for internal use. Its behavior can change\n without notice between MySQL versions. It can be used for\n testing and debugging of collations, especially if you are\n adding a new collation. See\n ."
},
{
"para": "This list briefly summarizes the arguments. More details are\n given in the discussion following the list."
},
{
"itemizedlist": [
[
{
"para": "str: The input string\n expression."
}
],
[
{
"para": "AS clause: Optional; cast the input\n string to a given type and length."
}
],
[
{
"para": "flags: Optional; unused."
}
]
]
},
{
"para": "The input string, str, is a string\n expression. If the input is a nonbinary (character) string\n such as a CHAR,\n VARCHAR, or\n TEXT value, the return value\n contains the collation weights for the string. If the input is\n a binary (byte) string such as a\n BINARY,\n VARBINARY, or\n BLOB value, the return value is\n the same as the input (the weight for each byte in a binary\n string is the byte value). If the input is\n NULL,\n WEIGHT_STRING() returns\n NULL."
},
{
"para": "Examples:"
},
{
"programlisting": ">\nmysql> SET @s = _utf8mb4 'AB' COLLATE utf8mb4_0900_ai_ci;\nmysql> SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));\n+------+---------+------------------------+\n| @s | HEX(@s) | HEX(WEIGHT_STRING(@s)) |\n+------+---------+------------------------+\n| AB | 4142 | 1C471C60 |\n+------+---------+------------------------+"
},
{
"programlisting": ">\nmysql> SET @s = _utf8mb4 'ab' COLLATE utf8mb4_0900_ai_ci;\nmysql> SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));\n+------+---------+------------------------+\n| @s | HEX(@s) | HEX(WEIGHT_STRING(@s)) |\n+------+---------+------------------------+\n| ab | 6162 | 1C471C60 |\n+------+---------+------------------------+"
},
{
"programlisting": ">\nmysql> SET @s = CAST('AB' AS BINARY);\nmysql> SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));\n+------+---------+------------------------+\n| @s | HEX(@s) | HEX(WEIGHT_STRING(@s)) |\n+------+---------+------------------------+\n| AB | 4142 | 4142 |\n+------+---------+------------------------+"
},
{
"programlisting": ">\nmysql> SET @s = CAST('ab' AS BINARY);\nmysql> SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));\n+------+---------+------------------------+\n| @s | HEX(@s) | HEX(WEIGHT_STRING(@s)) |\n+------+---------+------------------------+\n| ab | 6162 | 6162 |\n+------+---------+------------------------+"
}
],
"id": "WEIGHT_STRING",
"syntax": [
{
"para": "\n WEIGHT_STRING()\n \n\n WEIGHT_STRING(str\n [AS {CHAR|BINARY}(N)]\n [flags])"
}
]
},
{
"keywords": [
"ESCAPE"
],
"description": [
{
"para": "Pattern matching using an SQL pattern. Returns\n 1 (TRUE) or\n 0 (FALSE). If either\n expr or\n pat is NULL,\n the result is NULL."
},
{
"para": "The pattern need not be a literal string. For example, it\n can be specified as a string expression or table column."
}
],
"id": "LIKE",
"syntax": [
{
"para": "\n LIKE\n \n\n expr\n LIKE pat [ESCAPE\n 'escape_char']"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is the same as NOT\n (expr LIKE\n pat [ESCAPE\n 'escape_char'])."
}
],
"id": "NOT LIKE",
"syntax": [
{
"para": "\n NOT LIKE\n \n\n expr\n NOT LIKE pat [ESCAPE\n 'escape_char']"
}
]
},
{
"keywords": null,
"description": [
{
"para": "STRCMP() returns\n 0 if the strings are the same,\n -1 if the first argument is smaller than\n the second according to the current sort order, and\n 1 otherwise."
}
],
"id": "STRCMP",
"syntax": [
{
"para": "\n STRCMP()\n \n\n STRCMP(expr1,expr2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Addition:"
}
],
"id": "+",
"syntax": [
{
"para": "\n + (addition)\n \n\n \n addition (+)\n \n\n +"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Subtraction:"
}
],
"id": "- binary",
"syntax": [
{
"para": "\n - (subtraction)\n \n\n \n subtraction (-)\n \n\n -"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Unary minus. This operator changes the sign of the operand."
}
],
"id": "- unary",
"syntax": [
{
"para": "\n - (unary minus)\n \n\n \n minus\n unary (-)\n \n\n \n unary minus (-)\n \n\n -"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Multiplication:"
}
],
"id": "*",
"syntax": [
{
"para": "\n * (multiplication)\n \n\n \n multiplication (*)\n \n\n *"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Division:"
}
],
"id": "/",
"syntax": [
{
"para": "\n / (division)\n \n\n \n division (/)\n \n\n /"
}
]
},
{
"keywords": [
"FLOOR",
"BIGINT"
],
"description": [
{
"para": "Integer division. Discards from the division result any\n fractional part to the right of the decimal point."
},
{
"para": "If either operand has a noninteger type, the operands are\n converted to DECIMAL and\n divided using DECIMAL\n arithmetic before converting the result to\n BIGINT. If the result exceeds\n BIGINT range, an error occurs."
}
],
"id": "DIV",
"syntax": [
{
"para": "\n DIV\n \n\n DIV"
}
]
},
{
"keywords": [
"MOD"
],
"description": [
{
"para": "Modulo operation. Returns the remainder of\n N divided by\n M. For more information, see the\n description for the MOD()\n function in ."
}
],
"id": "%",
"syntax": [
{
"para": "\n %\n \n\n N\n % M,\n N\n MOD M"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the absolute value of X."
}
],
"id": "ABS",
"syntax": [
{
"para": "\n ABS()\n \n\n ABS(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the arc cosine of X, that\n is, the value whose cosine is X.\n Returns NULL if\n X is not in the range\n -1 to 1."
}
],
"id": "ACOS",
"syntax": [
{
"para": "\n ACOS()\n \n\n ACOS(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the arc sine of X, that\n is, the value whose sine is X.\n Returns NULL if\n X is not in the range\n -1 to 1."
}
],
"id": "ASIN",
"syntax": [
{
"para": "\n ASIN()\n \n\n ASIN(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the arc tangent of X,\n that is, the value whose tangent is\n X."
}
],
"id": "ATAN",
"syntax": [
{
"para": "\n ATAN()\n \n\n ATAN(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the arc tangent of the two variables\n X and\n Y. It is similar to calculating\n the arc tangent of Y /\n X, except that the\n signs of both arguments are used to determine the quadrant\n of the result."
}
],
"id": "ATAN2",
"syntax": [
{
"para": "\n ATAN2()\n \n\n ATAN(Y,X),\n ATAN2(Y,X)"
}
]
},
{
"keywords": [
"CEIL"
],
"description": [
{
"para": "CEIL() is a synonym for\n CEILING()."
}
],
"id": "CEIL",
"syntax": [
{
"para": "\n CEIL()\n \n\n CEIL(X)"
}
]
},
{
"keywords": [
"CEILING"
],
"description": [
{
"para": "Returns the smallest integer value not less than\n X."
}
],
"id": "CEILING",
"syntax": [
{
"para": "\n CEILING()\n \n\n CEILING(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Converts numbers between different number bases. Returns a\n string representation of the number\n N, converted from base\n from_base to base\n to_base. Returns\n NULL if any argument is\n NULL. The argument\n N is interpreted as an integer,\n but may be specified as an integer or a string. The minimum\n base is 2 and the maximum base is\n 36. If\n from_base is a negative number,\n N is regarded as a signed number.\n Otherwise, N is treated as\n unsigned. CONV() works with\n 64-bit precision."
}
],
"id": "CONV",
"syntax": [
{
"para": "\n CONV()\n \n\n CONV(N,from_base,to_base)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the cosine of X, where\n X is given in radians."
}
],
"id": "COS",
"syntax": [
{
"para": "\n COS()\n \n\n COS(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the cotangent of X."
}
],
"id": "COT",
"syntax": [
{
"para": "\n COT()\n \n\n COT(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Computes a cyclic redundancy check value and returns a\n 32-bit unsigned value. The result is NULL\n if the argument is NULL. The argument is\n expected to be a string and (if possible) is treated as one\n if it is not."
}
],
"id": "CRC32",
"syntax": [
{
"para": "\n CRC32()\n \n\n CRC32(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the argument X, converted\n from radians to degrees."
}
],
"id": "DEGREES",
"syntax": [
{
"para": "\n DEGREES()\n \n\n DEGREES(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the value of e (the base of\n natural logarithms) raised to the power of\n X. The inverse of this function\n is LOG() (using a single\n argument only) or LN()."
}
],
"id": "EXP",
"syntax": [
{
"para": "\n EXP()\n \n\n EXP(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the largest integer value not greater than\n X."
}
],
"id": "FLOOR",
"syntax": [
{
"para": "\n FLOOR()\n \n\n FLOOR(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the natural logarithm of\n X; that is, the\n base-e logarithm of\n X. If\n X is less than or equal to 0.0E0,\n the function returns NULL and a warning\n Invalid argument for logarithm is reported."
}
],
"id": "LN",
"syntax": [
{
"para": "\n LN()\n \n\n LN(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If called with one parameter, this function returns the\n natural logarithm of X. If\n X is less than or equal to 0.0E0,\n the function returns NULL and a warning\n Invalid argument for logarithm is reported."
},
{
"para": "The inverse of this function (when called with a single\n argument) is the EXP()\n function."
}
],
"id": "LOG",
"syntax": [
{
"para": "\n LOG()\n \n\n LOG(X),\n LOG(B,X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the base-2 logarithm of\n X. If\n X is less than or equal to 0.0E0,\n the function returns NULL and a warning\n Invalid argument for logarithm is reported."
}
],
"id": "LOG2",
"syntax": [
{
"para": "\n LOG2()\n \n\n LOG2(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the base-10 logarithm of\n X. If\n X is less than or equal to 0.0E0,\n the function returns NULL and a warning\n Invalid argument for logarithm is reported."
}
],
"id": "LOG10",
"syntax": [
{
"para": "\n LOG10()\n \n\n LOG10(X)"
}
]
},
{
"keywords": [
"MOD"
],
"description": [
{
"para": "Modulo operation. Returns the remainder of\n N divided by\n M."
}
],
"id": "MOD",
"syntax": [
{
"para": "\n MOD()\n \n\n \n % (modulo)\n \n\n \n MOD (modulo)\n \n\n \n modulo (%)\n \n\n \n modulo (MOD)\n \n\n MOD(N,M),\n N\n % M,\n N\n MOD M"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the value of pi (pi). The default number of\n decimal places displayed is seven, but MySQL uses the full\n double-precision value internally."
}
],
"id": "PI",
"syntax": [
{
"para": "\n PI()\n \n\n PI()"
}
]
},
{
"keywords": [
"POW"
],
"description": [
{
"para": "Returns the value of X raised to\n the power of Y."
}
],
"id": "POW",
"syntax": [
{
"para": "\n POW()\n \n\n POW(X,Y)"
}
]
},
{
"keywords": [
"POWER"
],
"description": [
{
"para": "This is a synonym for POW()."
}
],
"id": "POWER",
"syntax": [
{
"para": "\n POWER()\n \n\n POWER(X,Y)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the argument X, converted\n from degrees to radians. (Note that pi radians equals 180\n degrees.)"
}
],
"id": "RADIANS",
"syntax": [
{
"para": "\n RADIANS()\n \n\n RADIANS(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a random floating-point value\n v in the range\n 0 <= v <\n 1.0. To obtain a random integer\n R in the range\n i <=\n R <\n j, use the expression\n FLOOR(i\n plus RAND() * (j\n minus i)).\n For example, to obtain a random integer in the range the\n range 7 <=\n R < 12, use\n the following statement:"
},
{
"programlisting": ">\nSELECT FLOOR(7 plus (RAND() * 5));"
},
{
"para": "If an integer argument N is\n specified, it is used as the seed value:"
},
{
"itemizedlist": [
[
{
"para": "With a constant initializer argument, the seed is\n initialized once when the statement is prepared, prior\n to execution."
}
],
[
{
"para": "With a nonconstant initializer argument (such as a\n column name), the seed is initialized with the value for\n each invocation of\n RAND()."
}
]
]
},
{
"para": "One implication of this behavior is that for equal argument\n values,\n RAND(N)\n returns the same value each time, and thus produces a\n repeatable sequence of column values. In the following\n example, the sequence of values produced by\n RAND(3) is the same both places it\n occurs."
}
],
"id": "RAND",
"syntax": [
{
"para": "\n RAND()\n \n\n RAND([N])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Rounds the argument X to\n D decimal places. The rounding\n algorithm depends on the data type of\n X. D\n defaults to 0 if not specified. D\n can be negative to cause D digits\n left of the decimal point of the value\n X to become zero."
}
],
"id": "ROUND",
"syntax": [
{
"para": "\n ROUND()\n \n\n ROUND(X),\n ROUND(X,D)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the sign of the argument as -1,\n 0, or 1, depending on\n whether X is negative, zero, or\n positive."
}
],
"id": "SIGN",
"syntax": [
{
"para": "\n SIGN()\n \n\n SIGN(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the sine of X, where\n X is given in radians."
}
],
"id": "SIN",
"syntax": [
{
"para": "\n SIN()\n \n\n SIN(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the square root of a nonnegative number\n X."
}
],
"id": "SQRT",
"syntax": [
{
"para": "\n SQRT()\n \n\n SQRT(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the tangent of X, where\n X is given in radians."
}
],
"id": "TAN",
"syntax": [
{
"para": "\n TAN()\n \n\n TAN(X)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the number X, truncated\n to D decimal places. If\n D is 0, the\n result has no decimal point or fractional part.\n D can be negative to cause\n D digits left of the decimal\n point of the value X to become\n zero."
}
],
"id": "TRUNCATE",
"syntax": [
{
"para": "\n TRUNCATE()\n \n\n TRUNCATE(X,D)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "When invoked with the INTERVAL form of the\n second argument, ADDDATE() is a\n synonym for DATE_ADD(). The\n related function SUBDATE() is a\n synonym for DATE_SUB(). For\n information on the INTERVAL\n unit argument, see\n ."
},
{
"programlisting": ">\nmysql> SELECT DATE_ADD('2008-01-02', INTERVAL 31 DAY);\n -> '2008-02-02'\nmysql> SELECT ADDDATE('2008-01-02', INTERVAL 31 DAY);\n -> '2008-02-02'"
},
{
"para": "When invoked with the days form of\n the second argument, MySQL treats it as an integer number of\n days to be added to expr."
}
],
"id": "ADDDATE",
"syntax": [
{
"para": "\n ADDDATE()\n \n\n ADDDATE(date,INTERVAL\n expr\n unit),\n ADDDATE(expr,days)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "ADDTIME() adds\n expr2 to\n expr1 and returns the result.\n expr1 is a time or datetime\n expression, and expr2 is a time\n expression."
}
],
"id": "ADDTIME",
"syntax": [
{
"para": "\n ADDTIME()\n \n\n ADDTIME(expr1,expr2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "CONVERT_TZ() converts a\n datetime value dt from the time\n zone given by from_tz to the time\n zone given by to_tz and returns the\n resulting value. Time zones are specified as described in\n . This function returns\n NULL if the arguments are invalid."
}
],
"id": "CONVERT_TZ",
"syntax": [
{
"para": "\n CONVERT_TZ()\n \n\n CONVERT_TZ(dt,from_tz,to_tz)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current date as a value in\n 'YYYY-MM-DD' or\n YYYYMMDD format, depending on\n whether the function is used in a string or numeric context."
}
],
"id": "CURDATE",
"syntax": [
{
"para": "\n CURDATE()\n \n\n CURDATE()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "CURRENT_DATE and\n CURRENT_DATE() are synonyms for\n CURDATE()."
}
],
"id": "CURRENT_DATE",
"syntax": [
{
"para": "\n CURRENT_DATE\n \n\n CURRENT_DATE,\n CURRENT_DATE()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "CURRENT_TIME and\n CURRENT_TIME() are synonyms for\n CURTIME()."
}
],
"id": "CURRENT_TIME",
"syntax": [
{
"para": "\n CURRENT_TIME\n \n\n CURRENT_TIME,\n CURRENT_TIME([fsp])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "CURRENT_TIMESTAMP and\n CURRENT_TIMESTAMP() are\n synonyms for NOW()."
}
],
"id": "CURRENT_TIMESTAMP",
"syntax": [
{
"para": "\n CURRENT_TIMESTAMP\n \n\n CURRENT_TIMESTAMP,\n CURRENT_TIMESTAMP([fsp])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current time as a value in\n 'hh:mm:ss' or\n hhmmss format, depending on whether\n the function is used in a string or numeric context. The value\n is expressed in the session time zone."
},
{
"para": "If the fsp argument is given to\n specify a fractional seconds precision from 0 to 6, the return\n value includes a fractional seconds part of that many digits."
}
],
"id": "CURTIME",
"syntax": [
{
"para": "\n CURTIME()\n \n\n CURTIME([fsp])"
}
]
},
{
"keywords": [
"DATE"
],
"description": [
{
"para": "Extracts the date part of the date or datetime expression\n expr."
}
],
"id": "DATE function",
"syntax": [
{
"para": "\n DATE()\n \n\n DATE(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "DATEDIFF() returns\n expr1 minus\n expr2 expressed as a value in days\n from one date to the other. expr1\n and expr2 are date or date-and-time\n expressions. Only the date parts of the values are used in the\n calculation."
}
],
"id": "DATEDIFF",
"syntax": [
{
"para": "\n DATEDIFF()\n \n\n DATEDIFF(expr1,expr2)"
}
]
},
{
"keywords": [
"DATE",
"DATE_ADD",
"DATE_SUB",
"SECOND",
"MINUTE",
"HOUR",
"DAY",
"MONTH",
"YEAR",
"MINUTE_SECOND",
"HOUR_MINUTE",
"DAY_HOUR",
"YEAR_MONTH",
"HOUR_SECOND",
"DAY_MINUTE",
"DAY_SECOND",
"INTERVAL"
],
"description": [
{
"para": "These functions perform date arithmetic. The\n date argument specifies the\n starting date or datetime value.\n expr is an expression specifying\n the interval value to be added or subtracted from the starting\n date. expr is evaluated as a\n string; it may start with a - for negative\n intervals. unit is a keyword\n indicating the units in which the expression should be\n interpreted."
}
],
"id": "DATE_ADD",
"syntax": [
{
"para": "\n DATE_ADD()\n \n\n \n DATE_SUB()\n \n\n DATE_ADD(date,INTERVAL\n expr\n unit),\n DATE_SUB(date,INTERVAL\n expr\n unit)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Formats the date value according to\n the format string."
}
],
"id": "DATE_FORMAT",
"syntax": [
{
"para": "\n DATE_FORMAT()\n \n\n DATE_FORMAT(date,format)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "See the description for\n DATE_ADD()."
}
],
"id": "DATE_SUB",
"syntax": [
{
"para": "\n DATE_SUB()\n \n\n DATE_SUB(date,INTERVAL\n expr\n unit)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "DAY() is a synonym for\n DAYOFMONTH()."
}
],
"id": "DAY",
"syntax": [
{
"para": "\n DAY()\n \n\n DAY(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the name of the weekday for\n date. The language used for the\n name is controlled by the value of the\n lc_time_names system variable\n ()."
}
],
"id": "DAYNAME",
"syntax": [
{
"para": "\n DAYNAME()\n \n\n DAYNAME(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the day of the month for\n date, in the range\n 1 to 31, or\n 0 for dates such as\n '0000-00-00' or\n '2008-00-00' that have a zero day part."
}
],
"id": "DAYOFMONTH",
"syntax": [
{
"para": "\n DAYOFMONTH()\n \n\n DAYOFMONTH(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the weekday index for date\n (1 = Sunday, 2 = Monday,\n hellip, 7 = Saturday). These index values\n correspond to the ODBC standard."
}
],
"id": "DAYOFWEEK",
"syntax": [
{
"para": "\n DAYOFWEEK()\n \n\n DAYOFWEEK(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the day of the year for\n date, in the range\n 1 to 366."
}
],
"id": "DAYOFYEAR",
"syntax": [
{
"para": "\n DAYOFYEAR()\n \n\n DAYOFYEAR(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "The EXTRACT() function uses the\n same kinds of unit specifiers as\n DATE_ADD() or\n DATE_SUB(), but extracts parts\n from the date rather than performing date arithmetic. For\n information on the unit argument,\n see ."
}
],
"id": "EXTRACT",
"syntax": [
{
"para": "\n EXTRACT()\n \n\n EXTRACT(unit\n FROM date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given a day number N, returns a\n DATE value."
}
],
"id": "FROM_DAYS",
"syntax": [
{
"para": "\n FROM_DAYS()\n \n\n FROM_DAYS(N)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a representation of the\n unix_timestamp argument as a value\n in 'YYYY-MM-DD hh:mm:ss' or\n YYYYMMDDhhmmss.uuuuuu format,\n depending on whether the function is used in a string or\n numeric context. unix_timestamp is\n an internal timestamp value representing seconds since\n '1970-01-01 00:00:00' UTC, such as produced\n by the UNIX_TIMESTAMP()\n function."
},
{
"para": "The return value is expressed in the session time zone.\n (Clients can set the session time zone as described in\n .) The\n format string, if given, is used to\n format the result the same way as described in the entry for\n the DATE_FORMAT() function."
}
],
"id": "FROM_UNIXTIME",
"syntax": [
{
"para": "\n FROM_UNIXTIME()\n \n\n FROM_UNIXTIME(unix_timestamp[,format])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a format string. This function is useful in\n combination with the\n DATE_FORMAT() and the\n STR_TO_DATE() functions."
}
],
"id": "GET_FORMAT",
"syntax": [
{
"para": "\n GET_FORMAT()\n \n\n GET_FORMAT({DATE|TIME|DATETIME},\n {'EUR'|'USA'|'JIS'|'ISO'|'INTERNAL'})"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the hour for time. The\n range of the return value is 0 to\n 23 for time-of-day values. However, the\n range of TIME values actually\n is much larger, so HOUR can return values\n greater than 23."
}
],
"id": "HOUR",
"syntax": [
{
"para": "\n HOUR()\n \n\n HOUR(time)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Takes a date or datetime value and returns the corresponding\n value for the last day of the month. Returns\n NULL if the argument is invalid."
}
],
"id": "LAST_DAY",
"syntax": [
{
"para": "\n LAST_DAY()\n \n\n LAST_DAY(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "LOCALTIME and\n LOCALTIME() are synonyms for\n NOW()."
}
],
"id": "LOCALTIME",
"syntax": [
{
"para": "\n LOCALTIME\n \n\n LOCALTIME,\n LOCALTIME([fsp])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "LOCALTIMESTAMP and\n LOCALTIMESTAMP() are synonyms\n for NOW()."
}
],
"id": "LOCALTIMESTAMP",
"syntax": [
{
"para": "\n LOCALTIMESTAMP\n \n\n LOCALTIMESTAMP,\n LOCALTIMESTAMP([fsp])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a date, given year and day-of-year values.\n dayofyear must be greater than 0 or\n the result is NULL."
}
],
"id": "MAKEDATE",
"syntax": [
{
"para": "\n MAKEDATE()\n \n\n MAKEDATE(year,dayofyear)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a time value calculated from the\n hour,\n minute, and\n second arguments."
},
{
"para": "The second argument can have a\n fractional part."
}
],
"id": "MAKETIME",
"syntax": [
{
"para": "\n MAKETIME()\n \n\n MAKETIME(hour,minute,second)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the microseconds from the time or datetime expression\n expr as a number in the range from\n 0 to 999999."
}
],
"id": "MICROSECOND",
"syntax": [
{
"para": "\n MICROSECOND()\n \n\n MICROSECOND(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the minute for time, in the\n range 0 to 59."
}
],
"id": "MINUTE",
"syntax": [
{
"para": "\n MINUTE()\n \n\n MINUTE(time)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the month for date, in the\n range 1 to 12 for\n January to December, or 0 for dates such as\n '0000-00-00' or\n '2008-00-00' that have a zero month part."
}
],
"id": "MONTH",
"syntax": [
{
"para": "\n MONTH()\n \n\n MONTH(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the full name of the month for\n date. The language used for the\n name is controlled by the value of the\n lc_time_names system variable\n ()."
}
],
"id": "MONTHNAME",
"syntax": [
{
"para": "\n MONTHNAME()\n \n\n MONTHNAME(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current date and time as a value in\n 'YYYY-MM-DD hh:mm:ss' or\n YYYYMMDDhhmmss format, depending on\n whether the function is used in a string or numeric context.\n The value is expressed in the session time zone."
},
{
"para": "If the fsp argument is given to\n specify a fractional seconds precision from 0 to 6, the return\n value includes a fractional seconds part of that many digits."
}
],
"id": "NOW",
"syntax": [
{
"para": "\n NOW()\n \n\n NOW([fsp])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Adds N months to period\n P (in the format\n YYMM or\n YYYYMM). Returns a value in the\n format YYYYMM."
}
],
"id": "PERIOD_ADD",
"syntax": [
{
"para": "\n PERIOD_ADD()\n \n\n PERIOD_ADD(P,N)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the number of months between periods\n P1 and\n P2. P1\n and P2 should be in the format\n YYMM or\n YYYYMM. Note that the period\n arguments P1 and\n P2 are not\n date values."
}
],
"id": "PERIOD_DIFF",
"syntax": [
{
"para": "\n PERIOD_DIFF()\n \n\n PERIOD_DIFF(P1,P2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the quarter of the year for\n date, in the range\n 1 to 4."
}
],
"id": "QUARTER",
"syntax": [
{
"para": "\n QUARTER()\n \n\n QUARTER(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the second for time, in the\n range 0 to 59."
}
],
"id": "SECOND",
"syntax": [
{
"para": "\n SECOND()\n \n\n SECOND(time)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the seconds argument,\n converted to hours, minutes, and seconds, as a\n TIME value. The range of the\n result is constrained to that of the\n TIME data type. A warning\n occurs if the argument corresponds to a value outside that\n range."
}
],
"id": "SEC_TO_TIME",
"syntax": [
{
"para": "\n SEC_TO_TIME()\n \n\n SEC_TO_TIME(seconds)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is the inverse of the\n DATE_FORMAT() function. It\n takes a string str and a format\n string format.\n STR_TO_DATE() returns a\n DATETIME value if the format\n string contains both date and time parts, or a\n DATE or\n TIME value if the string\n contains only date or time parts. If the date, time, or\n datetime value extracted from str\n is illegal, STR_TO_DATE()\n returns NULL and produces a warning."
},
{
"para": "The server scans str attempting to\n match format to it. The format\n string can contain literal characters and format specifiers\n beginning with %. Literal characters in\n format must match literally in\n str. Format specifiers in\n format must match a date or time\n part in str. For the specifiers\n that can be used in format, see the\n DATE_FORMAT() function\n description."
},
{
"programlisting": ">\nmysql> SELECT STR_TO_DATE('01,5,2013','%d,%m,%Y');\n -> '2013-05-01'\nmysql> SELECT STR_TO_DATE('May 1, 2013','%M %d,%Y');\n -> '2013-05-01'"
},
{
"para": "Scanning starts at the beginning of\n str and fails if\n format is found not to match. Extra\n characters at the end of str are\n ignored."
},
{
"programlisting": ">\nmysql> SELECT STR_TO_DATE('a09:30:17','a%h:%i:%s');\n -> '09:30:17'\nmysql> SELECT STR_TO_DATE('a09:30:17','%h:%i:%s');\n -> NULL\nmysql> SELECT STR_TO_DATE('09:30:17a','%h:%i:%s');\n -> '09:30:17'"
},
{
"para": "Unspecified date or time parts have a value of 0, so\n incompletely specified values in\n str produce a result with some or\n all parts set to 0:"
},
{
"programlisting": ">\nmysql> SELECT STR_TO_DATE('abc','abc');\n -> '0000-00-00'\nmysql> SELECT STR_TO_DATE('9','%m');\n -> '0000-09-00'\nmysql> SELECT STR_TO_DATE('9','%s');\n -> '00:00:09'"
}
],
"id": "STR_TO_DATE",
"syntax": [
{
"para": "\n STR_TO_DATE()\n \n\n STR_TO_DATE(str,format)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "When invoked with the INTERVAL form of the\n second argument, SUBDATE() is a\n synonym for DATE_SUB(). For\n information on the INTERVAL\n unit argument, see the discussion\n for DATE_ADD()."
},
{
"programlisting": ">\nmysql> SELECT DATE_SUB('2008-01-02', INTERVAL 31 DAY);\n -> '2007-12-02'\nmysql> SELECT SUBDATE('2008-01-02', INTERVAL 31 DAY);\n -> '2007-12-02'"
},
{
"para": "The second form enables the use of an integer value for\n days. In such cases, it is\n interpreted as the number of days to be subtracted from the\n date or datetime expression expr."
},
{
"programlisting": ">\nmysql> SELECT SUBDATE('2008-01-02 12:00:00', 31);\n -> '2007-12-02 12:00:00'"
}
],
"id": "SUBDATE",
"syntax": [
{
"para": "\n SUBDATE()\n \n\n SUBDATE(date,INTERVAL\n expr\n unit),\n SUBDATE(expr,days)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "SUBTIME() returns\n expr1 minus\n expr2 expressed as a value in the\n same format as expr1.\n expr1 is a time or datetime\n expression, and expr2 is a time\n expression."
}
],
"id": "SUBTIME",
"syntax": [
{
"para": "\n SUBTIME()\n \n\n SUBTIME(expr1,expr2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current date and time as a value in\n 'YYYY-MM-DD hh:mm:ss' or\n YYYYMMDDhhmmss format, depending on\n whether the function is used in a string or numeric context."
},
{
"para": "If the fsp argument is given to\n specify a fractional seconds precision from 0 to 6, the return\n value includes a fractional seconds part of that many digits."
},
{
"para": "SYSDATE() returns the time at\n which it executes. This differs from the behavior for\n NOW(), which returns a constant\n time that indicates the time at which the statement began to\n execute. (Within a stored function or trigger,\n NOW() returns the time at which\n the function or triggering statement began to execute.)"
},
{
"programlisting": ">\nmysql> SELECT NOW(), SLEEP(2), NOW();\n+---------------------+----------+---------------------+\n| NOW() | SLEEP(2) | NOW() |\n+---------------------+----------+---------------------+\n| 2006-04-12 13:47:36 | 0 | 2006-04-12 13:47:36 |\n+---------------------+----------+---------------------+\n\nmysql> SELECT SYSDATE(), SLEEP(2), SYSDATE();\n+---------------------+----------+---------------------+\n| SYSDATE() | SLEEP(2) | SYSDATE() |\n+---------------------+----------+---------------------+\n| 2006-04-12 13:47:44 | 0 | 2006-04-12 13:47:46 |\n+---------------------+----------+---------------------+"
},
{
"para": "In addition, the SET TIMESTAMP statement\n affects the value returned by\n NOW() but not by\n SYSDATE(). This means that\n timestamp settings in the binary log have no effect on\n invocations of SYSDATE()."
},
{
"para": "Because SYSDATE() can return\n different values even within the same statement, and is not\n affected by SET TIMESTAMP, it is\n nondeterministic and therefore unsafe for replication if\n statement-based binary logging is used. If that is a problem,\n you can use row-based logging."
},
{
"para": "Alternatively, you can use the\n option to\n cause SYSDATE() to be an alias\n for NOW(). This works if the\n option is used on both the master and the slave."
},
{
"para": "The nondeterministic nature of\n SYSDATE() also means that\n indexes cannot be used for evaluating expressions that refer\n to it."
}
],
"id": "SYSDATE",
"syntax": [
{
"para": "\n SYSDATE()\n \n\n SYSDATE([fsp])"
}
]
},
{
"keywords": [
"TIME"
],
"description": [
{
"para": "Extracts the time part of the time or datetime expression\n expr and returns it as a string."
}
],
"id": "TIME function",
"syntax": [
{
"para": "\n TIME()\n \n\n TIME(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "TIMEDIFF() returns\n expr1 minus\n expr2 expressed as a time value.\n expr1 and\n expr2 are time or date-and-time\n expressions, but both must be of the same type."
},
{
"para": "The result returned by TIMEDIFF() is\n limited to the range allowed for\n TIME values. Alternatively, you\n can use either of the functions\n TIMESTAMPDIFF() and\n UNIX_TIMESTAMP(), both of which\n return integers."
}
],
"id": "TIMEDIFF",
"syntax": [
{
"para": "\n TIMEDIFF()\n \n\n TIMEDIFF(expr1,expr2)"
}
]
},
{
"keywords": [
"TIMESTAMP"
],
"description": [
{
"para": "With a single argument, this function returns the date or\n datetime expression expr as a\n datetime value. With two arguments, it adds the time\n expression expr2 to the date or\n datetime expression expr1 and\n returns the result as a datetime value."
}
],
"id": "TIMESTAMP function",
"syntax": [
{
"para": "\n TIMESTAMP()\n \n\n TIMESTAMP(expr),\n TIMESTAMP(expr1,expr2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Adds the integer expression\n interval to the date or datetime\n expression datetime_expr. The unit\n for interval is given by the\n unit argument, which should be one\n of the following values: MICROSECOND\n (microseconds), SECOND,\n MINUTE, HOUR,\n DAY, WEEK,\n MONTH, QUARTER, or\n YEAR."
},
{
"para": "The unit value may be specified\n using one of keywords as shown, or with a prefix of\n SQL_TSI_. For example,\n DAY and SQL_TSI_DAY both\n are legal."
}
],
"id": "TIMESTAMPADD",
"syntax": [
{
"para": "\n TIMESTAMPADD()\n \n\n TIMESTAMPADD(unit,interval,datetime_expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns datetime_expr2 minus\n datetime_expr1, where\n datetime_expr1 and\n datetime_expr2 are date or datetime\n expressions. One expression may be a date and the other a\n datetime; a date value is treated as a datetime having the\n time part '00:00:00' where necessary. The\n unit for the result (an integer) is given by the\n unit argument. The legal values for\n unit are the same as those listed\n in the description of the\n TIMESTAMPADD() function."
}
],
"id": "TIMESTAMPDIFF",
"syntax": [
{
"para": "\n TIMESTAMPDIFF()\n \n\n TIMESTAMPDIFF(unit,datetime_expr1,datetime_expr2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is used like the\n DATE_FORMAT() function, but the\n format string may contain format\n specifiers only for hours, minutes, seconds, and microseconds.\n Other specifiers produce a NULL value or\n 0."
}
],
"id": "TIME_FORMAT",
"syntax": [
{
"para": "\n TIME_FORMAT()\n \n\n TIME_FORMAT(time,format)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the time argument,\n converted to seconds."
}
],
"id": "TIME_TO_SEC",
"syntax": [
{
"para": "\n TIME_TO_SEC()\n \n\n TIME_TO_SEC(time)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given a date date, returns a day\n number (the number of days since year 0)."
}
],
"id": "TO_DAYS",
"syntax": [
{
"para": "\n TO_DAYS()\n \n\n TO_DAYS(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given a date or datetime expr,\n returns the number of seconds since the year 0. If\n expr is not a valid date or\n datetime value, returns NULL."
}
],
"id": "TO_SECONDS",
"syntax": [
{
"para": "\n TO_SECONDS()\n \n\n TO_SECONDS(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If UNIX_TIMESTAMP() is called\n with no date argument, it returns a\n Unix timestamp representing seconds since '1970-01-01\n 00:00:00' UTC."
},
{
"para": "If UNIX_TIMESTAMP() is called\n with a date argument, it returns\n the value of the argument as seconds since\n '1970-01-01 00:00:00' UTC. The server\n interprets date as a value in the\n session time zone and converts it to an internal Unix\n timestamp value in UTC. (Clients can set the session time zone\n as described in .) The\n date argument may be a\n DATE,\n DATETIME, or\n TIMESTAMP string, or a number\n in YYMMDD,\n YYMMDDhhmmss,\n YYYYMMDD, or\n YYYYMMDDhhmmss format. If the\n argument includes a time part, it may optionally include a\n fractional seconds part."
},
{
"para": "The return value is an integer if no argument is given or the\n argument does not include a fractional seconds part, or\n DECIMAL if an argument is given\n that includes a fractional seconds part."
},
{
"para": "When the date argument is a\n TIMESTAMP column,\n UNIX_TIMESTAMP() returns the\n internal timestamp value directly, with no implicit\n string-to-Unix-timestamp conversion."
},
{
"para": "The valid range of argument values is the same as for the\n TIMESTAMP data type:\n '1970-01-01 00:00:01.000000' UTC to\n '2038-01-19 03:14:07.999999' UTC. If you\n pass an out-of-range date to\n UNIX_TIMESTAMP(), it returns\n 0."
}
],
"id": "UNIX_TIMESTAMP",
"syntax": [
{
"para": "\n UNIX_TIMESTAMP()\n \n\n UNIX_TIMESTAMP([date])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current UTC date as a value in\n 'YYYY-MM-DD' or\n YYYYMMDD format, depending on\n whether the function is used in a string or numeric context."
}
],
"id": "UTC_DATE",
"syntax": [
{
"para": "\n UTC_DATE()\n \n\n UTC_DATE,\n UTC_DATE()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current UTC time as a value in\n 'hh:mm:ss' or\n hhmmss format, depending on whether\n the function is used in a string or numeric context."
},
{
"para": "If the fsp argument is given to\n specify a fractional seconds precision from 0 to 6, the return\n value includes a fractional seconds part of that many digits."
}
],
"id": "UTC_TIME",
"syntax": [
{
"para": "\n UTC_TIME()\n \n\n UTC_TIME,\n UTC_TIME([fsp])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current UTC date and time as a value in\n 'YYYY-MM-DD hh:mm:ss' or\n YYYYMMDDhhmmss format, depending on\n whether the function is used in a string or numeric context."
},
{
"para": "If the fsp argument is given to\n specify a fractional seconds precision from 0 to 6, the return\n value includes a fractional seconds part of that many digits."
}
],
"id": "UTC_TIMESTAMP",
"syntax": [
{
"para": "\n UTC_TIMESTAMP()\n \n\n UTC_TIMESTAMP,\n UTC_TIMESTAMP([fsp])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function returns the week number for\n date. The two-argument form of\n WEEK() enables you to specify\n whether the week starts on Sunday or Monday and whether the\n return value should be in the range from 0\n to 53 or from 1 to\n 53. If the mode\n argument is omitted, the value of the\n default_week_format system\n variable is used. See\n ."
}
],
"id": "WEEK",
"syntax": [
{
"para": "\n WEEK()\n \n\n WEEK(date[,mode])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the weekday index for date\n (0 = Monday, 1 =\n Tuesday, hellip 6 = Sunday)."
}
],
"id": "WEEKDAY",
"syntax": [
{
"para": "\n WEEKDAY()\n \n\n WEEKDAY(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the calendar week of the date as a number in the range\n from 1 to 53.\n WEEKOFYEAR() is a compatibility\n function that is equivalent to\n WEEK(date,3)."
}
],
"id": "WEEKOFYEAR",
"syntax": [
{
"para": "\n WEEKOFYEAR()\n \n\n WEEKOFYEAR(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the year for date, in the\n range 1000 to 9999, or\n 0 for the zero date."
}
],
"id": "YEAR",
"syntax": [
{
"para": "\n YEAR()\n \n\n YEAR(date)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns year and week for a date. The year in the result may\n be different from the year in the date argument for the first\n and the last week of the year."
},
{
"para": "The mode argument works exactly\n like the mode argument to\n WEEK(). For the single-argument\n syntax, a mode value of 0 is used.\n Unlike WEEK(), the value of\n default_week_format does not\n influence YEARWEEK()."
}
],
"id": "YEARWEEK",
"syntax": [
{
"para": "\n YEARWEEK()\n \n\n YEARWEEK(date),\n YEARWEEK(date,mode)"
}
]
},
{
"keywords": [
"MATCH",
"AGAINST",
"BOOLEAN",
"IN",
"MODE",
"QUERY",
"EXPANSION",
"WITH"
],
"description": [
{
"para": "MySQL has support for full-text indexing and searching:"
},
{
"itemizedlist": [
[
{
"para": "A full-text index in MySQL is an index of type\n FULLTEXT."
}
],
[
{
"para": "Full-text indexes can be used only with\n InnoDB or\n MyISAM tables, and can be created\n only for CHAR,\n VARCHAR, or\n TEXT columns."
}
],
[
{
"para": "MySQL provides a built-in full-text ngram\n parser that supports Chinese, Japanese, and Korean (CJK), and\n an installable MeCab full-text parser plugin for Japanese.\n Parsing differences are outlined in\n , and\n ."
}
],
[
{
"para": "A FULLTEXT index definition can be given in\n the CREATE TABLE statement when\n a table is created, or added later using\n ALTER TABLE or\n CREATE INDEX."
}
],
[
{
"para": "For large data sets, it is much faster to load your data into\n a table that has no FULLTEXT index and then\n create the index after that, than to load data into a table\n that has an existing FULLTEXT index."
}
]
]
},
{
"para": "Full-text searching is performed using\n MATCH() ... AGAINST syntax.\n MATCH() takes a comma-separated\n list that names the columns to be searched.\n AGAINST takes a string to search for, and an\n optional modifier that indicates what type of search to perform.\n The search string must be a string value that is constant during\n query evaluation. This rules out, for example, a table column\n because that can differ for each row."
},
{
"para": "There are three types of full-text searches:"
},
{
"itemizedlist": [
[
{
"para": "A natural language search interprets the search string as a\n phrase in natural human language (a phrase in free text).\n There are no special operators, with the exception of double\n quote (\") characters. The stopword list applies. For more\n information about stopword lists, see\n ."
},
{
"para": "Full-text searches are natural language searches if the\n IN NATURAL LANGUAGE MODE modifier is given\n or if no modifier is given. For more information, see\n ."
}
],
[
{
"para": "A boolean search interprets the search string using the rules\n of a special query language. The string contains the words to\n search for. It can also contain operators that specify\n requirements such that a word must be present or absent in\n matching rows, or that it should be weighted higher or lower\n than usual. Certain common words (stopwords) are omitted from\n the search index and do not match if present in the search\n string. The IN BOOLEAN MODE modifier\n specifies a boolean search. For more information, see\n ."
}
],
[
{
"para": "A query expansion search is a modification of a natural\n language search. The search string is used to perform a\n natural language search. Then words from the most relevant\n rows returned by the search are added to the search string and\n the search is done again. The query returns the rows from the\n second search. The IN NATURAL LANGUAGE MODE WITH\n QUERY EXPANSION or WITH QUERY\n EXPANSION modifier specifies a query expansion\n search. For more information, see\n ."
}
]
]
}
],
"id": "MATCH AGAINST",
"syntax": [
{
"para": ">\n MATCH\n (col1,col2,...)\n AGAINST (expr\n [search_modifier])"
},
{
"programlisting": ">\nsearch_modifier:\n {\n IN NATURAL LANGUAGE MODE\n | IN NATURAL LANGUAGE MODE WITH QUERY EXPANSION\n | IN BOOLEAN MODE\n | WITH QUERY EXPANSION\n }"
}
]
},
{
"keywords": null,
"description": [
{
"para": "The BINARY operator converts the\n expression to a binary string. A common use for\n BINARY is to force a character\n string comparison to be done byte by byte rather than\n character by character, in effect becoming case-sensitive. The\n BINARY operator also causes\n trailing spaces in comparisons to be significant."
}
],
"id": "BINARY operator",
"syntax": [
{
"para": "\n BINARY\n \n\n BINARY\n expr"
}
]
},
{
"keywords": [
"ARRAY",
"CONVERT"
],
"description": [
{
"para": "The CAST() function takes an\n expression of any type and produces a result value of the\n specified type, similar to\n CONVERT(). For more\n information, see the description of\n CONVERT()."
},
{
"para": "In MySQL 8.0.17 and later, InnoDB\n allows the use of an additional ARRAY\n keyword for creating a multi-valued index on a\n JSON array as part of\n CREATE INDEX,\n CREATE TABLE, and\n ALTER TABLE statements.\n ARRAY is not supported except when used to\n create a multi-valued index in one of these statements, in\n which case it is required. The column being indexed must be a\n column of type JSON.\n (CONVERT() does\n not support multi-valued index creation\n or the ARRAY keyword.) The\n type following the\n AS keyword may be any of the types\n supported by CAST(), with the exception of\n BINARY and JSON, which\n are not supported for this purpose.\n , provides syntax\n information and examples, as well as other relevant\n information."
},
{
"para": "CAST() is standard SQL syntax."
}
],
"id": "CAST",
"syntax": [
{
"para": "\n CAST\n \n\n CAST(expr AS\n type [ARRAY])"
}
]
},
{
"keywords": [
"CONVERT",
"BINARY",
"CHAR",
"DATE",
"DATETIME",
"DECIMAL",
"INTEGER",
"JSON",
"SIGNED",
"TIME",
"UNSIGNED"
],
"description": [
{
"para": "The CONVERT() function takes an\n expression of any type and produces a result value of the\n specified type."
},
{
"para": "Discussion of\n CONVERT(expr,\n type) syntax here also\n applies to\n CAST(expr AS\n type), which is\n equivalent."
},
{
"para": "CONVERT(... USING ...) is\n standard SQL syntax. The non-USING form of\n CONVERT() is ODBC syntax."
},
{
"para": "CONVERT() with\n USING converts data between different\n character sets. In MySQL, transcoding names are the same as\n the corresponding character set names. For example, this\n statement converts the string 'abc' in the\n default character set to the corresponding string in the\n utf8 character set:"
},
{
"programlisting": ">\nSELECT CONVERT('abc' USING utf8);"
},
{
"para": "CONVERT() without\n USING and\n CAST() take an expression and a\n type value specifying the result\n type. These type values are\n permitted:"
},
{
"itemizedlist": [
[
{
"para": "BINARY[(N)]"
},
{
"para": "Produces a string with the\n BINARY data type. See\n for a description of\n how this affects comparisons. If the optional length\n N is given,\n BINARY(N)\n causes the cast to use no more than\n N bytes of the argument. Values\n shorter than N bytes are padded\n with 0x00 bytes to a length of\n N."
}
],
[
{
"para": "CHAR[(N)]\n [charset_info]"
},
{
"para": "Produces a string with the\n CHAR data type. If the\n optional length N is given,\n CHAR(N)\n causes the cast to use no more than\n N characters of the argument.\n No padding occurs for values shorter than\n N characters."
},
{
"para": "With no charset_info clause,\n CHAR produces a string with the default\n character set. To specify the character set explicitly,\n these charset_info values are\n permitted:"
},
{
"itemizedlist": [
[
{
"para": "CHARACTER SET\n charset_name:\n Produces a string with the given character set."
}
],
[
{
"para": "ASCII: Shorthand for\n CHARACTER SET latin1."
}
],
[
{
"para": "UNICODE: Shorthand for\n CHARACTER SET ucs2."
}
]
]
},
{
"para": "In all cases, the string has the default collation for the\n character set."
}
],
[
{
"para": "DATE"
},
{
"para": "Produces a DATE value."
}
],
[
{
"para": "DATETIME"
},
{
"para": "Produces a DATETIME value."
}
],
[
{
"para": "DECIMAL[(M[,D])]"
},
{
"para": "Produces a DECIMAL value.\n If the optional M and\n D values are given, they\n specify the maximum number of digits (the precision) and\n the number of digits following the decimal point (the\n scale)."
}
],
[
{
"para": "DOUBLE"
},
{
"para": "Produces a DOUBLE result.\n Added in MySQL 8.0.17."
}
],
[
{
"para": "FLOAT[(P)]"
},
{
"para": "If the precision P is not\n specified, produces a result of type\n FLOAT. If\n P is provided and 0 <= <\n P <= 24, the result is of\n type FLOAT. If 25 <=\n P <= 53, the result is of\n type DOUBLE. If\n P < 0 or\n P > 53, an error is\n returned. Added in MySQL 8.0.17."
}
],
[
{
"para": "JSON"
},
{
"para": "Produces a JSON value. For\n details on the rules for conversion of values between\n JSON and other types, see\n ."
}
],
[
{
"para": "NCHAR[(N)]"
},
{
"para": "Like CHAR, but produces a string with\n the national character set. See\n ."
},
{
"para": "Unlike CHAR, NCHAR\n does not permit trailing character set information to be\n specified."
}
],
[
{
"para": "REAL"
},
{
"para": "Produces a result of type\n REAL. This is actually\n FLOAT if\n REAL_AS_FLOAT SQL mode\n is enabled; otherwise the result is of type\n DOUBLE."
}
],
[
{
"para": "SIGNED [INTEGER]"
},
{
"para": "Produces a signed integer value."
}
],
[
{
"para": "TIME"
},
{
"para": "Produces a TIME value."
}
],
[
{
"para": "UNSIGNED [INTEGER]"
},
{
"para": "Produces an unsigned integer value."
}
]
]
}
],
"id": "CONVERT",
"syntax": [
{
"para": "\n CONVERT\n \n\n CONVERT(expr,type),\n CONVERT(expr\n USING transcoding_name)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "ExtractValue() takes two string\n arguments, a fragment of XML markup\n xml_frag and an XPath expression\n xpath_expr (also known as a\n locator); it returns the\n text (CDATA) of the first text node which\n is a child of the element or elements matched by the XPath\n expression."
},
{
"para": "Using this function is the equivalent of performing a match\n using the xpath_expr after\n appending /text(). In other words,\n ExtractValue('<a><b>Sakila</b></a>',\n '/a/b') and\n ExtractValue('<a><b>Sakila</b></a>',\n '/a/b/text()') produce the same result."
},
{
"para": "If multiple matches are found, the content of the first child\n text node of each matching element is returned (in the order\n matched) as a single, space-delimited string."
},
{
"para": "If no matching text node is found for the expression\n (including the implicit /text())mdashfor\n whatever reason, as long as\n xpath_expr is valid, and\n xml_frag consists of elements which\n are properly nested and closedmdashan empty string is\n returned. No distinction is made between a match on an empty\n element and no match at all. This is by design."
},
{
"para": "If you need to determine whether no matching element was found\n in xml_frag or such an element was\n found but contained no child text nodes, you should test the\n result of an expression that uses the XPath\n count() function. For example, both of\n these statements return an empty string, as shown here:"
},
{
"programlisting": ">\nmysql> SELECT ExtractValue('<a><b/></a>', '/a/b');\n+-------------------------------------+\n| ExtractValue('<a><b/></a>', '/a/b') |\n+-------------------------------------+\n| |\n+-------------------------------------+\n1 row in set (0.00 sec)\n\nmysql> SELECT ExtractValue('<a><c/></a>', '/a/b');\n+-------------------------------------+\n| ExtractValue('<a><c/></a>', '/a/b') |\n+-------------------------------------+\n| |\n+-------------------------------------+\n1 row in set (0.00 sec)"
},
{
"para": "However, you can determine whether there was actually a\n matching element using the following:"
},
{
"programlisting": ">\nmysql> SELECT ExtractValue('<a><b/></a>', 'count(/a/b)');\n+-------------------------------------+\n| ExtractValue('<a><b/></a>', 'count(/a/b)') |\n+-------------------------------------+\n| 1 |\n+-------------------------------------+\n1 row in set (0.00 sec)\n\nmysql> SELECT ExtractValue('<a><c/></a>', 'count(/a/b)');\n+-------------------------------------+\n| ExtractValue('<a><c/></a>', 'count(/a/b)') |\n+-------------------------------------+\n| 0 |\n+-------------------------------------+\n1 row in set (0.01 sec)"
}
],
"id": "ExtractValue",
"syntax": [
{
"para": "\n ExtractValue()\n \n\n ExtractValue(xml_frag,\n xpath_expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function replaces a single portion of a given fragment of\n XML markup xml_target with a new\n XML fragment new_xml, and then\n returns the changed XML. The portion of\n xml_target that is replaced matches\n an XPath expression xpath_expr\n supplied by the user."
},
{
"para": "If no expression matching\n xpath_expr is found, or if multiple\n matches are found, the function returns the original\n xml_target XML fragment. All three\n arguments should be strings."
}
],
"id": "UpdateXML",
"syntax": [
{
"para": "\n UpdateXML()\n \n\n UpdateXML(xml_target,\n xpath_expr,\n new_xml)"
}
]
},
{
"keywords": [
"AES_DECRYPT"
],
"description": [
{
"para": "This function decrypts data using the official AES (Advanced\n Encryption Standard) algorithm. For more information, see the\n description of AES_ENCRYPT()."
},
{
"para": "The optional initialization vector argument,\n init_vector. Statements that use\n AES_DECRYPT() are unsafe for\n statement-based replication."
}
],
"id": "AES_DECRYPT",
"syntax": [
{
"para": "\n AES_DECRYPT()\n \n\n AES_DECRYPT(crypt_str,key_str[,init_vector])"
}
]
},
{
"keywords": [
"AES_ENCRYPT"
],
"description": [
{
"para": "AES_ENCRYPT() and\n AES_DECRYPT() implement\n encryption and decryption of data using the official AES\n (Advanced Encryption Standard) algorithm, previously known as\n Rijndael. The AES standard permits various key\n lengths. By default these functions implement AES with a\n 128-bit key length. Key lengths of 196 or 256 bits can be\n used, as described later. The key length is a trade off\n between performance and security."
},
{
"para": "AES_ENCRYPT() encrypts the\n string str using the key string\n key_str and returns a binary string\n containing the encrypted output.\n AES_DECRYPT() decrypts the\n encrypted string crypt_str using\n the key string key_str and returns\n the original plaintext string. If either function argument is\n NULL, the function returns\n NULL."
},
{
"para": "The str and\n crypt_str arguments can be any\n length, and padding is automatically added to\n str so it is a multiple of a block\n as required by block-based algorithms such as AES. This\n padding is automatically removed by the\n AES_DECRYPT() function. The\n length of crypt_str can be\n calculated using this formula:"
},
{
"programlisting": ">\n16 * (trunc(string_length / 16) + 1)"
},
{
"para": "For a key length of 128 bits, the most secure way to pass a\n key to the key_str argument is to\n create a truly random 128-bit value and pass it as a binary\n value. For example:"
},
{
"programlisting": ">\nINSERT INTO t\nVALUES (1,AES_ENCRYPT('text',UNHEX('F3229A0B371ED2D9441B830D21A390C3')));"
},
{
"para": "A passphrase can be used to generate an AES key by hashing the\n passphrase. For example:"
},
{
"programlisting": ">\nINSERT INTO t\nVALUES (1,AES_ENCRYPT('text', UNHEX(SHA2('My secret passphrase',512))));"
},
{
"para": "Do not pass a password or passphrase directly to\n crypt_str, hash it first. Previous\n versions of this documentation suggested the former approach,\n but it is no longer recommended as the examples shown here are\n more secure."
},
{
"para": "If AES_DECRYPT() detects\n invalid data or incorrect padding, it returns\n NULL. However, it is possible for\n AES_DECRYPT() to return a\n non-NULL value (possibly garbage) if the\n input data or the key is invalid."
},
{
"para": "AES_ENCRYPT() and\n AES_DECRYPT() permit control of\n the block encryption mode and take an optional\n init_vector initialization vector\n argument:"
},
{
"itemizedlist": [
[
{
"para": "The block_encryption_mode\n system variable controls the mode for block-based\n encryption algorithms. Its default value is\n aes-128-ecb, which signifies encryption\n using a key length of 128 bits and ECB mode. For a\n description of the permitted values of this variable, see\n ."
}
],
[
{
"para": "The optional init_vector\n argument provides an initialization vector for block\n encryption modes that require it."
}
]
]
},
{
"para": "For modes that require the optional\n init_vector argument, it must be 16\n bytes or longer (bytes in excess of 16 are ignored). An error\n occurs if init_vector is missing."
},
{
"para": "For modes that do not require\n init_vector, it is ignored and a\n warning is generated if it is specified."
},
{
"para": "A random string of bytes to use for the initialization vector\n can be produced by calling\n RANDOM_BYTES(16). For\n encryption modes that require an initialization vector, the\n same vector must be used for encryption and decryption."
}
],
"id": "AES_ENCRYPT",
"syntax": [
{
"para": "\n AES_ENCRYPT()\n \n\n AES_ENCRYPT(str,key_str[,init_vector])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Compresses a string and returns the result as a binary string.\n This function requires MySQL to have been compiled with a\n compression library such as zlib.\n Otherwise, the return value is always NULL.\n The compressed string can be uncompressed with\n UNCOMPRESS()."
}
],
"id": "COMPRESS",
"syntax": [
{
"para": "\n COMPRESS()\n \n\n COMPRESS(string_to_compress)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3."
},
{
"para": "Consider using AES_ENCRYPT()\n and AES_DECRYPT() instead."
}
],
"id": "DECODE",
"syntax": [
{
"para": "\n DECODE()\n \n\n DECODE(crypt_str,pass_str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3."
},
{
"para": "Consider using AES_ENCRYPT()\n and AES_DECRYPT() instead."
}
],
"id": "DES_DECRYPT",
"syntax": [
{
"para": "\n DES_DECRYPT()\n \n\n DES_DECRYPT(crypt_str[,key_str])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3."
},
{
"para": "Consider using AES_ENCRYPT()\n and AES_DECRYPT() instead."
}
],
"id": "DES_ENCRYPT",
"syntax": [
{
"para": "\n DES_ENCRYPT()\n \n\n DES_ENCRYPT(str[,{key_num|key_str}])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3."
},
{
"para": "Consider using AES_ENCRYPT()\n and AES_DECRYPT() instead."
}
],
"id": "ENCODE",
"syntax": [
{
"para": "\n ENCODE()\n \n\n ENCODE(str,pass_str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3. For one-way hashing,\n consider using SHA2() instead."
}
],
"id": "ENCRYPT",
"syntax": [
{
"para": "\n ENCRYPT()\n \n\n ENCRYPT(str[,salt])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Calculates an MD5 128-bit checksum for the string. The value\n is returned as a string of 32 hexadecimal digits, or\n NULL if the argument was\n NULL. The return value can, for example, be\n used as a hash key. See the notes at the beginning of this\n section about storing hash values efficiently."
},
{
"para": "The return value is a string in the connection character set."
},
{
"para": "If FIPS mode is enabled,\n MD5() returns\n NULL. See ."
}
],
"id": "MD5",
"syntax": [
{
"para": "\n MD5()\n \n\n MD5(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.11."
}
],
"id": "PASSWORD",
"syntax": [
{
"para": "\n PASSWORD()\n \n\n PASSWORD(str)"
}
]
},
{
"keywords": [
"RANDOM_BYTES"
],
"description": [
{
"para": "This function returns a binary string of\n len random bytes generated using\n the random number generator of the SSL library. Permitted\n values of len range from 1 to 1024.\n For values outside that range,\n RANDOM_BYTES() generates a\n warning and returns NULL."
},
{
"para": "RANDOM_BYTES() can be used to\n provide the initialization vector for the\n AES_DECRYPT() and\n AES_ENCRYPT() functions. For\n use in that context, len must be at\n least 16. Larger values are permitted, but bytes in excess of\n 16 are ignored."
},
{
"para": "RANDOM_BYTES() generates a\n random value, which makes its result nondeterministic.\n Consequently, statements that use this function are unsafe for\n statement-based replication."
}
],
"id": "RANDOM_BYTES",
"syntax": [
{
"para": "\n RANDOM_BYTES()\n \n\n RANDOM_BYTES(len)"
}
]
},
{
"keywords": [
"SHA1",
"SHA"
],
"description": [
{
"para": "Calculates an SHA-1 160-bit checksum for the string, as\n described in RFC 3174 (Secure Hash Algorithm). The value is\n returned as a string of 40 hexadecimal digits, or\n NULL if the argument was\n NULL. One of the possible uses for this\n function is as a hash key. See the notes at the beginning of\n this section about storing hash values efficiently.\n SHA() is\n synonymous with SHA1()."
},
{
"para": "The return value is a string in the connection character set."
}
],
"id": "SHA1",
"syntax": [
{
"para": "\n SHA1()\n \n\n \n SHA()\n \n\n SHA1(str),\n SHA(str)"
}
]
},
{
"keywords": [
"SHA2"
],
"description": [
{
"para": "Calculates the SHA-2 family of hash functions (SHA-224,\n SHA-256, SHA-384, and SHA-512). The first argument is the\n plaintext string to be hashed. The second argument indicates\n the desired bit length of the result, which must have a value\n of 224, 256, 384, 512, or 0 (which is equivalent to 256). If\n either argument is NULL or the hash length\n is not one of the permitted values, the return value is\n NULL. Otherwise, the function result is a\n hash value containing the desired number of bits. See the\n notes at the beginning of this section about storing hash\n values efficiently."
},
{
"para": "The return value is a string in the connection character set."
}
],
"id": "SHA2",
"syntax": [
{
"para": "\n SHA2()\n \n\n SHA2(str,\n hash_length)"
}
]
},
{
"keywords": [
"STATEMENT_DIGEST"
],
"description": [
{
"para": "STATEMENT_DIGEST(statement)"
},
{
"para": "Given an SQL statement as a string, returns the statement\n digest hash value as a string in the connection character set,\n or NULL if the argument is\n NULL. The related\n STATEMENT_DIGEST_TEXT()\n function returns the normalized statement digest. For\n information about statement digesting, see\n ."
},
{
"para": "Both functions use the MySQL parser to parse the statement. If\n parsing fails, an error occurs. The error message includes the\n parse error only if the statement is provided as a literal\n string."
},
{
"para": "The max_digest_length system\n variable determines the maximum number of bytes available to\n these functions for computing normalized statement digests."
}
],
"id": "STATEMENT_DIGEST",
"syntax": []
},
{
"keywords": [
"STATEMENT_DIGEST_TEXT"
],
"description": [
{
"para": "STATEMENT_DIGEST_TEXT(statement)"
},
{
"para": "Given an SQL statement as a string, returns the normalized\n statement digest as a string in the connection character set,\n or NULL if the argument is\n NULL. For additional discussion and\n examples, see the description of the related\n STATEMENT_DIGEST() function."
}
],
"id": "STATEMENT_DIGEST_TEXT",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "Uncompresses a string compressed by the\n COMPRESS() function. If the\n argument is not a compressed value, the result is\n NULL. This function requires MySQL to have\n been compiled with a compression library such as\n zlib. Otherwise, the return value is always\n NULL."
}
],
"id": "UNCOMPRESS",
"syntax": [
{
"para": "\n UNCOMPRESS()\n \n\n UNCOMPRESS(string_to_uncompress)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the length that the compressed string had before being\n compressed."
}
],
"id": "UNCOMPRESSED_LENGTH",
"syntax": [
{
"para": "\n UNCOMPRESSED_LENGTH()\n \n\n UNCOMPRESSED_LENGTH(compressed_string)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given an argument representing a plaintext password, this\n function returns an integer to indicate how strong the\n password is. The return value ranges from 0 (weak) to 100\n (strong)."
}
],
"id": "VALIDATE_PASSWORD_STRENGTH",
"syntax": [
{
"para": "\n DAY()\n \n\n VALIDATE_PASSWORD_STRENGTH(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Tries to obtain a lock with a name given by the string\n str, using a timeout of\n timeout seconds. A negative\n timeout value means infinite\n timeout. The lock is exclusive. While held by one session,\n other sessions cannot obtain a lock of the same name."
},
{
"para": "Returns 1 if the lock was obtained\n successfully, 0 if the attempt timed out\n (for example, because another client has previously locked the\n name), or NULL if an error occurred (such\n as running out of memory or the thread was killed with\n mysqladmin kill)."
},
{
"para": "A lock obtained with GET_LOCK()\n is released explicitly by executing\n RELEASE_LOCK() or implicitly\n when your session terminates (either normally or abnormally).\n Locks obtained with GET_LOCK()\n are not released when transactions commit or roll back."
},
{
"para": "GET_LOCK() is implemented using\n the metadata locking (MDL) subsystem. Multiple simultaneous\n locks can be acquired and\n GET_LOCK() does not release any\n existing locks. For example, suppose that you execute these\n statements:"
},
{
"programlisting": ">\nSELECT GET_LOCK('lock1',10);\nSELECT GET_LOCK('lock2',10);\nSELECT RELEASE_LOCK('lock2');\nSELECT RELEASE_LOCK('lock1');"
},
{
"para": "The second GET_LOCK() acquires\n a second lock and both\n RELEASE_LOCK() calls return 1\n (success)."
},
{
"para": "It is even possible for a given session to acquire multiple\n locks for the same name. Other sessions cannot acquire a lock\n with that name until the acquiring session releases all its\n locks for the name."
},
{
"para": "Uniquely named locks acquired with\n GET_LOCK() appear in the\n Performance Schema metadata_locks\n table. The OBJECT_TYPE column says\n USER LEVEL LOCK and the\n OBJECT_NAME column indicates the lock name.\n In the case that multiple locks are acquired for the\n same name, only the first lock for the\n name registers a row in the\n metadata_locks table. Subsequent\n locks for the name increment a counter in the lock but do not\n acquire additional metadata locks. The\n metadata_locks row for the lock\n is deleted when the last lock instance on the name is\n released."
},
{
"para": "The capability of acquiring multiple locks means there is the\n possibility of deadlock among clients. When this happens, the\n server chooses a caller and terminates its lock-acquisition\n request with an\n ER_USER_LOCK_DEADLOCK error.\n This error does not cause transactions to roll back."
},
{
"para": "MySQL enforces a maximum length on lock names of 64\n characters."
},
{
"para": "GET_LOCK() can be used to\n implement application locks or to simulate record locks. Names\n are locked on a server-wide basis. If a name has been locked\n within one session, GET_LOCK()\n blocks any request by another session for a lock with the same\n name. This enables clients that agree on a given lock name to\n use the name to perform cooperative advisory locking. But be\n aware that it also enables a client that is not among the set\n of cooperating clients to lock a name, either inadvertently or\n deliberately, and thus prevent any of the cooperating clients\n from locking that name. One way to reduce the likelihood of\n this is to use lock names that are database-specific or\n application-specific. For example, use lock names of the form\n db_name.str or\n app_name.str."
}
],
"id": "GET_LOCK",
"syntax": [
{
"para": "\n timeout\n \n\n \n GET_LOCK()\n \n\n GET_LOCK(str,timeout)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Checks whether the lock named str\n is free to use (that is, not locked). Returns\n 1 if the lock is free (no one is using the\n lock), 0 if the lock is in use, and\n NULL if an error occurs (such as an\n incorrect argument)."
}
],
"id": "IS_FREE_LOCK",
"syntax": [
{
"para": "\n IS_FREE_LOCK()\n \n\n IS_FREE_LOCK(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Checks whether the lock named str\n is in use (that is, locked). If so, it returns the connection\n identifier of the client session that holds the lock.\n Otherwise, it returns NULL."
}
],
"id": "IS_USED_LOCK",
"syntax": [
{
"para": "\n IS_USED_LOCK()\n \n\n IS_USED_LOCK(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Releases all named locks held by the current session and\n returns the number of locks released (0 if there were none)"
}
],
"id": "RELEASE_ALL_LOCKS",
"syntax": [
{
"para": "\n RELEASE_ALL_LOCKS()\n \n\n RELEASE_ALL_LOCKS()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Releases the lock named by the string\n str that was obtained with\n GET_LOCK(). Returns\n 1 if the lock was released,\n 0 if the lock was not established by this\n thread (in which case the lock is not released), and\n NULL if the named lock did not exist. The\n lock does not exist if it was never obtained by a call to\n GET_LOCK() or if it has\n previously been released."
},
{
"para": "The DO statement is convenient\n to use with RELEASE_LOCK(). See\n ."
}
],
"id": "RELEASE_LOCK",
"syntax": [
{
"para": "\n RELEASE_LOCK()\n \n\n RELEASE_LOCK(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "The BENCHMARK() function\n executes the expression expr\n repeatedly count times. It may be\n used to time how quickly MySQL processes the expression. The\n result value is 0, or\n NULL for inappropriate arguments such as a\n NULL or negative repeat count."
},
{
"para": "The intended use is from within the mysql\n client, which reports query execution times:"
}
],
"id": "BENCHMARK",
"syntax": [
{
"para": "\n BENCHMARK()\n \n\n BENCHMARK(count,expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the character set of the string argument."
}
],
"id": "CHARSET",
"syntax": [
{
"para": "\n CHARSET()\n \n\n CHARSET(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the collation coercibility value of the string\n argument."
}
],
"id": "COERCIBILITY",
"syntax": [
{
"para": "\n COERCIBILITY()\n \n\n COERCIBILITY(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the collation of the string argument."
}
],
"id": "COLLATION",
"syntax": [
{
"para": "\n COLLATION()\n \n\n COLLATION(str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the connection ID (thread ID) for the connection.\n Every connection has an ID that is unique among the set of\n currently connected clients."
},
{
"para": "The value returned by\n CONNECTION_ID() is the same\n type of value as displayed in the ID column\n of the\n INFORMATION_SCHEMA.PROCESSLIST\n table, the Id column of\n SHOW PROCESSLIST output, and\n the PROCESSLIST_ID column of the\n Performance Schema threads table."
}
],
"id": "CONNECTION_ID",
"syntax": [
{
"para": "\n CONNECTION_ID()\n \n\n CONNECTION_ID()"
}
]
},
{
"keywords": [
"CURRENT_ROLE"
],
"description": [
{
"para": "\n CURRENT_ROLE()\n \n\n CURRENT_ROLE()"
},
{
"para": "Returns a utf8 string containing the\n current active roles for the current session, separated by\n commas, or NONE if there are none. The\n value reflects the setting of the\n sql_quote_show_create system\n variable."
}
],
"id": "CURRENT_ROLE",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "Returns the user name and host name combination for the MySQL\n account that the server used to authenticate the current\n client. This account determines your access privileges. The\n return value is a string in the utf8\n character set."
},
{
"para": "The value of CURRENT_USER() can\n differ from the value of\n USER()."
}
],
"id": "CURRENT_USER",
"syntax": [
{
"para": "\n CURRENT_USER()\n \n\n CURRENT_USER,\n CURRENT_USER()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the default (current) database name as a string in the\n utf8 character set. If there is no default\n database, DATABASE() returns\n NULL. Within a stored routine, the default\n database is the database that the routine is associated with,\n which is not necessarily the same as the database that is the\n default in the calling context."
}
],
"id": "DATABASE",
"syntax": [
{
"para": "\n DATABASE()\n \n\n DATABASE()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "A SELECT statement may include\n a LIMIT clause to restrict the number of\n rows the server returns to the client. In some cases, it is\n desirable to know how many rows the statement would have\n returned without the LIMIT, but without\n running the statement again. To obtain this row count, include\n an SQL_CALC_FOUND_ROWS option in the\n SELECT statement, and then\n invoke FOUND_ROWS() afterward:"
}
],
"id": "FOUND_ROWS",
"syntax": [
{
"para": "\n FOUND_ROWS()\n \n\n \n LIMIT\n \n\n FOUND_ROWS()"
}
]
},
{
"keywords": [
"ICU_VERSION"
],
"description": [
{
"para": "ICU_VERSION()"
},
{
"para": "The version of the International Components for Unicode (ICU)\n library used to support regular expression operations (see\n ). This function is primarily intended\n for use in test cases."
}
],
"id": "ICU_VERSION",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "With no argument,\n LAST_INSERT_ID() returns a\n BIGINT UNSIGNED (64-bit) value representing\n the first automatically generated value successfully inserted\n for an AUTO_INCREMENT column as a result of\n the most recently executed\n INSERT statement. The value of\n LAST_INSERT_ID() remains\n unchanged if no rows are successfully inserted."
},
{
"para": "With an argument,\n LAST_INSERT_ID() returns an\n unsigned integer."
},
{
"para": "For example, after inserting a row that generates an\n AUTO_INCREMENT value, you can get the value\n like this:"
},
{
"programlisting": ">\nmysql> SELECT LAST_INSERT_ID();\n -> 195"
},
{
"para": "The currently executing statement does not affect the value of\n LAST_INSERT_ID(). Suppose that\n you generate an AUTO_INCREMENT value with\n one statement, and then refer to\n LAST_INSERT_ID() in a\n multiple-row INSERT statement\n that inserts rows into a table with its own\n AUTO_INCREMENT column. The value of\n LAST_INSERT_ID() will remain\n stable in the second statement; its value for the second and\n later rows is not affected by the earlier row insertions.\n (However, if you mix references to\n LAST_INSERT_ID() and\n LAST_INSERT_ID(expr),\n the effect is undefined.)"
},
{
"para": "If the previous statement returned an error, the value of\n LAST_INSERT_ID() is undefined.\n For transactional tables, if the statement is rolled back due\n to an error, the value of\n LAST_INSERT_ID() is left\n undefined. For manual\n ROLLBACK,\n the value of LAST_INSERT_ID()\n is not restored to that before the transaction; it remains as\n it was at the point of the\n ROLLBACK."
},
{
"para": "Within the body of a stored routine (procedure or function) or\n a trigger, the value of\n LAST_INSERT_ID() changes the\n same way as for statements executed outside the body of these\n kinds of objects. The effect of a stored routine or trigger\n upon the value of\n LAST_INSERT_ID() that is seen\n by following statements depends on the kind of routine:"
},
{
"itemizedlist": [
[
{
"para": "If a stored procedure executes statements that change the\n value of LAST_INSERT_ID(),\n the changed value is seen by statements that follow the\n procedure call."
}
],
[
{
"para": "For stored functions and triggers that change the value,\n the value is restored when the function or trigger ends,\n so following statements will not see a changed value."
}
]
]
}
],
"id": "LAST_INSERT_ID",
"syntax": [
{
"para": "\n LAST_INSERT_ID()\n \n\n LAST_INSERT_ID(),\n LAST_INSERT_ID(expr)"
}
]
},
{
"keywords": [
"ROLES_GRAPHML"
],
"description": [
{
"para": "\n ROLES_GRAPHML()\n \n\n ROLES_GRAPHML()"
},
{
"para": "Returns a utf8 string containing a GraphML\n document representing memory role subgraphs. The\n ROLE_ADMIN or\n SUPER privilege is required to\n see content in the <graphml> element.\n Otherwise, the result shows only an empty element:"
},
{
"programlisting": ">\nmysql> SELECT ROLES_GRAPHML();\n+---------------------------------------------------+\n| ROLES_GRAPHML() |\n+---------------------------------------------------+\n| <?xml version=\"1.0\" encoding=\"UTF-8\"?><graphml /> |\n+---------------------------------------------------+"
}
],
"id": "ROLES_GRAPHML",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "ROW_COUNT() returns a value as follows:"
},
{
"itemizedlist": [
[
{
"para": "DDL statements: 0. This applies to statements such as\n CREATE TABLE or\n DROP TABLE."
}
],
[
{
"para": "DML statements other than\n SELECT: The number of\n affected rows. This applies to statements such as\n UPDATE,\n INSERT, or\n DELETE (as before), but now\n also to statements such as ALTER\n TABLE and LOAD\n DATA."
}
],
[
{
"para": "SELECT: -1 if the statement\n returns a result set, or the number of rows\n affected if it does not. For example, for\n SELECT * FROM t1,\n ROW_COUNT() returns -1. For\n SELECT * FROM t1 INTO OUTFILE\n 'file_name',\n ROW_COUNT() returns the\n number of rows written to the file."
}
],
[
{
"para": "SIGNAL statements: 0."
}
]
]
},
{
"para": "For UPDATE statements, the\n affected-rows value by default is the number of rows actually\n changed. If you specify the\n CLIENT_FOUND_ROWS flag to\n mysql_real_connect() when\n connecting to mysqld, the affected-rows\n value is the number of rows found; that is,\n matched by the WHERE clause."
},
{
"para": "For REPLACE statements, the\n affected-rows value is 2 if the new row replaced an old row,\n because in this case, one row was inserted after the duplicate\n was deleted."
},
{
"para": "For\n INSERT\n ... ON DUPLICATE KEY UPDATE statements, the\n affected-rows value per row is 1 if the row is inserted as a\n new row, 2 if an existing row is updated, and 0 if an existing\n row is set to its current values. If you specify the\n CLIENT_FOUND_ROWS flag, the affected-rows\n value is 1 (not 0) if an existing row is set to its current\n values."
},
{
"para": "The ROW_COUNT() value is\n similar to the value from the\n mysql_affected_rows() C API\n function and the row count that the mysql\n client displays following statement execution."
}
],
"id": "ROW_COUNT",
"syntax": [
{
"para": "\n ROW_COUNT()\n \n\n ROW_COUNT()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function is a synonym for\n DATABASE()."
}
],
"id": "SCHEMA",
"syntax": [
{
"para": "\n SCHEMA()\n \n\n SCHEMA()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "SESSION_USER() is a synonym for\n USER()."
}
],
"id": "SESSION_USER",
"syntax": [
{
"para": "\n SESSION_USER()\n \n\n SESSION_USER()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "SYSTEM_USER() is a synonym for\n USER()."
}
],
"id": "SYSTEM_USER",
"syntax": [
{
"para": "\n SYSTEM_USER()\n \n\n SYSTEM_USER()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current MySQL user name and host name as a string\n in the utf8 character set."
}
],
"id": "USER",
"syntax": [
{
"para": "\n USER()\n \n\n USER()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string that indicates the MySQL server version. The\n string uses the utf8 character set. The\n value might have a suffix in addition to the version number.\n See the description of the\n version system variable in\n ."
}
],
"id": "VERSION",
"syntax": [
{
"para": "\n VERSION()\n \n\n VERSION()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given two sets of global transaction identifiers\n set1 and\n set2, returns true if all GTIDs in\n set1 are also in\n set2. Returns false otherwise."
}
],
"id": "GTID_SUBSET",
"syntax": [
{
"para": "\n GTID_SUBSET()\n \n\n GTID_SUBSET(set1,set2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given two sets of global transaction identifiers\n set1 and\n set2, returns only those GTIDs from\n set1 that are not in\n set2."
}
],
"id": "GTID_SUBTRACT",
"syntax": [
{
"para": "\n GTID_SUBTRACT()\n \n\n GTID_SUBTRACT(set1,set2)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Wait until the server has applied all of the transactions\n whose global transaction identifiers are contained in\n gtid_set; that is, until the\n condition GTID_SUBSET(gtid_subset,\n @@GLOBAL.gtid_executed) holds. See\n for a definition\n of GTID sets."
},
{
"para": "If a timeout is specified, and\n timeout seconds elapse before all\n of the transactions in the GTID set have been applied, the\n function stops waiting. timeout is\n optional, and the default timeout is 0 seconds, in which case\n the function always waits until all of the transactions in the\n GTID set have been applied."
},
{
"para": "WAIT_FOR_EXECUTED_GTID_SET() monitors all\n the GTIDs that are applied on the server, including\n transactions that arrive from all replication channels and\n user clients. It does not take into account whether\n replication channels have been started or stopped."
},
{
"para": "For more information, see ."
}
],
"id": "WAIT_FOR_EXECUTED_GTID_SET",
"syntax": [
{
"para": "\n WAIT_FOR_EXECUTED_GTID_SET()\n \n\n WAIT_FOR_EXECUTED_GTID_SET(gtid_set[,\n timeout])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS() is\n deprecated. Use\n WAIT_FOR_EXECUTED_GTID_SET() instead, which\n works regardless of the replication channel or user client\n through which the specified transactions arrive on the server."
}
],
"id": "WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS",
"syntax": [
{
"para": "\n WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()\n \n\n WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS(gtid_set[,\n timeout][,channel])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Decrypts an encrypted string using the given algorithm and\n key string, and returns the resulting plaintext as a binary\n string. If decryption fails, the result is\n NULL."
},
{
"para": "key_str must be a valid key\n string in PEM format. For successful decryption, it must be\n the public or private key string corresponding to the\n private or public key string used with\n ASYMMETRIC_ENCRYPT() to\n produce the encrypted string.\n algorithm indicates the\n encryption algorithm used to create the key."
},
{
"para": "Supported algorithm values:\n 'RSA'"
},
{
"para": "For a usage example, see the description of\n ASYMMETRIC_ENCRYPT()."
}
],
"id": "ASYMMETRIC_DECRYPT",
"syntax": [
{
"para": "\n ASYMMETRIC_DECRYPT()\n \n\n ASYMMETRIC_DECRYPT(algorithm,\n crypt_str,\n key_str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Derives a symmetric key using the private key of one party\n and the public key of another, and returns the resulting key\n as a binary string. If key derivation fails, the result is\n NULL."
},
{
"para": "pub_key_str and\n priv_key_str must be valid key\n strings in PEM format. They must be created using the DH\n algorithm."
},
{
"para": "Suppose that you have two pairs of public and private keys:"
},
{
"programlisting": ">\nSET @dhp = CREATE_DH_PARAMETERS(1024);\nSET @priv1 = CREATE_ASYMMETRIC_PRIV_KEY('DH', @dhp);\nSET @pub1 = CREATE_ASYMMETRIC_PUB_KEY('DH', @priv1);\nSET @priv2 = CREATE_ASYMMETRIC_PRIV_KEY('DH', @dhp);\nSET @pub2 = CREATE_ASYMMETRIC_PUB_KEY('DH', @priv2);"
},
{
"para": "Suppose further that you use the private key from one pair\n and the public key from the other pair to create a symmetric\n key string. Then this symmetric key identity relationship\n holds:"
},
{
"programlisting": ">\nASYMMETRIC_DERIVE(@pub1, @priv2) = ASYMMETRIC_DERIVE(@pub2, @priv1)"
}
],
"id": "ASYMMETRIC_DERIVE",
"syntax": [
{
"para": "\n ASYMMETRIC_DERIVE()\n \n\n ASYMMETRIC_DERIVE(pub_key_str,\n priv_key_str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Encrypts a string using the given algorithm and key string,\n and returns the resulting ciphertext as a binary string. If\n encryption fails, the result is NULL."
},
{
"para": "The str length cannot be greater\n than the key_str length minus\n 11, in bytes"
},
{
"para": "key_str must be a valid key\n string in PEM format. algorithm\n indicates the encryption algorithm used to create the key."
},
{
"para": "Supported algorithm values:\n 'RSA'"
},
{
"para": "To encrypt a string, pass a private or public key string to\n ASYMMETRIC_ENCRYPT(). To\n recover the original unencrypted string, pass the encrypted\n string to\n ASYMMETRIC_DECRYPT(), along\n with the public or private key string correponding to the\n private or public key string used for encryption."
}
],
"id": "ASYMMETRIC_ENCRYPT",
"syntax": [
{
"para": "\n ASYMMETRIC_ENCRYPT()\n \n\n ASYMMETRIC_ENCRYPT(algorithm,\n str,\n key_str)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Signs a digest string using a private key string, and\n returns the signature as a binary string. If signing fails,\n the result is NULL."
},
{
"para": "digest_str is the digest string.\n It can be generated by calling\n CREATE_DIGEST().\n digest_type indicates the digest\n algorithm used to generate the digest string."
},
{
"para": "priv_key_str is the private key\n string to use for signing the digest string. It must be a\n valid key string in PEM format.\n algorithm indicates the\n encryption algorithm used to create the key."
},
{
"para": "Supported algorithm values:\n 'RSA', 'DSA'"
},
{
"para": "Supported digest_type values:\n 'SHA224', 'SHA256',\n 'SHA384', 'SHA512'"
},
{
"para": "For a usage example, see the description of\n ASYMMETRIC_VERIFY()."
}
],
"id": "ASYMMETRIC_SIGN",
"syntax": [
{
"para": "\n ASYMMETRIC_SIGN()\n \n\n ASYMMETRIC_SIGN(algorithm,\n digest_str,\n priv_key_str,\n digest_type)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Verifies whether the signature string matches the digest\n string, and returns 1 or 0 to indicate whether verification\n succeeded or failed."
},
{
"para": "digest_str is the digest string.\n It can be generated by calling\n CREATE_DIGEST().\n digest_type indicates the digest\n algorithm used to generate the digest string."
},
{
"para": "sig_str is the signature string.\n It can be generated by calling\n ASYMMETRIC_SIGN()."
},
{
"para": "pub_key_str is the public key\n string of the signer. It corresponds to the private key\n passed to ASYMMETRIC_SIGN()\n to generate the signature string and must be a valid key\n string in PEM format. algorithm\n indicates the encryption algorithm used to create the key."
},
{
"para": "Supported algorithm values:\n 'RSA', 'DSA'"
},
{
"para": "Supported digest_type values:\n 'SHA224', 'SHA256',\n 'SHA384', 'SHA512'"
}
],
"id": "ASYMMETRIC_VERIFY",
"syntax": [
{
"para": "\n ASYMMETRIC_VERIFY()\n \n\n ASYMMETRIC_VERIFY(algorithm,\n digest_str,\n sig_str,\n pub_key_str,\n digest_type)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Creates a private key using the given algorithm and key\n length or DH secret, and returns the key as a binary string\n in PEM format. If key generation fails, the result is\n NULL."
},
{
"para": "Supported algorithm values:\n 'RSA', 'DSA',\n 'DH'"
},
{
"para": "Supported key_len values: The\n minimum key length in bits is 1,024. The maximum key length\n depends on the algorithm: 16,384 for RSA and 10,000 for DSA.\n These key-length limits are constraints imposed by OpenSSL.\n Server administrators can impose additional limits on\n maximum key length by setting environment variables. See\n ."
},
{
"para": "For DH keys, pass a shared DH secret instead of a key\n length. To create the secret, pass the key length to\n CREATE_DH_PARAMETERS()."
}
],
"id": "CREATE_ASYMMETRIC_PRIV_KEY",
"syntax": [
{
"para": "\n CREATE_ASYMMETRIC_PRIV_KEY()\n \n\n CREATE_ASYMMETRIC_PRIV_KEY(algorithm,\n {key_len|dh_secret})"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Derives a public key from the given private key using the\n given algorithm, and returns the key as a binary string in\n PEM format. If key derivation fails, the result is\n NULL."
},
{
"para": "priv_key_str must be a valid key\n string in PEM format. algorithm\n indicates the encryption algorithm used to create the key."
},
{
"para": "Supported algorithm values:\n 'RSA', 'DSA',\n 'DH'"
},
{
"para": "For a usage example, see the description of\n CREATE_ASYMMETRIC_PRIV_KEY()."
}
],
"id": "CREATE_ASYMMETRIC_PUB_KEY",
"syntax": [
{
"para": "\n CREATE_ASYMMETRIC_PUB_KEY()\n \n\n CREATE_ASYMMETRIC_PUB_KEY(algorithm,\n priv_key_str)"
}
]
},
{
"keywords": [
"CREATE_DH_PARAMETERS"
],
"description": [
{
"para": "\n CREATE_DH_PARAMETERS()\n \n\n CREATE_DH_PARAMETERS(key_len)"
},
{
"para": "Creates a shared secret for generating a DH private/public\n key pair and returns a binary string that can be passed to\n CREATE_ASYMMETRIC_PRIV_KEY().\n If secret generation fails, the result is null."
},
{
"para": "Supported key_len values: The\n minimum and maximum key lengths in bits are 1,024 and\n 10,000. These key-length limits are constraints imposed by\n OpenSSL. Server administrators can impose additional limits\n on maximum key length by setting environment variables. See\n ."
},
{
"para": "For an example showing how to use the return value for\n generating symmetric keys, see the description of\n ASYMMETRIC_DERIVE()."
}
],
"id": "CREATE_DH_PARAMETERS",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "Creates a digest from the given string using the given\n digest type, and returns the digest as a binary string. If\n digest generation fails, the result is\n NULL."
},
{
"para": "Supported digest_type values:\n 'SHA224', 'SHA256',\n 'SHA384', 'SHA512'"
}
],
"id": "CREATE_DIGEST",
"syntax": [
{
"para": "\n CREATE_DIGEST()\n \n\n CREATE_DIGEST(digest_type,\n str)"
}
]
},
{
"keywords": [
"DISTINCT"
],
"description": [
{
"para": "Returns the average value of\n expr. The\n DISTINCT option can be used to return the\n average of the distinct values of\n expr."
},
{
"para": "If there are no matching rows,\n AVG() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ; it cannot be used\n with DISTINCT."
}
],
"id": "AVG",
"syntax": [
{
"para": "\n AVG()\n \n\n \n AVG(DISTINCT)\n \n\n \n DISTINCT\n AVG()\n \n\n AVG([DISTINCT]\n expr)\n [over_clause]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the bitwise AND of all bits in\n expr."
},
{
"para": "The result type depends on whether the function argument\n values are evaluated as binary strings or numbers:"
},
{
"itemizedlist": [
[
{
"para": "Binary-string evaluation occurs when the argument values\n have a binary string type, and the argument is not a\n hexadecimal literal, bit literal, or\n NULL literal. Numeric evaluation\n occurs otherwise, with argument value conversion to\n unsigned 64-bit integers as necessary."
}
],
[
{
"para": "Binary-string evaluation produces a binary string of the\n same length as the argument values. If argument values\n have unequal lengths, an\n ER_INVALID_BITWISE_OPERANDS_SIZE\n error occurs. If the argument size exceeds 511 bytes, an\n ER_INVALID_BITWISE_AGGREGATE_OPERANDS_SIZE\n error occurs. Numeric evaluation produces an unsigned\n 64-bit integer."
}
]
]
},
{
"para": "If there are no matching rows,\n BIT_AND() returns a neutral\n value (all bits set to 1) having the same length as the\n argument values."
},
{
"para": "NULL values do not affect the result\n unless all values are NULL. In that case,\n the result is a neutral value having the same length as the\n argument values."
},
{
"para": "For more information discussion about argument evaluation\n and result types, see the introductory discussion in\n ."
},
{
"para": "As of MySQL 8.0.12, this function executes as a window\n function if over_clause is\n present. over_clause is as\n described in ."
}
],
"id": "BIT_AND",
"syntax": [
{
"para": "\n BIT_AND()\n \n\n BIT_AND(expr)\n [over_clause]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the bitwise OR of all bits in\n expr."
},
{
"para": "The result type depends on whether the function argument\n values are evaluated as binary strings or numbers:"
},
{
"itemizedlist": [
[
{
"para": "Binary-string evaluation occurs when the argument values\n have a binary string type, and the argument is not a\n hexadecimal literal, bit literal, or\n NULL literal. Numeric evaluation\n occurs otherwise, with argument value conversion to\n unsigned 64-bit integers as necessary."
}
],
[
{
"para": "Binary-string evaluation produces a binary string of the\n same length as the argument values. If argument values\n have unequal lengths, an\n ER_INVALID_BITWISE_OPERANDS_SIZE\n error occurs. If the argument size exceeds 511 bytes, an\n ER_INVALID_BITWISE_AGGREGATE_OPERANDS_SIZE\n error occurs. Numeric evaluation produces an unsigned\n 64-bit integer."
}
]
]
},
{
"para": "If there are no matching rows,\n BIT_OR() returns a neutral\n value (all bits set to 0) having the same length as the\n argument values."
},
{
"para": "NULL values do not affect the result\n unless all values are NULL. In that case,\n the result is a neutral value having the same length as the\n argument values."
},
{
"para": "For more information discussion about argument evaluation\n and result types, see the introductory discussion in\n ."
},
{
"para": "As of MySQL 8.0.12, this function executes as a window\n function if over_clause is\n present. over_clause is as\n described in ."
}
],
"id": "BIT_OR",
"syntax": [
{
"para": "\n BIT_OR()\n \n\n BIT_OR(expr)\n [over_clause]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the bitwise XOR of all\n bits in expr."
},
{
"para": "The result type depends on whether the function argument\n values are evaluated as binary strings or numbers:"
},
{
"itemizedlist": [
[
{
"para": "Binary-string evaluation occurs when the argument values\n have a binary string type, and the argument is not a\n hexadecimal literal, bit literal, or\n NULL literal. Numeric evaluation\n occurs otherwise, with argument value conversion to\n unsigned 64-bit integers as necessary."
}
],
[
{
"para": "Binary-string evaluation produces a binary string of the\n same length as the argument values. If argument values\n have unequal lengths, an\n ER_INVALID_BITWISE_OPERANDS_SIZE\n error occurs. If the argument size exceeds 511 bytes, an\n ER_INVALID_BITWISE_AGGREGATE_OPERANDS_SIZE\n error occurs. Numeric evaluation produces an unsigned\n 64-bit integer."
}
]
]
},
{
"para": "If there are no matching rows,\n BIT_XOR() returns a neutral\n value (all bits set to 0) having the same length as the\n argument values."
},
{
"para": "NULL values do not affect the result\n unless all values are NULL. In that case,\n the result is a neutral value having the same length as the\n argument values."
},
{
"para": "For more information discussion about argument evaluation\n and result types, see the introductory discussion in\n ."
},
{
"para": "As of MySQL 8.0.12, this function executes as a window\n function if over_clause is\n present. over_clause is as\n described in ."
}
],
"id": "BIT_XOR",
"syntax": [
{
"para": "\n BIT_XOR()\n \n\n BIT_XOR(expr)\n [over_clause]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a count of the number of non-NULL\n values of expr in the rows\n retrieved by a SELECT\n statement. The result is a\n BIGINT value."
},
{
"para": "If there are no matching rows,\n COUNT() returns\n 0."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ."
}
],
"id": "COUNT",
"syntax": [
{
"para": "\n COUNT()\n \n\n COUNT(expr)\n [over_clause]"
}
]
},
{
"keywords": [
"COUNT",
"DISTINCT"
],
"description": [
{
"para": "Returns a count of the number of rows with different\n non-NULLexpr\n values."
},
{
"para": "If there are no matching rows,\n COUNT(DISTINCT) returns\n 0."
}
],
"id": "COUNT DISTINCT",
"syntax": [
{
"para": "\n COUNT(DISTINCT)\n \n\n \n DISTINCT\n COUNT()\n \n\n COUNT(DISTINCT\n expr,[expr...])"
}
]
},
{
"keywords": [
"DISTINCT",
"SEPARATOR",
"ORDER",
"BY",
"ASC",
"DESC"
],
"description": [
{
"para": "This function returns a string result with the concatenated\n non-NULL values from a group. It returns\n NULL if there are no\n non-NULL values. The full syntax is as\n follows:"
},
{
"programlisting": ">\nGROUP_CONCAT([DISTINCT] expr [,expr ...]\n [ORDER BY {unsigned_integer | col_name | expr}\n [ASC | DESC] [,col_name ...]]\n [SEPARATOR str_val])"
}
],
"id": "GROUP_CONCAT",
"syntax": [
{
"para": "\n GROUP_CONCAT()\n \n\n GROUP_CONCAT(expr)"
}
]
},
{
"keywords": [
"JSON_ARRAYAGG"
],
"description": [
{
"para": "Aggregates a result set as a single\n JSON array whose elements\n consist of the rows. The order of elements in this array is\n undefined. The function acts on a column or an expression\n that evaluates to a single value. Returns\n NULL if the result contains no rows, or\n in the event of an error."
},
{
"para": "As of MySQL 8.0.14, this function executes as a window\n function if over_clause is\n present. over_clause is as\n described in ."
}
],
"id": "JSON_ARRAYAGG",
"syntax": [
{
"para": "\n JSON_ARRAYAGG()\n \n\n JSON_ARRAYAGG(col_or_expr)\n [over_clause]"
}
]
},
{
"keywords": [
"JSON_OBJECTAGG"
],
"description": [
{
"para": "Takes two column names or expressions as arguments, the\n first of these being used as a key and the second as a\n value, and returns a JSON object containing key-value pairs.\n Returns NULL if the result contains no\n rows, or in the event of an error. An error occurs if any\n key name is NULL or the number of\n arguments is not equal to 2."
},
{
"para": "As of MySQL 8.0.14, this function executes as a window\n function if over_clause is\n present. over_clause is as\n described in ."
}
],
"id": "JSON_OBJECTAGG",
"syntax": [
{
"para": "\n JSON_OBJECTAGG()\n \n\n JSON_OBJECTAGG(key,\n value)\n [over_clause]"
}
]
},
{
"keywords": [
"DISTINCT"
],
"description": [
{
"para": "Returns the maximum value of\n expr.\n MAX() may take a string\n argument; in such cases, it returns the maximum string\n value. See . The\n DISTINCT keyword can be used to find the\n maximum of the distinct values of\n expr, however, this produces the\n same result as omitting DISTINCT."
},
{
"para": "If there are no matching rows,\n MAX() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ; it cannot be used\n with DISTINCT."
}
],
"id": "MAX",
"syntax": [
{
"para": "\n MAX()\n \n\n \n MAX(DISTINCT)\n \n\n \n DISTINCT\n MAX()\n \n\n MAX([DISTINCT]\n expr)\n [over_clause]"
}
]
},
{
"keywords": [
"DISTINCT"
],
"description": [
{
"para": "Returns the minimum value of\n expr.\n MIN() may take a string\n argument; in such cases, it returns the minimum string\n value. See . The\n DISTINCT keyword can be used to find the\n minimum of the distinct values of\n expr, however, this produces the\n same result as omitting DISTINCT."
},
{
"para": "If there are no matching rows,\n MIN() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ; it cannot be used\n with DISTINCT."
}
],
"id": "MIN",
"syntax": [
{
"para": "\n MIN()\n \n\n \n MIN(DISTINCT)\n \n\n \n DISTINCT\n MIN()\n \n\n MIN([DISTINCT]\n expr)\n [over_clause]"
}
]
},
{
"keywords": [
"STD"
],
"description": [
{
"para": "Returns the population standard deviation of\n expr.\n STD() is a synonym for the\n standard SQL function\n STDDEV_POP(), provided as a\n MySQL extension."
},
{
"para": "If there are no matching rows,\n STD() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ."
}
],
"id": "STD",
"syntax": [
{
"para": "\n STD()\n \n\n STD(expr)\n [over_clause]"
}
]
},
{
"keywords": [
"STDDEV"
],
"description": [
{
"para": "Returns the population standard deviation of\n expr.\n STDDEV() is a synonym for the\n standard SQL function\n STDDEV_POP(), provided for\n compatibility with Oracle."
},
{
"para": "If there are no matching rows,\n STDDEV() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ."
}
],
"id": "STDDEV",
"syntax": [
{
"para": "\n STDDEV()\n \n\n \n Oracle compatibility\n \n\n \n compatibility\n with Oracle\n \n\n STDDEV(expr)\n [over_clause]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the population standard deviation of\n expr (the square root of\n VAR_POP()). You can also use\n STD() or\n STDDEV(), which are\n equivalent but not standard SQL."
},
{
"para": "If there are no matching rows,\n STDDEV_POP() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ."
}
],
"id": "STDDEV_POP",
"syntax": [
{
"para": "\n STDDEV_POP()\n \n\n STDDEV_POP(expr)\n [over_clause]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the sample standard deviation of\n expr (the square root of\n VAR_SAMP()."
},
{
"para": "If there are no matching rows,\n STDDEV_SAMP() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ."
}
],
"id": "STDDEV_SAMP",
"syntax": [
{
"para": "\n STDDEV_SAMP()\n \n\n STDDEV_SAMP(expr)\n [over_clause]"
}
]
},
{
"keywords": [
"DISTINCT"
],
"description": [
{
"para": "Returns the sum of expr. If the\n return set has no rows, SUM()\n returns NULL. The\n DISTINCT keyword can be used to sum only\n the distinct values of expr."
},
{
"para": "If there are no matching rows,\n SUM() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ; it cannot be used\n with DISTINCT."
}
],
"id": "SUM",
"syntax": [
{
"para": "\n SUM()\n \n\n \n SUM(DISTINCT)\n \n\n \n DISTINCT\n SUM()\n \n\n SUM([DISTINCT]\n expr)\n [over_clause]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the population standard variance of\n expr. It considers rows as the\n whole population, not as a sample, so it has the number of\n rows as the denominator. You can also use\n VARIANCE(), which is\n equivalent but is not standard SQL."
},
{
"para": "If there are no matching rows,\n VAR_POP() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ."
}
],
"id": "VAR_POP",
"syntax": [
{
"para": "\n VAR_POP()\n \n\n VAR_POP(expr)\n [over_clause]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the sample variance of\n expr. That is, the denominator is\n the number of rows minus one."
},
{
"para": "If there are no matching rows,\n VAR_SAMP() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ."
}
],
"id": "VAR_SAMP",
"syntax": [
{
"para": "\n VAR_SAMP()\n \n\n VAR_SAMP(expr)\n [over_clause]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the population standard variance of\n expr.\n VARIANCE() is a synonym for\n the standard SQL function\n VAR_POP(), provided as a\n MySQL extension."
},
{
"para": "If there are no matching rows,\n VARIANCE() returns\n NULL."
},
{
"para": "This function executes as a window function if\n over_clause is present.\n over_clause is as described in\n ."
}
],
"id": "VARIANCE",
"syntax": [
{
"para": "\n VARIANCE()\n \n\n VARIANCE(expr)\n [over_clause]"
}
]
},
{
"keywords": [
"CUME_DIST"
],
"description": [
{
"para": "CUME_DIST()\n over_clause"
},
{
"para": "Returns the cumulative distribution of a value within a\n group of values; that is, the percentage of partition values\n less than or equal to the value in the current row. This\n represents the number of rows preceding or peer with the\n current row in the window ordering of the window partition\n divided by the total number of rows in the window partition.\n Return values range from 0 to 1."
},
{
"para": "This function should be used with ORDER\n BY to sort partition rows into the desired order.\n Without ORDER BY, all rows are peers and\n have value\n N/N =\n 1, where N is the partition size."
},
{
"para": "over_clause is as described in\n ."
}
],
"id": "CUME_DIST",
"syntax": []
},
{
"keywords": [
"DENSE_RANK"
],
"description": [
{
"para": "DENSE_RANK()\n over_clause"
},
{
"para": "Returns the rank of the current row within its partition,\n without gaps. Peers are considered ties and receive the same\n rank. This function assigns consecutive ranks to peer\n groups; the result is that groups of size greater than one\n do not produce noncontiguous rank numbers. For an example,\n see the RANK() function\n description."
},
{
"para": "This function should be used with ORDER\n BY to sort partition rows into the desired order.\n Without ORDER BY, all rows are peers."
},
{
"para": "over_clause is as described in\n ."
}
],
"id": "DENSE_RANK",
"syntax": []
},
{
"keywords": [
"FIRST_VALUE"
],
"description": [
{
"para": "FIRST_VALUE(expr)\n [null_treatment]\n over_clause"
},
{
"para": "Returns the value of expr from\n the first row of the window frame."
},
{
"para": "over_clause is as described in\n .\n null_treatment is as described in\n the section introduction."
}
],
"id": "FIRST_VALUE",
"syntax": []
},
{
"keywords": [
"LAG"
],
"description": [
{
"para": "LAG(expr [,\n N[,\n default]])\n [null_treatment]\n over_clause"
},
{
"para": "Returns the value of expr from\n the row that lags (precedes) the current row by\n N rows within its partition. If\n there is no such row, the return value is\n default. For example, if\n N is 3, the return value is\n default for the first two rows.\n If N or\n default are missing, the defaults\n are 1 and NULL, respectively."
},
{
"para": "N must be a literal nonnegative\n integer. If N is 0,\n expr is evaluated for the current\n row."
},
{
"para": "over_clause is as described in\n .\n null_treatment is as described in\n the section introduction."
}
],
"id": "LAG",
"syntax": []
},
{
"keywords": [
"LAST_VALUE"
],
"description": [
{
"para": "LAST_VALUE(expr)\n [null_treatment]\n over_clause"
},
{
"para": "Returns the value of expr from\n the last row of the window frame."
},
{
"para": "over_clause is as described in\n .\n null_treatment is as described in\n the section introduction."
},
{
"para": "For an example, see the\n FIRST_VALUE() function\n description."
}
],
"id": "LAST_VALUE",
"syntax": []
},
{
"keywords": [
"LEAD"
],
"description": [
{
"para": "LEAD(expr [,\n N[,\n default]])\n [null_treatment]\n over_clause"
},
{
"para": "Returns the value of expr from\n the row that leads (follows) the current row by\n N rows within its partition. If\n there is no such row, the return value is\n default. For example, if\n N is 3, the return value is\n default for the last two rows. If\n N or\n default are missing, the defaults\n are 1 and NULL, respectively."
},
{
"para": "N must be a literal nonnegative\n integer. If N is 0,\n expr is evaluated for the current\n row."
},
{
"para": "over_clause is as described in\n .\n null_treatment is as described in\n the section introduction."
},
{
"para": "For an example, see the LAG()\n function description."
}
],
"id": "LEAD",
"syntax": []
},
{
"keywords": [
"NTH_VALUE"
],
"description": [
{
"para": "NTH_VALUE(expr,\n N)\n [from_first_last]\n [null_treatment]\n over_clause"
},
{
"para": "Returns the value of expr from\n the N-th row of the window frame.\n If there is no such row, the return value is\n NULL."
},
{
"para": "N must be a literal positive\n integer."
},
{
"para": "from_first_last is part of the\n SQL standard, but the MySQL implementation permits only\n FROM FIRST (which is also the default).\n This means that calculations begin at the first row of the\n window. FROM LAST is parsed, but produces\n an error. To obtain the same effect as FROM\n LAST (begin calculations at the last row of the\n window), use ORDER BY to sort in reverse\n order."
},
{
"para": "over_clause is as described in\n .\n null_treatment is as described in\n the section introduction."
},
{
"para": "For an example, see the\n FIRST_VALUE() function\n description."
}
],
"id": "NTH_VALUE",
"syntax": []
},
{
"keywords": [
"NTILE"
],
"description": [
{
"para": "NTILE(N)\n over_clause"
},
{
"para": "Divides a partition into N groups\n (buckets), assigns each row in the partition its bucket\n number, and returns the bucket number of the current row\n within its partition. For example, if\n N is 4,\n NTILE() divides rows into four buckets.\n If N is 100,\n NTILE() divides rows into 100 buckets."
},
{
"para": "N must be a literal positive\n integer. Bucket number return values range from 1 to\n N."
},
{
"para": "This function should be used with ORDER\n BY to sort partition rows into the desired order."
},
{
"para": "over_clause is as described in\n ."
}
],
"id": "NTILE",
"syntax": []
},
{
"keywords": [
"PERCENT_RANK"
],
"description": [
{
"para": "PERCENT_RANK()\n over_clause"
},
{
"para": "Returns the percentage of partition values less than the\n value in the current row, excluding the highest value.\n Return values range from 0 to 1 and represent the row\n relative rank, calculated as the result of this formula,\n where rank is the row rank and\n rows is the number of partition\n rows:"
},
{
"programlisting": ">\n(rank - 1) / (rows - 1)"
},
{
"para": "This function should be used with ORDER\n BY to sort partition rows into the desired order.\n Without ORDER BY, all rows are peers."
},
{
"para": "over_clause is as described in\n ."
},
{
"para": "For an example, see the\n CUME_DIST() function\n description."
}
],
"id": "PERCENT_RANK",
"syntax": []
},
{
"keywords": [
"RANK"
],
"description": [
{
"para": "RANK()\n over_clause"
},
{
"para": "Returns the rank of the current row within its partition,\n with gaps. Peers are considered ties and receive the same\n rank. This function does not assign consecutive ranks to\n peer groups if groups of size greater than one exist; the\n result is noncontiguous rank numbers."
},
{
"para": "This function should be used with ORDER\n BY to sort partition rows into the desired order.\n Without ORDER BY, all rows are peers."
},
{
"para": "over_clause is as described in\n ."
}
],
"id": "RANK",
"syntax": []
},
{
"keywords": [
"ROW_NUMBER"
],
"description": [
{
"para": "ROW_NUMBER()\n over_clause"
},
{
"para": "Returns the number of the current row within its partition.\n Rows numbers range from 1 to the number of partition rows."
},
{
"para": "ORDER BY affects the order in which rows\n are numbered. Without ORDER BY, row\n numbering is nondeterministic."
},
{
"para": "ROW_NUMBER() assigns peers\n different row numbers. To assign peers the same value, use\n RANK() or\n DENSE_RANK(). For an example,\n see the RANK() function\n description."
},
{
"para": "over_clause is as described in\n ."
}
],
"id": "ROW_NUMBER",
"syntax": []
},
{
"keywords": [
"FORMAT_BYTES"
],
"description": [
{
"para": "FORMAT_BYTES(count)"
},
{
"para": "Given a numeric byte count, converts it to human-readable\n format and returns a string consisting of a value and a units\n indicator. The string contains the number of bytes rounded to\n 2 decimal places and a minimum of 3 significant digits.\n Numbers less than 1024 bytes are represented as whole numbers\n and are not rounded."
}
],
"id": "FORMAT_BYTES",
"syntax": []
},
{
"keywords": [
"FORMAT_PICO_TIME"
],
"description": [
{
"para": "FORMAT_PICO_TIME(time_val)"
},
{
"para": "Given a numeric Performance Schema latency or wait time in\n picoseconds, converts it to human-readable format and returns\n a string consisting of a value and a units indicator. The\n string contains the decimal time rounded to 2 decimal places\n and a minimum of 3 significant digits. Times under 1\n nanosecond are represented as whole numbers and are not\n rounded."
}
],
"id": "FORMAT_PICO_TIME",
"syntax": []
},
{
"keywords": [
"PS_CURRENT_THREAD_ID"
],
"description": [
{
"para": "PS_CURRENT_THREAD_ID()"
},
{
"para": "Returns a BIGINT UNSIGNED value\n representing the Performance Schema thread ID assigned to the\n current connection."
},
{
"para": "The thread ID return value is a value of the type given in the\n THREAD_ID column of Performance Schema\n tables."
},
{
"para": "Performance Schema configuration affects\n PS_CURRENT_THREAD_ID() the same\n way as for PS_THREAD_ID(). For\n details, see the description of that function."
}
],
"id": "PS_CURRENT_THREAD_ID",
"syntax": []
},
{
"keywords": [
"PS_THREAD_ID"
],
"description": [
{
"para": "PS_THREAD_ID(connection_id)"
},
{
"para": "Given a connection ID, returns a BIGINT\n UNSIGNED value representing the Performance Schema\n thread ID assigned to the connection ID, or\n NULL if no thread ID exists for the\n connection ID. The latter can occur for threads that are not\n instrumented."
},
{
"para": "The connection ID argument is a value of the type given in the\n PROCESSLIST_ID column of the Performance\n Schema threads table or the\n Id column of SHOW\n PROCESSLIST output."
},
{
"para": "The thread ID return value is a value of the type given in the\n THREAD_ID column of Performance Schema\n tables."
},
{
"para": "Performance Schema configuration affects\n PS_THREAD_ID() operation as\n follows. (These remarks also apply to\n PS_CURRENT_THREAD_ID().)"
},
{
"itemizedlist": [
[
{
"para": "Disabling the thread_instrumentation\n consumer disables statistics from being collected and\n aggregated at the thread level, but has no effect on\n PS_THREAD_ID()."
}
],
[
{
"para": "If\n performance_schema_max_thread_instances\n is not 0, the Performance Schema allocates memory for\n thread statistics and assigns an internal ID to each\n thread for which instance memory is available. If there\n are threads for which instance memory is not available,\n PS_THREAD_ID() returns\n NULL; in this case,\n Performance_schema_thread_instances_lost\n will be nonzero."
}
],
[
{
"para": "If\n performance_schema_max_thread_instances\n is 0, the Performance Schema allocates no thread memory\n and PS_THREAD_ID() returns\n NULL."
}
],
[
{
"para": "If the Performance Schema itself is disabled,\n PS_THREAD_ID() produces an\n error."
}
]
]
}
],
"id": "PS_THREAD_ID",
"syntax": []
},
{
"keywords": [
"CAN_ACCESS_COLUMN"
],
"description": [
{
"para": "CAN_ACCESS_COLUMN(ARGS)"
}
],
"id": "CAN_ACCESS_COLUMN",
"syntax": []
},
{
"keywords": [
"CAN_ACCESS_DATABASE"
],
"description": [
{
"para": "CAN_ACCESS_DATABASE(ARGS)"
}
],
"id": "CAN_ACCESS_DATABASE",
"syntax": []
},
{
"keywords": [
"CAN_ACCESS_TABLE"
],
"description": [
{
"para": "CAN_ACCESS_TABLE(ARGS)"
}
],
"id": "CAN_ACCESS_TABLE",
"syntax": []
},
{
"keywords": [
"CAN_ACCESS_VIEW"
],
"description": [
{
"para": "CAN_ACCESS_VIEW(ARGS)"
}
],
"id": "CAN_ACCESS_VIEW",
"syntax": []
},
{
"keywords": [
"GET_DD_COLUMN_PRIVILEGES"
],
"description": [
{
"para": "GET_DD_COLUMN_PRIVILEGES(ARGS)"
}
],
"id": "GET_DD_COLUMN_PRIVILEGES",
"syntax": []
},
{
"keywords": [
"GET_DD_CREATE_OPTIONS"
],
"description": [
{
"para": "GET_DD_CREATE_OPTIONS(ARGS)"
}
],
"id": "GET_DD_CREATE_OPTIONS",
"syntax": []
},
{
"keywords": [
"GET_DD_INDEX_SUB_PART_LENGTH"
],
"description": [
{
"para": "GET_DD_INDEX_SUB_PART_LENGTH(ARGS)"
}
],
"id": "GET_DD_INDEX_SUB_PART_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_AUTO_INCREMENT"
],
"description": [
{
"para": "INTERNAL_AUTO_INCREMENT(ARGS)"
}
],
"id": "INTERNAL_AUTO_INCREMENT",
"syntax": []
},
{
"keywords": [
"INTERNAL_AVG_ROW_LENGTH"
],
"description": [
{
"para": "INTERNAL_AVG_ROW_LENGTH(ARGS)"
}
],
"id": "INTERNAL_AVG_ROW_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_CHECK_TIME"
],
"description": [
{
"para": "INTERNAL_CHECK_TIME(ARGS)"
}
],
"id": "INTERNAL_CHECK_TIME",
"syntax": []
},
{
"keywords": [
"INTERNAL_CHECKSUM"
],
"description": [
{
"para": "INTERNAL_CHECKSUM(ARGS)"
}
],
"id": "INTERNAL_CHECKSUM",
"syntax": []
},
{
"keywords": [
"INTERNAL_DATA_FREE"
],
"description": [
{
"para": "INTERNAL_DATA_FREE(ARGS)"
}
],
"id": "INTERNAL_DATA_FREE",
"syntax": []
},
{
"keywords": [
"INTERNAL_DATA_LENGTH"
],
"description": [
{
"para": "INTERNAL_DATA_LENGTH(ARGS)"
}
],
"id": "INTERNAL_DATA_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_DD_CHAR_LENGTH"
],
"description": [
{
"para": "INTERNAL_DD_CHAR_LENGTH(ARGS)"
}
],
"id": "INTERNAL_DD_CHAR_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_COMMENT_OR_ERROR"
],
"description": [
{
"para": "INTERNAL_GET_COMMENT_OR_ERROR(ARGS)"
}
],
"id": "INTERNAL_GET_COMMENT_OR_ERROR",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_ENABLED_ROLE_JSON"
],
"description": [
{
"para": "INTERNAL_GET_ENABLED_ROLE_JSON(ARGS)"
}
],
"id": "INTERNAL_GET_ENABLED_ROLE_JSON",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_HOSTNAME"
],
"description": [
{
"para": "INTERNAL_GET_HOSTNAME(ARGS)"
}
],
"id": "INTERNAL_GET_HOSTNAME",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_USERNAME"
],
"description": [
{
"para": "INTERNAL_GET_USERNAME(ARGS)"
}
],
"id": "INTERNAL_GET_USERNAME",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_VIEW_WARNING_OR_ERROR"
],
"description": [
{
"para": "INTERNAL_GET_VIEW_WARNING_OR_ERROR(ARGS)"
}
],
"id": "INTERNAL_GET_VIEW_WARNING_OR_ERROR",
"syntax": []
},
{
"keywords": [
"INTERNAL_INDEX_COLUMN_CARDINALITY"
],
"description": [
{
"para": "INTERNAL_INDEX_COLUMN_CARDINALITY(ARGS)"
}
],
"id": "INTERNAL_INDEX_COLUMN_CARDINALITY",
"syntax": []
},
{
"keywords": [
"INTERNAL_INDEX_LENGTH"
],
"description": [
{
"para": "INTERNAL_INDEX_LENGTH(ARGS)"
}
],
"id": "INTERNAL_INDEX_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_IS_ENABLED_ROLE"
],
"description": [
{
"para": "INTERNAL_IS_ENABLED_ROLE(ARGS)"
}
],
"id": "INTERNAL_IS_ENABLED_ROLE",
"syntax": []
},
{
"keywords": [
"INTERNAL_IS_MANDATORY_ROLE"
],
"description": [
{
"para": "INTERNAL_IS_MANDATORY_ROLE(ARGS)"
}
],
"id": "INTERNAL_IS_MANDATORY_ROLE",
"syntax": []
},
{
"keywords": [
"INTERNAL_KEYS_DISABLED"
],
"description": [
{
"para": "INTERNAL_KEYS_DISABLED(ARGS)"
}
],
"id": "INTERNAL_KEYS_DISABLED",
"syntax": []
},
{
"keywords": [
"INTERNAL_MAX_DATA_LENGTH"
],
"description": [
{
"para": "INTERNAL_MAX_DATA_LENGTH(ARGS)"
}
],
"id": "INTERNAL_MAX_DATA_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_TABLE_ROWS"
],
"description": [
{
"para": "INTERNAL_TABLE_ROWS(ARGS)"
}
],
"id": "INTERNAL_TABLE_ROWS",
"syntax": []
},
{
"keywords": [
"INTERNAL_UPDATE_TIME"
],
"description": [
{
"para": "INTERNAL_UPDATE_TIME(ARGS)"
}
],
"id": "INTERNAL_UPDATE_TIME",
"syntax": []
},
{
"keywords": [
"IS_VISIBLE_DD_OBJECT"
],
"description": [
{
"para": "IS_VISIBLE_DD_OBJECT(ARGS)"
}
],
"id": "IS_VISIBLE_DD_OBJECT",
"syntax": []
},
{
"keywords": [
"ANY_VALUE"
],
"description": [
{
"para": "\n ANY_VALUE()\n \n\n ANY_VALUE(arg)"
},
{
"para": "This function is useful for GROUP BY\n queries when the\n ONLY_FULL_GROUP_BY SQL mode\n is enabled, for cases when MySQL rejects a query that you know\n is valid for reasons that MySQL cannot determine. The function\n return value and type are the same as the return value and\n type of its argument, but the function result is not checked\n for the ONLY_FULL_GROUP_BY\n SQL mode."
},
{
"para": "For example, if name is a nonindexed\n column, the following query fails with\n ONLY_FULL_GROUP_BY enabled:"
},
{
"programlisting": ">\n\nmysql> SELECT name, address, MAX(age) FROM t GROUP BY name;\nERROR 1055 (42000): Expression #2 of SELECT list is not in GROUP\nBY clause and contains nonaggregated column 'mydb.t.address' which\nis not functionally dependent on columns in GROUP BY clause; this\nis incompatible with sql_mode=only_full_group_by"
},
{
"para": "The failure occurs because address is a\n nonaggregated column that is neither named among\n GROUP BY columns nor functionally dependent\n on them. As a result, the address value for\n rows within each name group is\n nondeterministic. There are multiple ways to cause MySQL to\n accept the query:"
},
{
"itemizedlist": [
[
{
"para": "Alter the table to make name a primary\n key or a unique NOT NULL column. This\n enables MySQL to determine that address\n is functionally dependent on name; that\n is, address is uniquely determined by\n name. (This technique is inapplicable\n if NULL must be permitted as a valid\n name value.)"
}
],
[
{
"para": "Use ANY_VALUE() to refer to\n address:"
},
{
"programlisting": ">\nSELECT name, ANY_VALUE(address), MAX(age) FROM t GROUP BY name;"
},
{
"para": "In this case, MySQL ignores the nondeterminism of\n address values within each\n name group and accepts the query. This\n may be useful if you simply do not care which value of a\n nonaggregated column is chosen for each group.\n ANY_VALUE() is not an\n aggregate function, unlike functions such as\n SUM() or\n COUNT(). It simply acts to\n suppress the test for nondeterminism."
}
],
[
{
"para": "Disable\n ONLY_FULL_GROUP_BY. This\n is equivalent to using\n ANY_VALUE() with\n ONLY_FULL_GROUP_BY\n enabled, as described in the previous item."
}
]
]
},
{
"para": "ANY_VALUE() is also useful if\n functional dependence exists between columns but MySQL cannot\n determine it. The following query is valid because\n age is functionally dependent on the\n grouping column age-1, but MySQL cannot\n tell that and rejects the query with\n ONLY_FULL_GROUP_BY enabled:"
},
{
"programlisting": ">\nSELECT age FROM t GROUP BY age-1;"
},
{
"para": "To cause MySQL to accept the query, use\n ANY_VALUE():"
},
{
"programlisting": ">\nSELECT ANY_VALUE(age) FROM t GROUP BY age-1;"
},
{
"para": "ANY_VALUE() can be used for\n queries that refer to aggregate functions in the absence of a\n GROUP BY clause:"
},
{
"programlisting": ">\n\nmysql> SELECT name, MAX(age) FROM t;\nERROR 1140 (42000): In aggregated query without GROUP BY, expression\n#1 of SELECT list contains nonaggregated column 'mydb.t.name'; this\nis incompatible with sql_mode=only_full_group_by"
},
{
"para": "Without GROUP BY, there is a single group\n and it is nondeterministic which name value\n to choose for the group.\n ANY_VALUE() tells MySQL to\n accept the query:"
},
{
"programlisting": ">\nSELECT ANY_VALUE(name), MAX(age) FROM t;"
},
{
"para": "It may be that, due to some property of a given data set, you\n know that a selected nonaggregated column is effectively\n functionally dependent on a GROUP BY\n column. For example, an application may enforce uniqueness of\n one column with respect to another. In this case, using\n ANY_VALUE() for the effectively\n functionally dependent column may make sense."
},
{
"para": "For additional discussion, see\n ."
}
],
"id": "ANY_VALUE",
"syntax": []
},
{
"keywords": [
"BIN_TO_UUID"
],
"description": [
{
"para": "\n BIN_TO_UUID()\n \n\n BIN_TO_UUID(binary_uuid),\n BIN_TO_UUID(binary_uuid,\n swap_flag)"
},
{
"para": "BIN_TO_UUID() is the inverse of\n UUID_TO_BIN(). It converts a\n binary UUID to a string UUID and returns the result. The\n binary value should be a UUID as a\n VARBINARY(16) value. The return\n value is a utf8 string of five hexadecimal\n numbers separated by dashes. (For details about this format,\n see the UUID() function\n description.) If the UUID argument is NULL,\n the return value is NULL. If any argument\n is invalid, an error occurs."
},
{
"para": "BIN_TO_UUID() takes one or two\n arguments:"
},
{
"itemizedlist": [
[
{
"para": "The one-argument form takes a binary UUID value. The UUID\n value is assumed not to have its time-low and time-high\n parts swapped. The string result is in the same order as\n the binary argument."
}
],
[
{
"para": "The two-argument form takes a binary UUID value and a\n swap-flag value:"
},
{
"itemizedlist": [
[
{
"para": "If swap_flag is 0, the\n two-argument form is equivalent to the one-argument\n form. The string result is in the same order as the\n binary argument."
}
],
[
{
"para": "If swap_flag is 1, the UUID\n value is assumed to have its time-low and time-high\n parts swapped. These parts are swapped back to their\n original position in the result value."
}
]
]
}
]
]
},
{
"para": "For usage examples and information about time-part swapping,\n see the UUID_TO_BIN() function\n description."
}
],
"id": "BIN_TO_UUID",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "Returns the default value for a table column. An error results\n if the column has no default value."
},
{
"para": "The use of\n DEFAULT(col_name)\n to specify the default value for a named column is permitted\n only for columns that have a literal default value, not for\n columns that have an expression default value."
}
],
"id": "DEFAULT",
"syntax": [
{
"para": "\n DEFAULT()\n \n\n DEFAULT(col_name)"
}
]
},
{
"keywords": [
"GROUPING"
],
"description": [
{
"para": "GROUPING(expr\n [, expr] ...)"
},
{
"para": "For GROUP BY queries that include a\n WITH ROLLUP modifier, the\n ROLLUP operation produces super-aggregate\n output rows where NULL represents the set\n of all values. The GROUPING()\n function enables you to distinguish NULL\n values for super-aggregate rows from NULL\n values in regular grouped rows."
},
{
"para": "GROUPING() is permitted only in\n the select list or HAVING clause."
},
{
"para": "Each argument to GROUPING()\n must be an expression that exactly matches an expression in\n the GROUP BY clause. The expression cannot\n be a positional specifier. For each expression,\n GROUPING() produces 1 if the\n expression value in the current row is a\n NULL representing a super-aggregate value.\n Otherwise, GROUPING() produces\n 0, indicating that the expression value is a\n NULL for a regular result row or is not\n NULL."
},
{
"para": "Suppose that table t1 contains these rows,\n where NULL indicates something like\n other or unknown:"
},
{
"programlisting": ">\nmysql> SELECT * FROM t1;\n+------+-------+----------+\n| name | size | quantity |\n+------+-------+----------+\n| ball | small | 10 |\n| ball | large | 20 |\n| ball | NULL | 5 |\n| hoop | small | 15 |\n| hoop | large | 5 |\n| hoop | NULL | 3 |\n+------+-------+----------+"
},
{
"para": "A summary of the table without WITH ROLLUP\n looks like this:"
},
{
"programlisting": ">\nmysql> SELECT name, size, SUM(quantity) AS quantity\n FROM t1\n GROUP BY name, size;\n+------+-------+----------+\n| name | size | quantity |\n+------+-------+----------+\n| ball | small | 10 |\n| ball | large | 20 |\n| ball | NULL | 5 |\n| hoop | small | 15 |\n| hoop | large | 5 |\n| hoop | NULL | 3 |\n+------+-------+----------+"
},
{
"para": "The result contains NULL values, but those\n do not represent super-aggregate rows because the query does\n not include WITH ROLLUP."
},
{
"para": "Adding WITH ROLLUP produces super-aggregate\n summary rows containing additional NULL\n values. However, without comparing this result to the previous\n one, it is not easy to see which NULL\n values occur in super-aggregate rows and which occur in\n regular grouped rows:"
},
{
"programlisting": ">\nmysql> SELECT name, size, SUM(quantity) AS quantity\n FROM t1\n GROUP BY name, size WITH ROLLUP;\n+------+-------+----------+\n| name | size | quantity |\n+------+-------+----------+\n| ball | NULL | 5 |\n| ball | large | 20 |\n| ball | small | 10 |\n| ball | NULL | 35 |\n| hoop | NULL | 3 |\n| hoop | large | 5 |\n| hoop | small | 15 |\n| hoop | NULL | 23 |\n| NULL | NULL | 58 |\n+------+-------+----------+"
},
{
"para": "To distinguish NULL values in\n super-aggregate rows from those in regular grouped rows, use\n GROUPING(), which returns 1\n only for super-aggregate NULL values:"
},
{
"programlisting": ">\nmysql> SELECT\n name, size, SUM(quantity) AS quantity,\n GROUPING(name) AS grp_name,\n GROUPING(size) AS grp_size\n FROM t1\n GROUP BY name, size WITH ROLLUP;\n+------+-------+----------+----------+----------+\n| name | size | quantity | grp_name | grp_size |\n+------+-------+----------+----------+----------+\n| ball | NULL | 5 | 0 | 0 |\n| ball | large | 20 | 0 | 0 |\n| ball | small | 10 | 0 | 0 |\n| ball | NULL | 35 | 0 | 1 |\n| hoop | NULL | 3 | 0 | 0 |\n| hoop | large | 5 | 0 | 0 |\n| hoop | small | 15 | 0 | 0 |\n| hoop | NULL | 23 | 0 | 1 |\n| NULL | NULL | 58 | 1 | 1 |\n+------+-------+----------+----------+----------+"
},
{
"para": "Common uses for GROUPING():"
},
{
"itemizedlist": [
[
{
"para": "Substitute a label for super-aggregate\n NULL values:"
},
{
"programlisting": ">\nmysql> SELECT\n IF(GROUPING(name) = 1, 'All items', name) AS name,\n IF(GROUPING(size) = 1, 'All sizes', size) AS size,\n SUM(quantity) AS quantity\n FROM t1\n GROUP BY name, size WITH ROLLUP;\n+-----------+-----------+----------+\n| name | size | quantity |\n+-----------+-----------+----------+\n| ball | NULL | 5 |\n| ball | large | 20 |\n| ball | small | 10 |\n| ball | All sizes | 35 |\n| hoop | NULL | 3 |\n| hoop | large | 5 |\n| hoop | small | 15 |\n| hoop | All sizes | 23 |\n| All items | All sizes | 58 |\n+-----------+-----------+----------+"
}
],
[
{
"para": "Return only super-aggregate lines by filtering out the\n regular grouped lines:"
},
{
"programlisting": ">\nmysql> SELECT name, size, SUM(quantity) AS quantity\n FROM t1\n GROUP BY name, size WITH ROLLUP\n HAVING GROUPING(name) = 1 OR GROUPING(size) = 1;\n+------+------+----------+\n| name | size | quantity |\n+------+------+----------+\n| ball | NULL | 35 |\n| hoop | NULL | 23 |\n| NULL | NULL | 58 |\n+------+------+----------+"
}
]
]
},
{
"para": "GROUPING() permits multiple\n expression arguments. In this case, the\n GROUPING() return value\n represents a bitmask combined from the results for each\n expression, where the lowest-order bit corresponds to the\n result for the rightmost expression. For example, with three\n expression arguments,\n GROUPING(expr1,\n expr2,\n expr3) is evaluated like\n this:"
},
{
"programlisting": ">\n result for GROUPING(expr3)\n+ result for GROUPING(expr2) << 1\n+ result for GROUPING(expr1) << 2"
},
{
"para": "The following query shows how\n GROUPING() results for single\n arguments combine for a multiple-argument call to produce a\n bitmask value:"
},
{
"programlisting": ">\nmysql> SELECT\n name, size, SUM(quantity) AS quantity,\n GROUPING(name) AS grp_name,\n GROUPING(size) AS grp_size,\n GROUPING(name, size) AS grp_all\n FROM t1\n GROUP BY name, size WITH ROLLUP;\n+------+-------+----------+----------+----------+---------+\n| name | size | quantity | grp_name | grp_size | grp_all |\n+------+-------+----------+----------+----------+---------+\n| ball | NULL | 5 | 0 | 0 | 0 |\n| ball | large | 20 | 0 | 0 | 0 |\n| ball | small | 10 | 0 | 0 | 0 |\n| ball | NULL | 35 | 0 | 1 | 1 |\n| hoop | NULL | 3 | 0 | 0 | 0 |\n| hoop | large | 5 | 0 | 0 | 0 |\n| hoop | small | 15 | 0 | 0 | 0 |\n| hoop | NULL | 23 | 0 | 1 | 1 |\n| NULL | NULL | 58 | 1 | 1 | 3 |\n+------+-------+----------+----------+----------+---------+"
},
{
"para": "With multiple expression arguments, the\n GROUPING() return value is\n nonzero if any expression represents a super-aggregate value.\n Multiple-argument GROUPING()\n syntax thus provides a simpler way to write the earlier query\n that returned only super-aggregate rows, by using a single\n multiple-argument GROUPING()\n call rather than multiple single-argument calls:"
},
{
"programlisting": ">\nmysql> SELECT name, size, SUM(quantity) AS quantity\n FROM t1\n GROUP BY name, size WITH ROLLUP\n HAVING GROUPING(name, size) <> 0;\n+------+------+----------+\n| name | size | quantity |\n+------+------+----------+\n| ball | NULL | 35 |\n| hoop | NULL | 23 |\n| NULL | NULL | 58 |\n+------+------+----------+"
},
{
"para": "Use of GROUPING() is subject to\n these limitations:"
},
{
"itemizedlist": [
[
{
"para": "Do not use subquery GROUP BY\n expressions as GROUPING()\n arguments because matching might fail. For example,\n matching fails for this query:"
},
{
"programlisting": ">\nmysql> SELECT GROUPING((SELECT MAX(name) FROM t1))\n FROM t1\n GROUP BY (SELECT MAX(name) FROM t1) WITH ROLLUP;\nERROR 3580 (HY000): Argument #1 of GROUPING function is not in GROUP BY"
}
],
[
{
"para": "GROUP BY literal expressions should not\n be used within a HAVING clause as\n GROUPING() arguments. Due\n to differences between when the optimizer evaluates\n GROUP BY and HAVING,\n matching may succeed but\n GROUPING() evaluation does\n not produce the expected result. Consider this query:"
},
{
"programlisting": ">\nSELECT a AS f1, 'w' AS f2\nFROM t\nGROUP BY f1, f2 WITH ROLLUP\nHAVING GROUPING(f2) = 1;"
},
{
"para": "GROUPING() is evaluated\n earlier for the literal constant expression than for the\n HAVING clause as a whole and returns 0.\n To check whether a query such as this is affected, use\n EXPLAIN and look for\n Impossible having in the\n Extra column."
}
]
]
}
],
"id": "GROUPING",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "Given the dotted-quad representation of an IPv4 network\n address as a string, returns an integer that represents the\n numeric value of the address in network byte order (big\n endian). INET_ATON() returns\n NULL if it does not understand its\n argument."
}
],
"id": "INET_ATON",
"syntax": [
{
"para": "\n INET_ATON()\n \n\n INET_ATON(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given a numeric IPv4 network address in network byte order,\n returns the dotted-quad string representation of the address\n as a string in the connection character set.\n INET_NTOA() returns\n NULL if it does not understand its\n argument."
}
],
"id": "INET_NTOA",
"syntax": [
{
"para": "\n INET_NTOA()\n \n\n INET_NTOA(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given an IPv6 or IPv4 network address as a string, returns a\n binary string that represents the numeric value of the address\n in network byte order (big endian). Because numeric-format\n IPv6 addresses require more bytes than the largest integer\n type, the representation returned by this function has the\n VARBINARY data type:\n VARBINARY(16) for IPv6\n addresses and VARBINARY(4) for\n IPv4 addresses. If the argument is not a valid address,\n INET6_ATON() returns\n NULL."
}
],
"id": "INET6_ATON",
"syntax": [
{
"para": "\n INET6_ATON()\n \n\n INET6_ATON(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given an IPv6 or IPv4 network address represented in numeric\n form as a binary string, returns the string representation of\n the address as a string in the connection character set. If\n the argument is not a valid address,\n INET6_NTOA() returns\n NULL."
},
{
"para": "INET6_NTOA() has these\n properties:"
},
{
"itemizedlist": [
[
{
"para": "It does not use operating system functions to perform\n conversions, thus the output string is platform\n independent."
}
],
[
{
"para": "The return string has a maximum length of 39 (4 x 8 + 7).\n Given this statement:"
},
{
"programlisting": ">\nCREATE TABLE t AS SELECT INET6_NTOA(expr) AS c1;"
},
{
"para": "The resulting table would have this definition:"
},
{
"programlisting": ">\nCREATE TABLE t (c1 VARCHAR(39) CHARACTER SET utf8 DEFAULT NULL);"
}
],
[
{
"para": "The return string uses lowercase letters for IPv6\n addresses."
}
]
]
}
],
"id": "INET6_NTOA",
"syntax": [
{
"para": "\n INET6_NTOA()\n \n\n INET6_NTOA(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns 1 if the argument is a valid IPv4 address specified as\n a string, 0 otherwise."
}
],
"id": "IS_IPV4",
"syntax": [
{
"para": "\n IS_IPV4()\n \n\n IS_IPV4(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function takes an IPv6 address represented in numeric\n form as a binary string, as returned by\n INET6_ATON(). It returns 1 if\n the argument is a valid IPv4-compatible IPv6 address, 0\n otherwise. IPv4-compatible addresses have the form\n ::ipv4_address."
}
],
"id": "IS_IPV4_COMPAT",
"syntax": [
{
"para": "\n IS_IPV4_COMPAT()\n \n\n IS_IPV4_COMPAT(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function takes an IPv6 address represented in numeric\n form as a binary string, as returned by\n INET6_ATON(). It returns 1 if\n the argument is a valid IPv4-mapped IPv6 address, 0 otherwise.\n IPv4-mapped addresses have the form\n ::ffff:ipv4_address."
}
],
"id": "IS_IPV4_MAPPED",
"syntax": [
{
"para": "\n IS_IPV4_MAPPED()\n \n\n IS_IPV4_MAPPED(expr)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns 1 if the argument is a valid IPv6 address specified as\n a string, 0 otherwise. This function does not consider IPv4\n addresses to be valid IPv6 addresses."
}
],
"id": "IS_IPV6",
"syntax": [
{
"para": "\n IS_IPV6()\n \n\n IS_IPV6(expr)"
}
]
},
{
"keywords": [
"IS_UUID"
],
"description": [
{
"para": "\n IS_UUID()\n \n\n IS_UUID(string_uuid)"
},
{
"para": "Returns 1 if the argument is a valid string-format UUID, 0 if\n the argument is not a valid UUID, and NULL\n if the argument is NULL."
},
{
"para": "Valid means that the value is in a format that\n can be parsed. That is, it has the correct length and contains\n only the permitted characters (hexadecimal digits in any\n lettercase and, optionally, dashes and curly braces). This\n format is most common:"
},
{
"programlisting": ">\naaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
},
{
"para": "These other formats are also permitted:"
},
{
"programlisting": ">\naaaaaaaabbbbccccddddeeeeeeeeeeee\n{aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee}"
},
{
"para": "For the meanings of fields within the value, see the\n UUID() function description."
}
],
"id": "IS_UUID",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "This function is useful for control of master/slave\n synchronization. It blocks until the slave has read and\n applied all updates up to the specified position in the master\n log. The return value is the number of log events the slave\n had to wait for to advance to the specified position. The\n function returns NULL if the slave SQL\n thread is not started, the slave's master information is not\n initialized, the arguments are incorrect, or an error occurs.\n It returns -1 if the timeout has been\n exceeded. If the slave SQL thread stops while\n MASTER_POS_WAIT() is waiting,\n the function returns NULL. If the slave is\n past the specified position, the function returns immediately."
},
{
"para": "On a multithreaded slave, the function waits until expiry of\n the limit set by the\n slave_checkpoint_group or\n slave_checkpoint_period\n system variable, when the checkpoint operation is called to\n update the status of the slave. Depending on the setting for\n the system variables, the function might therefore return some\n time after the specified position was reached."
},
{
"para": "If a timeout value is specified,\n MASTER_POS_WAIT() stops waiting\n when timeout seconds have elapsed.\n timeout must be greater than 0; a\n zero or negative timeout means no\n timeout."
},
{
"para": "The optional channel value enables\n you to name which replication channel the function applies to.\n See for more\n information."
}
],
"id": "MASTER_POS_WAIT",
"syntax": [
{
"para": "\n MASTER_POS_WAIT()\n \n\n MASTER_POS_WAIT(log_name,log_pos[,timeout][,channel])"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the given value. When used to produce a result set\n column, NAME_CONST() causes the\n column to have the given name. The arguments should be\n constants."
},
{
"programlisting": ">\nmysql> SELECT NAME_CONST('myname', 14);\n+--------+\n| myname |\n+--------+\n| 14 |\n+--------+"
}
],
"id": "NAME_CONST",
"syntax": [
{
"para": "\n NAME_CONST()\n \n\n NAME_CONST(name,value)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Sleeps (pauses) for the number of seconds given by the\n duration argument, then returns 0.\n The duration may have a fractional part. If the argument is\n NULL or negative,\n SLEEP() produces a warning, or\n an error in strict SQL mode."
},
{
"para": "When sleep returns normally (without interruption), it returns\n 0:"
},
{
"programlisting": ">\nmysql> SELECT SLEEP(1000);\n+-------------+\n| SLEEP(1000) |\n+-------------+\n| 0 |\n+-------------+"
},
{
"para": "When SLEEP() is the only thing\n invoked by a query that is interrupted, it returns 1 and the\n query itself returns no error. This is true whether the query\n is killed or times out:"
},
{
"itemizedlist": [
[
{
"para": "This statement is interrupted using\n KILL QUERY\n from another session:"
},
{
"programlisting": ">\nmysql> SELECT SLEEP(1000);\n+-------------+\n| SLEEP(1000) |\n+-------------+\n| 1 |\n+-------------+"
}
],
[
{
"para": "This statement is interrupted by timing out:"
},
{
"programlisting": ">\nmysql> SELECT /*+ MAX_EXECUTION_TIME(1) */ SLEEP(1000);\n+-------------+\n| SLEEP(1000) |\n+-------------+\n| 1 |\n+-------------+"
}
]
]
},
{
"para": "When SLEEP() is only part of a\n query that is interrupted, the query returns an error:"
},
{
"itemizedlist": [
[
{
"para": "This statement is interrupted using\n KILL QUERY\n from another session:"
},
{
"programlisting": ">\nmysql> SELECT 1 FROM t1 WHERE SLEEP(1000);\nERROR 1317 (70100): Query execution was interrupted"
}
],
[
{
"para": "This statement is interrupted by timing out:"
},
{
"programlisting": ">\nmysql> SELECT /*+ MAX_EXECUTION_TIME(1000) */ 1 FROM t1 WHERE SLEEP(1000);\nERROR 3024 (HY000): Query execution was interrupted, maximum statement\nexecution time exceeded"
}
]
]
}
],
"id": "SLEEP",
"syntax": [
{
"para": "\n SLEEP()\n \n\n SLEEP(duration)"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a Universal Unique Identifier (UUID) generated\n according to RFC 4122, A Universally Unique IDentifier\n (UUID) URN Namespace\n ()."
},
{
"para": "A UUID is designed as a number that is globally unique in\n space and time. Two calls to\n UUID() are expected to generate\n two different values, even if these calls are performed on two\n separate devices not connected to each other."
},
{
"para": "UUID() returns a value that\n conforms to UUID version 1 as described in RFC 4122. The value\n is a 128-bit number represented as a utf8\n string of five hexadecimal numbers in\n aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\n format:"
},
{
"itemizedlist": [
[
{
"para": "The first three numbers are generated from the low,\n middle, and high parts of a timestamp. The high part also\n includes the UUID version number."
}
],
[
{
"para": "The fourth number preserves temporal uniqueness in case\n the timestamp value loses monotonicity (for example, due\n to daylight saving time)."
}
],
[
{
"para": "The fifth number is an IEEE 802 node number that provides\n spatial uniqueness. A random number is substituted if the\n latter is not available (for example, because the host\n device has no Ethernet card, or it is unknown how to find\n the hardware address of an interface on the host operating\n system). In this case, spatial uniqueness cannot be\n guaranteed. Nevertheless, a collision should have\n very low probability."
},
{
"para": "The MAC address of an interface is taken into account only\n on FreeBSD, Linux, and Windows. On other operating\n systems, MySQL uses a randomly generated 48-bit number."
}
]
]
}
],
"id": "UUID",
"syntax": [
{
"para": "\n UUID()\n \n\n UUID()"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a short universal identifier as a\n 64-bit unsigned integer. Values returned by\n UUID_SHORT() differ from the\n string-format 128-bit identifiers returned by the\n UUID() function and have\n different uniqueness properties. The value of\n UUID_SHORT() is guaranteed to\n be unique if the following conditions hold:"
},
{
"itemizedlist": [
[
{
"para": "The server_id value of\n the current server is between 0 and 255 and is unique\n among your set of master and slave servers"
}
],
[
{
"para": "You do not set back the system time for your server host\n between mysqld restarts"
}
],
[
{
"para": "You invoke UUID_SHORT() on\n average fewer than 16 million times per second between\n mysqld restarts"
}
]
]
},
{
"para": "The UUID_SHORT() return value\n is constructed this way:"
},
{
"programlisting": ">\n (server_id & 255) << 56\n+ (server_startup_time_in_seconds << 24)\n+ incremented_variable++;"
}
],
"id": "UUID_SHORT",
"syntax": [
{
"para": "\n UUID_SHORT()\n \n\n UUID_SHORT()"
}
]
},
{
"keywords": [
"UUID_TO_BIN"
],
"description": [
{
"para": "\n UUID_TO_BIN()\n \n\n UUID_TO_BIN(string_uuid),\n UUID_TO_BIN(string_uuid,\n swap_flag)"
},
{
"para": "Converts a string UUID to a binary UUID and returns the\n result. (The IS_UUID() function\n description lists the permitted string UUID formats.) The\n return binary UUID is a\n VARBINARY(16) value. If the\n UUID argument is NULL, the return value is\n NULL. If any argument is invalid, an error\n occurs."
},
{
"para": "UUID_TO_BIN() takes one or two\n arguments:"
},
{
"itemizedlist": [
[
{
"para": "The one-argument form takes a string UUID value. The\n binary result is in the same order as the string argument."
}
],
[
{
"para": "The two-argument form takes a string UUID value and a flag\n value:"
},
{
"itemizedlist": [
[
{
"para": "If swap_flag is 0, the\n two-argument form is equivalent to the one-argument\n form. The binary result is in the same order as the\n string argument."
}
],
[
{
"para": "If swap_flag is 1, the\n format of the return value differs: The time-low and\n time-high parts (the first and third groups of\n hexadecimal digits, respectively) are swapped. This\n moves the more rapidly varying part to the right and\n can improve indexing efficiency if the result is\n stored in an indexed column."
}
]
]
}
]
]
},
{
"para": "Time-part swapping assumes the use of UUID version 1 values,\n such as are generated by the\n UUID() function. For UUID\n values produced by other means that do not follow version 1\n format, time-part swapping provides no benefit. For details\n about version 1 format, see the\n UUID() function description."
},
{
"para": "Suppose that you have the following string UUID value:"
},
{
"programlisting": ">\nmysql> SET @uuid = '6ccd780c-baba-1026-9564-5b8c656024db';"
},
{
"para": "To convert the string UUID to binary with or without time-part\n swapping, use UUID_TO_BIN():"
},
{
"programlisting": ">\n\nmysql> SELECT HEX(UUID_TO_BIN(@uuid));\n+----------------------------------+\n| HEX(UUID_TO_BIN(@uuid)) |\n+----------------------------------+\n| 6CCD780CBABA102695645B8C656024DB |\n+----------------------------------+\nmysql> SELECT HEX(UUID_TO_BIN(@uuid, 0));\n+----------------------------------+\n| HEX(UUID_TO_BIN(@uuid, 0)) |\n+----------------------------------+\n| 6CCD780CBABA102695645B8C656024DB |\n+----------------------------------+\nmysql> SELECT HEX(UUID_TO_BIN(@uuid, 1));\n+----------------------------------+\n| HEX(UUID_TO_BIN(@uuid, 1)) |\n+----------------------------------+\n| 1026BABA6CCD780C95645B8C656024DB |\n+----------------------------------+"
},
{
"para": "To convert a binary UUID returned by\n UUID_TO_BIN() to a string UUID,\n use BIN_TO_UUID(). If you\n produce a binary UUID by calling\n UUID_TO_BIN() with a second\n argument of 1 to swap time parts, you should also pass a\n second argument of 1 to\n BIN_TO_UUID() to unswap the\n time parts when converting the binary UUID back to a string\n UUID:"
},
{
"programlisting": ">\n\nmysql> SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid));\n+--------------------------------------+\n| BIN_TO_UUID(UUID_TO_BIN(@uuid)) |\n+--------------------------------------+\n| 6ccd780c-baba-1026-9564-5b8c656024db |\n+--------------------------------------+\nmysql> SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid,0),0);\n+--------------------------------------+\n| BIN_TO_UUID(UUID_TO_BIN(@uuid,0),0) |\n+--------------------------------------+\n| 6ccd780c-baba-1026-9564-5b8c656024db |\n+--------------------------------------+\nmysql> SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid,1),1);\n+--------------------------------------+\n| BIN_TO_UUID(UUID_TO_BIN(@uuid,1),1) |\n+--------------------------------------+\n| 6ccd780c-baba-1026-9564-5b8c656024db |\n+--------------------------------------+"
},
{
"para": "If the use of time-part swapping is not the same for the\n conversion in both directions, the original UUID will not be\n recovered properly:"
},
{
"programlisting": ">\n\nmysql> SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid,0),1);\n+--------------------------------------+\n| BIN_TO_UUID(UUID_TO_BIN(@uuid,0),1) |\n+--------------------------------------+\n| baba1026-780c-6ccd-9564-5b8c656024db |\n+--------------------------------------+\nmysql> SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid,1),0);\n+--------------------------------------+\n| BIN_TO_UUID(UUID_TO_BIN(@uuid,1),0) |\n+--------------------------------------+\n| 1026baba-6ccd-780c-9564-5b8c656024db |\n+--------------------------------------+"
}
],
"id": "UUID_TO_BIN",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "In an\n INSERT\n ... ON DUPLICATE KEY UPDATE statement, you can use\n the\n VALUES(col_name)\n function in the UPDATE clause\n to refer to column values from the\n INSERT portion of the\n statement. In other words,\n VALUES(col_name)\n in the UPDATE clause refers to\n the value of col_name that would be\n inserted, had no duplicate-key conflict occurred. This\n function is especially useful in multiple-row inserts. The\n VALUES() function is meaningful\n only in the ON DUPLICATE KEY UPDATE clause\n of INSERT statements and\n returns NULL otherwise. See\n ."
}
],
"id": "VALUES",
"syntax": [
{
"para": "\n VALUES()\n \n\n VALUES(col_name)"
}
]
},
{
"keywords": [
"JSON_ARRAY"
],
"description": [
{
"para": "Evaluates a (possibly empty) list of values and returns a JSON\n array containing those values."
}
],
"id": "JSON_ARRAY",
"syntax": [
{
"para": "\n JSON_ARRAY()\n \n\n JSON_ARRAY([val[,\n val] ...])"
}
]
},
{
"keywords": [
"JSON_OBJECT"
],
"description": [
{
"para": "Evaluates a (possibly empty) list of key-value pairs and\n returns a JSON object containing those pairs. An error occurs\n if any key name is NULL or the number of\n arguments is odd."
}
],
"id": "JSON_OBJECT",
"syntax": [
{
"para": "\n JSON_OBJECT()\n \n\n JSON_OBJECT([key,\n val[,\n key,\n val] ...])"
}
]
},
{
"keywords": [
"JSON_QUOTE"
],
"description": [
{
"para": "Quotes a string as a JSON value by wrapping it with double\n quote characters and escaping interior quote and other\n characters, then returning the result as a\n utf8mb4 string. Returns\n NULL if the argument is\n NULL."
},
{
"para": "This function is typically used to produce a valid JSON string\n literal for inclusion within a JSON document."
},
{
"para": "Certain special characters are escaped with backslashes per\n the escape sequences shown in\n ."
}
],
"id": "JSON_QUOTE",
"syntax": [
{
"para": "\n JSON_QUOTE()\n \n\n JSON_QUOTE(string)"
}
]
},
{
"keywords": [
"JSON_CONTAINS"
],
"description": [
{
"para": "Indicates by returning 1 or 0 whether a given\n candidate JSON document is\n contained within a target JSON\n document, ormdashif a path\n argument was suppliedmdashwhether the candidate is found at\n a specific path within the target. Returns\n NULL if any argument is\n NULL, or if the path argument does not\n identify a section of the target document. An error occurs if\n target or\n candidate is not a valid JSON\n document, or if the path argument\n is not a valid path expression or contains a\n * or ** wildcard."
},
{
"para": "To check only whether any data exists at the path, use\n JSON_CONTAINS_PATH() instead."
},
{
"para": "The following rules define containment:"
},
{
"itemizedlist": [
[
{
"para": "A candidate scalar is contained in a target scalar if and\n only if they are comparable and are equal. Two scalar\n values are comparable if they have the same\n JSON_TYPE() types, with the\n exception that values of types INTEGER\n and DECIMAL are also comparable to each\n other."
}
],
[
{
"para": "A candidate array is contained in a target array if and\n only if every element in the candidate is contained in\n some element of the target."
}
],
[
{
"para": "A candidate nonarray is contained in a target array if and\n only if the candidate is contained in some element of the\n target."
}
],
[
{
"para": "A candidate object is contained in a target object if and\n only if for each key in the candidate there is a key with\n the same name in the target and the value associated with\n the candidate key is contained in the value associated\n with the target key."
}
]
]
},
{
"para": "Otherwise, the candidate value is not contained in the target\n document."
},
{
"para": "Starting with MySQL 8.0.17, queries using\n JSON_CONTAINS() on\n InnoDB tables can be optimized\n using multi-valued indexes; see\n , for more\n information."
}
],
"id": "JSON_CONTAINS",
"syntax": [
{
"para": "\n JSON_CONTAINS()\n \n\n JSON_CONTAINS(target,\n candidate[,\n path])"
}
]
},
{
"keywords": [
"JSON_CONTAINS_PATH"
],
"description": [
{
"para": "Returns 0 or 1 to indicate whether a JSON document contains\n data at a given path or paths. Returns NULL\n if any argument is NULL. An error occurs if\n the json_doc argument is not a\n valid JSON document, any path\n argument is not a valid path expression, or\n one_or_all is not\n 'one' or 'all'."
},
{
"para": "To check for a specific value at a path, use\n JSON_CONTAINS() instead."
},
{
"para": "The return value is 0 if no specified path exists within the\n document. Otherwise, the return value depends on the\n one_or_all argument:"
},
{
"itemizedlist": [
[
{
"para": "'one': 1 if at least one path exists\n within the document, 0 otherwise."
}
],
[
{
"para": "'all': 1 if all paths exist within the\n document, 0 otherwise."
}
]
]
}
],
"id": "JSON_CONTAINS_PATH",
"syntax": [
{
"para": "\n JSON_CONTAINS_PATH()\n \n\n JSON_CONTAINS_PATH(json_doc,\n one_or_all,\n path[,\n path] ...)"
}
]
},
{
"keywords": [
"JSON_EXTRACT"
],
"description": [
{
"para": "Returns data from a JSON document, selected from the parts of\n the document matched by the path\n arguments. Returns NULL if any argument is\n NULL or no paths locate a value in the\n document. An error occurs if the\n json_doc argument is not a valid\n JSON document or any path argument\n is not a valid path expression."
},
{
"para": "The return value consists of all values matched by the\n path arguments. If it is possible\n that those arguments could return multiple values, the matched\n values are autowrapped as an array, in the order corresponding\n to the paths that produced them. Otherwise, the return value\n is the single matched value."
}
],
"id": "JSON_EXTRACT",
"syntax": [
{
"para": "\n JSON_EXTRACT()\n \n\n JSON_EXTRACT(json_doc,\n path[,\n path] ...)"
}
]
},
{
"keywords": [
"->",
"(JSON",
"extraction)"
],
"description": [
{
"para": "The\n ->\n operator serves as an alias for the\n JSON_EXTRACT() function when\n used with two arguments, a column identifier on the left and a\n JSON path on the right that is evaluated against the JSON\n document (the column value). You can use such expressions in\n place of column identifiers wherever they occur in SQL\n statements."
}
],
"id": "->",
"syntax": [
{
"para": "\n ->\n \n\n column->path"
}
]
},
{
"keywords": [
"->>",
"(JSON",
"inline",
"path)"
],
"description": [
{
"para": "This is an improved, unquoting extraction operator. Whereas\n the -> operator simply extracts a value,\n the ->> operator in addition unquotes\n the extracted result. In other words, given a\n JSON column value\n column and a path expression\n path, the following three\n expressions return the same value:"
},
{
"itemizedlist": [
[
{
"para": "JSON_UNQUOTE(\n JSON_EXTRACT(column,\n path) )"
}
],
[
{
"para": "JSON_UNQUOTE(column\n ->\n path)"
}
],
[
{
"para": "column->>path"
}
]
]
},
{
"para": "The ->> operator can be used wherever\n JSON_UNQUOTE(JSON_EXTRACT()) would be\n allowed. This includes (but is not limited to)\n SELECT lists, WHERE and\n HAVING clauses, and ORDER\n BY and GROUP BY clauses."
}
],
"id": "->>",
"syntax": [
{
"para": "\n ->>\n \n\n column->>path"
}
]
},
{
"keywords": [
"JSON_KEYS"
],
"description": [
{
"para": "Returns the keys from the top-level value of a JSON object as\n a JSON array, or, if a path\n argument is given, the top-level keys from the selected path.\n Returns NULL if any argument is\n NULL, the\n json_doc argument is not an object,\n or path, if given, does not locate\n an object. An error occurs if the\n json_doc argument is not a valid\n JSON document or the path argument\n is not a valid path expression or contains a\n * or ** wildcard."
},
{
"para": "The result array is empty if the selected object is empty. If\n the top-level value has nested subobjects, the return value\n does not include keys from those subobjects."
}
],
"id": "JSON_KEYS",
"syntax": [
{
"para": "\n JSON_KEYS()\n \n\n JSON_KEYS(json_doc[,\n path])"
}
]
},
{
"keywords": [
"JSON_OVERLAPS"
],
"description": [
{
"para": "Compares two JSON documents. Returns true (1) if the two\n document have any key-value pairs or array elements in common.\n If both arguments are scalars, the function performs a simple\n equality test."
},
{
"para": "This function serves as counterpart to\n JSON_CONTAINS(), which requires\n all elements of the array searched for to be present in the\n array searched in. Thus, JSON_CONTAINS()\n performs an AND operation on search keys,\n while JSON_OVERLAPS() performs an\n OR operation."
},
{
"para": "Queries on JSON columns of InnoDB\n tables using JSON_OVERLAPS() in the\n WHERE clause can be optimized using\n multi-valued indexes.\n , provides detailed\n information and examples."
}
],
"id": "JSON_OVERLAPS",
"syntax": [
{
"para": "\n JSON_OVERLAPS()\n \n\n JSON_OVERLAPS(json_doc1,\n json_doc2)"
}
]
},
{
"keywords": [
"JSON_SEARCH"
],
"description": [
{
"para": "Returns the path to the given string within a JSON document.\n Returns NULL if any of the\n json_doc,\n search_str, or\n path arguments are\n NULL; no path\n exists within the document; or\n search_str is not found. An error\n occurs if the json_doc argument is\n not a valid JSON document, any path\n argument is not a valid path expression,\n one_or_all is not\n 'one' or 'all', or\n escape_char is not a constant\n expression."
},
{
"para": "The one_or_all argument affects the\n search as follows:"
},
{
"itemizedlist": [
[
{
"para": "'one': The search terminates after the\n first match and returns one path string. It is undefined\n which match is considered first."
}
],
[
{
"para": "'all': The search returns all matching\n path strings such that no duplicate paths are included. If\n there are multiple strings, they are autowrapped as an\n array. The order of the array elements is undefined."
}
]
]
},
{
"para": "Within the search_str search string\n argument, the % and _\n characters work as for the LIKE\n operator: % matches any number of\n characters (including zero characters), and\n _ matches exactly one character."
},
{
"para": "To specify a literal % or\n _ character in the search string, precede\n it by the escape character. The default is\n \\ if the\n escape_char argument is missing or\n NULL. Otherwise,\n escape_char must be a constant that\n is empty or one character."
},
{
"para": "For more information about matching and escape character\n behavior, see the description of\n LIKE in\n . For escape\n character handling, a difference from the\n LIKE behavior is that the escape\n character for JSON_SEARCH()\n must evaluate to a constant at compile time, not just at\n execution time. For example, if\n JSON_SEARCH() is used in a\n prepared statement and the\n escape_char argument is supplied\n using a ? parameter, the parameter value\n might be constant at execution time, but is not at compile\n time."
}
],
"id": "JSON_SEARCH",
"syntax": [
{
"para": "\n JSON_SEARCH()\n \n\n JSON_SEARCH(json_doc,\n one_or_all,\n search_str[,\n escape_char[,\n path] ...])"
}
]
},
{
"keywords": [
"MEMBER",
"OF"
],
"description": [
{
"para": "Returns true (1) if value is an\n element of json_array, otherwise\n returns false (0). value must be a\n scalar or a JSON document; if it is a scalar, the operator\n attempts to treat it as an element of a JSON array."
},
{
"para": "Queries using MEMBER OF() on JSON columns\n of InnoDB tables in the\n WHERE clause can be optimized using\n multi-valued indexes. See\n , for detailed\n information and examples."
}
],
"id": "MEMBER OF",
"syntax": [
{
"para": "\n MEMBER OF()\n \n\n value\n MEMBER OF(json_array)"
}
]
},
{
"keywords": [
"JSON_ARRAY_APPEND"
],
"description": [
{
"para": "Appends values to the end of the indicated arrays within a\n JSON document and returns the result. Returns\n NULL if any argument is\n NULL. An error occurs if the\n json_doc argument is not a valid\n JSON document or any path argument\n is not a valid path expression or contains a\n * or ** wildcard."
},
{
"para": "The path-value pairs are evaluated left to right. The document\n produced by evaluating one pair becomes the new value against\n which the next pair is evaluated."
},
{
"para": "If a path selects a scalar or object value, that value is\n autowrapped within an array and the new value is added to that\n array. Pairs for which the path does not identify any value in\n the JSON document are ignored."
}
],
"id": "JSON_ARRAY_APPEND",
"syntax": [
{
"para": "\n JSON_ARRAY_APPEND()\n \n\n JSON_ARRAY_APPEND(json_doc,\n path,\n val[,\n path,\n val] ...)"
}
]
},
{
"keywords": [
"JSON_ARRAY_INSERT"
],
"description": [
{
"para": "Updates a JSON document, inserting into an array within the\n document and returning the modified document. Returns\n NULL if any argument is\n NULL. An error occurs if the\n json_doc argument is not a valid\n JSON document or any path argument\n is not a valid path expression or contains a\n * or ** wildcard or does\n not end with an array element identifier."
},
{
"para": "The path-value pairs are evaluated left to right. The document\n produced by evaluating one pair becomes the new value against\n which the next pair is evaluated."
},
{
"para": "Pairs for which the path does not identify any array in the\n JSON document are ignored. If a path identifies an array\n element, the corresponding value is inserted at that element\n position, shifting any following values to the right. If a\n path identifies an array position past the end of an array,\n the value is inserted at the end of the array."
}
],
"id": "JSON_ARRAY_INSERT",
"syntax": [
{
"para": "\n JSON_ARRAY_INSERT()\n \n\n JSON_ARRAY_INSERT(json_doc,\n path,\n val[,\n path,\n val] ...)"
}
]
},
{
"keywords": [
"JSON_INSERT"
],
"description": [
{
"para": "Inserts data into a JSON document and returns the result.\n Returns NULL if any argument is\n NULL. An error occurs if the\n json_doc argument is not a valid\n JSON document or any path argument\n is not a valid path expression or contains a\n * or ** wildcard."
},
{
"para": "The path-value pairs are evaluated left to right. The document\n produced by evaluating one pair becomes the new value against\n which the next pair is evaluated."
},
{
"para": "A path-value pair for an existing path in the document is\n ignored and does not overwrite the existing document value. A\n path-value pair for a nonexisting path in the document adds\n the value to the document if the path identifies one of these\n types of values:"
},
{
"itemizedlist": [
[
{
"para": "A member not present in an existing object. The member is\n added to the object and associated with the new value."
}
],
[
{
"para": "A position past the end of an existing array. The array is\n extended with the new value. If the existing value is not\n an array, it is autowrapped as an array, then extended\n with the new value."
}
]
]
},
{
"para": "Otherwise, a path-value pair for a nonexisting path in the\n document is ignored and has no effect."
},
{
"para": "For a comparison of\n JSON_INSERT(),\n JSON_REPLACE(), and\n JSON_SET(), see the discussion\n of JSON_SET()."
}
],
"id": "JSON_INSERT",
"syntax": [
{
"para": "\n JSON_INSERT()\n \n\n JSON_INSERT(json_doc,\n path,\n val[,\n path,\n val] ...)"
}
]
},
{
"keywords": [
"JSON_MERGE"
],
"description": [
{
"para": "Merges two or more JSON documents. Synonym for\n JSON_MERGE_PRESERVE(); deprecated in MySQL\n 8.0.3 and subject to removal in a future release."
}
],
"id": "JSON_MERGE",
"syntax": [
{
"para": "\n JSON_MERGE()\n \n\n JSON_MERGE(json_doc,\n json_doc[,\n json_doc] ...)"
}
]
},
{
"keywords": [
"JSON_MERGE_PATCH"
],
"description": [
{
"para": "Performs an\n RFC\n 7396 compliant merge of two or more JSON documents and\n returns the merged result, without preserving members having\n duplicate keys. Raises an error if at least one of the\n documents passed as arguments to this function is not valid."
},
{
"para": "JSON_MERGE_PATCH() performs a merge as\n follows:"
},
{
"para": "For additional information, see\n ."
}
],
"id": "JSON_MERGE_PATCH()",
"syntax": [
{
"para": "\n JSON_MERGE_PATCH()\n \n\n JSON_MERGE_PATCH(json_doc,\n json_doc[,\n json_doc] ...)"
}
]
},
{
"keywords": [
"JSON_MERGE_PRESERVE"
],
"description": [
{
"para": "Merges two or more JSON documents and returns the merged\n result. Returns NULL if any argument is\n NULL. An error occurs if any argument is\n not a valid JSON document."
},
{
"para": "Merging takes place according to the following rules. For\n additional information, see\n ."
},
{
"itemizedlist": [
[
{
"para": "Adjacent arrays are merged to a single array."
}
],
[
{
"para": "Adjacent objects are merged to a single object."
}
],
[
{
"para": "A scalar value is autowrapped as an array and merged as an\n array."
}
],
[
{
"para": "An adjacent array and object are merged by autowrapping\n the object as an array and merging the two arrays."
}
]
]
}
],
"id": "JSON_MERGE_PRESERVE()",
"syntax": [
{
"para": "\n JSON_MERGE_PRESERVE()\n \n\n JSON_MERGE_PRESERVE(json_doc,\n json_doc[,\n json_doc] ...)"
}
]
},
{
"keywords": [
"JSON_REMOVE"
],
"description": [
{
"para": "Removes data from a JSON document and returns the result.\n Returns NULL if any argument is\n NULL. An error occurs if the\n json_doc argument is not a valid\n JSON document or any path argument\n is not a valid path expression or is $ or\n contains a * or **\n wildcard."
},
{
"para": "The path arguments are evaluated\n left to right. The document produced by evaluating one path\n becomes the new value against which the next path is\n evaluated."
},
{
"para": "It is not an error if the element to be removed does not exist\n in the document; in that case, the path does not affect the\n document."
}
],
"id": "JSON_REMOVE",
"syntax": [
{
"para": "\n JSON_REMOVE()\n \n\n JSON_REMOVE(json_doc,\n path[,\n path] ...)"
}
]
},
{
"keywords": [
"JSON_REPLACE"
],
"description": [
{
"para": "Replaces existing values in a JSON document and returns the\n result. Returns NULL if any argument is\n NULL. An error occurs if the\n json_doc argument is not a valid\n JSON document or any path argument\n is not a valid path expression or contains a\n * or ** wildcard."
},
{
"para": "The path-value pairs are evaluated left to right. The document\n produced by evaluating one pair becomes the new value against\n which the next pair is evaluated."
},
{
"para": "A path-value pair for an existing path in the document\n overwrites the existing document value with the new value. A\n path-value pair for a nonexisting path in the document is\n ignored and has no effect."
},
{
"para": "In MySQL 8.0.4, the optimizer can perform a partial, in-place\n update of a JSON column instead of removing\n the old document and writing the new document in its entirety\n to the column. This optimization can be performed for an\n update statement that uses the\n JSON_REPLACE() function and\n meets the conditions outlined in\n ."
},
{
"para": "For a comparison of\n JSON_INSERT(),\n JSON_REPLACE(), and\n JSON_SET(), see the discussion\n of JSON_SET()."
}
],
"id": "JSON_REPLACE",
"syntax": [
{
"para": "\n JSON_REPLACE()\n \n\n JSON_REPLACE(json_doc,\n path,\n val[,\n path,\n val] ...)"
}
]
},
{
"keywords": [
"JSON_SET"
],
"description": [
{
"para": "Inserts or updates data in a JSON document and returns the\n result. Returns NULL if any argument is\n NULL or path, if\n given, does not locate an object. An error occurs if the\n json_doc argument is not a valid\n JSON document or any path argument\n is not a valid path expression or contains a\n * or ** wildcard."
},
{
"para": "The path-value pairs are evaluated left to right. The document\n produced by evaluating one pair becomes the new value against\n which the next pair is evaluated."
},
{
"para": "A path-value pair for an existing path in the document\n overwrites the existing document value with the new value. A\n path-value pair for a nonexisting path in the document adds\n the value to the document if the path identifies one of these\n types of values:"
},
{
"itemizedlist": [
[
{
"para": "A member not present in an existing object. The member is\n added to the object and associated with the new value."
}
],
[
{
"para": "A position past the end of an existing array. The array is\n extended with the new value. If the existing value is not\n an array, it is autowrapped as an array, then extended\n with the new value."
}
]
]
},
{
"para": "Otherwise, a path-value pair for a nonexisting path in the\n document is ignored and has no effect."
},
{
"para": "In MySQL 8.0.4, the optimizer can perform a partial, in-place\n update of a JSON column instead of removing\n the old document and writing the new document in its entirety\n to the column. This optimization can be performed for an\n update statement that uses the\n JSON_SET() function and meets\n the conditions outlined in\n ."
},
{
"para": "The JSON_SET(),\n JSON_INSERT(), and\n JSON_REPLACE() functions are\n related:"
},
{
"itemizedlist": [
[
{
"para": "JSON_SET() replaces\n existing values and adds nonexisting values."
}
],
[
{
"para": "JSON_INSERT() inserts\n values without replacing existing values."
}
],
[
{
"para": "JSON_REPLACE() replaces\n only existing values."
}
]
]
}
],
"id": "JSON_SET",
"syntax": [
{
"para": "\n JSON_SET()\n \n\n JSON_SET(json_doc,\n path,\n val[,\n path,\n val] ...)"
}
]
},
{
"keywords": [
"JSON_UNQUOTE"
],
"description": [
{
"para": "Unquotes JSON value and returns the result as a\n utf8mb4 string. Returns\n NULL if the argument is\n NULL. An error occurs if the value starts\n and ends with double quotes but is not a valid JSON string\n literal."
}
],
"id": "JSON_UNQUOTE",
"syntax": [
{
"para": "\n JSON_UNQUOTE()\n \n\n JSON_UNQUOTE(json_val)"
}
]
},
{
"keywords": [
"JSON_DEPTH"
],
"description": [
{
"para": "Returns the maximum depth of a JSON document. Returns\n NULL if the argument is\n NULL. An error occurs if the argument is\n not a valid JSON document."
},
{
"para": "An empty array, empty object, or scalar value has depth 1. A\n nonempty array containing only elements of depth 1 or nonempty\n object containing only member values of depth 1 has depth 2.\n Otherwise, a JSON document has depth greater than 2."
}
],
"id": "JSON_DEPTH",
"syntax": [
{
"para": "\n JSON_DEPTH()\n \n\n JSON_DEPTH(json_doc)"
}
]
},
{
"keywords": [
"JSON_LENGTH"
],
"description": [
{
"para": "Returns the length of a JSON document, or, if a\n path argument is given, the length\n of the value within the document identified by the path.\n Returns NULL if any argument is\n NULL or the path\n argument does not identify a value in the document. An error\n occurs if the json_doc argument is\n not a valid JSON document or the\n path argument is not a valid path\n expression or contains a * or\n ** wildcard."
},
{
"para": "The length of a document is determined as follows:"
},
{
"itemizedlist": [
[
{
"para": "The length of a scalar is 1."
}
],
[
{
"para": "The length of an array is the number of array elements."
}
],
[
{
"para": "The length of an object is the number of object members."
}
],
[
{
"para": "The length does not count the length of nested arrays or\n objects."
}
]
]
}
],
"id": "JSON_LENGTH",
"syntax": [
{
"para": "\n JSON_LENGTH()\n \n\n JSON_LENGTH(json_doc[,\n path])"
}
]
},
{
"keywords": [
"JSON_TYPE"
],
"description": [
{
"para": "Returns a utf8mb4 string indicating the\n type of a JSON value. This can be an object, an array, or a\n scalar type, as shown here:"
},
{
"programlisting": ">\nmysql> SET @j = '{\"a\": [10, true]}';\nmysql> SELECT JSON_TYPE(@j);\n+---------------+\n| JSON_TYPE(@j) |\n+---------------+\n| OBJECT |\n+---------------+\nmysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a'));\n+------------------------------------+\n| JSON_TYPE(JSON_EXTRACT(@j, '$.a')) |\n+------------------------------------+\n| ARRAY |\n+------------------------------------+\nmysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]'));\n+---------------------------------------+\n| JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]')) |\n+---------------------------------------+\n| INTEGER |\n+---------------------------------------+\nmysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]'));\n+---------------------------------------+\n| JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]')) |\n+---------------------------------------+\n| BOOLEAN |\n+---------------------------------------+"
},
{
"para": "JSON_TYPE() returns\n NULL if the argument is\n NULL:"
},
{
"programlisting": ">\nmysql> SELECT JSON_TYPE(NULL);\n+-----------------+\n| JSON_TYPE(NULL) |\n+-----------------+\n| NULL |\n+-----------------+"
},
{
"para": "An error occurs if the argument is not a valid JSON value:"
},
{
"programlisting": ">\nmysql> SELECT JSON_TYPE(1);\nERROR 3146 (22032): Invalid data type for JSON data in argument 1\nto function json_type; a JSON string or JSON type is required."
},
{
"para": "For a non-NULL, non-error result, the\n following list describes the possible\n JSON_TYPE() return values:"
},
{
"itemizedlist": [
[
{
"para": "Purely JSON types:"
},
{
"itemizedlist": [
[
{
"para": "OBJECT: JSON objects"
}
],
[
{
"para": "ARRAY: JSON arrays"
}
],
[
{
"para": "BOOLEAN: The JSON true and false\n literals"
}
],
[
{
"para": "NULL: The JSON null literal"
}
]
]
}
],
[
{
"para": "Numeric types:"
},
{
"itemizedlist": [
[
{
"para": "INTEGER: MySQL\n TINYINT,\n SMALLINT,\n MEDIUMINT and\n INT and\n BIGINT scalars"
}
],
[
{
"para": "DOUBLE: MySQL\n DOUBLE\n FLOAT scalars"
}
],
[
{
"para": "DECIMAL: MySQL\n DECIMAL and\n NUMERIC scalars"
}
]
]
}
],
[
{
"para": "Temporal types:"
},
{
"itemizedlist": [
[
{
"para": "DATETIME: MySQL\n DATETIME and\n TIMESTAMP scalars"
}
],
[
{
"para": "DATE: MySQL\n DATE scalars"
}
],
[
{
"para": "TIME: MySQL\n TIME scalars"
}
]
]
}
],
[
{
"para": "String types:"
},
{
"itemizedlist": [
[
{
"para": "STRING: MySQL\n utf8 character type scalars:\n CHAR,\n VARCHAR,\n TEXT,\n ENUM, and\n SET"
}
]
]
}
],
[
{
"para": "Binary types:"
},
{
"itemizedlist": [
[
{
"para": "BLOB: MySQL binary type scalars\n including BINARY,\n VARBINARY,\n BLOB, and\n BIT"
}
]
]
}
],
[
{
"para": "All other types:"
},
{
"itemizedlist": [
[
{
"para": "OPAQUE (raw bits)"
}
]
]
}
]
]
}
],
"id": "JSON_TYPE",
"syntax": [
{
"para": "\n JSON_TYPE()\n \n\n JSON_TYPE(json_val)"
}
]
},
{
"keywords": [
"JSON_VALID"
],
"description": [
{
"para": "Returns 0 or 1 to indicate whether a value is valid JSON.\n Returns NULL if the argument is\n NULL."
}
],
"id": "JSON_VALID",
"syntax": [
{
"para": "\n JSON_VALID()\n \n\n JSON_VALID(val)"
}
]
},
{
"keywords": [
"JSON_TABLE"
],
"description": [
{
"para": "Extracts data from a JSON document and returns it as a\n relational table having the specified columns. The complete\n syntax for this function is shown here:"
},
{
"programlisting": ">\nJSON_TABLE(\n expr,\n path COLUMNS (column_list)\n) [AS] alias\n\ncolumn_list:\n column[, column][, ...]\n\ncolumn:\n name FOR ORDINALITY\n | nametype PATH string path [on_empty] [on_error]\n | nametype EXISTS PATH string path\n | NESTED [PATH] path COLUMNS (column_list)\n\non_empty:\n {NULL | ERROR | DEFAULT json_string} ON EMPTY\n\non_error:\n {NULL | ERROR | DEFAULT json_string} ON ERROR"
},
{
"para": "expr: This is an expression that\n returns JSON data. This can be a constant\n ('{\"a\":1}'), a column\n (t1.json_data, given table\n t1 specified prior to\n JSON_TABLE() in the FROM\n clause), or a function call\n (JSON_EXTRACT(t1,jsn_data,'$.post.comments'))."
},
{
"para": "path: A JSON path expression, which\n is applied to the data source. We refer to the JSON value\n matching the path as the row source; this\n is used to generate a row of relational data. The\n COLUMNS clause evaluates the row source,\n finds specific JSON values within the row source, and returns\n those JSON values as SQL values in individual columns of a row\n of relational data."
},
{
"para": "The alias is required. The usual\n rules for table aliases apply (see\n )."
}
],
"id": "JSON_TABLE",
"syntax": [
{
"para": "\n JSON_TABLE()\n \n\n JSON_TABLE(expr,\n path COLUMNS\n (column_list) [AS]\n alias)"
}
]
},
{
"keywords": [
"JSON_SCHEMA_VALID"
],
"description": [
{
"para": "\n JSON_SCHEMA_VALID()\n \n\n JSON_SCHEMA_VALID(schema,document)"
},
{
"para": "Validates a JSON document against a\n JSON schema. Both\n schema and\n document are required. The schema\n must be a valid JSON object; the document must be a valid JSON\n document. Provided that these conditions are met: If the\n document validates against the schema, the function returns\n true (1); otherwise, it returns false (0)."
}
],
"id": "JSON_SCHEMA_VALID",
"syntax": []
},
{
"keywords": [
"JSON_SCHEMA_VALIDATION_REPORT"
],
"description": [
{
"para": "\n JSON_SCHEMA_VALIDATION_REPORT()\n \n\n JSON_SCHEMA_VALIDATION_REPORT(schema,document)"
},
{
"para": "Validates a JSON document against a\n JSON schema. Both\n schema and\n document are required. As with\n JSON_VALID_SCHEMA(), the schema must be a valid JSON object,\n and the document must be a valid JSON document. Provided that\n these conditions are met, the function returns a report, as a\n JSON document, on the outcome of the validation. If the JSON\n document is considered valid according to the JSON Schema, the\n function returns a JSON object with one property\n valid having the value \"true\". If the JSON\n document fails validation, the function returns a JSON object\n which includes the properties listed here:"
},
{
"itemizedlist": [
[
{
"para": "valid: Always \"false\" for a failed\n schema validation"
}
],
[
{
"para": "reason: A human-readable string\n containing the reason for the failure"
}
],
[
{
"para": "schema-location: A JSON pointer URI\n fragment identifier indicating where in the JSON schema\n the validation failed (see Note following this list)"
}
],
[
{
"para": "document-location: A JSON pointer URI\n fragment identifier indicating where in the JSON document\n the validation failed (see Note following this list)"
}
],
[
{
"para": "schema-failed-keyword: A string\n containing the name of the keyword or property in the JSON\n schema that was violated"
}
]
]
}
],
"id": "JSON_SCHEMA_VALIDATION_REPORT",
"syntax": []
},
{
"keywords": [
"JSON_PRETTY"
],
"description": [
{
"para": "\n JSON_PRETTY()\n \n\n JSON_PRETTY(json_val)"
},
{
"para": "Provides pretty-printing of JSON values similar to that\n implemented in PHP and by other languages and database\n systems. The value supplied must be a JSON value or a valid\n string representation of a JSON value. Extraneous whitespaces\n and newlines present in this value have no effect on the\n output. For a NULL value, the function\n returns NULL. If the value is not a JSON\n document, or if it cannot be parsed as one, the function fails\n with an error."
},
{
"para": "Formatting of the output from this function adheres to the\n following rules:"
},
{
"itemizedlist": [
[
{
"para": "Each array element or object member appears on a separate\n line, indented by one additional level as compared to its\n parent."
}
],
[
{
"para": "Each level of indentation adds two leading spaces."
}
],
[
{
"para": "A comma separating individual array elements or object\n members is printed before the newline that separates the\n two elements or members."
}
],
[
{
"para": "The key and the value of an object member are separated by\n a colon followed by a space (': ')."
}
],
[
{
"para": "An empty object or array is printed on a single line. No\n space is printed between the opening and closing brace."
}
],
[
{
"para": "Special characters in string scalars and key names are\n escaped employing the same rules used by the\n JSON_QUOTE() function."
}
]
]
}
],
"id": "JSON_PRETTY",
"syntax": []
},
{
"keywords": [
"JSON_STORAGE_FREE"
],
"description": [
{
"para": "\n JSON_STORAGE_FREE()\n \n\n JSON_STORAGE_FREE(json_val)"
},
{
"para": "For a JSON column value, this\n function shows how much storage space was freed in its binary\n representation after it was updated in place using\n JSON_SET(),\n JSON_REPLACE(), or\n JSON_REMOVE(). The argument can\n also be a valid JSON document or a string which can be parsed\n as onemdasheither as a literal value or as the value of a\n user variablemdashin which case the function returns 0. It\n returns a positive, nonzero value if the argument is a\n JSON column value which has been updated as\n described previously, such that its binary representation\n takes up less space than it did prior to the update. For a\n JSON column which has been updated such\n that its binary representation is the same as or larger than\n before, or if the update was not able to take advantage of a\n partial update, it returns 0; it returns\n NULL if the argument is\n NULL."
},
{
"para": "If json_val is not\n NULL, and neither is a valid JSON document\n nor can be successfully parsed as one, an error results."
}
],
"id": "JSON_STORAGE_FREE",
"syntax": []
},
{
"keywords": [
"JSON_STORAGE_SIZE"
],
"description": [
{
"para": "\n JSON_STORAGE_SIZE()\n \n\n JSON_STORAGE_SIZE(json_val)"
},
{
"para": "This function returns the number of bytes used to store the\n binary representation of a JSON document. When the argument is\n a JSON column, this is the space used to\n store the JSON document as it was inserted into the column,\n prior to any partial updates that may have been performed on\n it afterwards. json_val must be a\n valid JSON document or a string which can be parsed as one. In\n the case where it is string, the function returns the amount\n of storage space in the JSON binary representation that is\n created by parsing the string as JSON and converting it to\n binary. It returns NULL if the argument is\n NULL."
},
{
"para": "An error results when json_val is\n not NULL, and is notmdashor cannot be\n successfully parsed asmdasha JSON document."
}
],
"id": "JSON_STORAGE_SIZE",
"syntax": []
},
{
"keywords": [
"FALSE",
"TRUE"
],
"description": [
{
"para": "The constants TRUE and\n FALSE evaluate to 1 and\n 0, respectively. The constant names can be\n written in any lettercase."
},
{
"programlisting": ">\nmysql> SELECT TRUE, true, FALSE, false;\n -> 1, 1, 0, 0"
}
],
"id": "TRUE",
"syntax": []
},
{
"keywords": [
"ST_GeomCollFromText",
"ST_GeometryCollectionFromText"
],
"description": [
{
"para": "\n ST_GeomCollFromText()\n \n\n \n ST_GeometryCollectionFromText()\n \n\n ST_GeomCollFromText(wkt[,\n srid [,\n options]]),\n ST_GeometryCollectionFromText(wkt[,\n srid [,\n options]]),\n ST_GeomCollFromTxt(wkt[,\n srid [,\n options]])"
},
{
"para": "Constructs a GeometryCollection value using\n its WKT representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_GeomCollFromText",
"syntax": []
},
{
"keywords": [
"ST_GeomFromText",
"ST_GeometryFromText"
],
"description": [
{
"para": "\n ST_GeomFromText()\n \n\n \n ST_GeometryFromText()\n \n\n ST_GeomFromText(wkt[,\n srid [,\n options]]),\n ST_GeometryFromText(wkt[,\n srid [,\n options]])"
},
{
"para": "Constructs a geometry value of any type using its WKT\n representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_GeomFromText",
"syntax": []
},
{
"keywords": [
"ST_LineFromText",
"ST_LineStringFromText"
],
"description": [
{
"para": "\n ST_LineFromText()\n \n\n \n ST_LineStringFromText()\n \n\n ST_LineFromText(wkt[,\n srid [,\n options]]),\n ST_LineStringFromText(wkt[,\n srid [,\n options]])"
},
{
"para": "Constructs a LineString value using its WKT\n representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_LineFromText",
"syntax": []
},
{
"keywords": [
"ST_MLineFromText",
"ST_MultiLineStringFromText"
],
"description": [
{
"para": "\n ST_MLineFromText()\n \n\n \n ST_MultiLineStringFromText()\n \n\n ST_MLineFromText(wkt[,\n srid [,\n options]]),\n ST_MultiLineStringFromText(wkt[,\n srid [,\n options]])"
},
{
"para": "Constructs a MultiLineString value using\n its WKT representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_MLineFromText",
"syntax": []
},
{
"keywords": [
"ST_MPointFromText",
"ST_MultiPointFromText"
],
"description": [
{
"para": "\n ST_MPointFromText()\n \n\n \n ST_MultiPointFromText()\n \n\n ST_MPointFromText(wkt[,\n srid [,\n options]]),\n ST_MultiPointFromText(wkt[,\n srid [,\n options]])"
},
{
"para": "Constructs a MultiPoint value using its WKT\n representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_MPointFromText",
"syntax": []
},
{
"keywords": [
"ST_MPolyFromText",
"ST_MultiPolygonFromText"
],
"description": [
{
"para": "\n ST_MPolyFromText()\n \n\n \n ST_MultiPolygonFromText()\n \n\n ST_MPolyFromText(wkt[,\n srid [,\n options]]),\n ST_MultiPolygonFromText(wkt[,\n srid [,\n options]])"
},
{
"para": "Constructs a MultiPolygon value using its\n WKT representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_MPolyFromText",
"syntax": []
},
{
"keywords": [
"ST_PointFromText"
],
"description": [
{
"para": "\n ST_PointFromText()\n \n\n ST_PointFromText(wkt[,\n srid [,\n options]])"
},
{
"para": "Constructs a Point value using its WKT\n representation and SRID."
},
{
"para": "ST_PointFromText() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_PointFromText",
"syntax": []
},
{
"keywords": [
"ST_PolyFromText",
"ST_PolygonFromText"
],
"description": [
{
"para": "\n ST_PolyFromText()\n \n\n \n ST_PolygonFromText()\n \n\n ST_PolyFromText(wkt[,\n srid [,\n options]]),\n ST_PolygonFromText(wkt[,\n srid [,\n options]])"
},
{
"para": "Constructs a Polygon value using its WKT\n representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_PolyFromText",
"syntax": []
},
{
"keywords": [
"ST_GeomCollFromWKB",
"ST_GeometryCollectionFromWKB"
],
"description": [
{
"para": "\n ST_GeomCollFromWKB()\n \n\n \n ST_GeometryCollectionFromWKB()\n \n\n ST_GeomCollFromWKB(wkb[,\n srid [,\n options]]),\n ST_GeometryCollectionFromWKB(wkb[,\n srid [,\n options]])"
},
{
"para": "Constructs a GeometryCollection value using\n its WKB representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_GeomCollFromWKB",
"syntax": []
},
{
"keywords": [
"ST_GeomFromWKB",
"ST_GeometryFromWKB"
],
"description": [
{
"para": "\n ST_GeomFromWKB()\n \n\n \n ST_GeometryFromWKB()\n \n\n ST_GeomFromWKB(wkb[,\n srid [,\n options]]),\n ST_GeometryFromWKB(wkb[,\n srid [,\n options]])"
},
{
"para": "Constructs a geometry value of any type using its WKB\n representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_GeomFromWKB",
"syntax": []
},
{
"keywords": [
"ST_LineFromWKB",
"ST_LineStringFromWKB"
],
"description": [
{
"para": "\n ST_LineFromWKB()\n \n\n \n ST_LineStringFromWKB()\n \n\n ST_LineFromWKB(wkb[,\n srid [,\n options]]),\n ST_LineStringFromWKB(wkb[,\n srid [,\n options]])"
},
{
"para": "Constructs a LineString value using its WKB\n representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_LineFromWKB",
"syntax": []
},
{
"keywords": [
"ST_MLineFromWKB",
"ST_MultiLineStringFromWKB"
],
"description": [
{
"para": "\n ST_MLineFromWKB()\n \n\n \n ST_MultiLineStringFromWKB()\n \n\n ST_MLineFromWKB(wkb[,\n srid [,\n options]]),\n ST_MultiLineStringFromWKB(wkb[,\n srid [,\n options]])"
},
{
"para": "Constructs a MultiLineString value using\n its WKB representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_MLineFromWKB",
"syntax": []
},
{
"keywords": [
"ST_MPointFromWKB",
"ST_MultiPointFromWKB"
],
"description": [
{
"para": "\n ST_MPointFromWKB()\n \n\n \n ST_MultiPointFromWKB()\n \n\n ST_MPointFromWKB(wkb[,\n srid [,\n options]]),\n ST_MultiPointFromWKB(wkb[,\n srid [,\n options]])"
},
{
"para": "Constructs a MultiPoint value using its WKB\n representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_MPointFromWKB",
"syntax": []
},
{
"keywords": [
"ST_MPolyFromWKB",
"ST_MultiPolygonFromWKB"
],
"description": [
{
"para": "\n ST_MPolyFromWKB()\n \n\n \n ST_MultiPolygonFromWKB()\n \n\n ST_MPolyFromWKB(wkb[,\n srid [,\n options]]),\n ST_MultiPolygonFromWKB(wkb[,\n srid [,\n options]])"
},
{
"para": "Constructs a MultiPolygon value using its\n WKB representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_MPolyFromWKB",
"syntax": []
},
{
"keywords": [
"ST_PointFromWKB"
],
"description": [
{
"para": "\n ST_PointFromWKB()\n \n\n ST_PointFromWKB(wkb[,\n srid [,\n options]])"
},
{
"para": "Constructs a Point value using its WKB\n representation and SRID."
},
{
"para": "ST_PointFromWKB() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_PointFromWKB",
"syntax": []
},
{
"keywords": [
"ST_PolyFromWKB",
"ST_PolygonFromWKB"
],
"description": [
{
"para": "\n ST_PolyFromWKB()\n \n\n \n ST_PolygonFromWKB()\n \n\n ST_PolyFromWKB(wkb[,\n srid [,\n options]]),\n ST_PolygonFromWKB(wkb[,\n srid [,\n options]])"
},
{
"para": "Constructs a Polygon value using its WKB\n representation and SRID."
},
{
"para": "These functions handle their arguments as described in the\n introduction to this section."
}
],
"id": "ST_PolyFromWKB",
"syntax": []
},
{
"keywords": [
"GeomCollection"
],
"description": [
{
"para": "GeomCollection(g\n [, g] ...)"
},
{
"para": "Constructs a GeomCollection value from the\n geometry arguments."
},
{
"para": "GeomCollection() returns all\n the proper geometries contained in the arguments even if a\n nonsupported geometry is present."
},
{
"para": "GeomCollection() with no\n arguments is permitted as a way to create an empty geometry.\n Also, functions such as\n ST_GeomFromText() that accept\n WKT geometry collection arguments understand both OpenGIS\n 'GEOMETRYCOLLECTION EMPTY' standard syntax\n and MySQL 'GEOMETRYCOLLECTION()'\n nonstandard syntax."
},
{
"para": "GeomCollection() and\n GeometryCollection() are\n synonymous, with\n GeomCollection() the preferred\n function."
}
],
"id": "GeomCollection",
"syntax": []
},
{
"keywords": [
"GeometryCollection"
],
"description": [
{
"para": "GeometryCollection(g\n [, g] ...)"
},
{
"para": "Constructs a GeomCollection value from the\n geometry arguments."
},
{
"para": "GeometryCollection() returns\n all the proper geometries contained in the arguments even if a\n nonsupported geometry is present."
},
{
"para": "GeometryCollection() with no\n arguments is permitted as a way to create an empty geometry.\n Also, functions such as\n ST_GeomFromText() that accept\n WKT geometry collection arguments understand both OpenGIS\n 'GEOMETRYCOLLECTION EMPTY' standard syntax\n and MySQL 'GEOMETRYCOLLECTION()'\n nonstandard syntax."
},
{
"para": "GeomCollection() and\n GeometryCollection() are\n synonymous, with\n GeomCollection() the preferred\n function."
}
],
"id": "GeometryCollection",
"syntax": []
},
{
"keywords": [
"LineString"
],
"description": [
{
"para": "LineString(pt\n [, pt] ...)"
},
{
"para": "Constructs a LineString value from a number\n of Point or WKB Point\n arguments. If the number of arguments is less than two, the\n return value is NULL."
}
],
"id": "LineString",
"syntax": []
},
{
"keywords": [
"MultiLineString"
],
"description": [
{
"para": "MultiLineString(ls\n [, ls] ...)"
},
{
"para": "Constructs a MultiLineString value using\n LineString or WKB\n LineString arguments."
}
],
"id": "MultiLineString",
"syntax": []
},
{
"keywords": [
"MultiPoint"
],
"description": [
{
"para": "MultiPoint(pt\n [, pt2] ...)"
},
{
"para": "Constructs a MultiPoint value using\n Point or WKB Point\n arguments."
}
],
"id": "MultiPoint",
"syntax": []
},
{
"keywords": [
"MultiPolygon"
],
"description": [
{
"para": "MultiPolygon(poly\n [, poly] ...)"
},
{
"para": "Constructs a MultiPolygon value from a set\n of Polygon or WKB\n Polygon arguments."
}
],
"id": "MultiPolygon",
"syntax": []
},
{
"keywords": [
"Point"
],
"description": [
{
"para": "Point(x,\n y)"
},
{
"para": "Constructs a Point using its coordinates."
}
],
"id": "Point",
"syntax": []
},
{
"keywords": [
"Polygon"
],
"description": [
{
"para": "Polygon(ls [,\n ls] ...)"
},
{
"para": "Constructs a Polygon value from a number of\n LineString or WKB\n LineString arguments. If any argument does\n not represent a LinearRing (that is, not a\n closed and simple LineString), the return\n value is NULL."
}
],
"id": "Polygon",
"syntax": []
},
{
"keywords": [
"ST_AsBinary",
"ST_AsWKB"
],
"description": [
{
"para": "ST_AsBinary(g\n [, options]),\n ST_AsWKB(g\n [, options])"
},
{
"para": "Converts a value in internal geometry format to its WKB\n representation and returns the binary result."
},
{
"para": "The function return value has geographic coordinates\n (latitude, longitude) in the order specified by the spatial\n reference system that applies to the geometry argument. An\n optional options argument may be\n given to override the default axis order."
},
{
"para": "ST_AsBinary() and\n ST_AsWKB()\n handle their arguments as described in the introduction to\n this section."
}
],
"id": "ST_AsBinary",
"syntax": []
},
{
"keywords": [
"ST_AsText",
"ST_AsWKT"
],
"description": [
{
"para": "ST_AsText(g [,\n options]),\n ST_AsWKT(g\n [, options])"
},
{
"para": "Converts a value in internal geometry format to its WKT\n representation and returns the string result."
},
{
"para": "The function return value has geographic coordinates\n (latitude, longitude) in the order specified by the spatial\n reference system that applies to the geometry argument. An\n optional options argument may be\n given to override the default axis order."
},
{
"para": "ST_AsText() and\n ST_AsWKT()\n handle their arguments as described in the introduction to\n this section."
}
],
"id": "ST_AsText",
"syntax": []
},
{
"keywords": [
"ST_SwapXY"
],
"description": [
{
"para": "ST_SwapXY(g)"
},
{
"para": "Accepts an argument in internal geometry format, swaps the X\n and Y values of each coordinate pair within the geometry, and\n returns the result."
},
{
"para": "ST_SwapXY() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_SwapXY",
"syntax": []
},
{
"keywords": [
"ST_Dimension"
],
"description": [
{
"para": "ST_Dimension(g)"
},
{
"para": "Returns the inherent dimension of the geometry value\n g. The dimension can be minus1,\n 0, 1, or 2. The meaning of these values is given in\n ."
},
{
"para": "ST_Dimension() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Dimension",
"syntax": []
},
{
"keywords": [
"ST_Envelope"
],
"description": [
{
"para": "ST_Envelope(g)"
},
{
"para": "Returns the minimum bounding rectangle (MBR) for the\n geometry value g. The result is\n returned as a Polygon value that is\n defined by the corner points of the bounding box:"
},
{
"programlisting": ">\nPOLYGON((MINX MINY, MAXX MINY, MAXX MAXY, MINX MAXY, MINX MINY))"
},
{
"programlisting": ">\nmysql> SELECT ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,2 2)')));\n+----------------------------------------------------------------+\n| ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,2 2)'))) |\n+----------------------------------------------------------------+\n| POLYGON((1 1,2 1,2 2,1 2,1 1)) |\n+----------------------------------------------------------------+"
},
{
"para": "If the argument is a point or a vertical or horizontal line\n segment, ST_Envelope()\n returns the point or the line segment as its MBR rather than\n returning an invalid polygon:"
},
{
"programlisting": ">\nmysql> SELECT ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,1 2)')));\n+----------------------------------------------------------------+\n| ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,1 2)'))) |\n+----------------------------------------------------------------+\n| LINESTRING(1 1,1 2) |\n+----------------------------------------------------------------+"
},
{
"para": "ST_Envelope() handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry has an SRID value for a geographic\n spatial reference system (SRS), an\n ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS\n error occurs."
}
]
]
}
],
"id": "ST_Envelope",
"syntax": []
},
{
"keywords": [
"ST_GeometryType"
],
"description": [
{
"para": "ST_GeometryType(g)"
},
{
"para": "Returns a binary string indicating the name of the geometry\n type of which the geometry instance\n g is a member. The name\n corresponds to one of the instantiable\n Geometry subclasses."
},
{
"para": "ST_GeometryType() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_GeometryType",
"syntax": []
},
{
"keywords": [
"ST_IsEmpty"
],
"description": [
{
"para": "ST_IsEmpty(g)"
},
{
"para": "This function is a placeholder that returns 1 for an empty\n geometry collection value or 0 otherwise."
},
{
"para": "The only valid empty geometry is represented in the form of\n an empty geometry collection value. MySQL does not support\n GIS EMPTY values such as POINT\n EMPTY."
},
{
"para": "ST_IsEmpty() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_IsEmpty",
"syntax": []
},
{
"keywords": [
"ST_IsSimple"
],
"description": [
{
"para": "ST_IsSimple(g)"
},
{
"para": "Returns 1 if the geometry value g\n is simple according to the ISO SQL/MM Part 3:\n Spatial standard.\n ST_IsSimple() returns 0 if\n the argument is not simple."
},
{
"para": "The descriptions of the instantiable geometric classes given\n under include the\n specific conditions that cause class instances to be\n classified as not simple."
},
{
"para": "ST_IsSimple() handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry has a geographic SRS with a longitude or\n latitude that is out of range, an error occurs:"
},
{
"itemizedlist": [
[
{
"para": "If any longitude argument is not in the range\n (minus180, 180], an\n ER_LONGITUDE_OUT_OF_RANGE\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n ER_LATITUDE_OUT_OF_RANGE\n error occurs."
}
]
]
},
{
"para": "Ranges shown are in degrees. The exact range limits\n deviate slightly due to floating-point arithmetic."
}
]
]
}
],
"id": "ST_IsSimple",
"syntax": []
},
{
"keywords": [
"ST_SRID"
],
"description": [
{
"para": "ST_SRID(g[,\n srid])"
},
{
"para": "With a single argument representing a valid geometry object\n g,\n ST_SRID() returns an integer\n indicating the ID of the spatial reference system (SRS)\n associated with g."
},
{
"para": "With the optional second argument representing a valid SRID\n value, ST_SRID() returns an\n object with the same type as its first argument with an SRID\n value equal to the second argument. This only sets the SRID\n value of the object; it does not perform any transformation\n of coordinate values."
},
{
"para": "ST_SRID() handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "For the single-argument syntax,\n ST_SRID() returns the\n geometry SRID even if it refers to an undefined SRS. An\n ER_SRS_NOT_FOUND error\n does not occur."
}
]
]
},
{
"para": "ST_SRID(g,\n target_srid) and\n ST_Transform(g,\n target_srid) differ as\n follows:"
},
{
"itemizedlist": [
[
{
"para": "ST_SRID() changes the\n geometry SRID value without transforming its\n coordinates."
}
],
[
{
"para": "ST_Transform() transforms\n the geometry coordinates in addition to changing its\n SRID value."
}
]
]
}
],
"id": "ST_SRID",
"syntax": []
},
{
"keywords": [
"ST_Latitude"
],
"description": [
{
"para": "ST_Latitude(p\n [, new_latitude_val])"
},
{
"para": "With a single argument representing a valid\n Point object p\n that has a geographic spatial reference system (SRS),\n ST_Latitude() returns the\n latitude value of p as a\n double-precision number."
},
{
"para": "With the optional second argument representing a valid\n latitude value, ST_Latitude()\n returns a Point object like the first\n argument with its latitude equal to the second argument."
},
{
"para": "ST_Latitude() handles its\n arguments as described in the introduction to this section,\n with the addition that if the Point\n object is valid but does not have a geographic SRS, an\n ER_SRS_NOT_GEOGRAPHIC error\n occurs."
}
],
"id": "ST_Latitude",
"syntax": []
},
{
"keywords": [
"ST_Longitude"
],
"description": [
{
"para": "ST_Longitude(p\n [, new_longitude_val])"
},
{
"para": "With a single argument representing a valid\n Point object p\n that has a geographic spatial reference system (SRS),\n ST_Longitude() returns the\n longitude value of p as a\n double-precision number."
},
{
"para": "With the optional second argument representing a valid\n longitude value,\n ST_Longitude() returns a\n Point object like the first argument with\n its longitude equal to the second argument."
},
{
"para": "ST_Longitude() handles its\n arguments as described in the introduction to this section,\n with the addition that if the Point\n object is valid but does not have a geographic SRS, an\n ER_SRS_NOT_GEOGRAPHIC error\n occurs."
}
],
"id": "ST_Longitude",
"syntax": []
},
{
"keywords": [
"ST_X"
],
"description": [
{
"para": "ST_X(p[,\n new_x_val])"
},
{
"para": "With a single argument representing a valid\n Point object\n p,\n ST_X() returns the\n X-coordinate value of p as a\n double-precision number. As of MySQL 8.0.12, the X\n coordinate is considered to refer to the axis that appears\n first in the Point spatial reference\n system (SRS) definition."
},
{
"para": "With the optional second argument,\n ST_X() returns a\n Point object like the first argument with\n its X coordinate equal to the second argument. As of MySQL\n 8.0.12, if the Point object has a\n geographic SRS, the second argument must be in the proper\n range for longitude or latitude values."
},
{
"para": "ST_X() handles its arguments\n as described in the introduction to this section."
}
],
"id": "ST_X",
"syntax": []
},
{
"keywords": [
"ST_Y"
],
"description": [
{
"para": "ST_Y(p[,\n new_y_val])"
},
{
"para": "With a single argument representing a valid\n Point object\n p,\n ST_Y() returns the\n Y-coordinate value of p as a\n double-precision number. As of MySQL 8.0.12, the Y\n coordinate is considered to refer to the axis that appears\n second in the Point spatial reference\n system (SRS) definition."
},
{
"para": "With the optional second argument,\n ST_Y() returns a\n Point object like the first argument with\n its Y coordinate equal to the second argument. As of MySQL\n 8.0.12, if the Point object has a\n geographic SRS, the second argument must be in the proper\n range for longitude or latitude values."
},
{
"para": "ST_Y() handles its arguments\n as described in the introduction to this section."
}
],
"id": "ST_Y",
"syntax": []
},
{
"keywords": [
"ST_EndPoint"
],
"description": [
{
"para": "\n ST_EndPoint()\n \n\n ST_EndPoint(ls)"
},
{
"para": "Returns the Point that is the endpoint of\n the LineString value\n ls."
},
{
"para": "ST_EndPoint() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_EndPoint",
"syntax": []
},
{
"keywords": [
"ST_IsClosed"
],
"description": [
{
"para": "\n ST_IsClosed()\n \n\n ST_IsClosed(ls)"
},
{
"para": "For a LineString value\n ls,\n ST_IsClosed() returns 1 if\n ls is closed (that is, its\n ST_StartPoint() and\n ST_EndPoint() values are the\n same)."
},
{
"para": "For a MultiLineString value\n ls,\n ST_IsClosed() returns 1 if\n ls is closed (that is, the\n ST_StartPoint() and\n ST_EndPoint() values are the\n same for each LineString in\n ls)."
},
{
"para": "ST_IsClosed() returns 0 if\n ls is not closed, and\n NULL if ls is\n NULL."
},
{
"para": "ST_IsClosed() handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry has an SRID value for a geographic\n spatial reference system (SRS), an\n ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS\n error occurs."
}
]
]
}
],
"id": "ST_IsClosed",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n ST_Length()\n \n\n ST_Length(ls\n [, unit])"
},
{
"para": "Returns a double-precision number indicating the length of\n the LineString or\n MultiLineString value\n ls in its associated spatial\n reference system. The length of a\n MultiLineString value is equal to the sum\n of the lengths of its elements."
},
{
"para": "ST_Length() computes a result\n as follows:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry is a valid LineString\n in a Cartesian SRS, the return value is the Cartesian\n length of the geometry."
}
],
[
{
"para": "If the geometry is a valid\n MultiLineString in a Cartesian SRS,\n the return value is the sum of the Cartesian lengths of\n its elements."
}
],
[
{
"para": "If the geometry is a valid LineString\n in a geographic SRS, the return value is the geodetic\n length of the geometry in that SRS, in meters."
}
],
[
{
"para": "If the geometry is a valid\n MultiLineString in a geographic SRS,\n the return value is the sum of the geodetic lengths of\n its elements in that SRS, in meters."
}
]
]
},
{
"para": "ST_Length() handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry is not a LineString\n or MultiLineString, the return value\n is NULL."
}
],
[
{
"para": "If the geometry is geometrically invalid, either the\n result is an undefined length (that is, it can be any\n number), or an error occurs."
}
],
[
{
"para": "If the length computation result is\n +inf, an\n ER_DATA_OUT_OF_RANGE\n error occurs."
}
],
[
{
"para": "If the geometry has a geographic SRS with a longitude or\n latitude that is out of range, an error occurs:"
},
{
"itemizedlist": [
[
{
"para": "If any longitude argument is not in the range\n (minus180, 180], an\n ER_LONGITUDE_OUT_OF_RANGE\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n ER_LATITUDE_OUT_OF_RANGE\n error occurs."
}
]
]
},
{
"para": "Ranges shown are in degrees. The exact range limits\n deviate slightly due to floating-point arithmetic."
}
]
]
},
{
"para": "As of MySQL 8.0.16,\n ST_Length() permits an\n optional unit argument that\n specifies the linear unit for the returned length value.\n These rules apply:"
},
{
"itemizedlist": [
[
{
"para": "If a unit is specified but not supported by MySQL, an\n ER_UNIT_NOT_FOUND error\n occurs."
}
],
[
{
"para": "If a supported linear unit is specified and the SRID is\n 0, an\n ER_GEOMETRY_IN_UNKNOWN_LENGTH_UNIT\n error occurs."
}
],
[
{
"para": "If a supported linear unit is specified and the SRID is\n not 0, the result is in that unit."
}
],
[
{
"para": "If a unit is not specified, the result is in the unit of\n the SRS of the geometries, whether Cartesian or\n geographic. Currently, all MySQL SRSs are expressed in\n meters."
}
]
]
},
{
"para": "A unit is supported if it is found in the\n INFORMATION_SCHEMA\n ST_UNITS_OF_MEASURE table. See\n ."
}
],
"id": "ST_Length",
"syntax": []
},
{
"keywords": [
"ST_NumPoints"
],
"description": [
{
"para": "\n ST_NumPoints()\n \n\n ST_NumPoints(ls)"
},
{
"para": "Returns the number of Point objects in\n the LineString value\n ls."
},
{
"para": "ST_NumPoints() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_NumPoints",
"syntax": []
},
{
"keywords": [
"ST_PointN"
],
"description": [
{
"para": "\n ST_PointN()\n \n\n ST_PointN(ls,\n N)"
},
{
"para": "Returns the N-th\n Point in the\n Linestring value\n ls. Points are numbered beginning\n with 1."
},
{
"para": "ST_PointN() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_PointN",
"syntax": []
},
{
"keywords": [
"ST_StartPoint"
],
"description": [
{
"para": "\n ST_StartPoint()\n \n\n ST_StartPoint(ls)"
},
{
"para": "Returns the Point that is the start point\n of the LineString value\n ls."
},
{
"para": "ST_StartPoint() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_StartPoint",
"syntax": []
},
{
"keywords": [
"ST_Area"
],
"description": [
{
"para": "\n ST_Area()\n \n\n ST_Area({poly|mpoly})"
},
{
"para": "Returns a double-precision number indicating the area of the\n Polygon or\n MultiPolygon argument, as measured in its\n spatial reference system."
},
{
"para": "As of MySQL 8.0.13, ST_Area()\n handles its arguments as described in the introduction to\n this section, with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry is geometrically invalid, either the\n result is an undefined area (that is, it can be any\n number), or an error occurs."
}
],
[
{
"para": "If the geometry is valid but is not a\n Polygon or\n MultiPolygon object, an\n ER_UNEXPECTED_GEOMETRY_TYPE\n error occurs."
}
],
[
{
"para": "If the geometry is a valid Polygon in\n a Cartesian SRS, the result is the Cartesian area of the\n polygon."
}
],
[
{
"para": "If the geometry is a valid\n MultiPolygon in a Cartesian SRS, the\n result is the sum of the Cartesian area of the polygons."
}
],
[
{
"para": "If the geometry is a valid Polygon in\n a geographic SRS, the result is the geodetic area of the\n polygon in that SRS, in square meters."
}
],
[
{
"para": "If the geometry is a valid\n MultiPolygon in a geographic SRS, the\n result is the sum of geodetic area of the polygons in\n that SRS, in square meters."
}
],
[
{
"para": "If an area computation results in\n +inf, an\n ER_DATA_OUT_OF_RANGE\n error occurs."
}
],
[
{
"para": "If the geometry has a geographic SRS with a longitude or\n latitude that is out of range, an error occurs:"
},
{
"itemizedlist": [
[
{
"para": "If any longitude argument is not in the range\n (minus180, 180], an\n ER_LONGITUDE_OUT_OF_RANGE\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n ER_LATITUDE_OUT_OF_RANGE\n error occurs."
}
]
]
},
{
"para": "Ranges shown are in degrees. The exact range limits\n deviate slightly due to floating-point arithmetic."
}
]
]
},
{
"para": "Prior to MySQL 8.0.13,\n ST_Area() handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "For arguments of dimension 0 or 1, the result is 0."
}
],
[
{
"para": "If a geometry is empty, the return value is 0 rather\n than NULL."
}
],
[
{
"para": "For a geometry collection, the result is the sum of the\n area values of all components. If the geometry\n collection is empty, its area is returned as 0."
}
],
[
{
"para": "If the geometry has an SRID value for a geographic\n spatial reference system (SRS), an\n ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS\n error occurs."
}
]
]
}
],
"id": "ST_Area",
"syntax": []
},
{
"keywords": [
"ST_Centroid"
],
"description": [
{
"para": "\n ST_Centroid()\n \n\n ST_Centroid({poly|mpoly})"
},
{
"para": "Returns the mathematical centroid for the\n Polygon or\n MultiPolygon argument as a\n Point. The result is not guaranteed to be\n on the MultiPolygon."
},
{
"para": "This function processes geometry collections by computing\n the centroid point for components of highest dimension in\n the collection. Such components are extracted and made into\n a single MultiPolygon,\n MultiLineString, or\n MultiPoint for centroid computation."
},
{
"para": "ST_Centroid() handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "The return value is NULL for the\n additional condition that the argument is an empty\n geometry collection."
}
],
[
{
"para": "If the geometry has an SRID value for a geographic\n spatial reference system (SRS), an\n ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS\n error occurs."
}
]
]
}
],
"id": "ST_Centroid",
"syntax": []
},
{
"keywords": [
"ST_ExteriorRing"
],
"description": [
{
"para": "\n ST_ExteriorRing()\n \n\n ST_ExteriorRing(poly)"
},
{
"para": "Returns the exterior ring of the Polygon\n value poly as a\n LineString."
},
{
"para": "ST_ExteriorRing() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_ExteriorRing",
"syntax": []
},
{
"keywords": [
"ST_InteriorRingN"
],
"description": [
{
"para": "\n ST_InteriorRingN()\n \n\n ST_InteriorRingN(poly,\n N)"
},
{
"para": "Returns the N-th interior ring\n for the Polygon value\n poly as a\n LineString. Rings are numbered beginning\n with 1."
},
{
"para": "ST_InteriorRingN() handles\n its arguments as described in the introduction to this\n section."
}
],
"id": "ST_InteriorRingN",
"syntax": []
},
{
"keywords": [
"ST_NumInteriorRings",
"ST_NumInteriorRing"
],
"description": [
{
"para": "\n ST_NumInteriorRings()\n \n\n \n ST_NumInteriorRing()\n \n\n ST_NumInteriorRing(poly),\n ST_NumInteriorRings(poly)"
},
{
"para": "Returns the number of interior rings in the\n Polygon value\n poly."
},
{
"para": "ST_NumInteriorRing()\n and ST_NuminteriorRings()\n handle their arguments as described in the introduction to\n this section."
}
],
"id": "ST_NumInteriorRings",
"syntax": []
},
{
"keywords": [
"ST_GeometryN"
],
"description": [
{
"para": "\n ST_GeometryN()\n \n\n ST_GeometryN(gc,\n N)"
},
{
"para": "Returns the N-th geometry in the\n GeometryCollection value\n gc. Geometries are numbered\n beginning with 1."
},
{
"para": "ST_GeometryN() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_GeometryN",
"syntax": []
},
{
"keywords": [
"ST_NumGeometries"
],
"description": [
{
"para": "\n ST_NumGeometries()\n \n\n ST_NumGeometries(gc)"
},
{
"para": "Returns the number of geometries in the\n GeometryCollection value\n gc."
},
{
"para": "ST_NumGeometries() handles\n its arguments as described in the introduction to this\n section."
}
],
"id": "ST_NumGeometries",
"syntax": []
},
{
"keywords": [
"ST_Buffer"
],
"description": [
{
"para": "\n ST_Buffer()\n \n\n ST_Buffer(g,\n d[,\n strategy1[,\n strategy2[,\n strategy3]]])"
},
{
"para": "Returns a geometry that represents all points whose distance\n from the geometry value g is less\n than or equal to a distance of d."
},
{
"para": "If the geometry argument is empty,\n ST_Buffer() returns an empty\n geometry."
},
{
"para": "If the distance is 0,\n ST_Buffer() returns the\n geometry argument unchanged:"
},
{
"programlisting": ">\nmysql> SET @pt = ST_GeomFromText('POINT(0 0)');\nmysql> SELECT ST_AsText(ST_Buffer(@pt, 0));\n+------------------------------+\n| ST_AsText(ST_Buffer(@pt, 0)) |\n+------------------------------+\n| POINT(0 0) |\n+------------------------------+"
},
{
"para": "ST_Buffer() supports negative\n distances for Polygon and\n MultiPolygon values, and for geometry\n collections containing Polygon or\n MultiPolygon values. The result may be an\n empty geometry."
},
{
"para": "ST_Buffer() permits up to three\n optional strategy arguments following the distance argument.\n Strategies influence buffer computation. These arguments are\n byte string values produced by the\n ST_Buffer_Strategy() function,\n to be used for point, join, and end strategies:"
},
{
"itemizedlist": [
[
{
"para": "Point strategies apply to Point and\n MultiPoint geometries. If no point\n strategy is specified, the default is\n ST_Buffer_Strategy('point_circle',\n 32)."
}
],
[
{
"para": "Join strategies apply to LineString,\n MultiLineString,\n Polygon, and\n MultiPolygon geometries. If no join\n strategy is specified, the default is\n ST_Buffer_Strategy('join_round',\n 32)."
}
],
[
{
"para": "End strategies apply to LineString and\n MultiLineString geometries. If no end\n strategy is specified, the default is\n ST_Buffer_Strategy('end_round',\n 32)."
}
]
]
},
{
"para": "Up to one strategy of each type may be specified, and they may\n be given in any order."
},
{
"para": "ST_Buffer() handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "For a negative distance for Point,\n MultiPoint,\n LineString, and\n MultiLineString values, and for\n geometry collections not containing any\n Polygon or\n MultiPolygon values, an\n ER_WRONG_ARGUMENTS error\n occurs."
}
],
[
{
"para": "If multiple strategies of a given type are specified, an\n ER_WRONG_ARGUMENTS error\n occurs."
}
]
]
}
],
"id": "ST_Buffer",
"syntax": []
},
{
"keywords": [
"ST_BUFFER_STRATEGY"
],
"description": [
{
"para": "\n ST_Buffer_Strategy()\n \n\n ST_Buffer_Strategy(strategy[,\n points_per_circle])"
},
{
"para": "This function returns a strategy byte string for use with\n ST_Buffer() to influence buffer\n computation."
},
{
"para": "Information about strategies is available at\n Boost.org."
},
{
"para": "The first argument must be a string indicating a strategy\n option:"
},
{
"itemizedlist": [
[
{
"para": "For point strategies, permitted values are\n 'point_circle' and\n 'point_square'."
}
],
[
{
"para": "For join strategies, permitted values are\n 'join_round' and\n 'join_miter'."
}
],
[
{
"para": "For end strategies, permitted values are\n 'end_round' and\n 'end_flat'."
}
]
]
},
{
"para": "If the first argument is 'point_circle',\n 'join_round',\n 'join_miter', or\n 'end_round', the\n points_per_circle argument must be\n given as a positive numeric value. The maximum\n points_per_circle value is the\n value of the\n max_points_in_geometry system\n variable."
},
{
"para": "For examples, see the description of\n ST_Buffer()."
},
{
"para": "ST_Buffer_Strategy() handles\n its arguments as described in the introduction to this\n section, with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "If any argument is invalid, an\n ER_WRONG_ARGUMENTS error\n occurs."
}
],
[
{
"para": "If the first argument is 'point_square'\n or 'end_flat', the\n points_per_circle argument must\n not be given or an\n ER_WRONG_ARGUMENTS error\n occurs."
}
]
]
}
],
"id": "ST_Buffer_Strategy",
"syntax": []
},
{
"keywords": [
"ST_CONVEXHULL"
],
"description": [
{
"para": "\n ST_ConvexHull()\n \n\n ST_ConvexHull(g)"
},
{
"para": "Returns a geometry that represents the convex hull of the\n geometry value g."
},
{
"para": "This function computes a geometry's convex hull by first\n checking whether its vertex points are colinear. The function\n returns a linear hull if so, a polygon hull otherwise. This\n function processes geometry collections by extracting all\n vertex points of all components of the collection, creating a\n MultiPoint value from them, and computing\n its convex hull."
},
{
"para": "ST_ConvexHull() handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "The return value is NULL for the\n additional condition that the argument is an empty\n geometry collection."
}
]
]
}
],
"id": "ST_ConvexHull",
"syntax": []
},
{
"keywords": [
"ST_Difference"
],
"description": [
{
"para": "\n ST_Difference()\n \n\n ST_Difference(g1,\n g2)"
},
{
"para": "Returns a geometry that represents the point set difference of\n the geometry values g1 and\n g2."
},
{
"para": "ST_Difference() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Difference",
"syntax": []
},
{
"keywords": [
"ST_Intersection"
],
"description": [
{
"para": "\n ST_Intersection()\n \n\n ST_Intersection(g1,\n g2)"
},
{
"para": "Returns a geometry that represents the point set intersection\n of the geometry values g1 and\n g2."
},
{
"para": "ST_Intersection() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Intersection",
"syntax": []
},
{
"keywords": [
"ST_SymDifference"
],
"description": [
{
"para": "\n ST_SymDifference()\n \n\n ST_SymDifference(g1,\n g2)"
},
{
"para": "Returns a geometry that represents the point set symmetric\n difference of the geometry values\n g1 and\n g2, which is defined as:"
},
{
"programlisting": ">\ng1 symdifference g2 := (g1 union g2) difference (g1 intersection g2)"
},
{
"para": "Or, in function call notation:"
},
{
"programlisting": ">\nST_SymDifference(g1, g2) = ST_Difference(ST_Union(g1, g2), ST_Intersection(g1, g2))"
},
{
"para": "ST_SymDifference() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_SymDifference",
"syntax": []
},
{
"keywords": [
"ST_TRANSFORM"
],
"description": [
{
"para": "ST_Transform(g,\n target_srid)"
},
{
"para": "Transforms a geometry from one spatial reference system (SRS)\n to another. The return value is a geometry of the same type as\n the input geometry with all coordinates transformed to the\n target SRID, target_srid.\n Transformation support is limited to geographic SRSs, unless\n the SRID of the geometry argument is the same as the target\n SRID value, in which case the return value is the input\n geometry for any valid SRS."
},
{
"para": "ST_Transform() handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "Geometry arguments that have an SRID value for a\n geographic SRS do not produce an error."
}
],
[
{
"para": "If the geometry or target SRID argument has an SRID value\n that refers to an undefined spatial reference system\n (SRS), an ER_SRS_NOT_FOUND\n error occurs."
}
],
[
{
"para": "If the geometry is in an SRS that\n ST_Transform() cannot\n transform from, an\n ER_TRANSFORM_SOURCE_SRS_NOT_SUPPORTED\n error occurs."
}
],
[
{
"para": "If the target SRID is in an SRS that\n ST_Transform() cannot\n transform to, an\n ER_TRANSFORM_TARGET_SRS_NOT_SUPPORTED\n error occurs."
}
],
[
{
"para": "If the geometry is in an SRS that is not WGS 84 and has no\n TOWGS84 clause, an\n ER_TRANSFORM_SOURCE_SRS_MISSING_TOWGS84\n error occurs."
}
],
[
{
"para": "If the target SRID is in an SRS that is not WGS 84 and has\n no TOWGS84 clause, an\n ER_TRANSFORM_TARGET_SRS_MISSING_TOWGS84\n error occurs."
}
]
]
},
{
"para": "ST_SRID(g,\n target_srid) and\n ST_Transform(g,\n target_srid) differ as\n follows:"
},
{
"itemizedlist": [
[
{
"para": "ST_SRID() changes the\n geometry SRID value without transforming its coordinates."
}
],
[
{
"para": "ST_Transform() transforms\n the geometry coordinates in addition to changing its SRID\n value."
}
]
]
}
],
"id": "ST_Transform",
"syntax": []
},
{
"keywords": [
"ST_Union"
],
"description": [
{
"para": "\n ST_Union()\n \n\n ST_Union(g1,\n g2)"
},
{
"para": "Returns a geometry that represents the point set union of the\n geometry values g1 and\n g2."
},
{
"para": "ST_Union() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Union",
"syntax": []
},
{
"keywords": [
"ST_Contains"
],
"description": [
{
"para": "\n ST_Contains()\n \n\n ST_Contains(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether\n g1 completely contains\n g2. This tests the opposite\n relationship as ST_Within()."
},
{
"para": "ST_Contains() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Contains",
"syntax": []
},
{
"keywords": [
"ST_Crosses"
],
"description": [
{
"para": "\n ST_Crosses()\n \n\n ST_Crosses(g1,\n g2)"
},
{
"para": "Two geometries spatially cross if their\n spatial relation has the following properties:"
},
{
"itemizedlist": [
[
{
"para": "Unless g1 and g2\n are both of dimension 1: g1 crosses\n g2 if the interior of\n g2 has points in common with the\n interior of g1, but\n g2 does not cover the entire interior\n of g1."
}
],
[
{
"para": "If both g1 and g2\n are of dimension 1: If the lines cross each other in a\n finite number of points (that is, no common line\n segments, only single points in common)."
}
]
]
},
{
"para": "This function returns 1 or 0 to indicate whether\n g1 spatially crosses\n g2."
},
{
"para": "ST_Crosses() handles its\n arguments as described in the introduction to this section\n except that the return value is NULL for\n these additional conditions:"
},
{
"itemizedlist": [
[
{
"para": "g1 is of dimension 2\n (Polygon or\n MultiPolygon)."
}
],
[
{
"para": "g2 is of dimension 1\n (Point or\n MultiPoint)."
}
]
]
}
],
"id": "ST_Crosses",
"syntax": []
},
{
"keywords": [
"ST_Disjoint"
],
"description": [
{
"para": "\n ST_Disjoint()\n \n\n ST_Disjoint(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether\n g1 is spatially disjoint from\n (does not intersect) g2."
},
{
"para": "ST_Disjoint() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Disjoint",
"syntax": []
},
{
"keywords": [
"ST_Distance"
],
"description": [
{
"para": "\n ST_Distance()\n \n\n ST_Distance(g1,\n g2 [,\n unit])"
},
{
"para": "Returns the distance between g1\n and g2, measured in the length\n unit of the spatial reference system (SRS) of the geometry\n arguments, or in the unit of the optional\n unit argument if that is\n specified."
},
{
"para": "This function processes geometry collections by returning\n the shortest distance among all combinations of the\n components of the two geometry arguments."
},
{
"para": "ST_Distance() handles its\n geometry arguments as described in the introduction to this\n section, with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "ST_Distance() detects\n arguments in a geographic (ellipsoidal) spatial\n reference system and returns the geodetic distance on\n the ellipsoid. As of MySQL 8.0.18,\n ST_Distance() supports\n distance calculations for geographic SRS arguments of\n all geometry types. Prior to MySQL 8.0.18, the only\n permitted geographic argument types are\n Point and Point,\n or Point and\n MultiPoint (in any argument order).\n If called with other geometry type argument combinations\n in a geographic SRS, an\n ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS\n error occurs."
}
],
[
{
"para": "If any argument is geometrically invalid, either the\n result is an undefined distance (that is, it can be any\n number), or an error occurs."
}
],
[
{
"para": "If an intermediate or final result produces\n NaN or a negative number, an\n ER_GIS_INVALID_DATA\n error occurs."
}
]
]
},
{
"para": "As of MySQL 8.0.14,\n ST_Distance() permits an\n optional unit argument that\n specifies the linear unit for the returned distance value.\n These rules apply:"
},
{
"itemizedlist": [
[
{
"para": "If a unit is specified but not supported by MySQL, an\n ER_UNIT_NOT_FOUND error\n occurs."
}
],
[
{
"para": "If a supported linear unit is specified and the SRID is\n 0, an\n ER_GEOMETRY_IN_UNKNOWN_LENGTH_UNIT\n error occurs."
}
],
[
{
"para": "If a supported linear unit is specified and the SRID is\n not 0, the result is in that unit."
}
],
[
{
"para": "If a unit is not specified, the result is in the unit of\n the SRS of the geometries, whether Cartesian or\n geographic. Currently, all MySQL SRSs are expressed in\n meters."
}
]
]
},
{
"para": "A unit is supported if it is found in the\n INFORMATION_SCHEMA\n ST_UNITS_OF_MEASURE table. See\n ."
}
],
"id": "ST_Distance",
"syntax": []
},
{
"keywords": [
"ST_Equals"
],
"description": [
{
"para": "\n ST_Equals()\n \n\n ST_Equals(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether\n g1 is spatially equal to\n g2."
},
{
"para": "ST_Equals() handles its\n arguments as described in the introduction to this section,\n except that it does not return NULL for\n empty geometry arguments."
}
],
"id": "ST_Equals",
"syntax": []
},
{
"keywords": [
"ST_Intersects"
],
"description": [
{
"para": "\n ST_Intersects()\n \n\n ST_Intersects(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether\n g1 spatially intersects\n g2."
},
{
"para": "ST_Intersects() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Intersects",
"syntax": []
},
{
"keywords": [
"ST_Overlaps"
],
"description": [
{
"para": "\n ST_Overlaps()\n \n\n ST_Overlaps(g1,\n g2)"
},
{
"para": "Two geometries spatially overlap if\n they intersect and their intersection results in a geometry\n of the same dimension but not equal to either of the given\n geometries."
},
{
"para": "This function returns 1 or 0 to indicate whether\n g1 spatially overlaps\n g2."
},
{
"para": "ST_Overlaps() handles its\n arguments as described in the introduction to this section\n except that the return value is NULL for\n the additional condition that the dimensions of the two\n geometries are not equal."
}
],
"id": "ST_Overlaps",
"syntax": []
},
{
"keywords": [
"ST_Touches"
],
"description": [
{
"para": "\n ST_Touches()\n \n\n ST_Touches(g1,\n g2)"
},
{
"para": "Two geometries spatially touch if their\n interiors do not intersect, but the boundary of one of the\n geometries intersects either the boundary or the interior of\n the other."
},
{
"para": "This function returns 1 or 0 to indicate whether\n g1 spatially touches\n g2."
},
{
"para": "ST_Touches() handles its\n arguments as described in the introduction to this section\n except that the return value is NULL for\n the additional condition that both geometries are of\n dimension 0 (Point or\n MultiPoint)."
}
],
"id": "ST_Touches",
"syntax": []
},
{
"keywords": [
"ST_Within"
],
"description": [
{
"para": "\n ST_Within()\n \n\n ST_Within(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether\n g1 is spatially within\n g2. This tests the opposite\n relationship as\n ST_Contains()."
},
{
"para": "ST_Within() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Within",
"syntax": []
},
{
"keywords": [
"MBRContains"
],
"description": [
{
"para": "\n MBRContains()\n \n\n MBRContains(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangle of g1 contains the\n minimum bounding rectangle of g2.\n This tests the opposite relationship as\n MBRWithin()."
},
{
"para": "MBRContains() handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRContains",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n MBRCoveredBy()\n \n\n MBRCoveredBy(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangle of g1 is covered by the\n minimum bounding rectangle of g2.\n This tests the opposite relationship as\n MBRCovers()."
},
{
"para": "MBRCoveredBy() handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRCoveredBy",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n MBRCovers()\n \n\n MBRCovers(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangle of g1 covers the\n minimum bounding rectangle of g2.\n This tests the opposite relationship as\n MBRCoveredBy(). See the\n description of MBRCoveredBy()\n for examples."
},
{
"para": "MBRCovers() handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRCovers",
"syntax": []
},
{
"keywords": [
"MBRDisjoint"
],
"description": [
{
"para": "\n MBRDisjoint()\n \n\n MBRDisjoint(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangles of the two geometries\n g1 and\n g2 are disjoint (do not\n intersect)."
},
{
"para": "MBRDisjoint() handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRDisjoint",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "\n MBREquals()\n \n\n MBREquals(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangles of the two geometries\n g1 and\n g2 are the same."
},
{
"para": "MBREquals() handles its\n arguments as described in the introduction to this section,\n except that it does not return NULL for\n empty geometry arguments."
}
],
"id": "MBREquals",
"syntax": []
},
{
"keywords": [
"MBRIntersects"
],
"description": [
{
"para": "\n MBRIntersects()\n \n\n MBRIntersects(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangles of the two geometries\n g1 and\n g2 intersect."
},
{
"para": "MBRIntersects() handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRIntersects",
"syntax": []
},
{
"keywords": [
"MBROverlaps"
],
"description": [
{
"para": "\n MBROverlaps()\n \n\n MBROverlaps(g1,\n g2)"
},
{
"para": "Two geometries spatially overlap if\n they intersect and their intersection results in a geometry\n of the same dimension but not equal to either of the given\n geometries."
},
{
"para": "This function returns 1 or 0 to indicate whether the minimum\n bounding rectangles of the two geometries\n g1 and\n g2 overlap."
},
{
"para": "MBROverlaps() handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBROverlaps",
"syntax": []
},
{
"keywords": [
"MBRTouches"
],
"description": [
{
"para": "\n MBRTouches()\n \n\n MBRTouches(g1,\n g2)"
},
{
"para": "Two geometries spatially touch if their\n interiors do not intersect, but the boundary of one of the\n geometries intersects either the boundary or the interior of\n the other."
},
{
"para": "This function returns 1 or 0 to indicate whether the minimum\n bounding rectangles of the two geometries\n g1 and\n g2 touch."
},
{
"para": "MBRTouches() handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRTouches",
"syntax": []
},
{
"keywords": [
"MBRWithin"
],
"description": [
{
"para": "\n MBRWithin()\n \n\n MBRWithin(g1,\n g2)"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangle of g1 is within the\n minimum bounding rectangle of g2.\n This tests the opposite relationship as\n MBRContains()."
},
{
"para": "MBRWithin() handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRWithin",
"syntax": []
},
{
"keywords": [
"ST_GEOHASH"
],
"description": [
{
"para": "\n ST_GeoHash()\n \n\n ST_GeoHash(longitude,\n latitude,\n max_length),\n ST_GeoHash(point,\n max_length)"
},
{
"para": "Returns a geohash string in the connection character set and\n collation."
},
{
"para": "For the first syntax, the longitude\n must be a number in the range [minus180, 180], and the\n latitude must be a number in the\n range [minus90, 90]. For the second syntax, a\n POINT value is required, where the X and Y\n coordinates are in the valid ranges for longitude and\n latitude, respectively."
},
{
"para": "The resulting string is no longer than\n max_length characters, which has an\n upper limit of 100. The string might be shorter than\n max_length characters because the\n algorithm that creates the geohash value continues until it\n has created a string that is either an exact representation of\n the location or max_length\n characters, whichever comes first."
},
{
"para": "ST_GeoHash() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_GeoHash",
"syntax": []
},
{
"keywords": [
"ST_LATFROMGEOHASH"
],
"description": [
{
"para": "\n ST_LatFromGeoHash()\n \n\n ST_LatFromGeoHash(geohash_str)"
},
{
"para": "Returns the latitude from a geohash string value, as a\n double-precision number in the range [minus90, 90]."
},
{
"para": "The ST_LatFromGeoHash()\n decoding function reads no more than 433 characters from the\n geohash_str argument. That\n represents the upper limit on information in the internal\n representation of coordinate values. Characters past the 433rd\n are ignored, even if they are otherwise illegal and produce an\n error."
},
{
"para": "ST_LatFromGeoHash() handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_LatFromGeoHash",
"syntax": []
},
{
"keywords": [
"ST_LONGFROMGEOHASH"
],
"description": [
{
"para": "\n ST_LongFromGeoHash()\n \n\n ST_LongFromGeoHash(geohash_str)"
},
{
"para": "Returns the longitude from a geohash string value, as a\n double-precision number in the range [minus180, 180]."
},
{
"para": "The remarks in the description of\n ST_LatFromGeoHash() regarding\n the maximum number of characters processed from the\n geohash_str argument also apply to\n ST_LongFromGeoHash()."
},
{
"para": "ST_LongFromGeoHash() handles\n its arguments as described in the introduction to this\n section."
}
],
"id": "ST_LongFromGeoHash",
"syntax": []
},
{
"keywords": [
"ST_POINTFROMGEOHASH"
],
"description": [
{
"para": "\n ST_PointFromGeoHash()\n \n\n ST_PointFromGeoHash(geohash_str,\n srid)"
},
{
"para": "Returns a POINT value containing the\n decoded geohash value, given a geohash string value."
},
{
"para": "The X and Y coordinates of the point are the longitude in the\n range [minus180, 180] and the latitude in the range\n [minus90, 90], respectively."
},
{
"para": "The srid argument is an 32-bit\n unsigned integer."
},
{
"para": "The remarks in the description of\n ST_LatFromGeoHash() regarding\n the maximum number of characters processed from the\n geohash_str argument also apply to\n ST_PointFromGeoHash()."
},
{
"para": "ST_PointFromGeoHash() handles\n its arguments as described in the introduction to this\n section."
}
],
"id": "ST_PointFromGeoHash",
"syntax": []
},
{
"keywords": [
"ST_ASGEOJSON"
],
"description": [
{
"para": "\n ST_AsGeoJSON()\n \n\n ST_AsGeoJSON(g\n [, max_dec_digits [,\n options]])"
},
{
"para": "Generates a GeoJSON object from the geometry\n g. The object string has the\n connection character set and collation."
},
{
"para": "If any argument is NULL, the return value\n is NULL. If any non-NULL\n argument is invalid, an error occurs."
}
],
"id": "ST_AsGeoJSON",
"syntax": []
},
{
"keywords": [
"ST_GEOMFROMGEOJSON"
],
"description": [
{
"para": "\n ST_GeomFromGeoJSON()\n \n\n ST_GeomFromGeoJSON(str\n [, options [,\n srid]])"
},
{
"para": "Parses a string str representing a\n GeoJSON object and returns a geometry."
},
{
"para": "If any argument is NULL, the return value\n is NULL. If any non-NULL\n argument is invalid, an error occurs."
}
],
"id": "ST_GeomFromGeoJSON",
"syntax": []
},
{
"keywords": [
"ST_DISTANCE_SPHERE"
],
"description": [
{
"para": "\n ST_Distance_Sphere()\n \n\n ST_Distance_Sphere(g1,\n g2 [,\n radius])"
},
{
"para": "Returns the mimimum spherical distance between\n Point or MultiPoint\n arguments on a sphere, in meters. (For general-purpose\n distance calculations, see the\n ST_Distance() function.) The\n optional radius argument should be\n given in meters."
},
{
"para": "If both geometry parameters are valid Cartesian\n Point or MultiPoint\n values in SRID 0, the return value is shortest distance\n between the two geometries on a sphere with the provided\n radius. If omitted, the default radius is 6,370,986 meters,\n Point X and Y coordinates are interpreted as longitude and\n latitude, respectively, in degrees."
},
{
"para": "If both geometry parameters are valid Point\n or MultiPoint values in a geographic\n spatial reference system (SRS), the return value is the\n shortest distance between the two geometries on a sphere with\n the provided radius. If omitted, the default radius is equal\n to the mean radius, defined as (2a+b)/3, where a is the\n semi-major axis and b is the semi-minor axis of the SRS."
},
{
"para": "ST_Distance_Sphere() handles\n its arguments as described in the introduction to this\n section, with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "Supported geometry argument combinations are\n Point and Point, or\n Point and MultiPoint\n (in any argument order). If at least one of the geometries\n is neither Point nor\n MultiPoint, and its SRID is 0, an\n ER_NOT_IMPLEMENTED_FOR_CARTESIAN_SRS\n error occurs. If at least one of the geometries is neither\n Point nor\n MultiPoint, and its SRID refers to a\n geographic SRS, an\n ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS\n error occurs. If any geometry refers to a projected SRS,\n an\n ER_NOT_IMPLEMENTED_FOR_PROJECTED_SRS\n error occurs."
}
],
[
{
"para": "If any argument has a longitude or latitude that is out of\n range, an error occurs:"
},
{
"itemizedlist": [
[
{
"para": "If any longitude argument is not in the range\n (minus180, 180], an\n ER_LONGITUDE_OUT_OF_RANGE\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n ER_LATITUDE_OUT_OF_RANGE\n error occurs."
}
]
]
},
{
"para": "Ranges shown are in degrees. If an SRS uses another unit,\n the range uses the corresponding values in its unit. The\n exact range limits deviate slightly due to floating-point\n arithmetic."
}
],
[
{
"para": "If the radius argument is\n present but not positive, an\n ER_NONPOSITIVE_RADIUS\n error occurs."
}
],
[
{
"para": "If the distance exceeds the range of a double-precision\n number, an\n ER_STD_OVERFLOW_ERROR\n error occurs."
}
]
]
}
],
"id": "ST_Distance_Sphere",
"syntax": []
},
{
"keywords": [
"ST_ISVALID"
],
"description": [
{
"para": "\n ST_IsValid()\n \n\n ST_IsValid(g)"
},
{
"para": "Returns 1 if the argument is geometrically valid, 0 if the\n argument is not geometrically valid. Geometry validity is\n defined by the OGC specification."
},
{
"para": "The only valid empty geometry is represented in the form of an\n empty geometry collection value.\n ST_IsValid() returns 1 in this\n case. MySQL does not support GIS EMPTY\n values such as POINT EMPTY."
},
{
"para": "ST_IsValid() handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry has a geographic SRS with a longitude or\n latitude that is out of range, an error occurs:"
},
{
"itemizedlist": [
[
{
"para": "If any longitude argument is not in the range\n (minus180, 180], an\n ER_LONGITUDE_OUT_OF_RANGE\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n ER_LATITUDE_OUT_OF_RANGE\n error occurs."
}
]
]
},
{
"para": "Ranges shown are in degrees. If an SRS uses another unit,\n the range uses the corresponding values in its unit. The\n exact range limits deviate slightly due to floating-point\n arithmetic."
}
]
]
}
],
"id": "ST_IsValid",
"syntax": []
},
{
"keywords": [
"ST_MAKEENVELOPE"
],
"description": [
{
"para": "\n ST_MakeEnvelope()\n \n\n ST_MakeEnvelope(pt1,\n pt2)"
},
{
"para": "Returns the rectangle that forms the envelope around two\n points, as a Point,\n LineString, or Polygon."
},
{
"para": "Calculations are done using the Cartesian coordinate system\n rather than on a sphere, spheroid, or on earth."
},
{
"para": "Given two points pt1 and\n pt2,\n ST_MakeEnvelope() creates the\n result geometry on an abstract plane like this:"
},
{
"itemizedlist": [
[
{
"para": "If pt1 and\n pt2 are equal, the result is\n the point pt1."
}
],
[
{
"para": "Otherwise, if (pt1,\n pt2) is a vertical or\n horizontal line segment, the result is the line segment\n (pt1,\n pt2)."
}
],
[
{
"para": "Otherwise, the result is a polygon using\n pt1 and\n pt2 as diagonal points."
}
]
]
},
{
"para": "The result geometry has an SRID of 0."
},
{
"para": "ST_MakeEnvelope() handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "If the arguments are not Point values,\n an ER_WRONG_ARGUMENTS\n error occurs."
}
],
[
{
"para": "An ER_GIS_INVALID_DATA\n error occurs for the additional condition that any\n coordinate value of the two points is infinite or\n NaN."
}
],
[
{
"para": "If any geometry has an SRID value for a geographic spatial\n reference system (SRS), an\n ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS\n error occurs."
}
]
]
}
],
"id": "ST_MakeEnvelope",
"syntax": []
},
{
"keywords": [
"ST_SIMPLIFY"
],
"description": [
{
"para": "\n ST_Simplify()\n \n\n ST_Simplify(g,\n max_distance)"
},
{
"para": "Simplifies a geometry using the Douglas-Peucker algorithm and\n returns a simplified value of the same type."
},
{
"para": "The geometry may be any geometry type, although the\n Douglas-Peucker algorithm may not actually process every type.\n A geometry collection is processed by giving its components\n one by one to the simplification algorithm, and the returned\n geometries are put into a geometry collection as result."
},
{
"para": "The max_distance argument is the\n distance (in units of the input coordinates) of a vertex to\n other segments to be removed. Vertices within this distance of\n the simplified linestring are removed."
},
{
"para": "According to Boost.Geometry, geometries might become invalid\n as a result of the simplification process, and the process\n might create self-intersections. To check the validity of the\n result, pass it to\n ST_IsValid()."
},
{
"para": "ST_Simplify() handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "If the max_distance argument is\n not positive, or is NaN, an\n ER_WRONG_ARGUMENTS error\n occurs."
}
]
]
}
],
"id": "ST_Simplify",
"syntax": []
},
{
"keywords": [
"ST_VALIDATE"
],
"description": [
{
"para": "ST_Validate(g)"
},
{
"para": "Validates a geometry according to the OGC specification. A\n geometry can be syntactically well-formed (WKB value plus\n SRID) but geometrically invalid. For example, this polygon is\n geometrically invalid: POLYGON((0 0, 0 0, 0 0, 0 0, 0\n 0))"
},
{
"para": "ST_Validate() returns the\n geometry if it is syntactically well-formed and is\n geometrically valid, NULL if the argument\n is not syntactically well-formed or is not geometrically valid\n or is NULL."
},
{
"para": "ST_Validate() can be used to\n filter out invalid geometry data, although at a cost. For\n applications that require more precise results not tainted by\n invalid data, this penalty may be worthwhile."
},
{
"para": "If the geometry argument is valid, it is returned as is,\n except that if an input Polygon or\n MultiPolygon has clockwise rings, those\n rings are reversed before checking for validity. If the\n geometry is valid, the value with the reversed rings is\n returned."
},
{
"para": "The only valid empty geometry is represented in the form of an\n empty geometry collection value.\n ST_Validate() returns it\n directly without further checks in this case."
},
{
"para": "As of MySQL 8.0.13,\n ST_Validate() handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry has a geographic SRS with a longitude or\n latitude that is out of range, an error occurs:"
},
{
"itemizedlist": [
[
{
"para": "If any longitude argument is not in the range\n (minus180, 180], an\n ER_LONGITUDE_OUT_OF_RANGE\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n ER_LATITUDE_OUT_OF_RANGE\n error occurs."
}
]
]
},
{
"para": "Ranges shown are in degrees. The exact range limits\n deviate slightly due to floating-point arithmetic."
}
]
]
},
{
"para": "Prior to MySQL 8.0.13,\n ST_Validate() handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry is not syntactically well-formed, the\n return value is NULL. An\n ER_GIS_INVALID_DATA error\n does not occur."
}
],
[
{
"para": "If the geometry has an SRID value for a geographic spatial\n reference system (SRS), an\n ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS\n error occurs."
}
]
]
}
],
"id": "ST_Validate",
"syntax": []
},
{
"keywords": [
"BEGIN",
"END"
],
"description": [
{
"para": "BEGIN ... END\n syntax is used for writing compound statements, which can appear\n within stored programs (stored procedures and functions, triggers,\n and events). A compound statement can contain multiple statements,\n enclosed by the BEGIN and\n END keywords.\n statement_list represents a list of one\n or more statements, each terminated by a semicolon\n (;) statement delimiter. The\n statement_list itself is optional, so\n the empty compound statement (BEGIN END) is\n legal."
},
{
"para": "BEGIN ... END\n blocks can be nested."
},
{
"para": "Use of multiple statements requires that a client is able to send\n statement strings containing the ; statement\n delimiter. In the mysql command-line client,\n this is handled with the delimiter command.\n Changing the ; end-of-statement delimiter (for\n example, to //) permit ; to\n be used in a program body. For an example, see\n ."
},
{
"para": "A BEGIN ...\n END block can be labeled. See\n ."
}
],
"id": "BEGIN END",
"syntax": [
{
"programlisting": ">\n[begin_label:] BEGIN\n [statement_list]\nEND [end_label]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Labels are permitted for\n BEGIN ... END\n blocks and for the LOOP,\n REPEAT, and\n WHILE statements. Label use for\n those statements follows these rules:"
},
{
"itemizedlist": [
[
{
"para": "begin_label must be followed by a\n colon."
}
],
[
{
"para": "begin_label can be given without\n end_label. If\n end_label is present, it must be\n the same as begin_label."
}
],
[
{
"para": "end_label cannot be given without\n begin_label."
}
],
[
{
"para": "Labels at the same nesting level must be distinct."
}
],
[
{
"para": "Labels can be up to 16 characters long."
}
]
]
},
{
"para": "To refer to a label within the labeled construct, use an\n ITERATE or\n LEAVE statement. The following\n example uses those statements to continue iterating or terminate\n the loop:"
},
{
"programlisting": ">\nCREATE PROCEDURE doiterate(p1 INT)\nBEGIN\n label1: LOOP\n SET p1 = p1 + 1;\n IF p1 < 10 THEN ITERATE label1; END IF;\n LEAVE label1;\n END LOOP label1;\nEND;"
},
{
"para": "The scope of a block label does not include the code for handlers\n declared within the block. For details, see\n ."
}
],
"id": "labels",
"syntax": [
{
"programlisting": ">\n[begin_label:] BEGIN\n [statement_list]\nEND [end_label]\n\n[begin_label:] LOOP\n statement_list\nEND LOOP [end_label]\n\n[begin_label:] REPEAT\n statement_list\nUNTIL search_condition\nEND REPEAT [end_label]\n\n[begin_label:] WHILE search_condition DO\n statement_list\nEND WHILE [end_label]"
}
]
},
{
"keywords": [
"DECLARE",
"DEFAULT"
],
"description": [
{
"para": "This statement declares local variables within stored programs.\n To provide a default value for a variable, include a\n DEFAULT clause. The value can be specified as\n an expression; it need not be a constant. If the\n DEFAULT clause is missing, the initial value\n is NULL."
},
{
"para": "Local variables are treated like stored routine parameters with\n respect to data type and overflow checking. See\n ."
},
{
"para": "Variable declarations must appear before cursor or handler\n declarations."
},
{
"para": "Local variable names are not case-sensitive. Permissible\n characters and quoting rules are the same as for other\n identifiers, as described in ."
},
{
"para": "The scope of a local variable is the\n BEGIN ...\n END block within which it is declared. The variable\n can be referred to in blocks nested within the declaring block,\n except those blocks that declare a variable with the same name."
},
{
"para": "For examples of variable declarations, see\n ."
}
],
"id": "DECLARE variable",
"syntax": [
{
"programlisting": ">\nDECLARE var_name [, var_name] ... type [DEFAULT value]"
}
]
},
{
"keywords": [
"CASE",
"WHEN",
"THEN",
"ELSE",
"END"
],
"description": [
{
"para": "The CASE statement for stored\n programs implements a complex conditional construct."
},
{
"para": "For the first syntax, case_value is\n an expression. This value is compared to the\n when_value expression in each\n WHEN clause until one of them is equal. When\n an equal when_value is found, the\n corresponding THEN clause\n statement_list executes. If no\n when_value is equal, the\n ELSE clause\n statement_list executes, if there is\n one."
},
{
"para": "This syntax cannot be used to test for equality with\n NULL because NULL = NULL\n is false. See ."
},
{
"para": "For the second syntax, each WHEN clause\n search_condition expression is\n evaluated until one is true, at which point its corresponding\n THEN clause\n statement_list executes. If no\n search_condition is equal, the\n ELSE clause\n statement_list executes, if there is\n one."
},
{
"para": "If no when_value or\n search_condition matches the value\n tested and the CASE statement\n contains no ELSE clause, a Case\n not found for CASE statement error results."
},
{
"para": "Each statement_list consists of one\n or more SQL statements; an empty\n statement_list is not permitted."
},
{
"para": "To handle situations where no value is matched by any\n WHEN clause, use an ELSE\n containing an empty\n BEGIN ...\n END block, as shown in this example. (The indentation\n used here in the ELSE clause is for purposes\n of clarity only, and is not otherwise significant.)"
},
{
"programlisting": ">\nDELIMITER |\n\nCREATE PROCEDURE p()\n BEGIN\n DECLARE v INT DEFAULT 1;\n\n CASE v\n WHEN 2 THEN SELECT v;\n WHEN 3 THEN SELECT 0;\n ELSE\n BEGIN\n END;\n END CASE;\n END;\n |"
}
],
"id": "CASE statement",
"syntax": [
{
"programlisting": ">\nCASE case_value\n WHEN when_value THEN statement_list\n [WHEN when_value THEN statement_list] ...\n [ELSE statement_list]\nEND CASE"
},
{
"para": "Or:"
},
{
"programlisting": ">\nCASE\n WHEN search_condition THEN statement_list\n [WHEN search_condition THEN statement_list] ...\n [ELSE statement_list]\nEND CASE"
}
]
},
{
"keywords": [
"IF",
"THEN",
"ELSEIF",
"END"
],
"description": [
{
"para": "The IF statement for stored\n programs implements a basic conditional construct."
},
{
"para": "If a given search_condition evaluates\n to true, the corresponding THEN or\n ELSEIF clause\n statement_list executes. If no\n search_condition matches, the\n ELSE clause\n statement_list executes."
},
{
"para": "Each statement_list consists of one\n or more SQL statements; an empty\n statement_list is not permitted."
}
],
"id": "IF statement",
"syntax": [
{
"programlisting": ">\nIF search_condition THEN statement_list\n [ELSEIF search_condition THEN statement_list] ...\n [ELSE statement_list]\nEND IF"
}
]
},
{
"keywords": [
"ITERATE"
],
"description": [
{
"para": "ITERATE can appear only within\n LOOP,\n REPEAT, and\n WHILE statements.\n ITERATE means start the\n loop again."
}
],
"id": "ITERATE",
"syntax": [
{
"programlisting": ">\nITERATE label"
}
]
},
{
"keywords": [
"LEAVE"
],
"description": [
{
"para": "This statement is used to exit the flow control construct that\n has the given label. If the label is for the outermost stored\n program block, LEAVE exits the\n program."
},
{
"para": "LEAVE can be used within\n BEGIN ...\n END or loop constructs\n (LOOP,\n REPEAT,\n WHILE)."
}
],
"id": "LEAVE",
"syntax": [
{
"programlisting": ">\nLEAVE label"
}
]
},
{
"keywords": [
"LOOP",
"END"
],
"description": [
{
"para": "LOOP implements a simple loop\n construct, enabling repeated execution of the statement list,\n which consists of one or more statements, each terminated by a\n semicolon (;) statement delimiter. The\n statements within the loop are repeated until the loop is\n terminated. Usually, this is accomplished with a\n LEAVE statement. Within a stored\n function, RETURN can also be\n used, which exits the function entirely."
},
{
"para": "Neglecting to include a loop-termination statement results in an\n infinite loop."
},
{
"para": "A LOOP statement can be labeled.\n For the rules regarding label use, see\n ."
}
],
"id": "LOOP",
"syntax": [
{
"programlisting": ">\n[begin_label:] LOOP\n statement_list\nEND LOOP [end_label]"
}
]
},
{
"keywords": [
"REPEAT",
"UNTIL",
"END"
],
"description": [
{
"para": "The statement list within a\n REPEAT statement is repeated\n until the search_condition expression\n is true. Thus, a REPEAT always\n enters the loop at least once.\n statement_list consists of one or\n more statements, each terminated by a semicolon\n (;) statement delimiter."
},
{
"para": "A REPEAT statement can be\n labeled. For the rules regarding label use, see\n ."
}
],
"id": "REPEAT loop",
"syntax": [
{
"programlisting": ">\n[begin_label:] REPEAT\n statement_list\nUNTIL search_condition\nEND REPEAT [end_label]"
}
]
},
{
"keywords": [
"RETURN"
],
"description": [
{
"para": "The RETURN statement terminates\n execution of a stored function and returns the value\n expr to the function caller. There\n must be at least one RETURN\n statement in a stored function. There may be more than one if\n the function has multiple exit points."
},
{
"para": "This statement is not used in stored procedures, triggers, or\n events. The LEAVE statement can\n be used to exit a stored program of those types."
}
],
"id": "RETURN",
"syntax": [
{
"programlisting": ">\nRETURN expr"
}
]
},
{
"keywords": [
"WHILE",
"DO",
"END"
],
"description": [
{
"para": "The statement list within a WHILE\n statement is repeated as long as the\n search_condition expression is true.\n statement_list consists of one or\n more SQL statements, each terminated by a semicolon\n (;) statement delimiter."
},
{
"para": "A WHILE statement can be labeled.\n For the rules regarding label use, see\n ."
}
],
"id": "WHILE",
"syntax": [
{
"programlisting": ">\n[begin_label:] WHILE search_condition DO\n statement_list\nEND WHILE [end_label]"
}
]
},
{
"keywords": [
"CLOSE"
],
"description": [
{
"para": "This statement closes a previously opened cursor. For an\n example, see ."
},
{
"para": "An error occurs if the cursor is not open."
},
{
"para": "If not closed explicitly, a cursor is closed at the end of the\n BEGIN ...\n END block in which it was declared."
}
],
"id": "CLOSE",
"syntax": [
{
"programlisting": ">\nCLOSE cursor_name"
}
]
},
{
"keywords": [
"DECLARE",
"CURSOR",
"FOR"
],
"description": [
{
"para": "This statement declares a cursor and associates it with a\n SELECT statement that retrieves\n the rows to be traversed by the cursor. To fetch the rows later,\n use a FETCH statement. The number\n of columns retrieved by the\n SELECT statement must match the\n number of output variables specified in the\n FETCH statement."
},
{
"para": "The SELECT statement cannot have\n an INTO clause."
},
{
"para": "Cursor declarations must appear before handler declarations and\n after variable and condition declarations."
},
{
"para": "A stored program may contain multiple cursor declarations, but\n each cursor declared in a given block must have a unique name.\n For an example, see ."
},
{
"para": "For information available through\n SHOW statements, it is possible\n in many cases to obtain equivalent information by using a cursor\n with an INFORMATION_SCHEMA table."
}
],
"id": "DECLARE CURSOR",
"syntax": [
{
"programlisting": ">\nDECLARE cursor_name CURSOR FOR select_statement"
}
]
},
{
"keywords": [
"FETCH"
],
"description": [
{
"para": "This statement fetches the next row for the\n SELECT statement associated with\n the specified cursor (which must be open), and advances the\n cursor pointer. If a row exists, the fetched columns are stored\n in the named variables. The number of columns retrieved by the\n SELECT statement must match the\n number of output variables specified in the\n FETCH statement."
},
{
"para": "If no more rows are available, a No Data condition occurs with\n SQLSTATE value '02000'. To detect this\n condition, you can set up a handler for it (or for a\n NOT FOUND condition). For an example, see\n ."
},
{
"para": "Be aware that another operation, such as a\n SELECT or another FETCH,\n may also cause the handler to execute by raising the same\n condition. If it is necessary to distinguish which operation\n raised the condition, place the operation within its own\n BEGIN ...\n END block so that it can be associated with its own\n handler."
}
],
"id": "FETCH",
"syntax": [
{
"programlisting": ">\nFETCH [[NEXT] FROM] cursor_name INTO var_name [, var_name] ..."
}
]
},
{
"keywords": [
"OPEN"
],
"description": [
{
"para": "This statement opens a previously declared cursor. For an\n example, see ."
}
],
"id": "OPEN",
"syntax": [
{
"programlisting": ">\nOPEN cursor_name"
}
]
},
{
"keywords": [
"DECLARE",
"CONDITION",
"FOR"
],
"description": [
{
"para": "The DECLARE\n ... CONDITION statement declares a named error\n condition, associating a name with a condition that needs\n specific handling. The name can be referred to in a subsequent\n DECLARE ...\n HANDLER statement (see\n )."
},
{
"para": "Condition declarations must appear before cursor or handler\n declarations."
},
{
"para": "The condition_value for\n DECLARE ...\n CONDITION indicates the specific condition or class of\n conditions to associate with the condition name. It can take the\n following forms:"
},
{
"itemizedlist": [
[
{
"para": "mysql_error_code: An integer\n literal indicating a MySQL error code."
},
{
"para": "Do not use MySQL error code 0 because that indicates success\n rather than an error condition. For a list of MySQL error\n codes, see ."
}
],
[
{
"para": "SQLSTATE [VALUE] sqlstate_value:\n A 5-character string literal indicating an SQLSTATE value."
},
{
"para": "Do not use SQLSTATE values that begin with\n '00' because those indicate success\n rather than an error condition. For a list of SQLSTATE\n values, see ."
}
]
]
},
{
"para": "Condition names referred to in\n SIGNAL or use\n RESIGNAL statements must be\n associated with SQLSTATE values, not MySQL error codes."
}
],
"id": "DECLARE CONDITION",
"syntax": [
{
"programlisting": ">\nDECLARE condition_name CONDITION FOR condition_value\n\ncondition_value: {\n mysql_error_code\n | SQLSTATE [VALUE] sqlstate_value\n}"
}
]
},
{
"keywords": [
"DECLARE",
"HANDLER",
"FOR",
"CONTINUE",
"EXIT",
"UNDO"
],
"description": [
{
"para": "The DECLARE ...\n HANDLER statement specifies a handler that deals with\n one or more conditions. If one of these conditions occurs, the\n specified statement executes.\n statement can be a simple statement\n such as SET var_name =\n value, or a compound\n statement written using BEGIN and\n END (see )."
},
{
"para": "Handler declarations must appear after variable or condition\n declarations."
},
{
"para": "The handler_action value indicates\n what action the handler takes after execution of the handler\n statement:"
},
{
"itemizedlist": [
[
{
"para": "CONTINUE: Execution of the current\n program continues."
}
],
[
{
"para": "EXIT: Execution terminates for the\n BEGIN ...\n END compound statement in which the handler is\n declared. This is true even if the condition occurs in an\n inner block."
}
],
[
{
"para": "UNDO: Not supported."
}
]
]
},
{
"para": "The condition_value for\n DECLARE ...\n HANDLER indicates the specific condition or class of\n conditions that activates the handler. It can take the following\n forms:"
},
{
"itemizedlist": [
[
{
"para": "mysql_error_code: An integer\n literal indicating a MySQL error code, such as 1051 to\n specify unknown table:"
},
{
"programlisting": ">\nDECLARE CONTINUE HANDLER FOR 1051\n BEGIN\n -- body of handler\n END;"
},
{
"para": "Do not use MySQL error code 0 because that indicates success\n rather than an error condition. For a list of MySQL error\n codes, see ."
}
],
[
{
"para": "SQLSTATE [VALUE] sqlstate_value:\n A 5-character string literal indicating an SQLSTATE value,\n such as '42S01' to specify unknown\n table:"
},
{
"programlisting": ">\nDECLARE CONTINUE HANDLER FOR SQLSTATE '42S02'\n BEGIN\n -- body of handler\n END;"
},
{
"para": "Do not use SQLSTATE values that begin with\n '00' because those indicate success\n rather than an error condition. For a list of SQLSTATE\n values, see ."
}
],
[
{
"para": "condition_name: A condition name\n previously specified with\n DECLARE\n ... CONDITION. A condition name can be associated\n with a MySQL error code or SQLSTATE value. See\n ."
}
],
[
{
"para": "SQLWARNING: Shorthand for the class of\n SQLSTATE values that begin with '01'."
},
{
"programlisting": ">\nDECLARE CONTINUE HANDLER FOR SQLWARNING\n BEGIN\n -- body of handler\n END;"
}
],
[
{
"para": "NOT FOUND: Shorthand for the class of\n SQLSTATE values that begin with '02'.\n This is relevant within the context of cursors and is used\n to control what happens when a cursor reaches the end of a\n data set. If no more rows are available, a No Data condition\n occurs with SQLSTATE value '02000'. To\n detect this condition, you can set up a handler for it or\n for a NOT FOUND condition."
},
{
"programlisting": ">\nDECLARE CONTINUE HANDLER FOR NOT FOUND\n BEGIN\n -- body of handler\n END;"
},
{
"para": "For another example, see . The\n NOT FOUND condition also occurs for\n SELECT ... INTO\n var_list statements\n that retrieve no rows."
}
],
[
{
"para": "SQLEXCEPTION: Shorthand for the class of\n SQLSTATE values that do not begin with\n '00', '01', or\n '02'."
},
{
"programlisting": ">\nDECLARE CONTINUE HANDLER FOR SQLEXCEPTION\n BEGIN\n -- body of handler\n END;"
}
]
]
},
{
"para": "For information about how the server chooses handlers when a\n condition occurs, see ."
},
{
"para": "If a condition occurs for which no handler has been declared,\n the action taken depends on the condition class:"
},
{
"itemizedlist": [
[
{
"para": "For SQLEXCEPTION conditions, the stored\n program terminates at the statement that raised the\n condition, as if there were an EXIT\n handler. If the program was called by another stored\n program, the calling program handles the condition using the\n handler selection rules applied to its own handlers."
}
],
[
{
"para": "For SQLWARNING conditions, the program\n continues executing, as if there were a\n CONTINUE handler."
}
],
[
{
"para": "For NOT FOUND conditions, if the\n condition was raised normally, the action is\n CONTINUE. If it was raised by\n SIGNAL or\n RESIGNAL, the action is\n EXIT."
}
]
]
}
],
"id": "DECLARE HANDLER",
"syntax": [
{
"programlisting": ">\nDECLARE handler_action HANDLER\n FOR condition_value [, condition_value] ...\n statement\n\nhandler_action: {\n CONTINUE\n | EXIT\n | UNDO\n}\n\ncondition_value: {\n mysql_error_code\n | SQLSTATE [VALUE] sqlstate_value\n | condition_name\n | SQLWARNING\n | NOT FOUND\n | SQLEXCEPTION\n}"
}
]
},
{
"keywords": [
"GET",
"DIAGNOSTICS",
"NUMBER",
"ROW_COUNT",
"CLASS_ORIGIN",
"SUBCLASS_ORIGIN",
"CONSTRAINT_CATALOG",
"CONSTRAINT_SCHEMA",
"CONSTRAINT_NAME",
"CATALOG_NAME",
"SCHEMA_NAME",
"TABLE_NAME",
"COLUMN_NAME",
"CURSOR_NAME",
"MESSAGE_TEXT",
"MYSQL_ERRNO",
"RETURNED_SQLSTATE"
],
"description": [
{
"para": "SQL statements produce diagnostic information that populates the\n diagnostics area. The GET\n DIAGNOSTICS statement enables applications to inspect\n this information. (You can also use SHOW\n WARNINGS or SHOW ERRORS\n to see conditions or errors.)"
},
{
"para": "No special privileges are required to execute\n GET DIAGNOSTICS."
},
{
"para": "The keyword CURRENT means to retrieve\n information from the current diagnostics area. The keyword\n STACKED means to retrieve information from\n the second diagnostics area, which is available only if the\n current context is a condition handler. If neither keyword is\n given, the default is to use the current diagnostics area."
},
{
"para": "The GET DIAGNOSTICS statement is\n typically used in a handler within a stored program. It is a\n MySQL extension that\n GET [CURRENT]\n DIAGNOSTICS is permitted outside handler context to\n check the execution of any SQL statement. For example, if you\n invoke the mysql client program, you can\n enter these statements at the prompt:"
},
{
"programlisting": ">\nmysql> DROP TABLE test.no_such_table;\nERROR 1051 (42S02): Unknown table 'test.no_such_table'\nmysql> GET DIAGNOSTICS CONDITION 1\n @p1 = RETURNED_SQLSTATE, @p2 = MESSAGE_TEXT;\nmysql> SELECT @p1, @p2;\n+-------+------------------------------------+\n| @p1 | @p2 |\n+-------+------------------------------------+\n| 42S02 | Unknown table 'test.no_such_table' |\n+-------+------------------------------------+"
},
{
"para": "This extension applies only to the current diagnostics area. It\n does not apply to the second diagnostics area because\n GET STACKED DIAGNOSTICS is permitted only if\n the current context is a condition handler. If that is not the\n case, a GET STACKED DIAGNOSTICS when handler not\n active error occurs."
},
{
"para": "For a description of the diagnostics area, see\n . Briefly, it contains two\n kinds of information:"
},
{
"itemizedlist": [
[
{
"para": "Statement information, such as the number of conditions that\n occurred or the affected-rows count."
}
],
[
{
"para": "Condition information, such as the error code and message.\n If a statement raises multiple conditions, this part of the\n diagnostics area has a condition area for each one. If a\n statement raises no conditions, this part of the diagnostics\n area is empty."
}
]
]
},
{
"para": "For a statement that produces three conditions, the diagnostics\n area contains statement and condition information like this:"
},
{
"programlisting": ">\nStatement information:\n row count\n ... other statement information items ...\nCondition area list:\n Condition area 1:\n error code for condition 1\n error message for condition 1\n ... other condition information items ...\n Condition area 2:\n error code for condition 2:\n error message for condition 2\n ... other condition information items ...\n Condition area 3:\n error code for condition 3\n error message for condition 3\n ... other condition information items ..."
},
{
"para": "GET DIAGNOSTICS can obtain either\n statement or condition information, but not both in the same\n statement:"
},
{
"itemizedlist": [
[
{
"para": "To obtain statement information, retrieve the desired\n statement items into target variables. This instance of\n GET DIAGNOSTICS assigns the\n number of available conditions and the rows-affected count\n to the user variables @p1 and\n @p2:"
},
{
"programlisting": ">\nGET DIAGNOSTICS @p1 = NUMBER, @p2 = ROW_COUNT;"
}
],
[
{
"para": "To obtain condition information, specify the condition\n number and retrieve the desired condition items into target\n variables. This instance of GET\n DIAGNOSTICS assigns the SQLSTATE value and error\n message to the user variables @p3 and\n @p4:"
},
{
"programlisting": ">\nGET DIAGNOSTICS CONDITION 1\n @p3 = RETURNED_SQLSTATE, @p4 = MESSAGE_TEXT;"
}
]
]
},
{
"para": "The retrieval list specifies one or more\n target =\n item_name assignments,\n separated by commas. Each assignment names a target variable and\n either a\n statement_information_item_name or\n condition_information_item_name\n designator, depending on whether the statement retrieves\n statement or condition information."
},
{
"para": "Valid target designators for storing\n item information can be stored procedure or function parameters,\n stored program local variables declared with\n DECLARE, or user-defined\n variables."
},
{
"para": "Valid condition_number designators\n can be stored procedure or function parameters, stored program\n local variables declared with\n DECLARE, user-defined variables,\n system variables, or literals. A character literal may include a\n _charset introducer. A warning occurs\n if the condition number is not in the range from 1 to the number\n of condition areas that have information. In this case, the\n warning is added to the diagnostics area without clearing it."
},
{
"para": "When a condition occurs, MySQL does not populate all condition\n items recognized by GET\n DIAGNOSTICS. For example:"
},
{
"programlisting": ">\nmysql> GET DIAGNOSTICS CONDITION 1\n @p5 = SCHEMA_NAME, @p6 = TABLE_NAME;\nmysql> SELECT @p5, @p6;\n+------+------+\n| @p5 | @p6 |\n+------+------+\n| | |\n+------+------+"
},
{
"para": "In standard SQL, if there are multiple conditions, the first\n condition relates to the SQLSTATE value\n returned for the previous SQL statement. In MySQL, this is not\n guaranteed. To get the main error, you cannot do this:"
},
{
"programlisting": ">\nGET DIAGNOSTICS CONDITION 1 @errno = MYSQL_ERRNO;"
},
{
"para": "Instead, retrieve the condition count first, then use it to\n specify which condition number to inspect:"
},
{
"programlisting": ">\nGET DIAGNOSTICS @cno = NUMBER;\nGET DIAGNOSTICS CONDITION @cno @errno = MYSQL_ERRNO;"
},
{
"para": "For information about permissible statement and condition\n information items, and which ones are populated when a condition\n occurs, see\n ."
},
{
"para": "Here is an example that uses GET\n DIAGNOSTICS and an exception handler in stored\n procedure context to assess the outcome of an insert operation.\n If the insert was successful, the procedure uses\n GET DIAGNOSTICS to get the\n rows-affected count. This shows that you can use\n GET DIAGNOSTICS multiple times to\n retrieve information about a statement as long as the current\n diagnostics area has not been cleared."
},
{
"programlisting": ">\nCREATE PROCEDURE do_insert(value INT)\nBEGIN\n -- Declare variables to hold diagnostics area information\n DECLARE code CHAR(5) DEFAULT '00000';\n DECLARE msg TEXT;\n DECLARE rows INT;\n DECLARE result TEXT;\n -- Declare exception handler for failed insert\n DECLARE CONTINUE HANDLER FOR SQLEXCEPTION\n BEGIN\n GET DIAGNOSTICS CONDITION 1\n code = RETURNED_SQLSTATE, msg = MESSAGE_TEXT;\n END;\n\n -- Perform the insert\n INSERT INTO t1 (int_col) VALUES(value);\n -- Check whether the insert was successful\n IF code = '00000' THEN\n GET DIAGNOSTICS rows = ROW_COUNT;\n SET result = CONCAT('insert succeeded, row count = ',rows);\n ELSE\n SET result = CONCAT('insert failed, error = ',code,', message = ',msg);\n END IF;\n -- Say what happened\n SELECT result;\nEND;"
},
{
"para": "Suppose that t1.int_col is an integer column\n that is declared as NOT NULL. The procedure\n produces these results when invoked to insert\n non-NULL and NULL values,\n respectively:"
},
{
"programlisting": ">\nmysql> CALL do_insert(1);\n+---------------------------------+\n| result |\n+---------------------------------+\n| insert succeeded, row count = 1 |\n+---------------------------------+\n\nmysql> CALL do_insert(NULL);\n+-------------------------------------------------------------------------+\n| result |\n+-------------------------------------------------------------------------+\n| insert failed, error = 23000, message = Column 'int_col' cannot be null |\n+-------------------------------------------------------------------------+"
}
],
"id": "GET DIAGNOSTICS",
"syntax": [
{
"programlisting": ">\nGET [CURRENT | STACKED] DIAGNOSTICS\n{\n statement_information_item\n [, statement_information_item] ...\n | CONDITION condition_number\n condition_information_item\n [, condition_information_item] ...\n}\n\nstatement_information_item:\n target = statement_information_item_name\n\ncondition_information_item:\n target = condition_information_item_name\n\nstatement_information_item_name:\n NUMBER\n | ROW_COUNT\n\ncondition_information_item_name: {\n CLASS_ORIGIN\n | SUBCLASS_ORIGIN\n | RETURNED_SQLSTATE\n | MESSAGE_TEXT\n | MYSQL_ERRNO\n | CONSTRAINT_CATALOG\n | CONSTRAINT_SCHEMA\n | CONSTRAINT_NAME\n | CATALOG_NAME\n | SCHEMA_NAME\n | TABLE_NAME\n | COLUMN_NAME\n | CURSOR_NAME\n}\n\ncondition_number, target:\n (see following discussion)"
}
]
},
{
"keywords": [
"RESIGNAL",
"SET",
"SQLSTATE",
"VALUE",
"CLASS_ORIGIN",
"SUBCLASS_ORIGIN",
"CONSTRAINT_CATALOG",
"CONSTRAINT_SCHEMA",
"CONSTRAINT_NAME",
"CATALOG_NAME",
"SCHEMA_NAME",
"TABLE_NAME",
"COLUMN_NAME",
"CURSOR_NAME",
"MESSAGE_TEXT",
"MYSQL_ERRNO"
],
"description": [
{
"para": "RESIGNAL passes on the error\n condition information that is available during execution of a\n condition handler within a compound statement inside a stored\n procedure or function, trigger, or event.\n RESIGNAL may change some or all\n information before passing it on.\n RESIGNAL is related to\n SIGNAL, but instead of\n originating a condition as SIGNAL\n does, RESIGNAL relays existing\n condition information, possibly after modifying it."
},
{
"para": "RESIGNAL makes it possible to\n both handle an error and return the error information.\n Otherwise, by executing an SQL statement within the handler,\n information that caused the handler's activation is destroyed.\n RESIGNAL also can make some\n procedures shorter if a given handler can handle part of a\n situation, then pass the condition up the line to\n another handler."
},
{
"para": "No privileges are required to execute the\n RESIGNAL statement."
},
{
"para": "All forms of RESIGNAL require\n that the current context be a condition handler. Otherwise,\n RESIGNAL is illegal and a\n RESIGNAL when handler not active error\n occurs."
},
{
"para": "To retrieve information from the diagnostics area, use the\n GET DIAGNOSTICS statement (see\n ). For information about the\n diagnostics area, see ."
}
],
"id": "RESIGNAL",
"syntax": [
{
"programlisting": ">\nRESIGNAL [condition_value]\n [SET signal_information_item\n [, signal_information_item] ...]\n\ncondition_value: {\n SQLSTATE [VALUE] sqlstate_value\n | condition_name\n}\n\nsignal_information_item:\n condition_information_item_name = simple_value_specification\n\ncondition_information_item_name: {\n CLASS_ORIGIN\n | SUBCLASS_ORIGIN\n | MESSAGE_TEXT\n | MYSQL_ERRNO\n | CONSTRAINT_CATALOG\n | CONSTRAINT_SCHEMA\n | CONSTRAINT_NAME\n | CATALOG_NAME\n | SCHEMA_NAME\n | TABLE_NAME\n | COLUMN_NAME\n | CURSOR_NAME\n}\n\ncondition_name, simple_value_specification:\n (see following discussion)"
}
]
},
{
"keywords": [
"SIGNAL",
"SET",
"SQLSTATE",
"VALUE",
"CLASS_ORIGIN",
"SUBCLASS_ORIGIN",
"CONSTRAINT_CATALOG",
"CONSTRAINT_SCHEMA",
"CONSTRAINT_NAME",
"CATALOG_NAME",
"SCHEMA_NAME",
"TABLE_NAME",
"COLUMN_NAME",
"CURSOR_NAME",
"MESSAGE_TEXT",
"MYSQL_ERRNO"
],
"description": [
{
"para": "SIGNAL is the way to\n return an error.\n SIGNAL provides error information\n to a handler, to an outer portion of the application, or to the\n client. Also, it provides control over the error's\n characteristics (error number, SQLSTATE\n value, message). Without SIGNAL,\n it is necessary to resort to workarounds such as deliberately\n referring to a nonexistent table to cause a routine to return an\n error."
},
{
"para": "No privileges are required to execute the\n SIGNAL statement."
},
{
"para": "To retrieve information from the diagnostics area, use the\n GET DIAGNOSTICS statement (see\n ). For information about the\n diagnostics area, see ."
}
],
"id": "SIGNAL",
"syntax": [
{
"programlisting": ">\nSIGNAL condition_value\n [SET signal_information_item\n [, signal_information_item] ...]\n\ncondition_value: {\n SQLSTATE [VALUE] sqlstate_value\n | condition_name\n}\n\nsignal_information_item:\n condition_information_item_name = simple_value_specification\n\ncondition_information_item_name: {\n CLASS_ORIGIN\n | SUBCLASS_ORIGIN\n | MESSAGE_TEXT\n | MYSQL_ERRNO\n | CONSTRAINT_CATALOG\n | CONSTRAINT_SCHEMA\n | CONSTRAINT_NAME\n | CATALOG_NAME\n | SCHEMA_NAME\n | TABLE_NAME\n | COLUMN_NAME\n | CURSOR_NAME\n}\n\ncondition_name, simple_value_specification:\n (see following discussion)"
}
]
},
{
"keywords": [
"ALTER",
"DATABASE",
"SCHEMA",
"DEFAULT",
"CHARACTER",
"SET",
"COLLATE",
"ENCRYPTION"
],
"description": [
{
"para": "ALTER DATABASE enables you to\n change the overall characteristics of a database. These\n characteristics are stored in the data dictionary. To use\n ALTER DATABASE, you need the\n ALTER privilege on the database.\n ALTER\n SCHEMA is a synonym for ALTER\n DATABASE."
},
{
"para": "The database name can be omitted from the first syntax, in which\n case the statement applies to the default database."
},
{
"para": "The CHARACTER SET clause changes the default\n database character set. The COLLATE clause\n changes the default database collation. ,\n discusses character set and collation names."
},
{
"para": "You can see what character sets and collations are available\n using, respectively, the SHOW CHARACTER\n SET and SHOW COLLATION\n statements. See , and\n , for more information."
},
{
"para": "If you change the default character set or collation for a\n database, stored routines that use the database defaults must be\n dropped and recreated so that they use the new defaults. (In a\n stored routine, variables with character data types use the\n database defaults if the character set or collation are not\n specified explicitly. See .)"
},
{
"para": "The DEFAULT ENCRYPTION clause, introduced in\n MySQL 8.0.16, defines the default database encryption, which is\n inherited by tables created in the database. Changing the default\n encryption of the database does not alter the encryption of\n existing tables associated with the schema. Only newly-created\n tables inherit the default database encryption. An ALTER\n DATABASE statement executed without a DEFAULT\n ENCRYPTION clause retains the existing default database\n encryption. If the\n table_encryption_privilege_check\n variable is enabled, the\n TABLE_ENCRYPTION_ADMIN privilege is\n required to specify a default encryption setting that differs from\n the default_table_encryption\n setting. For more information, see\n ."
}
],
"id": "ALTER DATABASE",
"syntax": [
{
"programlisting": ">\nALTER {DATABASE | SCHEMA} [db_name]\n alter_specification ...\n\nalter_specification:\n [DEFAULT] CHARACTER SET [=] charset_name\n | [DEFAULT] COLLATE [=] collation_name\n | DEFAULT ENCRYPTION [=] {'Y' | 'N'}"
}
]
},
{
"keywords": [
"ALTER",
"EVENT",
"DEFINER",
"CURRENT_USER",
"SCHEDULE",
"RENAME",
"COMPLETION",
"PRESERVE",
"ENABLE",
"DISABLE",
"ON",
"SLAVE",
"COMMENT",
"DO"
],
"description": [
{
"para": "The ALTER EVENT statement changes\n one or more of the characteristics of an existing event without\n the need to drop and recreate it. The syntax for each of the\n DEFINER, ON SCHEDULE,\n ON COMPLETION, COMMENT,\n ENABLE / DISABLE, and\n DO clauses is exactly the same as\n when used with CREATE EVENT. (See\n .)"
},
{
"para": "Any user can alter an event defined on a database for which that\n user has the EVENT privilege. When\n a user executes a successful ALTER\n EVENT statement, that user becomes the definer for the\n affected event."
},
{
"para": "ALTER EVENT works only with an\n existing event:"
},
{
"programlisting": ">\nmysql> ALTER EVENT no_such_event \n > ON SCHEDULE \n > EVERY '2:3' DAY_HOUR;\nERROR 1517 (HY000): Unknown event 'no_such_event'"
}
],
"id": "ALTER EVENT",
"syntax": [
{
"programlisting": ">\nALTER\n [DEFINER = user]\n EVENT event_name\n [ON SCHEDULE schedule]\n [ON COMPLETION [NOT] PRESERVE]\n [RENAME TO new_event_name]\n [ENABLE | DISABLE | DISABLE ON SLAVE]\n [COMMENT 'string']\n [DO event_body]"
}
]
},
{
"keywords": [
"ALTER",
"FUNCTION"
],
"description": [
{
"para": "This statement can be used to change the characteristics of a\n stored function. More than one change may be specified in an\n ALTER FUNCTION statement. However,\n you cannot change the parameters or body of a stored function\n using this statement; to make such changes, you must drop and\n re-create the function using DROP\n FUNCTION and CREATE\n FUNCTION."
},
{
"para": "You must have the ALTER ROUTINE\n privilege for the function. (That privilege is granted\n automatically to the function creator.) If binary logging is\n enabled, the ALTER FUNCTION\n statement might also require the\n SUPER privilege, as described in\n ."
}
],
"id": "ALTER FUNCTION",
"syntax": [
{
"programlisting": ">\nALTER FUNCTION func_name [characteristic ...]\n\ncharacteristic:\n COMMENT 'string'\n | LANGUAGE SQL\n | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }\n | SQL SECURITY { DEFINER | INVOKER }"
}
]
},
{
"keywords": [
"ALTER",
"INSTANCE"
],
"description": [
{
"para": "ALTER INSTANCE defines actions applicable to a\n MySQL server instance. The statement supports these actions:"
},
{
"itemizedlist": [
[
{
"para": "ALTER INSTANCE ROTATE INNODB MASTER KEY"
},
{
"para": "This action rotates the master encryption key used for\n InnoDB tablespace encryption. Key rotation\n requires the\n ENCRYPTION_KEY_ADMIN or\n SUPER privilege. To perform\n this action, a keyring plugin must be installed and\n configured. For instructions, see ."
},
{
"para": "ALTER INSTANCE ROTATE INNODB MASTER KEY\n supports concurrent DML. However, it cannot be run\n concurrently with\n CREATE TABLE ...\n ENCRYPTION or\n ALTER TABLE ...\n ENCRYPTION operations, and locks are taken to\n prevent conflicts that could arise from concurrent execution\n of these statements. If one of the conflicting statements is\n running, it must complete before another can proceed."
},
{
"para": "ALTER INSTANCE ROTATE INNODB MASTER KEY\n statements are written to the binary log so that they can be\n executed on replicated servers."
},
{
"para": "For additional ALTER INSTANCE ROTATE INNODB MASTER\n KEY usage information, see\n ."
}
],
[
{
"para": "ALTER INSTANCE ROTATE BINLOG MASTER KEY"
},
{
"para": "This action rotates the binary log master key used for binary\n log encryption. Key rotation for the binary log master key\n requires the\n BINLOG_ENCRYPTION_ADMIN or\n SUPER privilege. The statement\n cannot be used if the\n binlog_encryption system\n variable is set to OFF. To perform this\n action, a keyring plugin must be installed and configured. For\n instructions, see ."
},
{
"para": "ALTER INSTANCE ROTATE BINLOG MASTER KEY\n actions are not written to the binary log and are not executed\n on replication slaves. Binary log master key rotation can\n therefore be carried out in replication environments including\n a mix of MySQL versions. To schedule regular rotation of the\n binary log master key on all applicable master and slave\n servers, you can enable the MySQL Event Scheduler on each\n server and issue the ALTER INSTANCE ROTATE BINLOG\n MASTER KEY statement using a\n CREATE EVENT statement. If you\n rotate the binary log master key because you suspect that the\n current or any of the previous binary log master keys might\n have been compromised, issue the statement on every applicable\n master and slave server, which enables you to verify immediate\n compliance."
},
{
"para": "For additional ALTER INSTANCE ROTATE BINLOG MASTER\n KEY usage information, including what to do if the\n process does not complete correctly or is interrupted by an\n unexpected server halt, see\n ."
}
],
[
{
"para": "ALTER INSTANCE RELOAD TLS"
},
{
"para": "This action reconfigures the SSL context from the current\n values of the system variables that define the context. It\n also updates the status variables that reflect the active\n context values. This action requires the\n CONNECTION_ADMIN privilege."
},
{
"para": "By default, the RELOAD TLS action rolls\n back with an error and has no effect if the configuration\n values do not permit creation of a new SSL context. The\n previous context values continue to be used for new\n connections."
},
{
"para": "If the optional NO ROLLBACK ON ERROR clause\n is given and a new context cannot be created, rollback does\n not occur. Instead, a warning is generated and SSL is disabled\n for new connections."
},
{
"para": "ALTER INSTANCE RELOAD TLS statements are\n not written to the binary log (and thus are not replicated).\n SSL configuration is local and depends on local files not\n necessarily present on all servers involved."
},
{
"para": "For additional information about reconfiguring the SSL\n context, including which system and status variables are\n context-related, see\n ."
}
]
]
}
],
"id": "ALTER INSTANCE",
"syntax": [
{
"programlisting": ">\nALTER INSTANCE instance_action\n\ninstance_action: {\n ROTATE INNODB MASTER KEY\n | ROTATE BINLOG MASTER KEY\n | RELOAD TLS [NO ROLLBACK ON ERROR]\n}"
}
]
},
{
"keywords": [
"ALTER",
"LOGFILE",
"GROUP"
],
"description": [
{
"para": "This statement adds an UNDO file named\n 'file_name' to an existing log file\n group logfile_group. An\n ALTER LOGFILE GROUP statement has\n one and only one ADD UNDOFILE clause. No\n DROP UNDOFILE clause is currently supported."
},
{
"para": "The optional INITIAL_SIZE parameter sets the\n UNDO file's initial size in bytes; if not\n specified, the initial size defaults to 134217728 (128 MB). You\n may optionally follow size with a\n one-letter abbreviation for an order of magnitude, similar to\n those used in my.cnf. Generally, this is one\n of the letters M (megabytes) or\n G (gigabytes). (Bug #13116514, Bug #16104705,\n Bug #62858)"
},
{
"para": "On 32-bit systems, the maximum supported value for\n INITIAL_SIZE is 4294967296 (4 GB). (Bug #29186)"
},
{
"para": "The minimum allowed value for INITIAL_SIZE is\n 1048576 (1 MB). (Bug #29574)"
},
{
"para": "The ENGINE parameter (required) determines the\n storage engine which is used by this log file group, with\n engine_name being the name of the\n storage engine. Currently, the only accepted values for\n engine_name are\n NDBCLUSTER and\n NDB. The two values\n are equivalent."
}
],
"id": "ALTER LOGFILE GROUP",
"syntax": [
{
"programlisting": ">\nALTER LOGFILE GROUP logfile_group\n ADD UNDOFILE 'file_name'\n [INITIAL_SIZE [=] size]\n [WAIT]\n ENGINE [=] engine_name"
}
]
},
{
"keywords": [
"ALTER",
"PROCEDURE"
],
"description": [
{
"para": "This statement can be used to change the characteristics of a\n stored procedure. More than one change may be specified in an\n ALTER PROCEDURE statement. However,\n you cannot change the parameters or body of a stored procedure\n using this statement; to make such changes, you must drop and\n re-create the procedure using DROP\n PROCEDURE and CREATE\n PROCEDURE."
},
{
"para": "You must have the ALTER ROUTINE\n privilege for the procedure. By default, that privilege is granted\n automatically to the procedure creator. This behavior can be\n changed by disabling the\n automatic_sp_privileges system\n variable. See ."
}
],
"id": "ALTER PROCEDURE",
"syntax": [
{
"programlisting": ">\nALTER PROCEDURE proc_name [characteristic ...]\n\ncharacteristic:\n COMMENT 'string'\n | LANGUAGE SQL\n | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }\n | SQL SECURITY { DEFINER | INVOKER }"
}
]
},
{
"keywords": [
"ALTER",
"SERVER",
"OPTIONS"
],
"description": [
{
"para": "Alters the server information for\n server_name,\n adjusting any of the options permitted in the\n CREATE SERVER statement. The\n corresponding fields in the mysql.servers table\n are updated accordingly. This statement requires the\n SUPER privilege."
}
],
"id": "ALTER SERVER",
"syntax": [
{
"programlisting": ">\nALTER SERVER server_name\n OPTIONS (option [, option] ...)"
}
]
},
{
"keywords": [
"ALTER",
"TABLE",
"ADD",
"AFTER",
"ALGORITHM",
"AVG_ROW_LENGTH",
"BY",
"COLUMN",
"COLUMNS",
"FIRST",
"INDEX",
"PRIMARY",
"KEY",
"KEYS",
"UNIQUE",
"FULLTEXT",
"SPATIAL",
"CONSTRAINT",
"DROP",
"DISABLE",
"ENABLE",
"RENAME",
"ORDER",
"MODIFY",
"CHANGE",
"DEFAULT",
"SET",
"FOREIGN",
"ENGINE",
"TYPE",
"WITH",
"PARSER",
"DISCARD",
"IMPORT",
"TABLESPACE",
"PARTITION",
"PARTITIONING",
"COALESCE",
"REORGANIZE",
"ANALYZE",
"CHECK",
"OPTIMIZE",
"REBUILD",
"REPAIR",
"REMOVE",
"TRUNCATE",
"EXCHANGE",
"LOCK",
"UPGRADE",
"VISIBLE",
"INVISIBLE",
"COMPRESSION",
"ENCRYPTION",
"AUTO_INCREMENT",
"CHARACTER",
"CHECKSUM",
"COLLATE",
"COMMENT",
"CONNECTION",
"DATA",
"DIRECTORY",
"DELAY_KEY_WRITE",
"INSERT_METHOD",
"KEY_BLOCK_SIZE",
"MAX_ROWS",
"MIN_ROWS",
"PACK_KEYS",
"PASSWORD",
"ROW_FORMAT",
"STATS_AUTO_RECALC",
"STATS_PERSISTENT",
"STATS_SAMPLE_PAGES",
"UNION"
],
"description": [
{
"para": "ALTER TABLE changes the structure\n of a table. For example, you can add or delete columns, create or\n destroy indexes, change the type of existing columns, or rename\n columns or the table itself. You can also change characteristics\n such as the storage engine used for the table or the table\n comment."
},
{
"itemizedlist": [
[
{
"para": "To use ALTER TABLE, you need\n ALTER,\n CREATE, and\n INSERT privileges for the\n table. Renaming a table requires\n ALTER and\n DROP on the old table,\n ALTER,\n CREATE, and\n INSERT on the new table."
}
],
[
{
"para": "Following the table name, specify the alterations to be made.\n If none are given, ALTER TABLE\n does nothing."
}
],
[
{
"para": "The syntax for many of the permissible alterations is similar\n to clauses of the CREATE TABLE\n statement. column_definition\n clauses use the same syntax for ADD and\n CHANGE as for CREATE\n TABLE. For more information, see\n ."
}
],
[
{
"para": "The word COLUMN is optional and can be\n omitted, except for RENAME COLUMN (to\n distinguish a column-renaming operation from the\n RENAME table-renaming operation)."
}
],
[
{
"para": "Multiple ADD, ALTER,\n DROP, and CHANGE clauses\n are permitted in a single ALTER\n TABLE statement, separated by commas. This is a\n MySQL extension to standard SQL, which permits only one of\n each clause per ALTER TABLE\n statement. For example, to drop multiple columns in a single\n statement, do this:"
},
{
"programlisting": ">\nALTER TABLE t2 DROP COLUMN c, DROP COLUMN d;"
}
],
[
{
"para": "If a storage engine does not support an attempted\n ALTER TABLE operation, a\n warning may result. Such warnings can be displayed with\n SHOW WARNINGS. See\n . For information on\n troubleshooting ALTER TABLE,\n see ."
}
],
[
{
"para": "For information about generated columns, see\n ."
}
],
[
{
"para": "For usage examples, see\n ."
}
],
[
{
"para": "InnoDB in MySQL 8.0.17 and later supports\n addition of multi-valued indexes on JSON columns using a\n key_part specification can take the\n form (CAST json_path AS\n type ARRAY). See\n , for detailed\n information regarding multi-valued index creation and usage\n of, as well as restrictions and limitations on multi-valued\n indexes."
}
],
[
{
"para": "With the mysql_info() C API\n function, you can find out how many rows were copied by\n ALTER TABLE. See\n ."
},
{
"indexterm": "mysql_info()"
}
]
]
}
],
"id": "ALTER TABLE",
"syntax": [
{
"programlisting": ">\nALTER TABLE tbl_name\n [alter_specification [, alter_specification] ...]\n [partition_options]\n\nalter_specification:\n table_options\n | ADD [COLUMN] col_namecolumn_definition\n [FIRST | AFTER col_name]\n | ADD [COLUMN] (col_namecolumn_definition,...)\n | ADD {INDEX|KEY} [index_name]\n [index_type] (key_part,...) [index_option] ...\n | ADD {FULLTEXT|SPATIAL} [INDEX|KEY] [index_name]\n (key_part,...) [index_option] ...\n | ADD [CONSTRAINT [symbol]] PRIMARY KEY\n [index_type] (key_part,...)\n [index_option] ...\n | ADD [CONSTRAINT [symbol]] UNIQUE [INDEX|KEY]\n [index_name] [index_type] (key_part,...)\n [index_option] ...\n | ADD [CONSTRAINT [symbol]] FOREIGN KEY\n [index_name] (col_name,...)\n reference_definition\n | ADD [CONSTRAINT [symbol]] CHECK (expr) [[NOT] ENFORCED]\n | DROP {CHECK|CONSTRAINT} symbol\n | ALTER {CHECK|CONSTRAINT} symbol [NOT] ENFORCED\n | ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}\n | ALTER [COLUMN] col_name\n {SET DEFAULT {literal | (expr)} | DROP DEFAULT}\n | ALTER INDEX index_name {VISIBLE | INVISIBLE}\n | CHANGE [COLUMN] old_col_namenew_col_namecolumn_definition\n [FIRST|AFTER col_name]\n | [DEFAULT] CHARACTER SET [=] charset_name [COLLATE [=] collation_name]\n | CONVERT TO CHARACTER SET charset_name [COLLATE collation_name]\n | {DISABLE|ENABLE} KEYS\n | {DISCARD|IMPORT} TABLESPACE\n | DROP [COLUMN] col_name\n | DROP {INDEX|KEY} index_name\n | DROP PRIMARY KEY\n | DROP FOREIGN KEY fk_symbol\n | FORCE\n | LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}\n | MODIFY [COLUMN] col_namecolumn_definition\n [FIRST | AFTER col_name]\n | ORDER BY col_name [, col_name] ...\n | RENAME COLUMN old_col_name TO new_col_name\n | RENAME {INDEX|KEY} old_index_name TO new_index_name\n | RENAME [TO|AS] new_tbl_name\n | {WITHOUT|WITH} VALIDATION\n\npartition_options:\n partition_option [partition_option] ...\n\npartition_option:\n ADD PARTITION (partition_definition)\n | DROP PARTITION partition_names\n | DISCARD PARTITION {partition_names | ALL} TABLESPACE\n | IMPORT PARTITION {partition_names | ALL} TABLESPACE\n | TRUNCATE PARTITION {partition_names | ALL}\n | COALESCE PARTITION number\n | REORGANIZE PARTITION partition_names INTO (partition_definitions)\n | EXCHANGE PARTITION partition_name WITH TABLE tbl_name [{WITH|WITHOUT} VALIDATION]\n | ANALYZE PARTITION {partition_names | ALL}\n | CHECK PARTITION {partition_names | ALL}\n | OPTIMIZE PARTITION {partition_names | ALL}\n | REBUILD PARTITION {partition_names | ALL}\n | REPAIR PARTITION {partition_names | ALL}\n | REMOVE PARTITIONING\n\nkey_part: {col_name [(length)] | (expr)} [ASC | DESC]\n\nindex_type:\n USING {BTREE | HASH}\n\nindex_option:\n KEY_BLOCK_SIZE [=] value\n | index_type\n | WITH PARSER parser_name\n | COMMENT 'string'\n | {VISIBLE | INVISIBLE}\n\ntable_options:\n table_option [[,] table_option] ...\n\ntable_option:\n AUTO_INCREMENT [=] value\n | AVG_ROW_LENGTH [=] value\n | [DEFAULT] CHARACTER SET [=] charset_name\n | CHECKSUM [=] {0 | 1}\n | [DEFAULT] COLLATE [=] collation_name\n | COMMENT [=] 'string'\n | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'}\n | CONNECTION [=] 'connect_string'\n | {DATA|INDEX} DIRECTORY [=] 'absolute path to directory'\n | DELAY_KEY_WRITE [=] {0 | 1}\n | ENCRYPTION [=] {'Y' | 'N'}\n | ENGINE [=] engine_name\n | INSERT_METHOD [=] { NO | FIRST | LAST }\n | KEY_BLOCK_SIZE [=] value\n | MAX_ROWS [=] value\n | MIN_ROWS [=] value\n | PACK_KEYS [=] {0 | 1 | DEFAULT}\n | PASSWORD [=] 'string'\n | ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT}\n | STATS_AUTO_RECALC [=] {DEFAULT|0|1}\n | STATS_PERSISTENT [=] {DEFAULT|0|1}\n | STATS_SAMPLE_PAGES [=] value\n | TABLESPACE tablespace_name [STORAGE {DISK|MEMORY}]\n | UNION [=] (tbl_name[,tbl_name]...)\n\npartition_options:\n (see CREATE TABLE options)"
}
]
},
{
"keywords": [
"ALTER",
"UNDO",
"TABLESPACE",
"ADD",
"DROP",
"DATAFILE",
"INITIAL_SIZE",
"WAIT",
"RENAME",
"TO",
"ENGINE"
],
"description": [
{
"para": "This statement is used with NDB and\n InnoDB tablespaces. It can be used to add a new\n data file to, or to drop a data file from an\n NDB tablespace. It can also be used to rename\n an NDB Cluster Disk Data tablespace, rename an\n InnoDB general tablespace, encrypt an\n InnoDB general tablespace, or mark an\n InnoDB undo tablespace as active or inactive."
},
{
"para": "The UNDO keyword, introduced in MySQL 8.0.14,\n is used with the SET {ACTIVE|INACTIVE} clause\n to mark an InnoDB undo tablespace as active or\n inactive. For more information, see\n ."
},
{
"para": "The ADD DATAFILE variant enables you to specify\n an initial size for an NDB Disk Data tablespace\n using an INITIAL_SIZE clause, where\n size is measured in bytes; the default\n value is 134217728 (128 MB). You may optionally follow\n size with a one-letter abbreviation for\n an order of magnitude, similar to those used in\n my.cnf. Generally, this is one of the letters\n M (megabytes) or G\n (gigabytes)."
},
{
"para": "On 32-bit systems, the maximum supported value for\n INITIAL_SIZE is 4294967296 (4 GB). (Bug #29186)"
},
{
"para": "INITIAL_SIZE is rounded, explicitly, as for\n CREATE TABLESPACE."
},
{
"para": "Once a data file has been created, its size cannot be changed;\n however, you can add more data files to an NDB tablespace using\n additional ALTER TABLESPACE ... ADD DATAFILE\n statements."
},
{
"para": "When ALTER TABLESPACE ... ADD DATAFILE is used\n with ENGINE = NDB, a data file is created on\n each Cluster data node, but only one row is generated in the\n INFORMATION_SCHEMA.FILES table. See\n the description of this table, as well as\n , for more\n information. ADD DATAFILE is not supported with\n InnoDB tablespaces."
},
{
"para": "Using DROP DATAFILE with\n ALTER TABLESPACE drops the data\n file 'file_name' from an NDB\n tablespace. You cannot drop a data file from a tablespace which is\n in use by any table; in other words, the data file must be empty\n (no extents used). See\n . In addition,\n any data file to be dropped must previously have been added to the\n tablespace with CREATE TABLESPACE\n or ALTER TABLESPACE. DROP\n DATAFILE is not supported with InnoDB\n tablespaces."
},
{
"para": "WAIT is parsed but otherwise ignored. It is\n intended for future expansion."
},
{
"para": "The ENGINE clause, which specifies the storage\n engine used by the tablespace, is deprecated and will be removed\n in a future release. The tablespace storage engine is known by the\n data dictionary, making the ENGINE clause\n obsolete. If the storage engine is specified, it must match the\n tablespace storage engine defined in the data dictionary. The only\n values for engine_name compatible with\n NDB tablespaces are\n NDB and NDBCLUSTER."
},
{
"para": "RENAME TO operations are implicitly performed\n in autocommit mode, regardless of\n the autocommit setting."
},
{
"para": "A RENAME TO operation cannot be performed while\n LOCK TABLES or\n FLUSH TABLES WITH READ\n LOCK is in effect for tables that reside in the\n tablespace."
},
{
"para": "Exclusive metadata locks\n are taken on tables that reside in a general tablespace while the\n tablespace is renamed, which prevents concurrent DDL. Concurrent\n DML is supported."
},
{
"para": "The CREATE TABLESPACE privilege is\n required to rename an InnoDB general\n tablespace."
},
{
"para": "The ENCRYPTION clause enables or disables\n page-level data encryption for an InnoDB\n general tablespace or the mysql system\n tablespace. Encryption support for general tablespaces was\n introduced in MySQL 8.0.13. Encryption support for the\n mysql system tablespace was introduced in MySQL\n 8.0.16."
},
{
"para": "A keyring plugin must be installed and configured before\n encryption can be enabled."
},
{
"para": "As of MySQL 8.0.16, if the\n table_encryption_privilege_check\n variable is enabled, the\n TABLE_ENCRYPTION_ADMIN privilege is\n required to alter a general tablespace with an\n ENCRYPTION clause setting that differs from the\n default_table_encryption setting."
},
{
"para": "Enabling encryption for a general tablespace fails if any table in\n the tablespace belongs to a schema defined with\n DEFAULT\n ENCRYPTION='N'. Similarly, disabling encryption fails if\n any table in the general tablespace belongs to a schema defined\n with DEFAULT\n ENCRYPTION='Y'. The\n DEFAULT\n ENCRYPTION schema option was introduced in MySQL 8.0.16."
},
{
"para": "If an ALTER TABLESPACE statement\n executed on a general tablespace does not include an\n ENCRYPTION clause, the tablespace retains its\n current encryption status, regardless of the\n default_table_encryption setting."
},
{
"para": "When a general tablespace or the mysql system\n tablespace is encrypted, all tables residing in the tablespace are\n encrypted. Likewise, a table created in an encrypted tablespace is\n encrypted."
},
{
"para": "The INPLACE algorithm is used when altering the\n ENCRYPTION attribute of a general tablespace or\n the mysql system tablespace. The\n INPLACE algorithm permits concurrent DML on\n tables that reside in the tablespace. Concurrent DDL is blocked."
},
{
"para": "For more information, see\n ."
}
],
"id": "ALTER TABLESPACE",
"syntax": [
{
"programlisting": ">\nALTER [UNDO] TABLESPACE tablespace_name\n NDB only: \n {ADD|DROP} DATAFILE 'file_name'\n [INITIAL_SIZE [=] size]\n [WAIT]\n InnoDB and NDB:\n [RENAME TO tablespace_name] \n InnoDB only:\n [SET {ACTIVE|INACTIVE}]\n [ENCRYPTION [=] {'Y' | 'N'}]\n InnoDB and NDB:\n [ENGINE [=] engine_name]"
}
]
},
{
"keywords": [
"ALTER",
"VIEW"
],
"description": [
{
"para": "This statement changes the definition of a view, which must exist.\n The syntax is similar to that for CREATE\n VIEW see ). This statement\n requires the CREATE VIEW and\n DROP privileges for the view, and\n some privilege for each column referred to in the\n SELECT statement.\n ALTER VIEW is permitted only to the\n definer or users with the\n SET_USER_ID or\n SUPER privilege."
}
],
"id": "ALTER VIEW",
"syntax": [
{
"programlisting": ">\nALTER\n [ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}]\n [DEFINER = user]\n [SQL SECURITY { DEFINER | INVOKER }]\n VIEW view_name [(column_list)]\n AS select_statement\n [WITH [CASCADED | LOCAL] CHECK OPTION]"
}
]
},
{
"keywords": [
"CREATE",
"DATABASE",
"SCHEMA",
"IF",
"EXISTS",
"NOT",
"DEFAULT",
"CHARACTER",
"SET",
"COLLATE",
"ENCRYPTION"
],
"description": [
{
"para": "CREATE DATABASE creates a database\n with the given name. To use this statement, you need the\n CREATE privilege for the database.\n CREATE\n SCHEMA is a synonym for CREATE\n DATABASE."
}
],
"id": "CREATE DATABASE",
"syntax": [
{
"programlisting": ">\nCREATE {DATABASE | SCHEMA} [IF NOT EXISTS] db_name\n [create_specification] ...\n\ncreate_specification:\n [DEFAULT] CHARACTER SET [=] charset_name\n | [DEFAULT] COLLATE [=] collation_name\n | DEFAULT ENCRYPTION [=] {'Y' | 'N'}"
}
]
},
{
"keywords": [
"CREATE",
"EVENT",
"DEFINER",
"CURRENT_USER",
"IF",
"NOT",
"EXISTS",
"SCHEDULE",
"COMPLETION",
"PRESERVE",
"ENABLE",
"DISABLE",
"ON",
"SLAVE",
"COMMENT",
"DO",
"AT",
"INTERVAL",
"EVERY",
"STARTS",
"ENDS"
],
"description": [
{
"para": "This statement creates and schedules a new event. The event will\n not run unless the Event Scheduler is enabled. For information\n about checking Event Scheduler status and enabling it if\n necessary, see ."
},
{
"para": "CREATE EVENT requires the\n EVENT privilege for the schema in\n which the event is to be created. If the\n DEFINER clause is present, the privileges\n required depend on the user value, as\n discussed in ."
},
{
"para": "The minimum requirements for a valid CREATE\n EVENT statement are as follows:"
},
{
"itemizedlist": [
[
{
"para": "The keywords CREATE EVENT plus\n an event name, which uniquely identifies the event in a\n database schema."
}
],
[
{
"para": "An ON SCHEDULE clause, which determines\n when and how often the event executes."
}
],
[
{
"para": "A DO clause, which contains the\n SQL statement to be executed by an event."
}
]
]
},
{
"para": "This is an example of a minimal CREATE\n EVENT statement:"
},
{
"programlisting": ">\nCREATE EVENT myevent\n ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 HOUR\n DO\n UPDATE myschema.mytable SET mycol = mycol + 1;"
},
{
"para": "The previous statement creates an event named\n myevent. This event executes oncemdashone\n hour following its creationmdashby running an SQL statement that\n increments the value of the myschema.mytable\n table's mycol column by 1."
},
{
"para": "The event_name must be a valid MySQL\n identifier with a maximum length of 64 characters. Event names are\n not case-sensitive, so you cannot have two events named\n myevent and MyEvent in the\n same schema. In general, the rules governing event names are the\n same as those for names of stored routines. See\n ."
},
{
"para": "An event is associated with a schema. If no schema is indicated as\n part of event_name, the default\n (current) schema is assumed. To create an event in a specific\n schema, qualify the event name with a schema using\n schema_name.event_name\n syntax."
}
],
"id": "CREATE EVENT",
"syntax": [
{
"programlisting": ">\nCREATE\n [DEFINER = user]\n EVENT\n [IF NOT EXISTS]\n event_name\n ON SCHEDULE schedule\n [ON COMPLETION [NOT] PRESERVE]\n [ENABLE | DISABLE | DISABLE ON SLAVE]\n [COMMENT 'string']\n DO event_body;\n\nschedule:\n AT timestamp [+ INTERVAL interval] ...\n | EVERY interval\n [STARTS timestamp [+ INTERVAL interval] ...]\n [ENDS timestamp [+ INTERVAL interval] ...]\n\ninterval:\n quantity {YEAR | QUARTER | MONTH | DAY | HOUR | MINUTE |\n WEEK | SECOND | YEAR_MONTH | DAY_HOUR | DAY_MINUTE |\n DAY_SECOND | HOUR_MINUTE | HOUR_SECOND | MINUTE_SECOND}"
}
]
},
{
"keywords": [
"BTREE",
"INDEX",
"CREATE",
"FULLTEXT",
"SPATIAL",
"WITH",
"PARSER",
"COMMENT",
"VISIBLE",
"INVISIBLE"
],
"description": [
{
"para": "Normally, you create all indexes on a table at the time the table\n itself is created with CREATE\n TABLE. See . This\n guideline is especially important for\n InnoDB tables, where the primary key\n determines the physical layout of rows in the data file.\n CREATE INDEX enables you to add\n indexes to existing tables."
},
{
"para": "CREATE INDEX is mapped to an\n ALTER TABLE statement to create\n indexes. See .\n CREATE INDEX cannot be used to\n create a PRIMARY KEY; use\n ALTER TABLE instead. For more\n information about indexes, see ."
}
],
"id": "CREATE INDEX",
"syntax": [
{
"programlisting": ">\nCREATE [UNIQUE | FULLTEXT | SPATIAL] INDEX index_name\n [index_type]\n ON tbl_name (key_part,...)\n [index_option]\n [algorithm_option | lock_option] ...\n\nkey_part: {col_name [(length)] | (expr)} [ASC | DESC]\n\nindex_option:\n KEY_BLOCK_SIZE [=] value\n | index_type\n | WITH PARSER parser_name\n | COMMENT 'string'\n | {VISIBLE | INVISIBLE}\n\nindex_type:\n USING {BTREE | HASH}\n\nalgorithm_option:\n ALGORITHM [=] {DEFAULT | INPLACE | COPY}\n\nlock_option:\n LOCK [=] {DEFAULT | NONE | SHARED | EXCLUSIVE}"
}
]
},
{
"keywords": [
"CREATE",
"LOGFILE",
"GROUP"
],
"description": [
{
"para": "This statement creates a new log file group named\n logfile_group having a single\n UNDO file named\n 'undo_file'. A\n CREATE LOGFILE GROUP statement has\n one and only one ADD UNDOFILE clause. For rules\n covering the naming of log file groups, see\n ."
},
{
"para": "There can be only one log file group per NDB Cluster instance at\n any given time."
},
{
"para": "The optional INITIAL_SIZE parameter sets the\n UNDO file's initial size; if not specified, it\n defaults to 128M (128 megabytes). The optional\n UNDO_BUFFER_SIZE parameter sets the size used\n by the UNDO buffer for the log file group; The\n default value for UNDO_BUFFER_SIZE is\n 8M (eight megabytes); this value cannot exceed\n the amount of system memory available. Both of these parameters\n are specified in bytes. You may optionally follow either or both\n of these with a one-letter abbreviation for an order of magnitude,\n similar to those used in my.cnf. Generally,\n this is one of the letters M (for megabytes)\n or G (for gigabytes)."
},
{
"para": "Memory used for UNDO_BUFFER_SIZE comes from the\n global pool whose size is determined by the value of the\n SharedGlobalMemory data\n node configuration parameter. This includes any default value\n implied for this option by the setting of the\n InitialLogFileGroup data\n node configuration parameter."
},
{
"para": "The maximum permitted for UNDO_BUFFER_SIZE is\n 629145600 (600 MB)."
},
{
"para": "On 32-bit systems, the maximum supported value for\n INITIAL_SIZE is 4294967296 (4 GB). (Bug #29186)"
},
{
"para": "The minimum allowed value for INITIAL_SIZE is\n 1048576 (1 MB)."
},
{
"para": "The ENGINE option determines the storage engine\n to be used by this log file group, with\n engine_name being the name of the\n storage engine. In MySQL current-series, this must be\n NDB (or\n NDBCLUSTER). If\n ENGINE is not set, MySQL tries to use the\n engine specified by the\n default_storage_engine server\n system variable (formerly\n storage_engine). In any case, if\n the engine is not specified as NDB or\n NDBCLUSTER, the CREATE\n LOGFILE GROUP statement appears to succeed but actually\n fails to create the log file group, as shown here:"
},
{
"programlisting": ">\nmysql> CREATE LOGFILE GROUP lg1\n -> ADD UNDOFILE 'undo.dat' INITIAL_SIZE = 10M;\nQuery OK, 0 rows affected, 1 warning (0.00 sec)\n\nmysql> SHOW WARNINGS;\n+-------+------+------------------------------------------------------------------------------------------------+\n| Level | Code | Message |\n+-------+------+------------------------------------------------------------------------------------------------+\n| Error | 1478 | Table storage engine 'InnoDB' does not support the create option 'TABLESPACE or LOGFILE GROUP' |\n+-------+------+------------------------------------------------------------------------------------------------+\n1 row in set (0.00 sec)\n\nmysql> DROP LOGFILE GROUP lg1 ENGINE = NDB; \nERROR 1529 (HY000): Failed to drop LOGFILE GROUP\n\nmysql> CREATE LOGFILE GROUP lg1\n -> ADD UNDOFILE 'undo.dat' INITIAL_SIZE = 10M\n -> ENGINE = NDB;\nQuery OK, 0 rows affected (2.97 sec)"
},
{
"para": "The fact that the CREATE LOGFILE GROUP\n statement does not actually return an error when a\n non-NDB storage engine is named, but rather\n appears to succeed, is a known issue which we hope to address in a\n future release of NDB Cluster."
},
{
"para": "REDO_BUFFER_SIZE,\n NODEGROUP, WAIT, and\n COMMENT are parsed but ignored, and so have no\n effect in MySQL current-series. These options are intended for\n future expansion."
},
{
"para": "When used with ENGINE [=] NDB, a log file group\n and associated UNDO log file are created on\n each Cluster data node. You can verify that the\n UNDO files were created and obtain information\n about them by querying the\n INFORMATION_SCHEMA.FILES table. For\n example:"
},
{
"programlisting": ">\nmysql> SELECT LOGFILE_GROUP_NAME, LOGFILE_GROUP_NUMBER, EXTRA\n -> FROM INFORMATION_SCHEMA.FILES\n -> WHERE FILE_NAME = 'undo_10.dat';\n+--------------------+----------------------+----------------+\n| LOGFILE_GROUP_NAME | LOGFILE_GROUP_NUMBER | EXTRA |\n+--------------------+----------------------+----------------+\n| lg_3 | 11 | CLUSTER_NODE=3 |\n| lg_3 | 11 | CLUSTER_NODE=4 |\n+--------------------+----------------------+----------------+\n2 rows in set (0.06 sec)"
},
{
"para": "CREATE LOGFILE GROUP is useful only\n with Disk Data storage for NDB Cluster. See\n ."
}
],
"id": "CREATE LOGFILE GROUP",
"syntax": [
{
"programlisting": ">\nCREATE LOGFILE GROUP logfile_group\n ADD UNDOFILE 'undo_file'\n [INITIAL_SIZE [=] initial_size]\n [UNDO_BUFFER_SIZE [=] undo_buffer_size]\n [REDO_BUFFER_SIZE [=] redo_buffer_size]\n [NODEGROUP [=] nodegroup_id]\n [WAIT]\n [COMMENT [=] 'string']\n ENGINE [=] engine_name"
}
]
},
{
"keywords": [
"CREATE",
"PROCEDURE",
"FUNCTION"
],
"description": [
{
"para": "These statements create stored routines. By default, a routine is\n associated with the default database. To associate the routine\n explicitly with a given database, specify the name as\n db_name.sp_name when you create it."
},
{
"para": "The CREATE FUNCTION statement is\n also used in MySQL to support UDFs (user-defined functions). See\n . A UDF can be regarded as an\n external stored function. Stored functions share their namespace\n with UDFs. See , for the\n rules describing how the server interprets references to different\n kinds of functions."
},
{
"para": "To invoke a stored procedure, use the\n CALL statement (see\n ). To invoke a stored function, refer to it\n in an expression. The function returns a value during expression\n evaluation."
},
{
"para": "CREATE PROCEDURE and\n CREATE FUNCTION require the\n CREATE ROUTINE privilege. If the\n DEFINER clause is present, the privileges\n required depend on the user value, as\n discussed in . If binary\n logging is enabled, CREATE FUNCTION\n might require the SUPER privilege,\n as discussed in ."
},
{
"para": "By default, MySQL automatically grants the\n ALTER ROUTINE and\n EXECUTE privileges to the routine\n creator. This behavior can be changed by disabling the\n automatic_sp_privileges system\n variable. See ."
},
{
"para": "The DEFINER and SQL SECURITY\n clauses specify the security context to be used when checking\n access privileges at routine execution time, as described later in\n this section."
},
{
"para": "If the routine name is the same as the name of a built-in SQL\n function, a syntax error occurs unless you use a space between the\n name and the following parenthesis when defining the routine or\n invoking it later. For this reason, avoid using the names of\n existing SQL functions for your own stored routines."
},
{
"para": "The IGNORE_SPACE SQL mode\n applies to built-in functions, not to stored routines. It is\n always permissible to have spaces after a stored routine name,\n regardless of whether\n IGNORE_SPACE is enabled."
},
{
"para": "The parameter list enclosed within parentheses must always be\n present. If there are no parameters, an empty parameter list of\n () should be used. Parameter names are not case\n sensitive."
},
{
"para": "Each parameter is an IN parameter by default.\n To specify otherwise for a parameter, use the keyword\n OUT or INOUT before the\n parameter name."
},
{
"para": "An IN parameter passes a value into a\n procedure. The procedure might modify the value, but the\n modification is not visible to the caller when the procedure\n returns. An OUT parameter passes a value from\n the procedure back to the caller. Its initial value is\n NULL within the procedure, and its value is\n visible to the caller when the procedure returns. An\n INOUT parameter is initialized by the caller,\n can be modified by the procedure, and any change made by the\n procedure is visible to the caller when the procedure returns."
},
{
"para": "For each OUT or INOUT\n parameter, pass a user-defined variable in the\n CALL statement that invokes the\n procedure so that you can obtain its value when the procedure\n returns. If you are calling the procedure from within another\n stored procedure or function, you can also pass a routine\n parameter or local routine variable as an OUT\n or INOUT parameter. If you are calling the\n procedure from within a trigger, you can also pass\n NEW.col_name as an\n OUT or INOUT parameter."
},
{
"para": "For information about the effect of unhandled conditions on\n procedure parameters, see\n ."
},
{
"para": "Routine parameters cannot be referenced in statements prepared\n within the routine; see\n ."
},
{
"para": "The following example shows a simple stored procedure that uses an\n OUT parameter:"
},
{
"programlisting": ">\nmysql> delimiter //\n\nmysql> CREATE PROCEDURE simpleproc (OUT param1 INT)\n -> BEGIN\n -> SELECT COUNT(*) INTO param1 FROM t;\n -> END//\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> delimiter ;\n\nmysql> CALL simpleproc(@a);\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> SELECT @a;\n+------+\n| @a |\n+------+\n| 3 |\n+------+\n1 row in set (0.00 sec)"
},
{
"para": "The example uses the mysql client\n delimiter command to change the statement\n delimiter from ; to // while\n the procedure is being defined. This enables the\n ; delimiter used in the procedure body to be\n passed through to the server rather than being interpreted by\n mysql itself. See\n ."
},
{
"para": "The RETURNS clause may be specified only for a\n FUNCTION, for which it is mandatory. It\n indicates the return type of the function, and the function body\n must contain a RETURN\n value statement. If the\n RETURN statement returns a value of\n a different type, the value is coerced to the proper type. For\n example, if a function specifies an\n ENUM or\n SET value in the\n RETURNS clause, but the\n RETURN statement returns an\n integer, the value returned from the function is the string for\n the corresponding ENUM member of\n set of SET members."
},
{
"para": "The following example function takes a parameter, performs an\n operation using an SQL function, and returns the result. In this\n case, it is unnecessary to use delimiter\n because the function definition contains no internal\n ; statement delimiters:"
},
{
"programlisting": ">\nmysql> CREATE FUNCTION hello (s CHAR(20))\nmysql> RETURNS CHAR(50) DETERMINISTIC\n -> RETURN CONCAT('Hello, ',s,'!');\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> SELECT hello('world');\n+----------------+\n| hello('world') |\n+----------------+\n| Hello, world! |\n+----------------+\n1 row in set (0.00 sec)"
},
{
"para": "Parameter types and function return types can be declared to use\n any valid data type. The COLLATE attribute can\n be used if preceded by a CHARACTER SET\n specification."
},
{
"para": "The routine_body consists of a valid\n SQL routine statement. This can be a simple statement such as\n SELECT or\n INSERT, or a compound statement\n written using BEGIN and END.\n Compound statements can contain declarations, loops, and other\n control structure statements. The syntax for these statements is\n described in . In\n practice, stored functions tend to use compound statements, unless\n the body consists of a single\n RETURN statement."
},
{
"para": "MySQL permits routines to contain DDL statements, such as\n CREATE and DROP. MySQL also\n permits stored procedures (but not stored functions) to contain\n SQL transaction statements such as\n COMMIT. Stored functions may not\n contain statements that perform explicit or implicit commit or\n rollback. Support for these statements is not required by the SQL\n standard, which states that each DBMS vendor may decide whether to\n permit them."
},
{
"para": "Statements that return a result set can be used within a stored\n procedure but not within a stored function. This prohibition\n includes SELECT statements that do\n not have an INTO\n var_list clause and other\n statements such as SHOW,\n EXPLAIN, and\n CHECK TABLE. For statements that\n can be determined at function definition time to return a result\n set, a Not allowed to return a result set from a\n function error occurs\n (ER_SP_NO_RETSET). For statements\n that can be determined only at runtime to return a result set, a\n PROCEDURE %s can't return a result set in the given\n context error occurs\n (ER_SP_BADSELECT)."
},
{
"para": "USE statements within stored\n routines are not permitted. When a routine is invoked, an implicit\n USE db_name is\n performed (and undone when the routine terminates). The causes the\n routine to have the given default database while it executes.\n References to objects in databases other than the routine default\n database should be qualified with the appropriate database name."
},
{
"para": "For additional information about statements that are not permitted\n in stored routines, see\n ."
},
{
"para": "For information about invoking stored procedures from within\n programs written in a language that has a MySQL interface, see\n ."
},
{
"para": "MySQL stores the sql_mode system\n variable setting in effect when a routine is created or altered,\n and always executes the routine with this setting in force,\n regardless of the current server SQL mode when the\n routine begins executing."
},
{
"para": "The switch from the SQL mode of the invoker to that of the routine\n occurs after evaluation of arguments and assignment of the\n resulting values to routine parameters. If you define a routine in\n strict SQL mode but invoke it in nonstrict mode, assignment of\n arguments to routine parameters does not take place in strict\n mode. If you require that expressions passed to a routine be\n assigned in strict SQL mode, you should invoke the routine with\n strict mode in effect."
}
],
"id": "CREATE PROCEDURE",
"syntax": [
{
"programlisting": ">\nCREATE\n [DEFINER = user]\n PROCEDURE sp_name ([proc_parameter[,...]])\n [characteristic ...] routine_body\n\nCREATE\n [DEFINER = user]\n FUNCTION sp_name ([func_parameter[,...]])\n RETURNS type\n [characteristic ...] routine_body\n\nproc_parameter:\n [ IN | OUT | INOUT ] param_nametype\n\nfunc_parameter:\n param_nametype\n\ntype:\n Any valid MySQL data type\n\ncharacteristic:\n COMMENT 'string'\n | LANGUAGE SQL\n | [NOT] DETERMINISTIC\n | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }\n | SQL SECURITY { DEFINER | INVOKER }\n\nroutine_body:\n Valid SQL routine statement"
}
]
},
{
"keywords": [
"CREATE",
"SERVER",
"DATA",
"WRAPPER",
"DATABASE",
"FOREIGN",
"HOST",
"OPTIONS",
"OWNER",
"PASSWORD",
"PORT",
"SOCKET",
"USER"
],
"description": [
{
"para": "This statement creates the definition of a server for use with the\n FEDERATED storage engine. The CREATE\n SERVER statement creates a new row in the\n servers table in the mysql\n database. This statement requires the\n SUPER privilege."
},
{
"para": "The server_name\n should be a unique reference to the server. Server definitions are\n global within the scope of the server, it is not possible to\n qualify the server definition to a specific database.\n server_name has a\n maximum length of 64 characters (names longer than 64 characters\n are silently truncated), and is case insensitive. You may specify\n the name as a quoted string."
},
{
"para": "The wrapper_name is\n an identifier and may be quoted with single quotation marks."
},
{
"para": "For each option you\n must specify either a character literal or numeric literal.\n Character literals are UTF-8, support a maximum length of 64\n characters and default to a blank (empty) string. String literals\n are silently truncated to 64 characters. Numeric literals must be\n a number between 0 and 9999, default value is 0."
},
{
"para": "The CREATE SERVER statement creates an entry in\n the mysql.servers table that can later be used\n with the CREATE TABLE statement\n when creating a FEDERATED table. The options\n that you specify will be used to populate the columns in the\n mysql.servers table. The table columns are\n Server_name, Host,\n Db, Username,\n Password, Port and\n Socket."
}
],
"id": "CREATE SERVER",
"syntax": [
{
"programlisting": ">\nCREATE SERVER server_name\n FOREIGN DATA WRAPPER wrapper_name\n OPTIONS (option [, option] ...)\n\noption:\n { HOST character-literal\n | DATABASE character-literal\n | USER character-literal\n | PASSWORD character-literal\n | SOCKET character-literal\n | OWNER character-literal\n | PORT numeric-literal }"
}
]
},
{
"keywords": [
"CREATE",
"SPATIAL",
"REFERENCE",
"SYSTEM",
"OR",
"REPLACE",
"IF",
"NOT",
"EXISTS",
"NAME",
"DEFINITION",
"ORGANIZATION",
"DESCRIPTION"
],
"description": [
{
"para": "This statement creates a\n spatial reference\n system (SRS) definition and stores it in the data\n dictionary. The definition can be inspected using the\n INFORMATION_SCHEMA\n ST_SPATIAL_REFERENCE_SYSTEMS table.\n This statement requires the SUPER\n privilege."
},
{
"para": "If neither OR REPLACE nor IF NOT\n EXISTS is specified, an error occurs if an SRS\n definition with the SRID value already exists."
},
{
"para": "With CREATE OR REPLACE syntax, any existing SRS\n definition with the same SRID value is replaced, unless the SRID\n value is used by some column in an existing table. In that case,\n an error occurs. For example:"
},
{
"programlisting": ">\nmysql> CREATE OR REPLACE SPATIAL REFERENCE SYSTEM 4326 ...;\nERROR 3716 (SR005): Can't modify SRID 4326. There is at\nleast one column depending on it."
},
{
"para": "To identify which column or columns use the SRID, use this query:"
},
{
"programlisting": ">\nSELECT * FROM INFORMATION_SCHEMA.ST_GEOMETRY_COLUMNS WHERE SRS_ID=4326;"
},
{
"para": "With CREATE ... IF NOT EXISTS syntax, any\n existing SRS definition with the same SRID value causes the new\n definition to be ignored and a warning occurs."
}
],
"id": "CREATE SPATIAL REFERENCE SYSTEM",
"syntax": [
{
"programlisting": ">\nCREATE OR REPLACE SPATIAL REFERENCE SYSTEM\n sridsrs_attribute ...\n\nCREATE SPATIAL REFERENCE SYSTEM\n [IF NOT EXISTS]\n sridsrs_attribute ...\n\nsrs_attribute: {\n NAME 'srs_name'\n | DEFINITION 'definition'\n | ORGANIZATION 'org_name' IDENTIFIED BY org_id\n | DESCRIPTION 'description'\n}\n\nsrid, org_id: 32-bit unsigned integer"
}
]
},
{
"keywords": [
"FOREIGN",
"KEY",
"REFERENCES",
"NO",
"ACTION",
"ON",
"DELETE",
"CASCADE",
"SET",
"NULL",
"RESTRICT",
"UPDATE",
"DEFAULT"
],
"description": [
{
"para": "MySQL supports foreign keys, which permit cross-referencing\n related data across tables, and foreign key constraints, which\n help keep the related data consistent."
},
{
"para": "A foreign key relationship involves a parent table that holds\n the initial column values, and a child table with column values\n that reference the parent column values. A foreign key\n constraint is defined on the child table."
},
{
"para": "The essential syntax for a defining a foreign key constraint in\n a CREATE TABLE or\n ALTER TABLE statement includes\n the following:"
},
{
"programlisting": ">\n[CONSTRAINT [symbol]] FOREIGN KEY\n [index_name] (col_name, ...)\n REFERENCES tbl_name (col_name,...)\n [ON DELETE reference_option]\n [ON UPDATE reference_option]\n\nreference_option:\n RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT"
}
],
"id": "FOREIGN KEY",
"syntax": []
},
{
"keywords": [
"CREATE",
"TABLE",
"ENGINE",
"KEY",
"DATA",
"ACTION",
"ARCHIVE",
"AVG_ROW_LENGTH",
"BY",
"CASCADE",
"CHECK",
"CHECKSUM",
"COLUMNS",
"COMMENT",
"COMPACT",
"CONSTRAINT",
"COMPRESSED",
"CONNECTION",
"CSV",
"FEDERATED",
"FIXED",
"DYNAMIC",
"DEFAULT",
"DELAY_KEY_WRITE",
"DELETE",
"DIRECTORY",
"INDEX",
"FIRST",
"FOREIGN",
"ROW_FORMAT",
"FULL",
"FULLTEXT",
"HEAP",
"INNODB",
"INSERT_METHOD",
"KEY_BLOCK_SIZE",
"MAX_ROWS",
"MIN_ROWS",
"PACK_KEYS",
"PARTIAL",
"PARTITION",
"MERGE",
"MRG_MYISAM",
"MYISAM",
"NDB",
"NDBCLUSTER",
"NO",
"REDUNDANT",
"REFERENCES",
"SERIAL",
"WITH",
"PARSER",
"CHARACTER",
"SET",
"COLLATE",
"STATS_PERSISTENT",
"STATS_AUTO_RECALC",
"STATS_SAMPLE_PAGES",
"VISIBLE",
"INVISIBLE",
"COMPRESSION",
"ENCRYPTION",
"VIRTUAL",
"STORED"
],
"description": [
{
"para": "CREATE TABLE creates a table with\n the given name. You must have the\n CREATE privilege for the table."
},
{
"para": "By default, tables are created in the default database, using the\n InnoDB storage engine. An error\n occurs if the table exists, if there is no default database, or if\n the database does not exist."
},
{
"para": "MySQL has no limit on the number of tables. The underlying file\n system may have a limit on the number of files that represent\n tables. Individual storage engines may impose engine-specific\n constraints. InnoDB permits up to 4 billion\n tables."
},
{
"para": "For information about the physical representation of a table, see\n ."
}
],
"id": "CREATE TABLE",
"syntax": [
{
"programlisting": ">\nCREATE [TEMPORARY] TABLE [IF NOT EXISTS] tbl_name\n (create_definition,...)\n [table_options]\n [partition_options]\n\nCREATE [TEMPORARY] TABLE [IF NOT EXISTS] tbl_name\n [(create_definition,...)]\n [table_options]\n [partition_options]\n [IGNORE | REPLACE]\n [AS] query_expression\n\nCREATE [TEMPORARY] TABLE [IF NOT EXISTS] tbl_name\n { LIKE old_tbl_name | (LIKE old_tbl_name) }\n\ncreate_definition:\n col_namecolumn_definition\n | {INDEX|KEY} [index_name] [index_type] (key_part,...)\n [index_option] ...\n | {FULLTEXT|SPATIAL} [INDEX|KEY] [index_name] (key_part,...)\n [index_option] ...\n | [CONSTRAINT [symbol]] PRIMARY KEY\n [index_type] (key_part,...)\n [index_option] ...\n | [CONSTRAINT [symbol]] UNIQUE [INDEX|KEY]\n [index_name] [index_type] (key_part,...)\n [index_option] ...\n | [CONSTRAINT [symbol]] FOREIGN KEY\n [index_name] (col_name,...)\n reference_definition\n | check_constraint_definition\n\ncolumn_definition:\n data_type [NOT NULL | NULL] [DEFAULT {literal | (expr)} ]\n [AUTO_INCREMENT] [UNIQUE [KEY]] [[PRIMARY] KEY]\n [COMMENT 'string']\n [COLLATE collation_name]\n [COLUMN_FORMAT {FIXED|DYNAMIC|DEFAULT}]\n [STORAGE {DISK|MEMORY}]\n [reference_definition]\n [check_constraint_definition]\n | data_type\n [COLLATE collation_name]\n [GENERATED ALWAYS] AS (expr)\n [VIRTUAL | STORED] [NOT NULL | NULL]\n [UNIQUE [KEY]] [[PRIMARY] KEY]\n [COMMENT 'string']\n [reference_definition]\n [check_constraint_definition]\n\ndata_type:\n (see )\n\nkey_part: {col_name [(length)] | (expr)} [ASC | DESC]\n\nindex_type:\n USING {BTREE | HASH}\n\nindex_option:\n KEY_BLOCK_SIZE [=] value\n | index_type\n | WITH PARSER parser_name\n | COMMENT 'string'\n | {VISIBLE | INVISIBLE}\n\ncheck_constraint_definition:\n [CONSTRAINT [symbol]] CHECK (expr) [[NOT] ENFORCED]\n\nreference_definition:\n REFERENCES tbl_name (key_part,...)\n [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE]\n [ON DELETE reference_option]\n [ON UPDATE reference_option]\n\nreference_option:\n RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT\n\ntable_options:\n table_option [[,] table_option] ...\n\ntable_option:\n AUTO_INCREMENT [=] value\n | AVG_ROW_LENGTH [=] value\n | [DEFAULT] CHARACTER SET [=] charset_name\n | CHECKSUM [=] {0 | 1}\n | [DEFAULT] COLLATE [=] collation_name\n | COMMENT [=] 'string'\n | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'}\n | CONNECTION [=] 'connect_string'\n | {DATA|INDEX} DIRECTORY [=] 'absolute path to directory'\n | DELAY_KEY_WRITE [=] {0 | 1}\n | ENCRYPTION [=] {'Y' | 'N'}\n | ENGINE [=] engine_name\n | INSERT_METHOD [=] { NO | FIRST | LAST }\n | KEY_BLOCK_SIZE [=] value\n | MAX_ROWS [=] value\n | MIN_ROWS [=] value\n | PACK_KEYS [=] {0 | 1 | DEFAULT}\n | PASSWORD [=] 'string'\n | ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT}\n | STATS_AUTO_RECALC [=] {DEFAULT|0|1}\n | STATS_PERSISTENT [=] {DEFAULT|0|1}\n | STATS_SAMPLE_PAGES [=] value\n | TABLESPACE tablespace_name [STORAGE {DISK|MEMORY}]\n | UNION [=] (tbl_name[,tbl_name]...)\n\npartition_options:\n PARTITION BY\n { [LINEAR] HASH(expr)\n | [LINEAR] KEY [ALGORITHM={1|2}] (column_list)\n | RANGE{(expr) | COLUMNS(column_list)}\n | LIST{(expr) | COLUMNS(column_list)} }\n [PARTITIONS num]\n [SUBPARTITION BY\n { [LINEAR] HASH(expr)\n | [LINEAR] KEY [ALGORITHM={1|2}] (column_list) }\n [SUBPARTITIONS num]\n ]\n [(partition_definition [, partition_definition] ...)]\n\npartition_definition:\n PARTITION partition_name\n [VALUES\n {LESS THAN {(expr | value_list) | MAXVALUE}\n |\n IN (value_list)}]\n [[STORAGE] ENGINE [=] engine_name]\n [COMMENT [=] 'string' ]\n [DATA DIRECTORY [=] 'data_dir']\n [INDEX DIRECTORY [=] 'index_dir']\n [MAX_ROWS [=] max_number_of_rows]\n [MIN_ROWS [=] min_number_of_rows]\n [TABLESPACE [=] tablespace_name]\n [(subpartition_definition [, subpartition_definition] ...)]\n\nsubpartition_definition:\n SUBPARTITION logical_name\n [[STORAGE] ENGINE [=] engine_name]\n [COMMENT [=] 'string' ]\n [DATA DIRECTORY [=] 'data_dir']\n [INDEX DIRECTORY [=] 'index_dir']\n [MAX_ROWS [=] max_number_of_rows]\n [MIN_ROWS [=] min_number_of_rows]\n [TABLESPACE [=] tablespace_name]\n\nquery_expression:\n SELECT ... (Some valid select or union statement)"
}
]
},
{
"keywords": [
"CREATE",
"TABLESPACE",
"UNDO",
"ADD",
"DATAFILE",
"FILE_BLOCK_SIZE",
"USE",
"LOGFILE",
"GROUP",
"EXTENT_SIZE",
"INITIAL_SIZE",
"AUTOEXTEND_SIZE",
"MAX_SIZE",
"NODEGROUP",
"WAIT",
"COMMENT",
"ENGINE"
],
"description": [
{
"para": "This statement is used to create a tablespace. The precise syntax\n and semantics depend on the storage engine used. In standard MySQL\n releases, this is always an InnoDB\n tablespace. MySQL NDB Cluster also supports tablespaces using the\n NDB storage engine."
},
{
"para": "CREATE TABLESPACE syntax is used to\n create general tablespaces or undo tablespaces. The\n UNDO keyword, introduced in MySQL 8.0.14, must\n be specified to create an undo tablespace."
},
{
"para": "A general tablespace is a shared tablespace. It can hold multiple\n tables, and supports all table row formats. General tablespaces\n can be created in a location relative to or independent of the\n data directory."
},
{
"para": "After creating an InnoDB general tablespace,\n use CREATE TABLE\n tbl_name ... TABLESPACE [=]\n tablespace_name or\n ALTER TABLE\n tbl_name TABLESPACE [=]\n tablespace_name to add tables\n to the tablespace. For more information, see\n ."
},
{
"para": "Undo tablespaces contain undo logs. Undo tablespaces can be\n created in a chosen location by specifying a fully qualified data\n file path. For more information, see\n ."
},
{
"para": "This statement is used to create a tablespace, which can contain\n one or more data files, providing storage space for NDB Cluster\n Disk Data tables (see ).\n One data file is created and added to the tablespace using this\n statement. Additional data files may be added to the tablespace by\n using the ALTER TABLESPACE\n statement (see )."
},
{
"para": "A log file group of one or more UNDO log files\n must be assigned to the tablespace to be created with the\n USE LOGFILE GROUP clause.\n logfile_group must be an existing log\n file group created with CREATE LOGFILE\n GROUP (see ).\n Multiple tablespaces may use the same log file group for\n UNDO logging."
},
{
"para": "When setting EXTENT_SIZE or\n INITIAL_SIZE, you may optionally follow the\n number with a one-letter abbreviation for an order of magnitude,\n similar to those used in my.cnf. Generally,\n this is one of the letters M (for megabytes) or\n G (for gigabytes)."
},
{
"para": "INITIAL_SIZE and EXTENT_SIZE\n are subject to rounding as follows:"
},
{
"itemizedlist": [
[
{
"para": "EXTENT_SIZE is rounded up to the nearest\n whole multiple of 32K."
}
],
[
{
"para": "INITIAL_SIZE is rounded\n down to the nearest whole multiple of\n 32K; this result is rounded up to the nearest whole multiple\n of EXTENT_SIZE (after any rounding)."
}
]
]
},
{
"para": "The rounding just described is done explicitly, and a warning is\n issued by the MySQL Server when any such rounding is performed.\n The rounded values are also used by the NDB kernel for calculating\n INFORMATION_SCHEMA.FILES column\n values and other purposes. However, to avoid an unexpected result,\n we suggest that you always use whole multiples of 32K in\n specifying these options."
},
{
"para": "When CREATE TABLESPACE is used with\n ENGINE [=] NDB, a tablespace and associated\n data file are created on each Cluster data node. You can verify\n that the data files were created and obtain information about them\n by querying the\n INFORMATION_SCHEMA.FILES table. (See\n the example later in this section.)"
},
{
"para": "(See .)"
},
{
"itemizedlist": [
[
{
"para": "ADD DATAFILE: Defines the name of a\n tablespace data file. The ADD DATAFILE\n clause is required when creating undo tablespaces. Otherwise,\n it is optional as of MySQL 8.0.14."
},
{
"para": "An InnoDB tablespace supports only a single\n data file, whose name must include a .ibd\n extension. An NDB Cluster tablespace supports multiple data\n files which can have any legal file names; more data files can\n be added to an NDB Cluster tablespace following its creation\n by using an ALTER TABLESPACE\n statement."
},
{
"para": "To place a general tablespace data file in a location outside\n of the data directory, include a fully qualified path or a\n path relative to the data directory. Only a fully qualified\n path is permitted for undo tablespaces. If you do not specify\n a path, a general tablespace is created in the data directory.\n An undo tablespace created without specifying a path is\n created in the directory defined by the\n innodb_undo_directory\n variable. If the\n innodb_undo_directory\n variable is undefined, undo tablespaces are created in the\n data directory."
},
{
"para": "Creating a general tablespace in a subdirectory under the data\n directory is not supported to avoid conflicts with implicitly\n created file-per-table tablespaces. When creating a general\n tablespace or undo tablespace outside of the data directory,\n the directory must exist and must be known to\n InnoDB prior to creating the tablespace. To\n make a directory known to InnoDB, add it to\n the innodb_directories value\n or to one of the variables whose values are appended to the\n innodb_directories value.\n innodb_directories is a\n read-only variable. Configuring it requires restarting the\n server."
},
{
"para": "The file_name,\n including any specified path, must be quoted with single or\n double quotations marks. File names (not counting the file\n extension) and directory names must be at least one byte in\n length. Zero length file names and directory names are not\n supported."
},
{
"para": "If the ADD DATAFILE clause is not specified\n when creating a tablespace, a tablespace data file with a\n unique file name is created implicitly. The unique file name\n is a 128 bit UUID formatted into five groups of hexadecimal\n numbers separated by dashes\n (aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee).\n A file extension is added if required by the storage engine.\n An .ibd file extension is added for\n InnoDB general tablespace data files. In a\n replication environment, the data file name created on the\n master is not the same as the data file name created on the\n slave."
},
{
"para": "As of MySQL 8.0.17, the ADD DATAFILE clause\n does not permit circular directory references when creating an\n InnoDB tablespace. For example, the\n circular directory reference (/../) in the\n following statement is not permitted:"
},
{
"programlisting": ">\nCREATE TABLESPACE ts1 ADD DATAFILE ts1.ibd 'any_directory/../ts1.ibd';"
},
{
"para": "An exception to this restriction exists on Linux, where a\n circular directory reference is permitted if the preceding\n directory is a symbolic link. For example, the data file path\n in the example above is permitted if\n any_directory is a symbolic link.\n (It is still permitted for data file paths to begin with\n '../'.)"
}
],
[
{
"para": "FILE_BLOCK_SIZE: This optionmdashwhich is\n specific to InnoDB general tablespaces, and\n is ignored by NDBmdashdefines the block\n size for the tablespace data file. Values can be specified in\n bytes or kilobytes. For example, an 8 kilobyte file block size\n can be specified as 8192 or 8K. If you do not specify this\n option, FILE_BLOCK_SIZE defaults to the\n innodb_page_size value.\n FILE_BLOCK_SIZE is required when you intend\n to use the tablespace for storing compressed\n InnoDB tables\n (ROW_FORMAT=COMPRESSED). In this case, you\n must define the tablespace FILE_BLOCK_SIZE\n when creating the tablespace."
},
{
"para": "If FILE_BLOCK_SIZE is equal the\n innodb_page_size value, the\n tablespace can contain only tables having an uncompressed row\n format (COMPACT,\n REDUNDANT, and DYNAMIC).\n Tables with a COMPRESSED row format have a\n different physical page size than uncompressed tables.\n Therefore, compressed tables cannot coexist in the same\n tablespace as uncompressed tables."
},
{
"para": "For a general tablespace to contain compressed tables,\n FILE_BLOCK_SIZE must be specified, and the\n FILE_BLOCK_SIZE value must be a valid\n compressed page size in relation to the\n innodb_page_size value. Also,\n the physical page size of the compressed table\n (KEY_BLOCK_SIZE) must be equal to\n FILE_BLOCK_SIZE/1024. For example, if\n innodb_page_size=16K, and\n FILE_BLOCK_SIZE=8K, the\n KEY_BLOCK_SIZE of the table must be 8. For\n more information, see ."
}
],
[
{
"para": "USE LOGFILE GROUP: Required for\n NDB, this is the name of a log file group\n previously created using CREATE LOGFILE\n GROUP. Not supported for InnoDB,\n where it fails with an error."
}
],
[
{
"para": "EXTENT_SIZE: This option is specific to\n NDB, and is not supported by InnoDB, where it fails with an\n error. EXTENT_SIZE sets the size, in bytes,\n of the extents used by any files belonging to the tablespace.\n The default value is 1M. The minimum size is 32K, and\n theoretical maximum is 2G, although the practical maximum size\n depends on a number of factors. In most cases, changing the\n extent size does not have any measurable effect on\n performance, and the default value is recommended for all but\n the most unusual situations."
},
{
"para": "An extent is a unit of\n disk space allocation. One extent is filled with as much data\n as that extent can contain before another extent is used. In\n theory, up to 65,535 (64K) extents may used per data file;\n however, the recommended maximum is 32,768 (32K). The\n recommended maximum size for a single data file is\n 32Gmdashthat is, 32K extents times 1 MB per extent. In\n addition, once an extent is allocated to a given partition, it\n cannot be used to store data from a different partition; an\n extent cannot store data from more than one partition. This\n means, for example that a tablespace having a single datafile\n whose INITIAL_SIZE (described in the\n following item) is 256 MB and whose\n EXTENT_SIZE is 128M has just two extents,\n and so can be used to store data from at most two different\n disk data table partitions."
},
{
"para": "You can see how many extents remain free in a given data file\n by querying the\n INFORMATION_SCHEMA.FILES table,\n and so derive an estimate for how much space remains free in\n the file. For further discussion and examples, see\n ."
}
],
[
{
"para": "INITIAL_SIZE: This option is specific to\n NDB, and is not supported by\n InnoDB, where it fails with an error."
},
{
"para": "The INITIAL_SIZE parameter sets the total\n size in bytes of the data file that was specific using\n ADD DATATFILE. Once this file has been\n created, its size cannot be changed; however, you can add more\n data files to the tablespace using\n ALTER\n TABLESPACE ... ADD DATAFILE."
},
{
"para": "INITIAL_SIZE is optional; its default value\n is 134217728 (128 MB)."
},
{
"para": "On 32-bit systems, the maximum supported value for\n INITIAL_SIZE is 4294967296 (4 GB)."
}
],
[
{
"para": "AUTOEXTEND_SIZE: Currently ignored by\n MySQL; reserved for possible future use. Has no effect in any\n release of MySQL 8.0 or MySQL NDB Cluster 8.0, regardless of\n the storage engine used."
}
],
[
{
"para": "MAX_SIZE: Currently ignored by MySQL;\n reserved for possible future use. Has no effect in any release\n of MySQL 8.0 or MySQL NDB Cluster 8.0, regardless of the\n storage engine used."
}
],
[
{
"para": "NODEGROUP: Currently ignored by MySQL;\n reserved for possible future use. Has no effect in any release\n of MySQL 8.0 or MySQL NDB Cluster 8.0, regardless of the\n storage engine used."
}
],
[
{
"para": "WAIT: Currently ignored by MySQL; reserved\n for possible future use. Has no effect in any release of MySQL\n 8.0 or MySQL NDB Cluster 8.0, regardless of the storage engine\n used."
}
],
[
{
"para": "COMMENT: Currently ignored by MySQL;\n reserved for possible future use. Has no effect in any release\n of MySQL 8.0 or MySQL NDB Cluster 8.0, regardless of the\n storage engine used."
}
],
[
{
"para": "The ENCRYPTION clause enables or disables\n page-level data encryption for an InnoDB\n general tablespace. Encryption support for general tablespaces\n was introduced in MySQL 8.0.13."
},
{
"para": "As of MySQL 8.0.16, if the ENCRYPTION\n clause is not specified, the\n default_table_encryption\n setting controls whether encryption is enabled. The\n ENCRYPTION clause overrides the\n default_table_encryption\n setting. However, if the\n table_encryption_privilege_check\n variable is enabled, the\n TABLE_ENCRYPTION_ADMIN\n privilege is required to use an ENCRYPTION\n clause setting that differs from the\n default_table_encryption\n setting."
},
{
"para": "A keyring plugin must be installed and configured before an\n encryption-enabled tablespace can be created."
},
{
"para": "When a general tablespace is encrypted, all tables residing in\n the tablespace are encrypted. Likewise, a table created in an\n encrypted tablespace is encrypted."
},
{
"para": "For more information, see\n "
}
],
[
{
"para": "ENGINE: Defines the storage engine which\n uses the tablespace, where\n engine_name is the name of the\n storage engine. Currently, only the InnoDB\n storage engine is supported by standard MySQL current-series\n releases. MySQL NDB Cluster supports both\n NDB and InnoDB\n tablespaces. The value of the\n default_storage_engine system\n variable is used for ENGINE if the option\n is not specified."
}
]
]
},
{
"itemizedlist": [
[
{
"para": "For the rules covering the naming of MySQL tablespaces, see\n . In addition to these rules, the\n slash character (/) is not permitted, nor can\n you use names beginning with innodb_, as\n this prefix is reserved for system use."
}
],
[
{
"para": "Creation of temporary general tablespaces is not supported."
}
],
[
{
"para": "General tablespaces do not support temporary tables."
}
],
[
{
"para": "The TABLESPACE option may be used with\n CREATE TABLE or\n ALTER TABLE to assign an\n InnoDB table partition or subpartition to a\n file-per-table tablespace. All partitions must belong to the\n same storage engine. Assigning table partitions to shared\n InnoDB tablespaces is not supported. Shared\n tablespaces include the InnoDB system\n tablespace and general tablespaces."
}
],
[
{
"para": "General tablespaces support the addition of tables of any row\n format using\n CREATE TABLE ...\n TABLESPACE.\n innodb_file_per_table does\n not need to be enabled."
}
],
[
{
"para": "innodb_strict_mode is not\n applicable to general tablespaces. Tablespace management rules\n are strictly enforced independently of\n innodb_strict_mode. If\n CREATE TABLESPACE parameters are incorrect\n or incompatible, the operation fails regardless of the\n innodb_strict_mode setting.\n When a table is added to a general tablespace using\n CREATE TABLE ...\n TABLESPACE or\n ALTER TABLE ...\n TABLESPACE,\n innodb_strict_mode is ignored\n but the statement is evaluated as if\n innodb_strict_mode is\n enabled."
}
],
[
{
"para": "Use DROP TABLESPACE to remove a tablespace.\n All tables must be dropped from a tablespace using\n DROP TABLE prior to dropping\n the tablespace. Before dropping an NDB Cluster tablespace you\n must also remove all its data files using one or more\n ALTER\n TABLESPACE ... DROP DATATFILE statements. See\n ."
}
],
[
{
"para": "All parts of an InnoDB table added to an\n InnoDB general tablespace reside in the\n general tablespace, including indexes and\n BLOB pages."
},
{
"para": "For an NDB table assigned to a tablespace,\n only those columns which are not indexed are stored on disk,\n and actually use the tablespace data files. Indexes and\n indexed columns for all NDB tables are\n always kept in memory."
}
],
[
{
"para": "Similar to the system tablespace, truncating or dropping\n tables stored in a general tablespace creates free space\n internally in the general tablespace\n .ibd data file which can\n only be used for new InnoDB data. Space is\n not released back to the operating system as it is for\n file-per-table tablespaces."
}
],
[
{
"para": "A general tablespace is not associated with any database or\n schema."
}
],
[
{
"para": "ALTER TABLE ...\n DISCARD TABLESPACE and\n ALTER TABLE\n ...IMPORT TABLESPACE are not supported for tables\n that belong to a general tablespace."
}
],
[
{
"para": "The server uses tablespace-level metadata locking for DDL that\n references general tablespaces. By comparison, the server uses\n table-level metadata locking for DDL that references\n file-per-table tablespaces."
}
],
[
{
"para": "A generated or existing tablespace cannot be changed to a\n general tablespace."
}
],
[
{
"para": "There is no conflict between general tablespace names and\n file-per-table tablespace names. The /\n character, which is present in file-per-table tablespace\n names, is not permitted in general tablespace names."
}
],
[
{
"para": "mysqldump and mysqlpump\n do not dump InnoDB\n CREATE TABLESPACE statements."
}
]
]
},
{
"para": "This example demonstrates creating a general tablespace and adding\n three uncompressed tables of different row formats."
},
{
"programlisting": ">\nmysql> CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' ENGINE=INNODB;\n\nmysql> CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=REDUNDANT;\n\nmysql> CREATE TABLE t2 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=COMPACT;\n\nmysql> CREATE TABLE t3 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=DYNAMIC;"
},
{
"para": "This example demonstrates creating a general tablespace and adding\n a compressed table. The example assumes a default\n innodb_page_size value of 16K.\n The FILE_BLOCK_SIZE of 8192 requires that the\n compressed table have a KEY_BLOCK_SIZE of 8."
},
{
"programlisting": ">\nmysql> CREATE TABLESPACE `ts2` ADD DATAFILE 'ts2.ibd' FILE_BLOCK_SIZE = 8192 Engine=InnoDB;\n\nmysql> CREATE TABLE t4 (c1 INT PRIMARY KEY) TABLESPACE ts2 ROW_FORMAT=COMPRESSED KEY_BLOCK_SIZE=8;"
},
{
"para": "This example demonstrates creating a general tablespace without\n specifying the ADD DATAFILE clause, which is\n optional as of MySQL 8.0.14."
},
{
"programlisting": ">\nmysql> CREATE TABLESPACE `ts3` ENGINE=INNODB;"
},
{
"para": "This example demonstrates creating an undo tablespace."
},
{
"programlisting": ">\nmysql> CREATE UNDO TABLESPACE undo_003 ADD DATAFILE 'undo_003.ibu';"
},
{
"para": "Suppose that you wish to create an NDB Cluster Disk Data\n tablespace named myts using a datafile named\n mydata-1.dat. An NDB\n tablespace always requires the use of a log file group consisting\n of one or more undo log files. For this example, we first create a\n log file group named mylg that contains one\n undo long file named myundo-1.dat, using the\n CREATE LOGFILE GROUP statement\n shown here:"
},
{
"programlisting": ">\nmysql> CREATE LOGFILE GROUP myg1\n -> ADD UNDOFILE 'myundo-1.dat'\n -> ENGINE=NDB;\nQuery OK, 0 rows affected (3.29 sec)"
},
{
"para": "Now you can create the tablespace previously described using the\n following statement:"
},
{
"programlisting": ">\nmysql> CREATE TABLESPACE myts\n -> ADD DATAFILE 'mydata-1.dat'\n -> USE LOGFILE GROUP mylg\n -> ENGINE=NDB;\nQuery OK, 0 rows affected (2.98 sec)"
},
{
"para": "You can now create a Disk Data table using a\n CREATE TABLE statement with the\n TABLESPACE and STORAGE DISK\n options, similar to what is shown here:"
},
{
"programlisting": ">\nmysql> CREATE TABLE mytable (\n -> id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,\n -> lname VARCHAR(50) NOT NULL,\n -> fname VARCHAR(50) NOT NULL,\n -> dob DATE NOT NULL,\n -> joined DATE NOT NULL,\n -> INDEX(last_name, first_name)\n -> )\n -> TABLESPACE myts STORAGE DISK\n -> ENGINE=NDB;\nQuery OK, 0 rows affected (1.41 sec)"
},
{
"para": "It is important to note that only the dob and\n joined columns from mytable\n are actually stored on disk, due to the fact that the\n id, lname, and\n fname columns are all indexed."
},
{
"para": "As mentioned previously, when CREATE TABLESPACE\n is used with ENGINE [=] NDB, a tablespace and\n associated data file are created on each NDB Cluster data node.\n You can verify that the data files were created and obtain\n information about them by querying the\n INFORMATION_SCHEMA.FILES table, as\n shown here:"
},
{
"programlisting": ">\nmysql> SELECT FILE_NAME, FILE_TYPE, LOGFILE_GROUP_NAME, STATUS, EXTRA\n -> FROM INFORMATION_SCHEMA.FILES\n -> WHERE TABLESPACE_NAME = 'myts';\n\n+--------------+------------+--------------------+--------+----------------+\n| file_name | file_type | logfile_group_name | status | extra |\n+--------------+------------+--------------------+--------+----------------+\n| mydata-1.dat | DATAFILE | mylg | NORMAL | CLUSTER_NODE=5 |\n| mydata-1.dat | DATAFILE | mylg | NORMAL | CLUSTER_NODE=6 |\n| NULL | TABLESPACE | mylg | NORMAL | NULL |\n+--------------+------------+--------------------+--------+----------------+\n3 rows in set (0.01 sec)"
},
{
"para": "For additional information and examples, see\n ."
}
],
"id": "CREATE TABLESPACE",
"syntax": [
{
"programlisting": ">\nCREATE [UNDO] TABLESPACE tablespace_name\n\n InnoDB and NDB:\n [ADD DATAFILE 'file_name']\n\n InnoDB only:\n [FILE_BLOCK_SIZE = value]\n [ENCRYPTION [=] {'Y' | 'N'}]\n\n NDB only:\n USE LOGFILE GROUP logfile_group\n [EXTENT_SIZE [=] extent_size]\n [INITIAL_SIZE [=] initial_size]\n [AUTOEXTEND_SIZE [=] autoextend_size]\n [MAX_SIZE [=] max_size]\n [NODEGROUP [=] nodegroup_id]\n [WAIT]\n [COMMENT [=] 'string']\n\n InnoDB and NDB:\n [ENGINE [=] engine_name]"
}
]
},
{
"keywords": [
"CREATE",
"TRIGGER"
],
"description": [
{
"para": "This statement creates a new trigger. A trigger is a named\n database object that is associated with a table, and that\n activates when a particular event occurs for the table. The\n trigger becomes associated with the table named\n tbl_name, which must refer to a\n permanent table. You cannot associate a trigger with a\n TEMPORARY table or a view."
},
{
"para": "Trigger names exist in the schema namespace, meaning that all\n triggers must have unique names within a schema. Triggers in\n different schemas can have the same name."
},
{
"para": "This section describes CREATE\n TRIGGER syntax. For additional discussion, see\n ."
},
{
"para": "CREATE TRIGGER requires the\n TRIGGER privilege for the table\n associated with the trigger. If the DEFINER\n clause is present, the privileges required depend on the\n user value, as discussed in\n . If binary logging is\n enabled, CREATE TRIGGER might\n require the SUPER privilege, as\n discussed in ."
},
{
"para": "The DEFINER clause determines the security\n context to be used when checking access privileges at trigger\n activation time, as described later in this section."
},
{
"para": "trigger_time is the trigger action\n time. It can be BEFORE or\n AFTER to indicate that the trigger activates\n before or after each row to be modified."
},
{
"para": "Basic column value checks occur prior to trigger activation, so\n you cannot use BEFORE triggers to convert\n values inappropriate for the column type to valid values."
},
{
"para": "trigger_event indicates the kind of\n operation that activates the trigger. These\n trigger_event values are permitted:"
},
{
"itemizedlist": [
[
{
"para": "INSERT: The trigger activates\n whenever a new row is inserted into the table (for example,\n through INSERT,\n LOAD DATA, and\n REPLACE statements)."
}
],
[
{
"para": "UPDATE: The trigger activates\n whenever a row is modified (for example, through\n UPDATE statements)."
}
],
[
{
"para": "DELETE: The trigger activates\n whenever a row is deleted from the table (for example, through\n DELETE and\n REPLACE statements).\n DROP TABLE and\n TRUNCATE TABLE statements on\n the table do not activate this trigger,\n because they do not use DELETE.\n Dropping a partition does not activate\n DELETE triggers, either."
}
]
]
}
],
"id": "CREATE TRIGGER",
"syntax": [
{
"programlisting": ">\nCREATE\n [DEFINER = user]\n TRIGGER trigger_name\n trigger_timetrigger_event\n ON tbl_name FOR EACH ROW\n [trigger_order]\n trigger_body\n\ntrigger_time: { BEFORE | AFTER }\n\ntrigger_event: { INSERT | UPDATE | DELETE }\n\ntrigger_order: { FOLLOWS | PRECEDES } other_trigger_name"
}
]
},
{
"keywords": [
"CREATE",
"VIEW"
],
"description": [
{
"para": "The CREATE VIEW statement creates a\n new view, or replaces an existing view if the OR\n REPLACE clause is given. If the view does not exist,\n CREATE OR REPLACE\n VIEW is the same as CREATE\n VIEW. If the view does exist,\n CREATE OR REPLACE\n VIEW replaces it."
},
{
"para": "For information about restrictions on view use, see\n ."
},
{
"para": "The select_statement is a\n SELECT statement that provides the\n definition of the view. (Selecting from the view selects, in\n effect, using the SELECT\n statement.) The select_statement can\n select from base tables or other views."
},
{
"para": "The view definition is frozen at creation time and\n is not affected by subsequent changes to the definitions of the\n underlying tables. For example, if a view is defined as\n SELECT * on a table, new columns added to the\n table later do not become part of the view, and columns dropped\n from the table will result in an error when selecting from the\n view."
},
{
"para": "The ALGORITHM clause affects how MySQL\n processes the view. The DEFINER and\n SQL SECURITY clauses specify the security\n context to be used when checking access privileges at view\n invocation time. The WITH CHECK OPTION clause\n can be given to constrain inserts or updates to rows in tables\n referenced by the view. These clauses are described later in this\n section."
},
{
"para": "The CREATE VIEW statement requires\n the CREATE VIEW privilege for the\n view, and some privilege for each column selected by the\n SELECT statement. For columns used\n elsewhere in the SELECT statement,\n you must have the SELECT privilege.\n If the OR REPLACE clause is present, you must\n also have the DROP privilege for\n the view. If the DEFINER clause is present, the\n privileges required depend on the user\n value, as discussed in ."
},
{
"para": "When a view is referenced, privilege checking occurs as described\n later in this section."
},
{
"para": "A view belongs to a database. By default, a new view is created in\n the default database. To create the view explicitly in a given\n database, use db_name.view_name syntax\n to qualify the view name with the database name:"
},
{
"programlisting": ">\nCREATE VIEW test.v AS SELECT * FROM t;"
},
{
"para": "Unqualified table or view names in the\n SELECT statement are also\n interpreted with respect to the default database. A view can refer\n to tables or views in other databases by qualifying the table or\n view name with the appropriate database name."
},
{
"para": "Within a database, base tables and views share the same namespace,\n so a base table and a view cannot have the same name."
},
{
"para": "Columns retrieved by the SELECT\n statement can be simple references to table columns, or\n expressions that use functions, constant values, operators, and so\n forth."
},
{
"para": "A view must have unique column names with no duplicates, just like\n a base table. By default, the names of the columns retrieved by\n the SELECT statement are used for\n the view column names. To define explicit names for the view\n columns, specify the optional\n column_list clause as a list of\n comma-separated identifiers. The number of names in\n column_list must be the same as the\n number of columns retrieved by the\n SELECT statement."
},
{
"para": "A view can be created from many kinds of\n SELECT statements. It can refer to\n base tables or other views. It can use joins,\n UNION, and subqueries. The\n SELECT need not even refer to any\n tables:"
},
{
"programlisting": ">\nCREATE VIEW v_today (today) AS SELECT CURRENT_DATE;"
},
{
"para": "The following example defines a view that selects two columns from\n another table as well as an expression calculated from those\n columns:"
},
{
"programlisting": ">\nmysql> CREATE TABLE t (qty INT, price INT);\nmysql> INSERT INTO t VALUES(3, 50);\nmysql> CREATE VIEW v AS SELECT qty, price, qty*price AS value FROM t;\nmysql> SELECT * FROM v;\n+------+-------+-------+\n| qty | price | value |\n+------+-------+-------+\n| 3 | 50 | 150 |\n+------+-------+-------+"
},
{
"para": "A view definition is subject to the following restrictions:"
},
{
"itemizedlist": [
[
{
"para": "The SELECT statement cannot\n refer to system variables or user-defined variables."
}
],
[
{
"para": "Within a stored program, the\n SELECT statement cannot refer\n to program parameters or local variables."
}
],
[
{
"para": "The SELECT statement cannot\n refer to prepared statement parameters."
}
],
[
{
"para": "Any table or view referred to in the definition must exist.\n If, after the view has been created, a table or view that the\n definition refers to is dropped, use of the view results in an\n error. To check a view definition for problems of this kind,\n use the CHECK TABLE statement."
}
],
[
{
"para": "The definition cannot refer to a TEMPORARY\n table, and you cannot create a TEMPORARY\n view."
}
],
[
{
"para": "You cannot associate a trigger with a view."
}
],
[
{
"para": "Aliases for column names in the\n SELECT statement are checked\n against the maximum column length of 64 characters (not the\n maximum alias length of 256 characters)."
}
]
]
},
{
"para": "ORDER BY is permitted in a view definition, but\n it is ignored if you select from a view using a statement that has\n its own ORDER BY."
},
{
"para": "For other options or clauses in the definition, they are added to\n the options or clauses of the statement that references the view,\n but the effect is undefined. For example, if a view definition\n includes a LIMIT clause, and you select from\n the view using a statement that has its own\n LIMIT clause, it is undefined which limit\n applies. This same principle applies to options such as\n ALL, DISTINCT, or\n SQL_SMALL_RESULT that follow the\n SELECT keyword, and to clauses such\n as INTO, FOR UPDATE,\n FOR SHARE, LOCK IN SHARE\n MODE, and PROCEDURE."
},
{
"para": "The results obtained from a view may be affected if you change the\n query processing environment by changing system variables:"
},
{
"programlisting": ">\n\nmysql> CREATE VIEW v (mycol) AS SELECT 'abc';\nQuery OK, 0 rows affected (0.01 sec)\n\nmysql> SET sql_mode = '';\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> SELECT \"mycol\" FROM v;\n+-------+\n| mycol |\n+-------+\n| mycol |\n+-------+\n1 row in set (0.01 sec)\n\nmysql> SET sql_mode = 'ANSI_QUOTES';\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> SELECT \"mycol\" FROM v;\n+-------+\n| mycol |\n+-------+\n| abc |\n+-------+\n1 row in set (0.00 sec)"
},
{
"para": "The DEFINER and SQL SECURITY\n clauses determine which MySQL account to use when checking access\n privileges for the view when a statement is executed that\n references the view. The valid SQL SECURITY\n characteristic values are DEFINER (the default)\n and INVOKER. These indicate that the required\n privileges must be held by the user who defined or invoked the\n view, respectively."
},
{
"para": "If the DEFINER clause is present, the\n user value should be a MySQL account\n specified as\n 'user_name'@'host_name',\n CURRENT_USER, or\n CURRENT_USER(). The permitted\n user values depend on the privileges\n you hold, as discussed in\n . Also see that section\n for additional information about view security."
},
{
"para": "If the DEFINER clause is omitted, the default\n definer is the user who executes the CREATE\n VIEW statement. This is the same as specifying\n DEFINER = CURRENT_USER explicitly."
},
{
"para": "Within a view definition, the\n CURRENT_USER function returns the\n view's DEFINER value by default. For views\n defined with the SQL SECURITY INVOKER\n characteristic, CURRENT_USER\n returns the account for the view's invoker. For information about\n user auditing within views, see\n ."
},
{
"para": "Within a stored routine that is defined with the SQL\n SECURITY DEFINER characteristic,\n CURRENT_USER returns the routine's\n DEFINER value. This also affects a view defined\n within such a routine, if the view definition contains a\n DEFINER value of\n CURRENT_USER."
},
{
"para": "MySQL checks view privileges like this:"
},
{
"itemizedlist": [
[
{
"para": "At view definition time, the view creator must have the\n privileges needed to use the top-level objects accessed by the\n view. For example, if the view definition refers to table\n columns, the creator must have some privilege for each column\n in the select list of the definition, and the\n SELECT privilege for each\n column used elsewhere in the definition. If the definition\n refers to a stored function, only the privileges needed to\n invoke the function can be checked. The privileges required at\n function invocation time can be checked only as it executes:\n For different invocations, different execution paths within\n the function might be taken."
}
],
[
{
"para": "The user who references a view must have appropriate\n privileges to access it (SELECT\n to select from it, INSERT to\n insert into it, and so forth.)"
}
],
[
{
"para": "When a view has been referenced, privileges for objects\n accessed by the view are checked against the privileges held\n by the view DEFINER account or invoker,\n depending on whether the SQL SECURITY\n characteristic is DEFINER or\n INVOKER, respectively."
}
],
[
{
"para": "If reference to a view causes execution of a stored function,\n privilege checking for statements executed within the function\n depend on whether the function SQL SECURITY\n characteristic is DEFINER or\n INVOKER. If the security characteristic is\n DEFINER, the function runs with the\n privileges of the DEFINER account. If the\n characteristic is INVOKER, the function\n runs with the privileges determined by the view's SQL\n SECURITY characteristic."
}
]
]
},
{
"para": "Example: A view might depend on a stored function, and that\n function might invoke other stored routines. For example, the\n following view invokes a stored function f():"
},
{
"programlisting": ">\nCREATE VIEW v AS SELECT * FROM t WHERE t.id = f(t.name);"
},
{
"para": "Suppose that f() contains a statement such as\n this:"
},
{
"programlisting": ">\nIF name IS NULL then\n CALL p1();\nELSE\n CALL p2();\nEND IF;"
},
{
"para": "The privileges required for executing statements within\n f() need to be checked when\n f() executes. This might mean that privileges\n are needed for p1() or p2(),\n depending on the execution path within f().\n Those privileges must be checked at runtime, and the user who must\n possess the privileges is determined by the SQL\n SECURITY values of the view v and the\n function f()."
},
{
"para": "The DEFINER and SQL SECURITY\n clauses for views are extensions to standard SQL. In standard SQL,\n views are handled using the rules for SQL SECURITY\n DEFINER. The standard says that the definer of the view,\n which is the same as the owner of the view's schema, gets\n applicable privileges on the view (for example,\n SELECT) and may grant them. MySQL\n has no concept of a schema owner, so MySQL adds a\n clause to identify the definer. The DEFINER\n clause is an extension where the intent is to have what the\n standard has; that is, a permanent record of who defined the view.\n This is why the default DEFINER value is the\n account of the view creator."
},
{
"para": "The optional ALGORITHM clause is a MySQL\n extension to standard SQL. It affects how MySQL processes the\n view. ALGORITHM takes three values:\n MERGE, TEMPTABLE, or\n UNDEFINED. For more information, see\n , as well as\n ."
},
{
"para": "Some views are updatable. That is, you can use them in statements\n such as UPDATE,\n DELETE, or\n INSERT to update the contents of\n the underlying table. For a view to be updatable, there must be a\n one-to-one relationship between the rows in the view and the rows\n in the underlying table. There are also certain other constructs\n that make a view nonupdatable."
},
{
"para": "A generated column in a view is considered updatable because it is\n possible to assign to it. However, if such a column is updated\n explicitly, the only permitted value is\n DEFAULT. For information about generated\n columns, see ."
},
{
"para": "The WITH CHECK OPTION clause can be given for\n an updatable view to prevent inserts or updates to rows except\n those for which the WHERE clause in the\n select_statement is true."
},
{
"para": "In a WITH CHECK OPTION clause for an updatable\n view, the LOCAL and CASCADED\n keywords determine the scope of check testing when the view is\n defined in terms of another view. The LOCAL\n keyword restricts the CHECK OPTION only to the\n view being defined. CASCADED causes the checks\n for underlying views to be evaluated as well. When neither keyword\n is given, the default is CASCADED."
},
{
"para": "For more information about updatable views and the WITH\n CHECK OPTION clause, see\n , and\n ."
}
],
"id": "CREATE VIEW",
"syntax": [
{
"programlisting": ">\nCREATE\n [OR REPLACE]\n [ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}]\n [DEFINER = user]\n [SQL SECURITY { DEFINER | INVOKER }]\n VIEW view_name [(column_list)]\n AS select_statement\n [WITH [CASCADED | LOCAL] CHECK OPTION]"
}
]
},
{
"keywords": [
"DROP",
"DATABASE",
"SCHEMA",
"IF",
"EXISTS"
],
"description": [
{
"para": "DROP DATABASE drops all tables in\n the database and deletes the database. Be\n very careful with this statement! To use\n DROP DATABASE, you need the\n DROP privilege on the database.\n DROP\n SCHEMA is a synonym for DROP\n DATABASE."
},
{
"para": "IF EXISTS is used to prevent an error from\n occurring if the database does not exist."
}
],
"id": "DROP DATABASE",
"syntax": [
{
"programlisting": ">\nDROP {DATABASE | SCHEMA} [IF EXISTS] db_name"
}
]
},
{
"keywords": [
"DROP",
"EVENT",
"IF",
"EXISTS"
],
"description": [
{
"para": "This statement drops the event named\n event_name. The event immediately\n ceases being active, and is deleted completely from the server."
},
{
"para": "If the event does not exist, the error ERROR 1517\n (HY000): Unknown event\n 'event_name' results. You\n can override this and cause the statement to generate a warning\n for nonexistent events instead using IF EXISTS."
},
{
"para": "This statement requires the EVENT\n privilege for the schema to which the event to be dropped belongs."
}
],
"id": "DROP EVENT",
"syntax": [
{
"programlisting": ">\nDROP EVENT [IF EXISTS] event_name"
}
]
},
{
"keywords": [
"DROP",
"INDEX"
],
"description": [
{
"para": "DROP INDEX drops the index named\n index_name from the table\n tbl_name. This statement is mapped to\n an ALTER TABLE statement to drop\n the index. See ."
},
{
"para": "To drop a primary key, the index name is always\n PRIMARY, which must be specified as a quoted\n identifier because PRIMARY is a reserved word:"
},
{
"programlisting": ">\nDROP INDEX `PRIMARY` ON t;"
}
],
"id": "DROP INDEX",
"syntax": [
{
"programlisting": ">\nDROP INDEX index_name ON tbl_name\n [algorithm_option | lock_option] ...\n\nalgorithm_option:\n ALGORITHM [=] {DEFAULT|INPLACE|COPY}\n\nlock_option:\n LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}"
}
]
},
{
"keywords": [
"DROP",
"PROCEDURE",
"FUNCTION"
],
"description": [
{
"para": "This statement is used to drop a stored procedure or function.\n That is, the specified routine is removed from the server. You\n must have the ALTER ROUTINE\n privilege for the routine. (If the\n automatic_sp_privileges system variable is\n enabled, that privilege and EXECUTE\n are granted automatically to the routine creator when the routine\n is created and dropped from the creator when the routine is\n dropped. See .)"
},
{
"para": "The IF EXISTS clause is a MySQL extension. It\n prevents an error from occurring if the procedure or function does\n not exist. A warning is produced that can be viewed with\n SHOW WARNINGS."
}
],
"id": "DROP PROCEDURE",
"syntax": [
{
"programlisting": ">\nDROP {PROCEDURE | FUNCTION} [IF EXISTS] sp_name"
}
]
},
{
"keywords": [
"DROP",
"SERVER",
"IF",
"EXISTS"
],
"description": [
{
"para": "Drops the server definition for the server named\n server_name. The\n corresponding row in the mysql.servers table is\n deleted. This statement requires the\n SUPER privilege."
},
{
"para": "Dropping a server for a table does not affect any\n FEDERATED tables that used this connection\n information when they were created. See\n ."
}
],
"id": "DROP SERVER",
"syntax": [
{
"programlisting": ">\nDROP SERVER [ IF EXISTS ] server_name"
}
]
},
{
"keywords": [
"DROP",
"SPATIAL",
"REFERENCE",
"SYSTEM",
"IF",
"EXISTS"
],
"description": [
{
"para": "This statement removes a\n spatial reference\n system (SRS) definition from the data dictionary. It\n requires the SUPER privilege."
},
{
"para": "Example:"
},
{
"programlisting": ">\nDROP SPATIAL REFERENCE SYSTEM 4120;"
},
{
"para": "If no SRS definition with the SRID value exists, an error occurs\n unless IF EXISTS is specified. In that case, a\n warning occurs rather than an error."
},
{
"para": "If the SRID value is used by some column in an existing table, an\n error occurs. For example:"
},
{
"programlisting": ">\nmysql> DROP SPATIAL REFERENCE SYSTEM 4326;\nERROR 3716 (SR005): Can't modify SRID 4326. There is at\nleast one column depending on it."
},
{
"para": "To identify which column or columns use the SRID, use this query:"
},
{
"programlisting": ">\nSELECT * FROM INFORMATION_SCHEMA.ST_GEOMETRY_COLUMNS WHERE SRS_ID=4326;"
},
{
"para": "SRID values must be in the range of 32-bit unsigned integers, with\n these restrictions:"
},
{
"itemizedlist": [
[
{
"para": "SRID 0 is a valid SRID but cannot be used with\n DROP SPATIAL REFERENCE SYSTEM."
}
],
[
{
"para": "If the value is in a reserved SRID range, a warning occurs.\n Reserved ranges are [0, 32767] (reserved by EPSG),\n [60,000,000, 69,999,999] (reserved by EPSG), and\n [2,000,000,000, 2,147,483,647] (reserved by MySQL). EPSG\n stands for the European Petroleum\n Survey Group."
}
],
[
{
"para": "Users should not drop SRSs with SRIDs in the reserved ranges.\n If system-installed SRSs are dropped, the SRS definitions may\n be recreated for MySQL upgrades."
}
]
]
}
],
"id": "DROP SPATIAL REFERENCE SYSTEM",
"syntax": [
{
"programlisting": ">\nDROP SPATIAL REFERENCE SYSTEM\n [IF EXISTS]\n srid\n\nsrid: 32-bit unsigned integer"
}
]
},
{
"keywords": [
"DROP",
"TABLE",
"EXISTS",
"IF",
"TEMPORARY",
"RESTRICT",
"CASCADE"
],
"description": [
{
"para": "DROP TABLE removes one or more\n tables. You must have the DROP\n privilege for each table."
},
{
"para": "Be careful with this statement! For each\n table, it removes the table definition and all table data. If the\n table is partitioned, the statement removes the table definition,\n all its partitions, all data stored in those partitions, and all\n partition definitions associated with the dropped table."
},
{
"para": "Dropping a table also drops any triggers for the table."
},
{
"para": "DROP TABLE causes an implicit\n commit, except when used with the TEMPORARY\n keyword. See ."
},
{
"para": "If any tables named in the argument list do not exist,\n DROP TABLE behavior depends on\n whether the IF EXISTS clause is given:"
},
{
"itemizedlist": [
[
{
"para": "Without IF EXISTS, the statement fails with\n an error indicating which nonexisting tables it was unable to\n drop, and no changes are made."
}
],
[
{
"para": "With IF EXISTS, no error occurs for\n nonexisting tables. The statement drops all named tables that\n do exist, and generates a NOTE diagnostic\n for each nonexistent table. These notes can be displayed with\n SHOW WARNINGS. See\n ."
}
]
]
},
{
"para": "IF EXISTS can also be useful for dropping\n tables in unusual circumstances under which there is an entry in\n the data dictionary but no table managed by the storage engine.\n (For example, if an abnormal server exit occurs after removal of\n the table from the storage engine but before removal of the data\n dictionary entry.)"
},
{
"para": "The TEMPORARY keyword has the following\n effects:"
},
{
"itemizedlist": [
[
{
"para": "The statement drops only TEMPORARY tables."
}
],
[
{
"para": "The statement does not cause an implicit commit."
}
],
[
{
"para": "No access rights are checked. A TEMPORARY\n table is visible only with the session that created it, so no\n check is necessary."
}
]
]
},
{
"para": "Including the TEMPORARY keyword is a good way\n to prevent accidentally dropping non-TEMPORARY\n tables."
},
{
"para": "The RESTRICT and CASCADE\n keywords do nothing. They are permitted to make porting easier\n from other database systems."
},
{
"para": "DROP TABLE is not supported with\n all innodb_force_recovery\n settings. See ."
}
],
"id": "DROP TABLE",
"syntax": [
{
"programlisting": ">\nDROP [TEMPORARY] TABLE [IF EXISTS]\n tbl_name [, tbl_name] ...\n [RESTRICT | CASCADE]"
}
]
},
{
"keywords": [
"DROP",
"UNDO",
"TABLESPACE",
"ENGINE"
],
"description": [
{
"para": "This statement drops a tablespace that was previously created\n using CREATE TABLESPACE. It is\n supported by the NDB and\n InnoDB storage engines."
},
{
"para": "The UNDO keyword, introduced in MySQL 8.0.14,\n must be specified to drop an undo tablespace. Only undo\n tablespaces created using\n CREATE UNDO\n TABLESPACE syntax can be dropped. An undo tablespace\n must be in an empty state before it can be\n dropped. For more information, see\n ."
},
{
"para": "ENGINE sets the storage engine that uses the\n tablespace, where engine_name is the\n name of the storage engine. Currently, the values\n InnoDB and NDB are\n supported. If not set, the value of\n default_storage_engine is used.\n If it is not the same as the storage engine used to create the\n tablespace, the DROP TABLESPACE statement\n fails."
},
{
"para": "tablespace_name is a\n case-sensitive identifier in MySQL."
},
{
"para": "For an InnoDB general tablespace, all tables\n must be dropped from the tablespace prior to a DROP\n TABLESPACE operation. If the tablespace is not empty,\n DROP TABLESPACE returns an error."
},
{
"para": "An NDB tablespace to be dropped must not\n contain any data files; in other words, before you can drop an\n NDB tablespace, you must first drop each of its\n data files using\n ALTER TABLESPACE\n ... DROP DATAFILE."
},
{
"itemizedlist": [
[
{
"para": "A general InnoDB tablespace is not deleted\n automatically when the last table in the tablespace is\n dropped. The tablespace must be dropped explicitly using\n DROP TABLESPACE\n tablespace_name."
}
],
[
{
"para": "A DROP DATABASE operation can\n drop tables that belong to a general tablespace but it cannot\n drop the tablespace, even if the operation drops all tables\n that belong to the tablespace. The tablespace must be dropped\n explicitly using DROP TABLESPACE\n tablespace_name."
}
],
[
{
"para": "Similar to the system tablespace, truncating or dropping\n tables stored in a general tablespace creates free space\n internally in the general tablespace\n .ibd data file which can\n only be used for new InnoDB data. Space is\n not released back to the operating system as it is for\n file-per-table tablespaces."
}
]
]
},
{
"para": "This example demonstrates how to drop an InnoDB\n general tablespace. The general tablespace ts1\n is created with a single table. Before dropping the tablespace,\n the table must be dropped."
},
{
"programlisting": ">\nmysql> CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' Engine=InnoDB; \n\nmysql> CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1 Engine=InnoDB; \n\nmysql> DROP TABLE t1;\n\nmysql> DROP TABLESPACE ts1;"
},
{
"para": "This example demonstrates dropping an undo tablespace. An undo\n tablespace must be in an empty state before it\n can be dropped. For more information, see\n ."
},
{
"programlisting": ">\nmysql> DROP UNDO TABLESPACE undo_003;"
},
{
"para": "This example shows how to drop an NDB\n tablespace myts having a data file named\n mydata-1.dat after first creating the\n tablespace, and assumes the existence of a log file group named\n mylg (see\n )."
},
{
"programlisting": ">\nmysql> CREATE TABLESPACE myts\n -> ADD DATAFILE 'mydata-1.dat'\n -> USE LOGFILE GROUP mylg\n -> ENGINE=NDB;"
},
{
"para": "You must remove all data files from the tablespace using\n ALTER TABLESPACE, as shown here,\n before it can be dropped:"
},
{
"programlisting": ">\nmysql> ALTER TABLESPACE myts\n -> DROP DATAFILE 'mydata-1.dat'\n -> ENGINE=NDB;\n\nmysql> DROP TABLESPACE myts;"
}
],
"id": "DROP TABLESPACE",
"syntax": [
{
"programlisting": ">\nDROP [UNDO] TABLESPACE tablespace_name\n [ENGINE [=] engine_name]"
}
]
},
{
"keywords": [
"DROP",
"TRIGGER"
],
"description": [
{
"para": "This statement drops a trigger. The schema (database) name is\n optional. If the schema is omitted, the trigger is dropped from\n the default schema. DROP TRIGGER\n requires the TRIGGER privilege for\n the table associated with the trigger."
},
{
"para": "Use IF EXISTS to prevent an error from\n occurring for a trigger that does not exist. A\n NOTE is generated for a nonexistent trigger\n when using IF EXISTS. See\n ."
},
{
"para": "Triggers for a table are also dropped if you drop the table."
}
],
"id": "DROP TRIGGER",
"syntax": [
{
"programlisting": ">\nDROP TRIGGER [IF EXISTS] [schema_name.]trigger_name"
}
]
},
{
"keywords": [
"DROP",
"VIEW",
"IF",
"EXISTS",
"RESTRICT",
"CASCADE"
],
"description": [
{
"para": "DROP VIEW removes one or more\n views. You must have the DROP\n privilege for each view."
},
{
"para": "If any views named in the argument list do not exist, the\n statement fails with an error indicating by name which nonexisting\n views it was unable to drop, and no changes are made."
},
{
"para": "The IF EXISTS clause prevents an error from\n occurring for views that don't exist. When this clause is given, a\n NOTE is generated for each nonexistent view.\n See ."
},
{
"para": "RESTRICT and CASCADE, if\n given, are parsed and ignored."
}
],
"id": "DROP VIEW",
"syntax": [
{
"programlisting": ">\nDROP VIEW [IF EXISTS]\n view_name [, view_name] ...\n [RESTRICT | CASCADE]"
}
]
},
{
"keywords": [
"RENAME",
"TABLE"
],
"description": [
{
"para": "RENAME TABLE renames one or more\n tables. You must have ALTER and\n DROP privileges for the original\n table, and CREATE and\n INSERT privileges for the new\n table."
},
{
"para": "For example, to rename a table named old_table\n to new_table, use this statement:"
},
{
"programlisting": ">\nRENAME TABLE old_table TO new_table;"
},
{
"para": "That statement is equivalent to the following\n ALTER TABLE statement:"
},
{
"programlisting": ">\nALTER TABLE old_table RENAME new_table;"
},
{
"para": "RENAME TABLE, unlike ALTER\n TABLE, can rename multiple tables within a single\n statement:"
},
{
"programlisting": ">\nRENAME TABLE old_table1 TO new_table1,\n old_table2 TO new_table2,\n old_table3 TO new_table3;"
},
{
"para": "Renaming operations are performed left to right. Thus, to swap two\n table names, do this (assuming that a table with the intermediary\n name tmp_table does not already exist):"
},
{
"programlisting": ">\nRENAME TABLE old_table TO tmp_table,\n new_table TO old_table,\n tmp_table TO new_table;"
},
{
"para": "Metadata locks on tables are acquired in name order, which in some\n cases can make a difference in operation outcome when multiple\n transactions execute concurrently. See\n ."
},
{
"para": "As of MySQL 8.0.13, you can rename tables locked with a\n LOCK TABLES statement, provided\n that they are locked with a WRITE lock or are\n the product of renaming WRITE-locked tables\n from earlier steps in a multiple-table rename operation. For\n example, this is permitted:"
},
{
"programlisting": ">\nLOCK TABLE old_table1 WRITE;\nRENAME TABLE old_table1 TO new_table1,\n new_table1 TO new_table2;"
},
{
"para": "This is not permitted:"
},
{
"programlisting": ">\nLOCK TABLE old_table1 READ;\nRENAME TABLE old_table1 TO new_table1,\n new_table1 TO new_table2;"
},
{
"para": "Prior to MySQL 8.0.13, to execute RENAME TABLE,\n there must be no tables locked with LOCK\n TABLES."
},
{
"para": "With the transaction table locking conditions satisfied, the\n rename operation is done atomically; no other session can access\n any of the tables while the rename is in progress."
},
{
"para": "If any errors occur during a RENAME TABLE, the\n statement fails and no changes are made."
},
{
"para": "You can use RENAME TABLE to move a table from\n one database to another:"
},
{
"programlisting": ">\nRENAME TABLE current_db.tbl_name TO other_db.tbl_name;"
},
{
"para": "Using this method to move all tables from one database to a\n different one in effect renames the database (an operation for\n which MySQL has no single statement), except that the original\n database continues to exist, albeit with no tables."
},
{
"para": "Like RENAME TABLE, ALTER TABLE ...\n RENAME can also be used to move a table to a different\n database. Regardless of the statement used, if the rename\n operation would move the table to a database located on a\n different file system, the success of the outcome is platform\n specific and depends on the underlying operating system calls used\n to move table files."
},
{
"para": "If a table has triggers, attempts to rename the table into a\n different database fail with a Trigger in wrong\n schema\n (ER_TRG_IN_WRONG_SCHEMA) error."
},
{
"para": "An unencrypted table can be moved to an encryption-enabled\n database and vice versa. However, if the\n table_encryption_privilege_check\n variable is enabled, the\n TABLE_ENCRYPTION_ADMIN privilege is\n required if the table encryption setting differs from the default\n database encryption."
},
{
"para": "To rename TEMPORARY tables, RENAME\n TABLE does not work. Use ALTER\n TABLE instead."
},
{
"para": "RENAME TABLE works for views, except that views\n cannot be renamed into a different database."
},
{
"para": "Any privileges granted specifically for a renamed table or view\n are not migrated to the new name. They must be changed manually."
},
{
"para": "RENAME TABLE tbl_name TO\n new_tbl_name changes\n internally generated foreign key constraint names and user-defined\n foreign key constraint names that begin with the string\n tbl_name_ibfk_ to\n reflect the new table name. InnoDB interprets\n foreign key constraint names that begin with the string\n tbl_name_ibfk_ as\n internally generated names."
},
{
"para": "Foreign key constraint names that point to the renamed table are\n automatically updated unless there is a conflict, in which case\n the statement fails with an error. A conflict occurs if the\n renamed constraint name already exists. In such cases, you must\n drop and re-create the foreign keys for them to function properly."
},
{
"para": "RENAME TABLE tbl_name TO\n new_tbl_name changes\n internally generated and user-defined CHECK\n constraint names that begin with the string\n tbl_name_chk_ to reflect\n the new table name. MySQL interprets CHECK\n constraint names that begin with the string\n tbl_name_chk_ as\n internally generated names. Example:"
},
{
"programlisting": ">\nmysql> SHOW CREATE TABLE t1\\G\n*************************** 1. row ***************************\n Table: t1\nCreate Table: CREATE TABLE `t1` (\n `i1` int(11) DEFAULT NULL,\n `i2` int(11) DEFAULT NULL,\n CONSTRAINT `t1_chk_1` CHECK ((`i1` > 0)),\n CONSTRAINT `t1_chk_2` CHECK ((`i2` < 0))\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci\n1 row in set (0.02 sec)\n\nmysql> RENAME TABLE t1 TO t3;\nQuery OK, 0 rows affected (0.03 sec)\n\nmysql> SHOW CREATE TABLE t3\\G\n*************************** 1. row ***************************\n Table: t3\nCreate Table: CREATE TABLE `t3` (\n `i1` int(11) DEFAULT NULL,\n `i2` int(11) DEFAULT NULL,\n CONSTRAINT `t3_chk_1` CHECK ((`i1` > 0)),\n CONSTRAINT `t3_chk_2` CHECK ((`i2` < 0))\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci\n1 row in set (0.01 sec)"
}
],
"id": "RENAME TABLE",
"syntax": [
{
"programlisting": ">\nRENAME TABLE\n tbl_name TO new_tbl_name\n [, tbl_name2 TO new_tbl_name2] ..."
}
]
},
{
"keywords": [
"TRUNCATE",
"TABLE"
],
"description": [
{
"para": "TRUNCATE TABLE empties a table\n completely. It requires the DROP\n privilege. Logically, TRUNCATE\n TABLE is similar to a\n DELETE statement that deletes all\n rows, or a sequence of DROP TABLE\n and CREATE TABLE statements."
},
{
"para": "To achieve high performance, TRUNCATE\n TABLE bypasses the DML method of deleting data. Thus, it\n does not cause ON DELETE triggers to fire, it\n cannot be performed for InnoDB tables with\n parent-child foreign key relationships, and it cannot be rolled\n back like a DML operation. However, TRUNCATE\n TABLE operations on tables that use an atomic\n DDL-supported storage engine are either fully committed or rolled\n back if the server halts during their operation. For more\n information, see ."
},
{
"para": "Although TRUNCATE TABLE is similar\n to DELETE, it is classified as a\n DDL statement rather than a DML statement. It differs from\n DELETE in the following ways:"
},
{
"itemizedlist": [
[
{
"para": "Truncate operations drop and re-create the table, which is\n much faster than deleting rows one by one, particularly for\n large tables."
}
],
[
{
"para": "Truncate operations cause an implicit commit, and so cannot be\n rolled back. See ."
}
],
[
{
"para": "Truncation operations cannot be performed if the session holds\n an active table lock."
}
],
[
{
"para": "TRUNCATE TABLE fails for an\n InnoDB table or\n NDB table if there are any\n FOREIGN KEY constraints from other tables\n that reference the table. Foreign key constraints between\n columns of the same table are permitted."
}
],
[
{
"para": "Truncation operations do not return a meaningful value for the\n number of deleted rows. The usual result is 0 rows\n affected, which should be interpreted as no\n information."
}
],
[
{
"para": "As long as the table definition is valid, the table can be\n re-created as an empty table with\n TRUNCATE TABLE, even if the\n data or index files have become corrupted."
}
],
[
{
"para": "Any AUTO_INCREMENT value is reset to its\n start value. This is true even for MyISAM\n and InnoDB, which normally do not reuse\n sequence values."
}
],
[
{
"para": "When used with partitioned tables,\n TRUNCATE TABLE preserves the\n partitioning; that is, the data and index files are dropped\n and re-created, while the partition definitions are\n unaffected."
}
],
[
{
"para": "The TRUNCATE TABLE statement\n does not invoke ON DELETE triggers."
}
],
[
{
"para": "Truncating a corrupted InnoDB table is\n supported."
}
]
]
}
],
"id": "TRUNCATE TABLE",
"syntax": [
{
"programlisting": ">\nTRUNCATE [TABLE] tbl_name"
}
]
},
{
"keywords": [
"CALL"
],
"description": [
{
"para": "The CALL statement invokes a stored\n procedure that was defined previously with\n CREATE PROCEDURE."
},
{
"para": "Stored procedures that take no arguments can be invoked without\n parentheses. That is, CALL p() and\n CALL p are equivalent."
},
{
"para": "CALL can pass back values to its\n caller using parameters that are declared as\n OUT or INOUT parameters.\n When the procedure returns, a client program can also obtain the\n number of rows affected for the final statement executed within\n the routine: At the SQL level, call the\n ROW_COUNT() function; from the C\n API, call the\n mysql_affected_rows() function."
},
{
"para": "For information about the effect of unhandled conditions on\n procedure parameters, see\n ."
}
],
"id": "CALL",
"syntax": [
{
"programlisting": ">\nCALL sp_name([parameter[,...]])\nCALL sp_name[()]"
}
]
},
{
"keywords": [
"DELETE",
"BY",
"ORDER",
"LIMIT",
"WHERE",
"FROM",
"USING",
"LOW_PRIORITY",
"QUICK",
"PARTITION"
],
"description": [
{
"para": "You need the DELETE privilege on a\n table to delete rows from it. You need only the\n SELECT privilege for any columns\n that are only read, such as those named in the\n WHERE clause."
},
{
"para": "When you do not need to know the number of deleted rows, the\n TRUNCATE TABLE statement is a\n faster way to empty a table than a\n DELETE statement with no\n WHERE clause. Unlike\n DELETE,\n TRUNCATE TABLE cannot be used\n within a transaction or if you have a lock on the table. See\n and\n ."
},
{
"para": "The speed of delete operations may also be affected by factors\n discussed in ."
},
{
"para": "To ensure that a given DELETE\n statement does not take too much time, the MySQL-specific\n LIMIT row_count\n clause for DELETE specifies the\n maximum number of rows to be deleted. If the number of rows to\n delete is larger than the limit, repeat the\n DELETE statement until the number of affected\n rows is less than the LIMIT value."
},
{
"para": "You cannot delete from a table and select from the same table in a\n subquery."
},
{
"para": "DELETE supports explicit partition selection\n using the PARTITION option, which takes a list\n of the comma-separated names of one or more partitions or\n subpartitions (or both) from which to select rows to be dropped.\n Partitions not included in the list are ignored. Given a\n partitioned table t with a partition named\n p0, executing the statement DELETE\n FROM t PARTITION (p0) has the same effect on the table\n as executing ALTER\n TABLE t TRUNCATE PARTITION (p0); in both cases, all rows\n in partition p0 are dropped."
},
{
"para": "PARTITION can be used along with a\n WHERE condition, in which case the condition is\n tested only on rows in the listed partitions. For example,\n DELETE FROM t PARTITION (p0) WHERE c < 5\n deletes rows only from partition p0 for which\n the condition c < 5 is true; rows in any\n other partitions are not checked and thus not affected by the\n DELETE."
},
{
"para": "The PARTITION option can also be used in\n multiple-table DELETE statements. You can use\n up to one such option per table named in the\n FROM option."
},
{
"para": "For more information and examples, see\n ."
}
],
"id": "DELETE",
"syntax": [
{
"para": "DELETE is a DML statement that\n removes rows from a table."
},
{
"para": "A DELETE statement can start with a\n WITH clause to define common table\n expressions accessible within the\n DELETE. See ."
},
{
"programlisting": ">\nDELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROM tbl_name [[AS] tbl_alias]\n [PARTITION (partition_name [, partition_name] ...)]\n [WHERE where_condition]\n [ORDER BY ...]\n [LIMIT row_count]"
},
{
"para": "The DELETE statement deletes rows from\n tbl_name and returns the number of\n deleted rows. To check the number of deleted rows, call the\n ROW_COUNT() function described in\n ."
},
{
"para": "The conditions in the optional WHERE clause\n identify which rows to delete. With no WHERE\n clause, all rows are deleted."
},
{
"para": "where_condition is an expression that\n evaluates to true for each row to be deleted. It is specified as\n described in ."
},
{
"para": "If the ORDER BY clause is specified, the rows\n are deleted in the order that is specified. The\n LIMIT clause places a limit on the number of\n rows that can be deleted. These clauses apply to single-table\n deletes, but not multi-table deletes."
},
{
"programlisting": ">\nDELETE [LOW_PRIORITY] [QUICK] [IGNORE]\n tbl_name[.*] [, tbl_name[.*]] ...\n FROM table_references\n [WHERE where_condition]\n\nDELETE [LOW_PRIORITY] [QUICK] [IGNORE]\n FROM tbl_name[.*] [, tbl_name[.*]] ...\n USING table_references\n [WHERE where_condition]"
}
]
},
{
"keywords": [
"DO"
],
"description": [
{
"para": "DO executes the expressions but\n does not return any results. In most respects,\n DO is shorthand for SELECT\n expr, ..., but has the\n advantage that it is slightly faster when you do not care about\n the result."
},
{
"para": "DO is useful primarily with\n functions that have side effects, such as\n RELEASE_LOCK()."
},
{
"para": "Example: This SELECT statement\n pauses, but also produces a result set:"
},
{
"programlisting": ">\nmysql> SELECT SLEEP(5);\n+----------+\n| SLEEP(5) |\n+----------+\n| 0 |\n+----------+\n1 row in set (5.02 sec)"
},
{
"para": "DO, on the other hand, pauses\n without producing a result set.:"
},
{
"programlisting": ">\nmysql> DO SLEEP(5);\nQuery OK, 0 rows affected (4.99 sec)"
},
{
"para": "This could be useful, for example in a stored function or trigger,\n which prohibit statements that produce result sets."
},
{
"para": "DO only executes expressions. It\n cannot be used in all cases where SELECT can be\n used. For example, DO id FROM t1 is invalid\n because it references a table."
}
],
"id": "DO",
"syntax": [
{
"programlisting": ">\nDO expr [, expr] ..."
}
]
},
{
"keywords": [
"HANDLER",
"OPEN",
"READ",
"LIMIT",
"FIRST",
"NEXT",
"PREV",
"LAST",
"WHERE",
"CLOSE"
],
"description": [
{
"para": "The HANDLER statement provides direct access to\n table storage engine interfaces. It is available for\n InnoDB and MyISAM tables."
}
],
"id": "HANDLER",
"syntax": [
{
"programlisting": ">\nHANDLER tbl_name OPEN [ [AS] alias]\n\nHANDLER tbl_name READ index_name { = | <= | >= | < | > } (value1,value2,...)\n [ WHERE where_condition ] [LIMIT ... ]\nHANDLER tbl_name READ index_name { FIRST | NEXT | PREV | LAST }\n [ WHERE where_condition ] [LIMIT ... ]\nHANDLER tbl_name READ { FIRST | NEXT }\n [ WHERE where_condition ] [LIMIT ... ]\n\nHANDLER tbl_name CLOSE"
}
]
},
{
"keywords": [
"IMPORT",
"TABLE",
"FROM"
],
"description": [
{
"para": "The IMPORT TABLE statement imports\n MyISAM tables based on information contained in\n .sdi (serialized dictionary information)\n metadata files. IMPORT TABLE\n requires the FILE privilege to read\n the .sdi and table content files, and the\n CREATE privilege for the table to\n be created."
},
{
"para": "Tables can be exported from one server using\n mysqldump to write a file of SQL statements and\n imported into another server using mysql to\n process the dump file. IMPORT TABLE\n provides a faster alternative using the raw table\n files."
},
{
"para": "Prior to import, the files that provide the table content must be\n placed in the appropriate schema directory for the import server,\n and the .sdi file must be located in a\n directory accessible to the server. For example, the\n .sdi file can be placed in the directory\n named by the secure_file_priv\n system variable, or (if\n secure_file_priv is empty) in a\n directory under the server data directory."
},
{
"para": "The following example describes how to export\n MyISAM tables named\n employees and managers from\n the hr schema of one server and import them\n into the hr schema of another server. The\n example uses these assumptions (to perform a similar operation on\n your own system, modify the path names as appropriate):"
},
{
"itemizedlist": [
[
{
"para": "For the export server,\n export_basedir represents its base\n directory, and its data directory is\n export_basedir/data."
}
],
[
{
"para": "For the import server,\n import_basedir represents its base\n directory, and its data directory is\n import_basedir/data."
}
],
[
{
"para": "Table files are exported from the export server into the\n /tmp/export directory and this directory\n is secure (not accessible to other users)."
}
],
[
{
"para": "The import server uses /tmp/mysql-files\n as the directory named by its\n secure_file_priv system\n variable."
}
]
]
},
{
"para": "To export tables from the export server, use this procedure:"
},
{
"para": "To import tables into the import server, use this procedure:"
},
{
"para": "The .sdi file need not be placed in the\n import server directory named by the\n secure_file_priv system variable\n if that variable is empty; it can be in any directory accessible\n to the server, including the schema directory for the imported\n table. If the .sdi file is placed in that\n directory, however, it may be rewritten; the import operation\n creates a new .sdi file for the table, which\n will overwrite the old .sdi file if the\n operation uses the same file name for the new file."
},
{
"para": "Each sdi_file value must be a string\n literal that names the .sdi file for a table\n or is a pattern that matches .sdi files. If\n the string is a pattern, any leading directory path and the\n .sdi file name suffix must be given\n literally. Pattern characters are permitted only in the base name\n part of the file name:"
},
{
"itemizedlist": [
[
{
"para": "? matches any single character"
}
],
[
{
"para": "* matches any sequence of characters,\n including no characters"
}
]
]
},
{
"para": "Using a pattern, the previous IMPORT\n TABLE statement could have been written like this\n (assuming that the /tmp/mysql-files directory\n contains no other .sdi files matching the\n pattern):"
},
{
"programlisting": ">\nIMPORT TABLE FROM '/tmp/mysql-files/*.sdi';"
},
{
"para": "To interpret the location of .sdi file path\n names, the server uses the same rules for\n IMPORT TABLE as the server-side\n rules for LOAD DATA (that is, the\n non-LOCAL rules). See\n , paying particular attention to the\n rules used to interpret relative path names."
},
{
"para": "IMPORT TABLE fails if the\n .sdi or table files cannot be located. After\n importing a table, the server attempts to open it and reports as\n warnings any problems detected. To attempt a repair to correct any\n reported issues, use REPAIR TABLE."
},
{
"para": "IMPORT TABLE is not written to the\n binary log."
}
],
"id": "IMPORT TABLE",
"syntax": [
{
"programlisting": ">\nIMPORT TABLE FROM sdi_file [, sdi_file] ..."
}
]
},
{
"keywords": [
"INSERT",
"SELECT"
],
"description": [
{
"para": "With INSERT ...\n SELECT, you can quickly insert many rows into a table\n from the result of a SELECT\n statement, which can select from one or many tables. For\n example:"
},
{
"programlisting": ">\nINSERT INTO tbl_temp2 (fld_id)\n SELECT tbl_temp1.fld_order_id\n FROM tbl_temp1 WHERE tbl_temp1.fld_order_id > 100;"
}
],
"id": "INSERT SELECT",
"syntax": [
{
"programlisting": ">\nINSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE]\n [INTO] tbl_name\n [PARTITION (partition_name [, partition_name] ...)]\n [(col_name [, col_name] ...)]\n SELECT ...\n [ON DUPLICATE KEY UPDATE assignment_list]\n\nvalue:\n {expr | DEFAULT}\n\nassignment:\n col_name = value\n\nassignment_list:\n assignment [, assignment] ..."
}
]
},
{
"keywords": [
"INSERT",
"DELAYED"
],
"description": [
{
"para": "The DELAYED option for the\n INSERT statement is a MySQL\n extension to standard SQL. In previous versions of MySQL, it can\n be used for certain kinds of tables (such as\n MyISAM), such that when a client uses\n INSERT DELAYED, it gets an okay\n from the server at once, and the row is queued to be inserted\n when the table is not in use by any other thread."
},
{
"para": "DELAYED inserts and replaces were deprecated\n in MySQL 5.6. In MySQL current-series,\n DELAYED is not supported. The server\n recognizes but ignores the DELAYED keyword,\n handles the insert as a nondelayed insert, and generates an\n ER_WARN_LEGACY_SYNTAX_CONVERTED warning\n (INSERT DELAYED is no longer supported. The statement was\n converted to INSERT). The DELAYED\n keyword is scheduled for removal in a future release."
}
],
"id": "INSERT DELAYED",
"syntax": [
{
"programlisting": ">\nINSERT DELAYED ..."
}
]
},
{
"keywords": [
"INSERT",
"INTO",
"LOW_PRIORITY",
"HIGH_PRIORITY",
"IGNORE",
"DUPLICATE",
"KEY",
"UPDATE",
"DELAYED",
"DEFAULT",
"VALUES",
"VALUE",
"SELECT",
"SET",
"PARTITION"
],
"description": [
{
"para": "INSERT inserts new rows into an\n existing table. The INSERT\n ... VALUES and\n INSERT ... SET\n forms of the statement insert rows based on explicitly specified\n values. The INSERT\n ... SELECT form inserts rows selected from another table\n or tables. INSERT with an\n ON DUPLICATE KEY UPDATE clause enables existing\n rows to be updated if a row to be inserted would cause a duplicate\n value in a UNIQUE index or PRIMARY\n KEY."
},
{
"para": "For additional information about\n INSERT ...\n SELECT and\n INSERT ... ON\n DUPLICATE KEY UPDATE, see\n , and\n ."
},
{
"para": "In MySQL current-series, the DELAYED keyword\n is accepted but ignored by the server. For the reasons for this,\n see ,"
},
{
"para": "Inserting into a table requires the\n INSERT privilege for the table. If\n the ON DUPLICATE KEY UPDATE clause is used and\n a duplicate key causes an UPDATE to\n be performed instead, the statement requires the\n UPDATE privilege for the columns to\n be updated. For columns that are read but not modified you need\n only the SELECT privilege (such as\n for a column referenced only on the right hand side of an\n col_name=expr\n assignment in an ON DUPLICATE KEY UPDATE\n clause)."
},
{
"para": "When inserting into a partitioned table, you can control which\n partitions and subpartitions accept new rows. The\n PARTITION option takes a list of the\n comma-separated names of one or more partitions or subpartitions\n (or both) of the table. If any of the rows to be inserted by a\n given INSERT statement do not match\n one of the partitions listed, the\n INSERT statement fails with the\n error Found a row not matching the given partition\n set. For more information and examples, see\n ."
}
],
"id": "INSERT",
"syntax": [
{
"programlisting": ">\nINSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]\n [INTO] tbl_name\n [PARTITION (partition_name [, partition_name] ...)]\n [(col_name [, col_name] ...)]\n {VALUES | VALUE} (value_list) [, (value_list)] ...\n [ON DUPLICATE KEY UPDATE assignment_list]\n\nINSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]\n [INTO] tbl_name\n [PARTITION (partition_name [, partition_name] ...)]\n SET assignment_list\n [ON DUPLICATE KEY UPDATE assignment_list]\n\nINSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE]\n [INTO] tbl_name\n [PARTITION (partition_name [, partition_name] ...)]\n [(col_name [, col_name] ...)]\n SELECT ...\n [ON DUPLICATE KEY UPDATE assignment_list]\n\nvalue:\n {expr | DEFAULT}\n\nvalue_list:\n value [, value] ...\n\nassignment:\n col_name = value\n\nassignment_list:\n assignment [, assignment] ..."
}
]
},
{
"keywords": [
"BY",
"LOAD",
"DATA",
"LOW_PRIORITY",
"CONCURRENT",
"LOCAL",
"INFILE",
"REPLACE",
"IGNORE",
"FIELDS",
"COLUMNS",
"ENCLOSED",
"TERMINATED",
"ESCAPED",
"LINES",
"IMPORT",
"CSV",
"OPTIONALLY",
"STARTING",
"CHARACTER",
"SET",
"PARTITION"
],
"description": [
{
"para": "The LOAD DATA statement reads rows\n from a text file into a table at a very high speed.\n LOAD DATA is the complement of\n SELECT ... INTO\n OUTFILE. (See .) To write\n data from a table to a file, use\n SELECT ... INTO\n OUTFILE. To read the file back into a table, use\n LOAD DATA. The syntax of the\n FIELDS and LINES clauses is\n the same for both statements."
},
{
"para": "You can also load data files by using the\n mysqlimport utility; see\n . mysqlimport\n operates by sending a LOAD DATA\n statement to the server."
},
{
"para": "For more information about the efficiency of\n INSERT versus\n LOAD DATA and speeding up\n LOAD DATA, see\n ."
}
],
"id": "LOAD DATA",
"syntax": [
{
"programlisting": ">\nLOAD DATA\n [LOW_PRIORITY | CONCURRENT] [LOCAL]\n INFILE 'file_name'\n [REPLACE | IGNORE]\n INTO TABLE tbl_name\n [PARTITION (partition_name [, partition_name] ...)]\n [CHARACTER SET charset_name]\n [{FIELDS | COLUMNS}\n [TERMINATED BY 'string']\n [[OPTIONALLY] ENCLOSED BY 'char']\n [ESCAPED BY 'char']\n ]\n [LINES\n [STARTING BY 'string']\n [TERMINATED BY 'string']\n ]\n [IGNORE number {LINES | ROWS}]\n [(col_name_or_user_var\n [, col_name_or_user_var] ...)]\n [SET col_name={expr | DEFAULT},\n [, col_name={expr | DEFAULT}] ...]"
}
]
},
{
"keywords": [
"LOW_PRIORITY",
"CONCURRENT",
"LOCAL",
"INFILE",
"REPLACE",
"IGNORE",
"CHARACTER",
"SET",
"ROWS",
"IDENTIFIED",
"BY",
"LINES"
],
"description": [
{
"para": "The LOAD XML statement reads data\n from an XML file into a table. The\n file_name must be given as a literal\n string. The tagname in the optional\n ROWS IDENTIFIED BY clause must also be given as\n a literal string, and must be surrounded by angle brackets\n (< and >)."
},
{
"para": "LOAD XML acts as the complement of\n running the mysql client in XML output mode\n (that is, starting the client with the\n option). To write data from a\n table to an XML file, you can invoke the mysql\n client with the and\n options from\n the system shell, as shown here:"
},
{
"programlisting": ">\nshell> mysql --xml -e 'SELECT * FROM mydb.mytable' > file.xml"
},
{
"para": "To read the file back into a table, use LOAD\n XML. By default, the <row>\n element is considered to be the equivalent of a database table\n row; this can be changed using the ROWS IDENTIFIED\n BY clause."
},
{
"para": "This statement supports three different XML formats:"
},
{
"itemizedlist": [
[
{
"para": "Column names as attributes and column values as attribute\n values:"
},
{
"programlisting": ">\n<rowcolumn1=\"value1\" column2=\"value2\" .../>"
}
],
[
{
"para": "Column names as tags and column values as the content of these\n tags:"
},
{
"programlisting": ">\n<row>\n <column1>value1</column1>\n <column2>value2</column2>\n</row>"
}
],
[
{
"para": "Column names are the name attributes of\n <field> tags, and values are the\n contents of these tags:"
},
{
"programlisting": ">\n<row>\n <field name='column1'>value1</field>\n <field name='column2'>value2</field>\n</row>"
},
{
"para": "This is the format used by other MySQL tools, such as\n mysqldump."
}
]
]
},
{
"para": "All three formats can be used in the same XML file; the import\n routine automatically detects the format for each row and\n interprets it correctly. Tags are matched based on the tag or\n attribute name and the column name."
},
{
"para": "The following clauses work essentially the same way for\n LOAD XML as they do for\n LOAD DATA:"
},
{
"itemizedlist": [
[
{
"para": "LOW_PRIORITY or\n CONCURRENT"
}
],
[
{
"para": "LOCAL"
}
],
[
{
"para": "REPLACE or IGNORE"
}
],
[
{
"para": "CHARACTER SET"
}
],
[
{
"para": "SET"
}
]
]
},
{
"para": "See , for more information about these\n clauses."
},
{
"para": "(field_name_or_user_var,\n ...) is a list of one or more comma-separated XML fields\n or user variables. The name of a user variable used for this\n purpose must match the name of a field from the XML file, prefixed\n with @. You can use field names to select only\n desired fields. User variables can be employed to store the\n corresponding field values for subsequent re-use."
},
{
"para": "The IGNORE number\n LINES or IGNORE\n number ROWS clause causes the\n first number rows in the XML file to be\n skipped. It is analogous to the LOAD\n DATA statement's IGNORE ... LINES\n clause."
}
],
"id": "LOAD XML",
"syntax": [
{
"programlisting": ">\nLOAD XML\n [LOW_PRIORITY | CONCURRENT] [LOCAL]\n INFILE 'file_name'\n [REPLACE | IGNORE]\n INTO TABLE [db_name.]tbl_name\n [CHARACTER SET charset_name]\n [ROWS IDENTIFIED BY '<tagname>']\n [IGNORE number {LINES | ROWS}]\n [(field_name_or_user_var\n [, field_name_or_user_var] ...)]\n [SET col_name={expr | DEFAULT},\n [, col_name={expr | DEFAULT}] ...]"
}
]
},
{
"keywords": [
"REPLACE",
"DELAYED",
"LOW_PRIORITY",
"INTO",
"PARTITION",
"VALUES",
"VALUE",
"SELECT",
"SET",
"DEFAULT"
],
"description": [
{
"para": "REPLACE works exactly like\n INSERT, except that if an old row\n in the table has the same value as a new row for a\n PRIMARY KEY or a UNIQUE\n index, the old row is deleted before the new row is inserted. See\n ."
},
{
"para": "REPLACE is a MySQL extension to the\n SQL standard. It either inserts, or deletes\n and inserts. For another MySQL extension to standard\n SQLmdashthat either inserts or\n updatesmdashsee\n ."
},
{
"para": "DELAYED inserts and replaces were deprecated in\n MySQL 5.6. In MySQL current-series, DELAYED\n is not supported. The server recognizes but ignores the\n DELAYED keyword, handles the replace as a\n nondelayed replace, and generates an\n ER_WARN_LEGACY_SYNTAX_CONVERTED warning.\n (REPLACE DELAYED is no longer supported. The statement was\n converted to REPLACE.) The DELAYED\n keyword will be removed in a future release."
},
{
"para": "Values for all columns are taken from the values specified in the\n REPLACE statement. Any missing\n columns are set to their default values, just as happens for\n INSERT. You cannot refer to values\n from the current row and use them in the new row. If you use an\n assignment such as SET\n col_name =\n col_name + 1, the reference\n to the column name on the right hand side is treated as\n DEFAULT(col_name),\n so the assignment is equivalent to SET\n col_name =\n DEFAULT(col_name) + 1."
},
{
"para": "To use REPLACE, you must have both\n the INSERT and\n DELETE privileges for the table."
},
{
"para": "If a generated column is replaced explicitly, the only permitted\n value is DEFAULT. For information about\n generated columns, see\n ."
},
{
"para": "REPLACE supports explicit partition selection\n using the PARTITION keyword with a list of\n comma-separated names of partitions, subpartitions, or both. As\n with INSERT, if it is not possible\n to insert the new row into any of these partitions or\n subpartitions, the REPLACE statement fails with\n the error Found a row not matching the given partition\n set. For more information and examples, see\n ."
}
],
"id": "REPLACE",
"syntax": [
{
"programlisting": ">\nREPLACE [LOW_PRIORITY | DELAYED]\n [INTO] tbl_name\n [PARTITION (partition_name [, partition_name] ...)]\n [(col_name [, col_name] ...)]\n {VALUES | VALUE} (value_list) [, (value_list)] ...\n\nREPLACE [LOW_PRIORITY | DELAYED]\n [INTO] tbl_name\n [PARTITION (partition_name [, partition_name] ...)]\n SET assignment_list\n\nREPLACE [LOW_PRIORITY | DELAYED]\n [INTO] tbl_name\n [PARTITION (partition_name [, partition_name] ...)]\n [(col_name [, col_name] ...)]\n SELECT ...\n\nvalue:\n {expr | DEFAULT}\n\nvalue_list:\n value [, value] ...\n\nassignment:\n col_name = value\n\nassignment_list:\n assignment [, assignment] ..."
}
]
},
{
"keywords": [
"SELECT",
"AS",
"ASC",
"DESC",
"ORDER",
"GROUP",
"HAVING",
"BY",
"STRAIGHT_JOIN",
"SQL_SMALL_RESULT",
"SQL_BIG_RESULT",
"SQL_BUFFER_RESULT",
"SQL_NO_CACHE",
"SQL_CALC_FOUND_ROWS",
"HIGH_PRIORITY",
"DISTINCT",
"DISTINCTROW",
"ALL",
"INTO",
"FROM",
"OUTFILE",
"DUMPFILE",
"IGNORE",
"JOIN",
"LOCK",
"IN",
"SHARE",
"MODE",
"FOR",
"UPDATE",
"OFFSET",
"LIMIT",
"MEMORY",
"CHARACTER",
"SET",
"PARTITION"
],
"description": [
{
"para": "SELECT is used to retrieve rows\n selected from one or more tables, and can include\n UNION statements and subqueries.\n See , and . A\n SELECT statement can start with a\n WITH clause to define common table\n expressions accessible within the\n SELECT. See ."
},
{
"para": "The most commonly used clauses of\n SELECT statements are these:"
},
{
"itemizedlist": [
[
{
"para": "Each select_expr indicates a column\n that you want to retrieve. There must be at least one\n select_expr."
}
],
[
{
"para": "table_references indicates the\n table or tables from which to retrieve rows. Its syntax is\n described in ."
}
],
[
{
"para": "SELECT supports explicit partition\n selection using the PARTITION with a list\n of partitions or subpartitions (or both) following the name of\n the table in a table_reference (see\n ). In this case, rows are selected only\n from the partitions listed, and any other partitions of the\n table are ignored. For more information and examples, see\n ."
},
{
"para": "SELECT ... PARTITION from tables using\n storage engines such as MyISAM\n that perform table-level locks (and thus partition locks) lock\n only the partitions or subpartitions named by the\n PARTITION option."
},
{
"para": "For more information, see\n ."
}
],
[
{
"para": "The WHERE clause, if given, indicates the\n condition or conditions that rows must satisfy to be selected.\n where_condition is an expression\n that evaluates to true for each row to be selected. The\n statement selects all rows if there is no\n WHERE clause."
},
{
"para": "In the WHERE expression, you can use any of\n the functions and operators that MySQL supports, except for\n aggregate (summary) functions. See\n , and\n ."
}
]
]
},
{
"para": "SELECT can also be used to retrieve\n rows computed without reference to any table."
}
],
"id": "SELECT",
"syntax": [
{
"programlisting": ">\nSELECT\n [ALL | DISTINCT | DISTINCTROW ]\n [HIGH_PRIORITY]\n [STRAIGHT_JOIN]\n [SQL_SMALL_RESULT] [SQL_BIG_RESULT] [SQL_BUFFER_RESULT]\n [SQL_NO_CACHE] [SQL_CALC_FOUND_ROWS]\n select_expr [, select_expr ...]\n [FROM table_references\n [PARTITION partition_list]\n [WHERE where_condition]\n [GROUP BY {col_name | expr | position}, ... [WITH ROLLUP]]\n [HAVING where_condition]\n [WINDOW window_name AS (window_spec)\n [, window_name AS (window_spec)] ...]\n [ORDER BY {col_name | expr | position}\n [ASC | DESC], ... [WITH ROLLUP]]\n [LIMIT {[offset,] row_count | row_count OFFSET offset}]\n [INTO OUTFILE 'file_name'\n [CHARACTER SET charset_name]\n export_options\n | INTO DUMPFILE 'file_name'\n | INTO var_name [, var_name]]\n [FOR {UPDATE | SHARE} [OF tbl_name [, tbl_name] ...] [NOWAIT | SKIP LOCKED] \n | LOCK IN SHARE MODE]]"
}
]
},
{
"keywords": [
"JOIN",
"INNER",
"CROSS",
"LEFT",
"OUTER",
"NATURAL",
"RIGHT",
"STRAIGHT_JOIN",
"USE",
"INDEX",
"AS",
"IGNORE",
"FORCE",
"ON",
"USING",
"PARTITION"
],
"description": [
{
"para": "MySQL supports the following JOIN syntax for\n the table_references part of\n SELECT statements and\n multiple-table DELETE and\n UPDATE statements:"
},
{
"programlisting": ">\ntable_references:\n escaped_table_reference [, escaped_table_reference] ...\n\nescaped_table_reference:\n table_reference\n | { OJ table_reference }\n\ntable_reference:\n table_factor\n | joined_table\n\ntable_factor:\n tbl_name [PARTITION (partition_names)]\n [[AS] alias] [index_hint_list]\n | table_subquery [AS] alias [(col_list)]\n | ( table_references )\n\njoined_table:\n table_reference {[INNER | CROSS] JOIN | STRAIGHT_JOIN} table_factor [join_specification]\n | table_reference {LEFT|RIGHT} [OUTER] JOIN table_referencejoin_specification\n | table_reference NATURAL [INNER | {LEFT|RIGHT} [OUTER]] JOIN table_factor\n\njoin_specification:\n ON search_condition\n | USING (join_column_list)\n\njoin_column_list:\n column_name [, column_name] ...\n\nindex_hint_list:\n index_hint [, index_hint] ...\n\nindex_hint:\n USE {INDEX|KEY}\n [FOR {JOIN|ORDER BY|GROUP BY}] ([index_list])\n | {IGNORE|FORCE} {INDEX|KEY}\n [FOR {JOIN|ORDER BY|GROUP BY}] (index_list)\n\nindex_list:\n index_name [, index_name] ..."
},
{
"para": "A table reference is also known as a join expression."
},
{
"para": "A table reference (when it refers to a partitioned table) may\n contain a PARTITION option, including a list\n of comma-separated partitions, subpartitions, or both. This\n option follows the name of the table and precedes any alias\n declaration. The effect of this option is that rows are selected\n only from the listed partitions or subpartitions. Any partitions\n or subpartitions not named in the list are ignored. For more\n information and examples, see\n ."
},
{
"para": "The syntax of table_factor is\n extended in MySQL in comparison with standard SQL. The standard\n accepts only table_reference, not a\n list of them inside a pair of parentheses."
},
{
"para": "This is a conservative extension if each comma in a list of\n table_reference items is considered\n as equivalent to an inner join. For example:"
},
{
"programlisting": ">\nSELECT * FROM t1 LEFT JOIN (t2, t3, t4)\n ON (t2.a = t1.a AND t3.b = t1.b AND t4.c = t1.c)"
},
{
"para": "is equivalent to:"
},
{
"programlisting": ">\nSELECT * FROM t1 LEFT JOIN (t2 CROSS JOIN t3 CROSS JOIN t4)\n ON (t2.a = t1.a AND t3.b = t1.b AND t4.c = t1.c)"
},
{
"para": "In MySQL, JOIN, CROSS\n JOIN, and INNER JOIN are syntactic\n equivalents (they can replace each other). In standard SQL, they\n are not equivalent. INNER JOIN is used with\n an ON clause, CROSS JOIN\n is used otherwise."
},
{
"para": "In general, parentheses can be ignored in join expressions\n containing only inner join operations. MySQL also supports\n nested joins. See ."
},
{
"para": "Index hints can be specified to affect how the MySQL optimizer\n makes use of indexes. For more information, see\n . Optimizer hints and the\n optimizer_switch system variable are other\n ways to influence optimizer use of indexes. See\n , and\n ."
}
],
"id": "JOIN",
"syntax": []
},
{
"keywords": [
"UNION",
"ALL",
"DISTINCT"
],
"description": [
{
"para": "UNION is used to combine the\n result from multiple SELECT\n statements into a single result set."
},
{
"para": "The column names from the first\n SELECT statement are used as the\n column names for the results returned. Selected columns listed\n in corresponding positions of each\n SELECT statement should have the\n same data type. (For example, the first column selected by the\n first statement should have the same type as the first column\n selected by the other statements.)"
}
],
"id": "UNION",
"syntax": [
{
"programlisting": ">\nSELECT ...\nUNION [ALL | DISTINCT] SELECT ...\n[UNION [ALL | DISTINCT] SELECT ...]"
}
]
},
{
"keywords": [
"DUAL"
],
"description": [
{
"para": "\n DUAL\n \n\n You are permitted to specify DUAL as a dummy\n table name in situations where no tables are referenced:"
},
{
"programlisting": ">\nmysql> SELECT 1 + 1 FROM DUAL;\n -> 2"
},
{
"para": "DUAL is purely for the convenience of people\n who require that all SELECT\n statements should have FROM and possibly other\n clauses. MySQL may ignore the clauses. MySQL does not require\n FROM DUAL if no tables are referenced."
}
],
"id": "DUAL",
"syntax": [
{
"programlisting": ">\nSELECT\n [ALL | DISTINCT | DISTINCTROW ]\n [HIGH_PRIORITY]\n [STRAIGHT_JOIN]\n [SQL_SMALL_RESULT] [SQL_BIG_RESULT] [SQL_BUFFER_RESULT]\n [SQL_NO_CACHE] [SQL_CALC_FOUND_ROWS]\n select_expr [, select_expr ...]\n [FROM table_references\n [PARTITION partition_list]\n [WHERE where_condition]\n [GROUP BY {col_name | expr | position}, ... [WITH ROLLUP]]\n [HAVING where_condition]\n [WINDOW window_name AS (window_spec)\n [, window_name AS (window_spec)] ...]\n [ORDER BY {col_name | expr | position}\n [ASC | DESC], ... [WITH ROLLUP]]\n [LIMIT {[offset,] row_count | row_count OFFSET offset}]\n [INTO OUTFILE 'file_name'\n [CHARACTER SET charset_name]\n export_options\n | INTO DUMPFILE 'file_name'\n | INTO var_name [, var_name]]\n [FOR {UPDATE | SHARE} [OF tbl_name [, tbl_name] ...] [NOWAIT | SKIP LOCKED] \n | LOCK IN SHARE MODE]]"
}
]
},
{
"keywords": [
"UPDATE",
"BY",
"LOW_PRIORITY",
"IGNORE",
"SET",
"ORDER",
"LIMIT",
"WHERE"
],
"description": [
{
"para": "For the single-table syntax, the\n UPDATE statement updates columns of\n existing rows in the named table with new values. The\n SET clause indicates which columns to modify\n and the values they should be given. Each value can be given as an\n expression, or the keyword DEFAULT to set a\n column explicitly to its default value. The\n WHERE clause, if given, specifies the\n conditions that identify which rows to update. With no\n WHERE clause, all rows are updated. If the\n ORDER BY clause is specified, the rows are\n updated in the order that is specified. The\n LIMIT clause places a limit on the number of\n rows that can be updated."
},
{
"para": "For the multiple-table syntax,\n UPDATE updates rows in each table\n named in table_references that satisfy\n the conditions. Each matching row is updated once, even if it\n matches the conditions multiple times. For multiple-table syntax,\n ORDER BY and LIMIT cannot be\n used."
},
{
"para": "For partitioned tables, both the single-single and multiple-table\n forms of this statement support the use of a\n PARTITION option as part of a table reference.\n This option takes a list of one or more partitions or\n subpartitions (or both). Only the partitions (or subpartitions)\n listed are checked for matches, and a row that is not in any of\n these partitions or subpartitions is not updated, whether it\n satisfies the where_condition or not."
},
{
"para": "For more information and examples, see\n ."
},
{
"para": "where_condition is an expression that\n evaluates to true for each row to be updated. For expression\n syntax, see ."
},
{
"para": "table_references and\n where_condition are specified as\n described in ."
},
{
"para": "You need the UPDATE privilege only\n for columns referenced in an UPDATE\n that are actually updated. You need only the\n SELECT privilege for any columns\n that are read but not modified."
},
{
"para": "The UPDATE statement supports the\n following modifiers:"
},
{
"itemizedlist": [
[
{
"para": "With the LOW_PRIORITY modifier, execution\n of the UPDATE is delayed until\n no other clients are reading from the table. This affects only\n storage engines that use only table-level locking (such as\n MyISAM, MEMORY, and\n MERGE)."
},
{
"indexterm": "LOW_PRIORITY\n UPDATE modifier"
}
],
[
{
"para": "With the IGNORE modifier, the update\n statement does not abort even if errors occur during the\n update. Rows for which duplicate-key conflicts occur on a\n unique key value are not updated. Rows updated to values that\n would cause data conversion errors are updated to the closest\n valid values instead. For more information, see\n ."
},
{
"indexterm": "IGNORE\n UPDATE modifier"
}
]
]
}
],
"id": "UPDATE",
"syntax": [
{
"para": "UPDATE is a DML statement that\n modifies rows in a table."
},
{
"para": "An UPDATE statement can start with\n a WITH clause to define common\n table expressions accessible within the\n UPDATE. See ."
},
{
"para": "Single-table syntax:"
},
{
"programlisting": ">\nUPDATE [LOW_PRIORITY] [IGNORE] table_reference\n SET assignment_list\n [WHERE where_condition]\n [ORDER BY ...]\n [LIMIT row_count]\n\nvalue:\n {expr | DEFAULT}\n\nassignment:\n col_name = value\n\nassignment_list:\n assignment [, assignment] ..."
},
{
"para": "Multiple-table syntax:"
},
{
"programlisting": ">\nUPDATE [LOW_PRIORITY] [IGNORE] table_references\n SET assignment_list\n [WHERE where_condition]"
}
]
},
{
"keywords": [
"PREPARE"
],
"description": [
{
"para": "The PREPARE statement prepares a\n SQL statement and assigns it a name,\n stmt_name, by which to refer to the\n statement later. The prepared statement is executed with\n EXECUTE and released with\n DEALLOCATE PREPARE. For examples,\n see ."
},
{
"para": "Statement names are not case-sensitive.\n preparable_stmt is either a string\n literal or a user variable that contains the text of the SQL\n statement. The text must represent a single statement, not\n multiple statements. Within the statement, ?\n characters can be used as parameter markers to indicate where data\n values are to be bound to the query later when you execute it. The\n ? characters should not be enclosed within\n quotation marks, even if you intend to bind them to string values.\n Parameter markers can be used only where data values should\n appear, not for SQL keywords, identifiers, and so forth."
},
{
"para": "If a prepared statement with the given name already exists, it is\n deallocated implicitly before the new statement is prepared. This\n means that if the new statement contains an error and cannot be\n prepared, an error is returned and no statement with the given\n name exists."
},
{
"para": "The scope of a prepared statement is the session within which it\n is created, which as several implications:"
},
{
"itemizedlist": [
[
{
"para": "A prepared statement created in one session is not available\n to other sessions."
}
],
[
{
"para": "When a session ends, whether normally or abnormally, its\n prepared statements no longer exist. If auto-reconnect is\n enabled, the client is not notified that the connection was\n lost. For this reason, clients may wish to disable\n auto-reconnect. See ."
}
],
[
{
"para": "A prepared statement created within a stored program continues\n to exist after the program finishes executing and can be\n executed outside the program later."
}
],
[
{
"para": "A statement prepared in stored program context cannot refer to\n stored procedure or function parameters or local variables\n because they go out of scope when the program ends and would\n be unavailable were the statement to be executed later outside\n the program. As a workaround, refer instead to user-defined\n variables, which also have session scope; see\n ."
}
]
]
}
],
"id": "PREPARE",
"syntax": [
{
"programlisting": ">\nPREPARE stmt_name FROM preparable_stmt"
}
]
},
{
"keywords": [
"EXECUTE",
"USING"
],
"description": [
{
"para": "After preparing a statement with\n PREPARE, you execute it with an\n EXECUTE statement that refers to\n the prepared statement name. If the prepared statement contains\n any parameter markers, you must supply a USING\n clause that lists user variables containing the values to be bound\n to the parameters. Parameter values can be supplied only by user\n variables, and the USING clause must name\n exactly as many variables as the number of parameter markers in\n the statement."
},
{
"para": "You can execute a given prepared statement multiple times, passing\n different variables to it or setting the variables to different\n values before each execution."
}
],
"id": "EXECUTE statement",
"syntax": [
{
"programlisting": ">\nEXECUTE stmt_name\n [USING @var_name [, @var_name] ...]"
}
]
},
{
"keywords": [
"DEALLOCATE",
"PREPARE",
"DROP"
],
"description": [
{
"para": "To deallocate a prepared statement produced with\n PREPARE, use a\n DEALLOCATE PREPARE statement that\n refers to the prepared statement name. Attempting to execute a\n prepared statement after deallocating it results in an error. If\n too many prepared statements are created and not deallocated by\n either the DEALLOCATE PREPARE statement or the\n end of the session, you might encounter the upper limit enforced\n by the max_prepared_stmt_count\n system variable."
}
],
"id": "DEALLOCATE PREPARE",
"syntax": [
{
"programlisting": ">\n{DEALLOCATE | DROP} PREPARE stmt_name"
}
]
},
{
"keywords": [
"PURGE",
"BINARY",
"MASTER",
"LOGS",
"BEFORE",
"TO"
],
"description": [
{
"para": "The binary log is a set of files that contain information about\n data modifications made by the MySQL server. The log consists of\n a set of binary log files, plus an index file (see\n )."
},
{
"para": "The PURGE BINARY LOGS statement\n deletes all the binary log files listed in the log index file\n prior to the specified log file name or date.\n BINARY and MASTER are\n synonyms. Deleted log files also are removed from the list\n recorded in the index file, so that the given log file becomes\n the first in the list."
},
{
"para": "PURGE BINARY LOGS requires the\n BINLOG_ADMIN privilege. This\n statement has no effect if the server was not started with the\n option to enable binary\n logging."
}
],
"id": "PURGE BINARY LOGS",
"syntax": [
{
"programlisting": ">\nPURGE { BINARY | MASTER } LOGS {\n TO 'log_name'\n | BEFORE datetime_expr\n}"
}
]
},
{
"keywords": [
"RESET",
"MASTER"
],
"description": [
{
"para": "RESET MASTER requires the\n RELOAD privilege."
},
{
"para": "For a server where binary logging is enabled\n (log_bin is\n ON), RESET MASTER deletes\n all existing binary log files and resets the binary log index\n file, resetting the server to its state before binary logging\n was started. A new empty binary log file is created so that\n binary logging can be restarted."
},
{
"para": "For a server where GTIDs are in use\n (gtid_mode is\n ON), issuing RESET MASTER\n resets the GTID execution history. The value of the\n gtid_purged system variable is\n set to an empty string (''), the global value\n (but not the session value) of the\n gtid_executed system variable\n is set to an empty string, and the\n mysql.gtid_executed table is cleared (see\n ). If the\n GTID-enabled server has binary logging enabled,\n RESET MASTER also resets the\n binary log as described above. Note that\n RESET MASTER is the method to\n reset the GTID execution history even if the GTID-enabled server\n is a replication slave where binary logging is disabled;\n RESET SLAVE has no effect on the\n GTID execution history. For more information on resetting the\n GTID execution history, see\n ."
},
{
"para": "Issuing RESET MASTER without the optional\n TO clause deletes all binary log files listed\n in the index file, resets the binary log index file to be empty,\n and creates a new binary log file starting at\n 1. Use the optional TO\n clause to start the binary log file index from a number other\n than 1 after the reset."
},
{
"para": "Using RESET MASTER with the\n TO clause to specify a binary log file index\n number to start from simplifies failover by providing a single\n statement alternative to the FLUSH BINARY\n LOGS and\n PURGE BINARY\n LOGS TO statements. Check that you are using a\n reasonable value for the index number. If you enter an incorrect\n value, you can correct this by issuing another\n RESET MASTER statement with or\n without the TO clause. If you do not correct\n a value that is out of range, the server cannot be restarted."
},
{
"para": "The following example demonstrates TO clause\n usage:"
},
{
"programlisting": ">\nRESET MASTER TO 1234;\n\nSHOW BINARY LOGS;\n+-------------------+-----------+-----------+\n| Log_name | File_size | Encrypted |\n+-------------------+-----------+-----------+\n| master-bin.001234 | 154 | No |\n+-------------------+-----------+-----------+"
}
],
"id": "RESET MASTER",
"syntax": [
{
"programlisting": ">\nRESET MASTER [TO binary_log_file_index_number]"
}
]
},
{
"keywords": [
"SET",
"SQL_LOG_BIN"
],
"description": [
{
"para": "The sql_log_bin variable\n controls whether logging to the binary log is enabled for the\n current session (assuming that the binary log itself is\n enabled). The default value is ON. To disable\n or enable binary logging for the current session, set the\n session sql_log_bin variable to\n OFF or ON."
},
{
"para": "Set this variable to OFF for a session to\n temporarily disable binary logging while making changes to the\n master you do not want replicated to the slave."
},
{
"para": "Setting the session value of this system variable is a\n restricted operation. The session user must have privileges\n sufficient to set restricted session variables. See\n ."
},
{
"para": "It is not possible to set the session value of\n sql_log_bin within a\n transaction or subquery."
},
{
"para": "Setting this variable to OFF\n prevents new GTIDs from being assigned to transactions in the\n binary log. If you are using GTIDs for replication,\n this means that even when binary logging is later enabled again,\n the GTIDs written into the log from this point do not account\n for any transactions that occurred in the meantime, so in effect\n those transactions are lost."
},
{
"para": "mysqldump adds a SET\n @@SESSION.sql_log_bin=0 statement to a dump file from\n a server where GTIDs are in use, which disables binary logging\n while the dump file is being reloaded. The statement prevents\n new GTIDs from being generated and assigned to the transactions\n in the dump file as they are executed, so that the original\n GTIDs for the transactions are used."
}
],
"id": "SET sql_log_bin",
"syntax": [
{
"programlisting": ">\nSET sql_log_bin = {OFF|ON}"
}
]
},
{
"keywords": [
"CHANGE",
"MASTER",
"TO",
"IGNORE_SERVER_IDS",
"MASTER_BIND",
"MASTER_AUTO_POSITION",
"MASTER_HEARTBEAT_PERIOD",
"MASTER_HOST",
"MASTER_USER",
"MASTER_PASSWORD",
"MASTER_PORT",
"MASTER_LOG_FILE",
"MASTER_LOG_POS",
"MASTER_CONNECT_RETRY",
"MASTER_RETRY_COUNT",
"RELAY_LOG_POS",
"RELAY_LOG_FILE",
"MASTER_SSL",
"MASTER_SSL_CA",
"MASTER_SSL_CERT",
"MASTER_SSL_KEY",
"MASTER_SSL_CIPHER",
"MASTER_SSL_VERIFY_SERVER_CERT",
"MASTER_SSL_CRL",
"MASTER_SSL_CRLPATH",
"MASTER_TLS_VERSION",
"FOR",
"CHANNEL",
"MASTER_COMPRESSION_ALGORITHMS",
"MASTER_ZSTD_COMPRESSION_LEVEL",
"PRIVILEGE_CHECKS_USER"
],
"description": [
{
"para": "CHANGE MASTER TO changes the\n parameters that the slave server uses for connecting to the\n master server, for reading the master binary log, and reading\n the slave relay log. It also updates the contents of the master\n info and relay log info repositories (see\n ). CHANGE\n MASTER TO requires the\n REPLICATION_SLAVE_ADMIN or\n SUPER privilege."
},
{
"para": "You can issue CHANGE MASTER TO statements on\n a running slave without first stopping it, depending on the\n states of the slave SQL thread and slave I/O thread. The rules\n governing such use are provided later in this section."
},
{
"para": "When using a multithreaded slave (in other words\n slave_parallel_workers is\n greater than 0), stopping the slave can cause\n gaps in the sequence of transactions that have\n been executed from the relay log, regardless of whether the\n slave was stopped intentionally or otherwise. When such gaps\n exist, issuing CHANGE MASTER TO\n fails. The solution in this situation is to issue\n START SLAVE UNTIL\n SQL_AFTER_MTS_GAPS which ensures that the gaps are\n closed."
},
{
"para": "The optional FOR CHANNEL\n channel clause enables you\n to name which replication channel the statement applies to.\n Providing a FOR CHANNEL\n channel clause applies the\n CHANGE MASTER TO statement to a specific\n replication channel, and is used to add a new channel or modify\n an existing channel. For example, to add a new channel called\n channel2:"
},
{
"programlisting": ">CHANGE MASTER TO MASTER_HOST=host1, MASTER_PORT=3002 FOR CHANNEL 'channel2'"
},
{
"para": "If no clause is named and no extra channels exist, the statement\n applies to the default channel."
},
{
"para": "When using multiple replication channels, if a CHANGE\n MASTER TO statement does not name a channel using a\n FOR CHANNEL\n channel clause, an error\n occurs. See for more\n information."
},
{
"para": "Options not specified retain their value, except as indicated in\n the following discussion. Thus, in most cases, there is no need\n to specify options that do not change."
},
{
"para": "MASTER_HOST, MASTER_USER,\n MASTER_PASSWORD, and\n MASTER_PORT provide information to the slave\n about how to connect to its master:"
},
{
"itemizedlist": [
[
{
"para": "MASTER_HOST and\n MASTER_PORT are the host name (or IP\n address) of the master host and its TCP/IP port."
},
{
"note": "\n Replication cannot use Unix socket files. You must be able\n to connect to the master MySQL server using TCP/IP.\n "
},
{
"para": "If you specify the MASTER_HOST or\n MASTER_PORT option, the slave assumes\n that the master server is different from before (even if the\n option value is the same as its current value.) In this\n case, the old values for the master binary log file name and\n position are considered no longer applicable, so if you do\n not specify MASTER_LOG_FILE and\n MASTER_LOG_POS in the statement,\n MASTER_LOG_FILE='' and\n MASTER_LOG_POS=4 are silently appended to\n it."
},
{
"para": "Setting MASTER_HOST='' (that is, setting\n its value explicitly to an empty string) is\n not the same as not setting\n MASTER_HOST at all. Trying to set\n MASTER_HOST to an empty string fails with\n an error."
},
{
"para": "Values used for MASTER_HOST and other\n CHANGE MASTER TO options are checked for\n linefeed (\\n or 0x0A)\n characters; the presence of such characters in these values\n causes the statement to fail with\n ER_MASTER_INFO. (Bug\n #11758581, Bug #50801)"
}
],
[
{
"para": "MASTER_USER and\n MASTER_PASSWORD are the user name and\n password of the account to use for connecting to the master."
},
{
"para": "MASTER_USER cannot be made empty; setting\n MASTER_USER = '' or leaving it unset when\n setting a value for MASTER_PASSWORD\n causes an error (Bug #13427949)."
},
{
"para": "The password used for a MySQL Replication slave account in a\n CHANGE MASTER TO statement is limited to\n 32 characters in length; trying to use a password of more\n than 32 characters causes CHANGE MASTER\n TO to fail."
},
{
"para": "The text of a running CHANGE MASTER\n TO statement, including values for\n MASTER_USER and\n MASTER_PASSWORD, can be seen in the\n output of a concurrent SHOW\n PROCESSLIST statement. (The complete text of a\n START SLAVE statement is also\n visible to SHOW PROCESSLIST.)"
}
]
]
},
{
"para": "PRIVILEGE_CHECKS_USER (available as of MySQL\n 8.0.18) names a user account that supplies a security context\n for the specified channel. NULL, which is the\n default, means no security context is used. If you do not\n specify a channel and no other channels exist, the statement is\n applied to the default channel. For example, to start privilege\n checks on the channel channel_1 on a running\n replication slave, issue the following statements:"
},
{
"programlisting": ">\nmysql> STOP SLAVE FOR CHANNEL 'channel_1';\nmysql> CHANGE MASTER TO PRIVILEGE_CHECKS_USER = 'priv_repl'@'%.example.com' FOR CHANNEL 'channel_1'; \nmysql> START SLAVE FOR CHANNEL 'channel_1';"
},
{
"para": "The user name and host name for the user account must follow the\n syntax described in , and the\n user must not be an anonymous user (with a blank user name) or\n the CURRENT_USER. The account must have the\n REPLICATION_APPLIER privilege,\n plus the required privileges to execute the transactions\n replicated on the channel. When you restart the replication\n channel, the privilege checks are applied from that point on.\n For more information, see\n ."
},
{
"para": "MASTER_COMPRESSION_ALGORITHMS and\n MASTER_ZSTD_COMPRESSION_LEVEL (available as\n of MySQL 8.0.18) enable control over the use of compression for\n connections to the master:"
},
{
"itemizedlist": [
[
{
"para": "MASTER_COMPRESSION_ALGORITHMS specifies\n the permitted compression algorithms. The available\n algorithms are the same as for the\n protocol_compression_algorithms\n system variable. The default value is\n uncompressed."
},
{
"para": "The value of\n MASTER_COMPRESSION_ALGORITHMS applies\n only if the\n slave_compressed_protocol\n system variable is disabled. If\n slave_compressed_protocol\n is enabled, it takes precedence over\n MASTER_COMPRESSION_ALGORITHMS and\n connections to the master use zlib\n compression if both master and slave support that algorithm."
}
],
[
{
"para": "MASTER_ZSTD_COMPRESSION_LEVEL is the\n compression level to use for connections that use the\n zstd compression algorithm. The permitted\n levels are from 1 to 22, with larger values indicating\n increasing levels of compression. The default\n zstd compression level is 3. The\n compression level setting has no effect on connections that\n do not use zstd compression."
}
]
]
},
{
"para": "For more information, see\n ."
},
{
"para": "The MASTER_SSL_xxx\n options and the MASTER_TLS_VERSION option\n specify how the slave uses encryption and ciphers to secure the\n replication connection. These options can be changed even on\n slaves that are compiled without SSL support. They are saved to\n the master info repository, but are ignored if the slave does\n not have SSL support enabled. The\n MASTER_SSL_xxx and\n MASTER_TLS_VERSION options perform the same\n functions as the\n --ssl-xxx and\n --tls-version client options described in\n . The\n correspondence between the two sets of options, and the use of\n the MASTER_SSL_xxx\n and MASTER_TLS_VERSION options to set up a\n secure connection, is explained in\n ."
},
{
"para": "To enable RSA key pair-based password exchange, specify either\n the MASTER_PUBLIC_KEY_PATH or the\n GET_MASTER_PUBLIC_KEY=1 option. Either of\n these options provides the RSA public key to the slave:"
},
{
"itemizedlist": [
[
{
"para": "MASTER_PUBLIC_KEY_PATH indicates the path\n name to a file containing a slave-side copy of the public\n key required by the master for RSA key pair-based password\n exchange. The file must be in PEM format. This option\n applies to slaves that authenticate with the\n sha256_password or\n caching_sha2_password authentication\n plugin. (For sha256_password,\n MASTER_PUBLIC_KEY_PATH can be used only\n if MySQL was built using OpenSSL.)"
}
],
[
{
"para": "GET_MASTER_PUBLIC_KEY indicates whether\n to request from the master the public key required for RSA\n key pair-based password exchange. This option applies to\n slaves that authenticate with the\n caching_sha2_password authentication\n plugin. For connections by accounts that authenticate using\n this plugin, the master does not send the public key unless\n requested, so it must be requested or specified in the\n client. If MASTER_PUBLIC_KEY_PATH is\n given and specifies a valid public key file, it takes\n precedence over GET_MASTER_PUBLIC_KEY."
}
]
]
},
{
"para": "The MASTER_HEARTBEAT_PERIOD,\n MASTER_CONNECT_RETRY, and\n MASTER_RETRY_COUNT options control how the\n slave recognizes that the connection to the master has been lost\n and makes attempts to reconnect."
},
{
"itemizedlist": [
[
{
"para": "The slave_net_timeout\n system variable specifies the number of seconds that the\n slave waits for either more data or a heartbeat signal from\n the master, before the slave considers the connection\n broken, aborts the read, and tries to reconnect. The default\n value is 60 seconds (one minute)."
}
],
[
{
"para": "The heartbeat interval, which stops the connection timeout\n occurring in the absence of data if the connection is still\n good, is controlled by the\n MASTER_HEARTBEAT_PERIOD option. A\n heartbeat signal is sent to the slave after that number of\n seconds, and the waiting period is reset whenever the\n master's binary log is updated with an event. Heartbeats are\n therefore sent by the master only if there are no unsent\n events in the binary log file for a period longer than this.\n The heartbeat interval interval\n is a decimal value having the range 0 to 4294967 seconds and\n a resolution in milliseconds; the smallest nonzero value is\n 0.001. Setting interval to 0\n disables heartbeats altogether. The heartbeat interval\n defaults to half the value of the\n slave_net_timeout system\n variable. It is recorded in the master info log and shown in\n the\n replication_connection_configuration\n Performance Schema table. Issuing RESET\n SLAVE resets the heartbeat interval to the default\n value."
},
{
"para": "Note that a change to the value or default setting of\n slave_net_timeout does not\n automatically change the heartbeat interval, whether that\n has been set explicitly or is using a previously calculated\n default. A warning is issued if you set\n @@GLOBAL.slave_net_timeout to a value\n less than that of the current heartbeat interval. If\n slave_net_timeout is\n changed, you must also issue CHANGE\n MASTER TO to adjust the heartbeat interval to an\n appropriate value so that the heartbeat signal occurs before\n the connection timeout. If you do not do this, the heartbeat\n signal has no effect, and if no data is received from the\n master, the slave can make repeated reconnection attempts,\n creating zombie dump threads."
}
],
[
{
"para": "If the slave does need to reconnect, the first retry occurs\n immediately after the timeout.\n MASTER_CONNECT_RETRY specifies the\n interval between reconnection attempts, and\n MASTER_RETRY_COUNT limits the number of\n reconnection attempts. If both the default settings are\n used, the slave waits 60 seconds between reconnection\n attempts (MASTER_CONNECT_RETRY=60), and\n keeps attempting to reconnect at this rate for 60 days\n (MASTER_RETRY_COUNT=86400). These values\n are recorded in the master info log and shown in the\n replication_connection_configuration\n Performance Schema table.\n MASTER_RETRY_COUNT supersedes the\n server\n startup option."
}
]
]
},
{
"para": "MASTER_DELAY specifies how many seconds\n behind the master the slave must lag. An event received from the\n master is not executed until at least\n interval seconds later than its\n execution on the master. The default is 0. An error occurs if\n interval is not a nonnegative integer\n in the range from 0 to 231minus1.\n For more information, see ."
},
{
"para": "A CHANGE MASTER TO statement employing the\n MASTER_DELAY option can be executed on a\n running slave when the slave SQL thread is stopped."
},
{
"para": "MASTER_BIND is for use on replication slaves\n having multiple network interfaces, and determines which of the\n slave's network interfaces is chosen for connecting to the\n master."
},
{
"para": "The address configured with this option, if any, can be seen in\n the Master_Bind column of the output from\n SHOW SLAVE STATUS. In the master\n info repository table\n mysql.slave_master_info, the value can be\n seen as the Master_bind column."
},
{
"para": "The ability to bind a replication slave to a specific network\n interface is also supported by NDB Cluster."
},
{
"para": "MASTER_LOG_FILE and\n MASTER_LOG_POS are the coordinates at which\n the slave I/O thread should begin reading from the master the\n next time the thread starts. RELAY_LOG_FILE\n and RELAY_LOG_POS are the coordinates at\n which the slave SQL thread should begin reading from the relay\n log the next time the thread starts. If you specify either of\n MASTER_LOG_FILE or\n MASTER_LOG_POS, you cannot specify\n RELAY_LOG_FILE or\n RELAY_LOG_POS. If you specify either of\n MASTER_LOG_FILE or\n MASTER_LOG_POS, you also cannot specify\n MASTER_AUTO_POSITION = 1 (described later in\n this section). If neither of MASTER_LOG_FILE\n or MASTER_LOG_POS is specified, the slave\n uses the last coordinates of the slave SQL\n thread before CHANGE MASTER\n TO was issued. This ensures that there is no\n discontinuity in replication, even if the slave SQL thread was\n late compared to the slave I/O thread, when you merely want to\n change, say, the password to use."
},
{
"para": "RELAY_LOG_FILE can use either an absolute or\n relative path, and uses the same base name as\n MASTER_LOG_FILE. A CHANGE MASTER\n TO statement employing\n RELAY_LOG_FILE,\n RELAY_LOG_POS, or both options can be\n executed on a running slave when the slave SQL thread is\n stopped. Relay logs are preserved if at least one of the slave\n SQL thread and the slave I/O thread is running. If both threads\n are stopped, all relay log files are deleted unless at least one\n of RELAY_LOG_FILE or\n RELAY_LOG_POS is specified. Note that the\n Group Replication applier channel\n (group_replication_applier) has no I/O\n thread, only a SQL thread. For this channel, the relay logs are\n not preserved when the SQL thread is stopped."
},
{
"para": "When MASTER_AUTO_POSITION = 1 is used with\n CHANGE MASTER TO, the slave attempts to\n connect to the master using the GTID-based replication protocol.\n This option can be used with CHANGE MASTER TO\n only if both the slave SQL and slave I/O threads are stopped.\n Both the slave and the master must have GTIDs enabled\n (GTID_MODE=ON,\n ON_PERMISSIVE, or\n OFF_PERMISSIVE on the slave, and\n GTID_MODE=ON on the master).\n Auto-positioning is used for the connection, so the coordinates\n represented by MASTER_LOG_FILE and\n MASTER_LOG_POS are not used, and the use of\n either or both of these options together with\n MASTER_AUTO_POSITION = 1 causes an error. If\n multi-source replication is enabled on the slave, you need to\n set the MASTER_AUTO_POSITION = 1 option for\n each applicable replication channel."
},
{
"para": "With MASTER_AUTO_POSITION = 1 set, in the\n initial connection handshake, the slave sends a GTID set\n containing the transactions that it has already received,\n committed, or both. The master responds by sending all\n transactions recorded in its binary log whose GTID is not\n included in the GTID set sent by the slave. This exchange\n ensures that the master only sends the transactions with a GTID\n that the slave has not already recorded or committed. If the\n slave receives transactions from more than one master, as in the\n case of a diamond topology, the auto-skip function ensures that\n the transactions are not applied twice. For details of how the\n GTID set sent by the slave is computed, see\n ."
},
{
"para": "If any of the transactions that should be sent by the master\n have been purged from the master's binary log, or added to the\n set of GTIDs in the gtid_purged\n system variable by another method, the master sends the error\n ER_MASTER_HAS_PURGED_REQUIRED_GTIDS to\n the slave, and replication does not start. The GTIDs of the\n missing purged transactions are identified and listed in the\n master's error log in the warning message\n ER_FOUND_MISSING_GTIDS. Also, if during\n the exchange of transactions it is found that the slave has\n recorded or committed transactions with the master's UUID in the\n GTID, but the master itself has not committed them, the master\n sends the error\n ER_SLAVE_HAS_MORE_GTIDS_THAN_MASTER to\n the slave and replication does not start. For information on how\n to handle these situations, see\n ."
},
{
"para": "You can see whether replication is running with auto-positioning\n enabled by checking the Performance Schema\n replication_connection_status table\n or the output of SHOW SLAVE\n STATUS. Disabling the\n MASTER_AUTO_POSITION option again makes the\n slave revert to file-based replication, in which case you must\n also specify one or both of the\n MASTER_LOG_FILE or\n MASTER_LOG_POS options."
},
{
"para": "IGNORE_SERVER_IDS takes a comma-separated\n list of 0 or more server IDs. Events originating from the\n corresponding servers are ignored, with the exception of log\n rotation and deletion events, which are still recorded in the\n relay log."
},
{
"para": "In circular replication, the originating server normally acts as\n the terminator of its own events, so that they are not applied\n more than once. Thus, this option is useful in circular\n replication when one of the servers in the circle is removed.\n Suppose that you have a circular replication setup with 4\n servers, having server IDs 1, 2, 3, and 4, and server 3 fails.\n When bridging the gap by starting replication from server 2 to\n server 4, you can include IGNORE_SERVER_IDS =\n (3) in the CHANGE MASTER\n TO statement that you issue on server 4 to tell it to\n use server 2 as its master instead of server 3. Doing so causes\n it to ignore and not to propagate any statements that originated\n with the server that is no longer in use."
},
{
"para": "If IGNORE_SERVER_IDS contains the\n server's own ID and the server was started with the\n option\n enabled, an error results."
},
{
"para": "The master info repository and the output of\n SHOW SLAVE STATUS provide the\n list of servers that are currently ignored. For more\n information, see , and\n ."
},
{
"para": "If a CHANGE MASTER TO statement\n is issued without any IGNORE_SERVER_IDS\n option, any existing list is preserved. To clear the list of\n ignored servers, it is necessary to use the option with an empty\n list:"
},
{
"programlisting": ">\nCHANGE MASTER TO IGNORE_SERVER_IDS = ();"
},
{
"para": "RESET SLAVE ALL clears\n IGNORE_SERVER_IDS."
},
{
"para": "Invoking CHANGE MASTER TO causes\n the previous values for MASTER_HOST,\n MASTER_PORT,\n MASTER_LOG_FILE, and\n MASTER_LOG_POS to be written to the error\n log, along with other information about the slave's state\n prior to execution."
},
{
"para": "CHANGE MASTER TO causes an implicit commit of\n an ongoing transaction. See ."
},
{
"para": "From MySQL 5.7, the strict requirement to execute\n STOP SLAVE prior to issuing any\n CHANGE MASTER TO statement (and\n START SLAVE afterward) is\n removed. Instead of depending on whether the slave is stopped,\n the behavior of CHANGE MASTER TO depends on\n the states of the slave SQL thread and slave I/O threads; which\n of these threads is stopped or running now determines the\n options that can or cannot be used with a CHANGE MASTER\n TO statement at a given point in time. The rules for\n making this determination are listed here:"
},
{
"itemizedlist": [
[
{
"para": "If the SQL thread is stopped, you can execute\n CHANGE MASTER TO using any combination\n that is otherwise allowed of\n RELAY_LOG_FILE,\n RELAY_LOG_POS, and\n MASTER_DELAY options, even if the slave\n I/O thread is running. No other options may be used with\n this statement when the I/O thread is running."
}
],
[
{
"para": "If the I/O thread is stopped, you can execute\n CHANGE MASTER TO using any of the options\n for this statement (in any allowed combination)\n except\n RELAY_LOG_FILE,\n RELAY_LOG_POS,\n MASTER_DELAY, or\n MASTER_AUTO_POSITION = 1 even when the\n SQL thread is running."
}
],
[
{
"para": "Both the SQL thread and the I/O thread must be stopped\n before issuing a CHANGE MASTER TO\n statement that employs MASTER_AUTO_POSITION =\n 1."
}
]
]
},
{
"para": "You can check the current state of the slave SQL and I/O threads\n using SHOW SLAVE STATUS. Note\n that the Group Replication applier channel\n (group_replication_applier) has no I/O\n thread, only a SQL thread."
},
{
"para": "For more information, see\n ."
},
{
"para": "If you are using statement-based replication and temporary\n tables, it is possible for a CHANGE MASTER TO\n statement following a STOP SLAVE statement to\n leave behind temporary tables on the slave. A warning\n (ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO)\n is now issued whenever this occurs. You can avoid this in such\n cases by making sure that the value of the\n Slave_open_temp_tables system\n status variable is equal to 0 prior to executing such a\n CHANGE MASTER TO statement."
},
{
"para": "CHANGE MASTER TO is useful for\n setting up a slave when you have the snapshot of the master and\n have recorded the master binary log coordinates corresponding to\n the time of the snapshot. After loading the snapshot into the\n slave to synchronize it with the master, you can run\n CHANGE MASTER TO\n MASTER_LOG_FILE='log_name',\n MASTER_LOG_POS=log_pos on\n the slave to specify the coordinates at which the slave should\n begin reading the master binary log."
},
{
"para": "The following example changes the master server the slave uses\n and establishes the master binary log coordinates from which the\n slave begins reading. This is used when you want to set up the\n slave to replicate the master:"
},
{
"programlisting": ">\nCHANGE MASTER TO\n MASTER_HOST='master2.example.com',\n MASTER_USER='replication',\n MASTER_PASSWORD='password',\n MASTER_PORT=3306,\n MASTER_LOG_FILE='master2-bin.001',\n MASTER_LOG_POS=4,\n MASTER_CONNECT_RETRY=10;"
},
{
"para": "The next example shows an operation that is less frequently\n employed. It is used when the slave has relay log files that you\n want it to execute again for some reason. To do this, the master\n need not be reachable. You need only use\n CHANGE MASTER TO and start the\n SQL thread (START SLAVE SQL_THREAD):"
},
{
"programlisting": ">\nCHANGE MASTER TO\n RELAY_LOG_FILE='slave-relay-bin.006',\n RELAY_LOG_POS=4025;"
}
],
"id": "CHANGE MASTER TO",
"syntax": [
{
"programlisting": ">\nCHANGE MASTER TO option [, option] ... [ channel_option ]\n\noption:\n MASTER_BIND = 'interface_name'\n | MASTER_HOST = 'host_name'\n | MASTER_USER = 'user_name'\n | MASTER_PASSWORD = 'password'\n | MASTER_PORT = port_num\n | PRIVILEGE_CHECKS_USER = {'account' | NULL}\n | MASTER_CONNECT_RETRY = interval\n | MASTER_RETRY_COUNT = count\n | MASTER_DELAY = interval\n | MASTER_HEARTBEAT_PERIOD = interval\n | MASTER_LOG_FILE = 'master_log_name'\n | MASTER_LOG_POS = master_log_pos\n | MASTER_AUTO_POSITION = {0|1}\n | RELAY_LOG_FILE = 'relay_log_name'\n | RELAY_LOG_POS = relay_log_pos\n | MASTER_COMPRESSION_ALGORITHMS = 'value'\n | MASTER_ZSTD_COMPRESSION_LEVEL = level\n | MASTER_SSL = {0|1}\n | MASTER_SSL_CA = 'ca_file_name'\n | MASTER_SSL_CAPATH = 'ca_directory_name'\n | MASTER_SSL_CERT = 'cert_file_name'\n | MASTER_SSL_CRL = 'crl_file_name'\n | MASTER_SSL_CRLPATH = 'crl_directory_name'\n | MASTER_SSL_KEY = 'key_file_name'\n | MASTER_SSL_CIPHER = 'cipher_list'\n | MASTER_SSL_VERIFY_SERVER_CERT = {0|1}\n | MASTER_TLS_VERSION = 'protocol_list'\n | MASTER_PUBLIC_KEY_PATH = 'key_file_name'\n | GET_MASTER_PUBLIC_KEY = {0|1}\n | IGNORE_SERVER_IDS = (server_id_list)\n\nchannel_option:\n FOR CHANNEL channel\n\nserver_id_list:\n [server_id [, server_id] ... ]"
}
]
},
{
"keywords": [
"CHANGE",
"REPLICATION",
"FILTER",
"REPLICATE_DO_DB",
"REPLICATE_IGNORE_DB",
"REPLICATE_DO_TABLE",
"REPLICATE_IGNORE_TABLE",
"REPLICATE_WILD_DO_TABLE",
"REPLICATE_WILD_IGNORE_TABLE",
"REPLICATE_REWRITE_DB"
],
"description": [
{
"para": "CHANGE REPLICATION FILTER sets one or more\n replication filtering rules on the slave in the same way as\n starting the slave mysqld with replication\n filtering options such as\n or\n .\n Unlike the case with the server options, this statement does not\n require restarting the server to take effect, only that the\n slave SQL thread be stopped using\n STOP SLAVE\n SQL_THREAD first (and restarted with\n START SLAVE\n SQL_THREAD afterwards). CHANGE\n REPLICATION FILTER requires the\n REPLICATION_SLAVE_ADMIN or\n SUPER privilege. Use the\n FOR CHANNEL\n channel clause to make a\n replication filter specific to a replication channel, for\n example on a multi-source replication slave. Filters applied\n without a specific FOR CHANNEL clause are\n considered global filters, meaning that they are applied to all\n replication channels."
},
{
"para": "\n \n Global replication filters cannot be set on a MySQL server\n instance that is configured for Group Replication, because\n filtering transactions on some servers would make the group\n unable to reach agreement on a consistent state. Channel\n specific replication filters can be set on replication\n channels that are not directly involved with Group\n Replication, such as where a group member also acts as a\n replication slave to a master that is outside the group.\n They cannot be set on the\n group_replication_applier or\n group_replication_recovery channels.\n \n "
},
{
"para": "The following list shows the CHANGE REPLICATION\n FILTER options and how they relate to\n server options:"
},
{
"itemizedlist": [
[
{
"para": "REPLICATE_DO_DB: Include updates based on\n database name. Equivalent to\n ."
}
],
[
{
"para": "REPLICATE_IGNORE_DB: Exclude updates\n based on database name. Equivalent to\n ."
}
],
[
{
"para": "REPLICATE_DO_TABLE: Include updates based\n on table name. Equivalent to\n ."
}
],
[
{
"para": "REPLICATE_IGNORE_TABLE: Exclude updates\n based on table name. Equivalent to\n ."
}
],
[
{
"para": "REPLICATE_WILD_DO_TABLE: Include updates\n based on wildcard pattern matching table name. Equivalent to\n ."
}
],
[
{
"para": "REPLICATE_WILD_IGNORE_TABLE: Exclude\n updates based on wildcard pattern matching table name.\n Equivalent to\n ."
}
],
[
{
"para": "REPLICATE_REWRITE_DB: Perform updates on\n slave after substituting new name on slave for specified\n database on master. Equivalent to\n ."
}
]
]
},
{
"para": "The precise effects of REPLICATE_DO_DB and\n REPLICATE_IGNORE_DB filters are dependent on\n whether statement-based or row-based replication is in effect.\n See , for more information."
},
{
"para": "Multiple replication filtering rules can be created in a single\n CHANGE REPLICATION FILTER statement by\n separating the rules with commas, as shown here:"
},
{
"programlisting": ">\nCHANGE REPLICATION FILTER\n REPLICATE_DO_DB = (d1), REPLICATE_IGNORE_DB = (d2);"
},
{
"para": "Issuing the statement just shown is equivalent to starting the\n slave mysqld with the options\n \n ."
},
{
"para": "On a multi-source replication slave, which uses multiple\n replication channels to process transaction from different\n sources, use the FOR CHANNEL\n channel clause to set a\n replication filter on a replication channel:"
},
{
"programlisting": ">CHANGE REPLICATION FILTER REPLICATE_DO_DB = (d1) FOR CHANNEL channel_1;"
},
{
"para": "This enables you to create a channel specific replication filter\n to filter out selected data from a source. When a FOR\n CHANNEL clause is provided, the replication filter\n statement acts on that slave replication channel removing any\n existing replication filter which has the same filter type as\n the specified replication filters, and replacing them with the\n specified filter. Filter types not explicitly listed in the\n statement are not modified. If issued against a slave\n replication channel which is not configured, the statement fails\n with an ER_SLAVE_CONFIGURATION error. If\n issued against Group Replication channels, the statement fails\n with an\n ER_SLAVE_CHANNEL_OPERATION_NOT_ALLOWED\n error."
},
{
"para": "On a replication slave with multiple replication channels\n configured, issuing CHANGE REPLICATION\n FILTER with no FOR CHANNEL clause\n configures the replication filter for every configured slave\n replication channel, and for the global replication filters. For\n every filter type, if the filter type is listed in the\n statement, then any existing filter rules of that type are\n replaced by the filter rules specified in the most recently\n issued statement, otherwise the old value of the filter type is\n retained. For more information see\n ."
},
{
"para": "If the same filtering rule is specified multiple times, only the\n last such rule is actually used. For\n example, the two statements shown here have exactly the same\n effect, because the first REPLICATE_DO_DB\n rule in the first statement is ignored:"
},
{
"programlisting": ">\nCHANGE REPLICATION FILTER\n REPLICATE_DO_DB = (db1, db2), REPLICATE_DO_DB = (db3, db4);\n\nCHANGE REPLICATION FILTER\n REPLICATE_DO_DB = (db3, db4);"
},
{
"para": "Names of tables and database not containing any special\n characters need not be quoted. Values used with\n REPLICATION_WILD_TABLE and\n REPLICATION_WILD_IGNORE_TABLE are string\n expressions, possibly containing (special) wildcard characters,\n and so must be quoted. This is shown in the following example\n statements:"
},
{
"programlisting": ">\nCHANGE REPLICATION FILTER\n REPLICATE_WILD_DO_TABLE = ('db1.old%');\n\nCHANGE REPLICATION FILTER\n REPLICATE_WILD_IGNORE_TABLE = ('db1.new%', 'db2.new%');"
},
{
"para": "Values used with REPLICATE_REWRITE_DB\n represent pairs of database names; each\n such value must be enclosed in parentheses. The following\n statement rewrites statements occurring on database\n db1 on the master to database\n db2 on the slave:"
},
{
"programlisting": ">\nCHANGE REPLICATION FILTER REPLICATE_REWRITE_DB = ((db1, db2));"
},
{
"para": "The statement just shown contains two sets of parentheses, one\n enclosing the pair of database names, and the other enclosing\n the entire list. This is perhaps more easily seen in the\n following example, which creates two\n rewrite-db rules, one rewriting database\n dbA to dbB, and one\n rewriting database dbC to\n dbD:"
},
{
"programlisting": ">\nCHANGE REPLICATION FILTER\n REPLICATE_REWRITE_DB = ((dbA, dbB), (dbC, dbD));"
},
{
"para": "The CHANGE REPLICATION FILTER\n statement replaces replication filtering rules only for the\n filter types and replication channels affected by the statement,\n and leaves other rules and channels unchanged. If you want to\n unset all filters of a given type, set the filter's value\n to an explicitly empty list, as shown in this example, which\n removes all existing REPLICATE_DO_DB and\n REPLICATE_IGNORE_DB rules:"
},
{
"programlisting": ">\nCHANGE REPLICATION FILTER\n REPLICATE_DO_DB = (), REPLICATE_IGNORE_DB = ();"
},
{
"para": "Setting a filter to empty in this way removes all existing\n rules, does not create any new ones, and does not restore any\n rules set at mysqld startup using \n options on the command line or in the configuration file."
},
{
"para": "The RESET SLAVE\n ALL statement removes channel specific replication\n filters that were set on channels deleted by the statement. When\n the deleted channel or channels are recreated, any global\n replication filters specified for the slave are copied to them,\n and no channel specific replication filters are applied."
},
{
"para": "For more information, see ."
}
],
"id": "CHANGE REPLICATION FILTER",
"syntax": [
{
"programlisting": ">\nCHANGE REPLICATION FILTER filter[, filter]\n\t[, ...] [FOR CHANNEL channel]\n\nfilter:\n REPLICATE_DO_DB = (db_list)\n | REPLICATE_IGNORE_DB = (db_list)\n | REPLICATE_DO_TABLE = (tbl_list)\n | REPLICATE_IGNORE_TABLE = (tbl_list)\n | REPLICATE_WILD_DO_TABLE = (wild_tbl_list)\n | REPLICATE_WILD_IGNORE_TABLE = (wild_tbl_list)\n | REPLICATE_REWRITE_DB = (db_pair_list)\n\ndb_list:\n db_name[, db_name][, ...]\n\ntbl_list:\n db_name.table_name[, db_name.table_name][, ...]\nwild_tbl_list:\n 'db_pattern.table_pattern'[, 'db_pattern.table_pattern'][, ...]\n\ndb_pair_list:\n (db_pair)[, (db_pair)][, ...]\n\ndb_pair:\n from_db, to_db"
}
]
},
{
"keywords": [
"RESET",
"SLAVE",
"ALL",
"FOR",
"CHANNEL"
],
"description": [
{
"para": "RESET SLAVE makes the slave\n forget its replication position in the master's binary log. This\n statement is meant to be used for a clean start: It clears the\n master info and relay log info repositories, deletes all the\n relay log files, and starts a new relay log file. It also resets\n to 0 the replication delay specified with the\n MASTER_DELAY option to CHANGE MASTER\n TO."
},
{
"para": "For a server where GTIDs are in use\n (gtid_mode is\n ON), issuing RESET\n SLAVE has no effect on the GTID execution history. The\n statement does not change the values of\n gtid_executed or\n gtid_purged, or the\n mysql.gtid_executed table. If you need to\n reset the GTID execution history, use RESET\n MASTER, even if the GTID-enabled server is a\n replication slave where binary logging is disabled."
},
{
"para": "RESET SLAVE requires the\n RELOAD privilege."
},
{
"para": "To use RESET SLAVE, the slave\n replication threads must be stopped, so on a running slave use\n STOP SLAVE before issuing\n RESET SLAVE. To use\n RESET SLAVE on a Group\n Replication group member, the member status must be\n OFFLINE, meaning that the plugin is loaded\n but the member does not currently belong to any group. A group\n member can be taken offline by using a STOP\n GROUP REPLICATION statement."
},
{
"para": "The optional FOR CHANNEL\n channel clause enables you\n to name which replication channel the statement applies to.\n Providing a FOR CHANNEL\n channel clause applies the\n RESET SLAVE statement to a specific\n replication channel. Combining a FOR CHANNEL\n channel clause with the\n ALL option deletes the specified channel. If\n no channel is named and no extra channels exist, the statement\n applies to the default channel. Issuing a\n RESET SLAVE\n ALL statement without a FOR CHANNEL\n channel clause when\n multiple replication channels exist deletes\n all replication channels and recreates only\n the default channel. See \n for more information."
},
{
"para": "RESET SLAVE does not change any\n replication connection parameters such as the master host,\n master port, master user, or master password.\n RESET SLAVE also does not affect\n the PRIVILEGE_CHECKS_USER account. If you\n want to reset the connection parameters intentionally, you need\n to use RESET SLAVE\n ALL, which clears the connection parameters, including\n the MASTER_USER and\n PRIVILEGE_CHECKS_USER accounts.\n RESET SLAVE ALL also clears the\n IGNORE_SERVER_IDS list set by\n CHANGE MASTER TO. When you have\n used RESET SLAVE ALL, you must issue a\n CHANGE MASTER TO statement after\n the server start to specify new connection parameters."
},
{
"para": "In the event of a server crash or deliberate restart after\n issuing RESET SLAVE but before\n issuing START SLAVE, retention of\n the replication connection parameters depends on the repository\n used for the master info log:"
},
{
"itemizedlist": [
[
{
"para": "From MySQL 8.0.13, when\n master_info_repository=TABLE\n is set on the server (which is the default from MySQL 8.0),\n replication connection parameters are preserved in the\n crash-safe InnoDB table\n mysql.slave_master_info as part of the\n RESET SLAVE operation. They\n are also retained in memory. In the event of a server crash\n or deliberate restart after issuing\n RESET SLAVE but before\n issuing START SLAVE, the\n replication connection parameters are retrieved from the\n table and reused for the new connection."
}
],
[
{
"para": "When\n master_info_repository=FILE\n is set on the server, replication connection parameters are\n only retained in memory. If the slave\n mysqld is restarted immediately after\n issuing RESET SLAVE due to a\n server crash or deliberate restart, the connection\n parameters are lost. In that case, you must issue a\n CHANGE MASTER TO statement\n after the server start to respecify the connection\n parameters before issuing START\n SLAVE."
}
]
]
},
{
"para": "RESET SLAVE does not change any\n replication filter settings (such as\n ) for\n channels affected by the statement. However, RESET\n SLAVE ALL removes the replication filters that were\n set on the channels deleted by the statement. When the deleted\n channel or channels are recreated, any global replication\n filters specified for the slave are copied to them, and no\n channel specific replication filters are applied. For more\n information see\n ."
},
{
"para": "RESET SLAVE causes an implicit commit of an\n ongoing transaction. See ."
},
{
"para": "If the slave SQL thread was in the middle of replicating\n temporary tables when it was stopped, and\n RESET SLAVE is issued, these\n replicated temporary tables are deleted on the slave."
},
{
"para": "RESET SLAVE does not reset the heartbeat\n period\n (Slave_heartbeat_period) or\n SSL_VERIFY_SERVER_CERT."
}
],
"id": "RESET SLAVE",
"syntax": [
{
"programlisting": ">\nRESET SLAVE [ALL] [channel_option]\n\nchannel_option:\n FOR CHANNEL channel"
}
]
},
{
"keywords": [
"SET",
"GLOBAL",
"sql_slave_skip_counter"
],
"description": [
{
"para": "This statement skips the next N\n events from the master. This is useful for recovering from\n replication stops caused by a statement."
},
{
"para": "This statement is valid only when the slave threads are not\n running. Otherwise, it produces an error."
}
],
"id": "SET GLOBAL sql_slave_skip_counter",
"syntax": [
{
"programlisting": ">\nSET GLOBAL sql_slave_skip_counter = N"
}
]
},
{
"keywords": [
"START",
"SLAVE",
"IO_THREAD",
"SQL_THREAD",
"USER",
"PASSWORD",
"DEFAULT_AUTH",
"PLUGIN_DIR",
"SQL_BEFORE_GTIDS",
"SQL_AFTER_GTIDS",
"SQL_AFTER_MTS_GAPS",
"FOR",
"CHANNEL"
],
"description": [
{
"para": "START SLAVE with no\n thread_type options starts both of\n the slave threads. The I/O thread reads events from the master\n server and stores them in the relay log. The SQL thread reads\n events from the relay log and executes them.\n START SLAVE requires the\n REPLICATION_SLAVE_ADMIN or\n SUPER privilege."
},
{
"para": "If START SLAVE succeeds in\n starting the slave threads, it returns without any error.\n However, even in that case, it might be that the slave threads\n start and then later stop (for example, because they do not\n manage to connect to the master or read its binary log, or some\n other problem). START SLAVE does\n not warn you about this. You must check the slave's error log\n for error messages generated by the slave threads, or check that\n they are running satisfactorily with SHOW\n SLAVE STATUS."
},
{
"para": "START SLAVE causes an implicit commit of an\n ongoing transaction. See ."
},
{
"para": "gtid_next must be set to\n AUTOMATIC before issuing this statement."
},
{
"para": "The optional FOR CHANNEL\n channel clause enables you\n to name which replication channel the statement applies to.\n Providing a FOR CHANNEL\n channel clause applies the\n START SLAVE statement to a specific\n replication channel. If no clause is named and no extra channels\n exist, the statement applies to the default channel. If a\n START SLAVE statement does not have a channel\n defined when using multiple channels, this statement starts the\n specified threads for all channels. This statement is disallowed\n for the group_replication_recovery channel.\n See for more information."
},
{
"para": "You can add IO_THREAD and\n SQL_THREAD options to the statement to name\n which of the threads to start. Note that the Group Replication\n applier channel (group_replication_applier)\n has no I/O thread, only a SQL thread. Specifying the\n IO_THREAD or SQL_THREAD\n options when you start this channel has no benefit."
},
{
"para": "MySQL supports pluggable user-password authentication with\n START SLAVE with the USER,\n PASSWORD, DEFAULT_AUTH and\n PLUGIN_DIR options, as described in the\n following list:"
},
{
"itemizedlist": [
[
{
"para": "USER: User name. Cannot be set to an\n empty or null string, or left unset if\n PASSWORD is used."
}
],
[
{
"para": "PASSWORD: Password."
}
],
[
{
"para": "DEFAULT_AUTH: Name of plugin; default is\n MySQL native authentication."
}
],
[
{
"para": "PLUGIN_DIR: Location of plugin."
}
]
]
},
{
"para": "You cannot use the SQL_THREAD option when\n specifying any of USER,\n PASSWORD, DEFAULT_AUTH, or\n PLUGIN_DIR, unless the\n IO_THREAD option is also provided."
},
{
"para": "See , for more\n information."
},
{
"para": "If an insecure connection is used with any these options, the\n server issues the warning Sending passwords in plain\n text without SSL/TLS is extremely insecure."
},
{
"para": "START SLAVE ... UNTIL supports two additional\n options for use with global transaction identifiers (GTIDs) (see\n ). Each of these takes a set\n of one or more global transaction identifiers\n gtid_set as an argument (see\n , for more\n information)."
},
{
"para": "When no thread_type is specified,\n START SLAVE UNTIL SQL_BEFORE_GTIDS causes the\n slave SQL thread to process transactions until it has reached\n the first transaction whose GTID is listed\n in the gtid_set. START SLAVE\n UNTIL SQL_AFTER_GTIDS causes the slave threads to\n process all transactions until the\n last transaction in the\n gtid_set has been processed by both\n threads. In other words, START SLAVE UNTIL\n SQL_BEFORE_GTIDS causes the slave SQL thread to\n process all transactions occurring before the first GTID in the\n gtid_set is reached, and\n START SLAVE UNTIL SQL_AFTER_GTIDS causes the\n slave threads to handle all transactions, including those whose\n GTIDs are found in gtid_set, until\n each has encountered a transaction whose GTID is not part of the\n set. SQL_BEFORE_GTIDS and\n SQL_AFTER_GTIDS each support the\n SQL_THREAD and IO_THREAD\n options, although using IO_THREAD with them\n currently has no effect."
},
{
"para": "For example, START SLAVE SQL_THREAD UNTIL\n SQL_BEFORE_GTIDS =\n 3E11FA47-71CA-11E1-9E33-C80AA9429562:11-56 causes the\n slave SQL thread to process all transactions originating from\n the master whose server_uuid is\n 3E11FA47-71CA-11E1-9E33-C80AA9429562 until it\n encounters the transaction having sequence number 11; it then\n stops without processing this transaction. In other words, all\n transactions up to and including the transaction with sequence\n number 10 are processed. Executing START SLAVE\n SQL_THREAD UNTIL SQL_AFTER_GTIDS =\n 3E11FA47-71CA-11E1-9E33-C80AA9429562:11-56, on the\n other hand, would cause the slave SQL thread to obtain all\n transactions just mentioned from the master, including all of\n the transactions having the sequence numbers 11 through 56, and\n then to stop without processing any additional transactions;\n that is, the transaction having sequence number 56 would be the\n last transaction fetched by the slave SQL thread."
},
{
"para": "When using a multithreaded slave\n\n\n\n with slave_preserve_commit_order=0 set, there\n is a chance of gaps in the sequence of transactions that have\n been executed from the relay log in the following cases:"
},
{
"itemizedlist": [
[
{
"para": "killing the coordinator thread"
}
],
[
{
"para": "after an error occurs in the applier threads"
}
],
[
{
"para": "mysqld shuts down unexpectedly"
}
]
]
},
{
"para": "Use the START SLAVE\n UNTIL SQL_AFTER_MTS_GAPS statement to cause a\n multithreaded slave's worker threads to only run until no\n more gaps are found in the relay log, and then to stop. This\n statement can take an SQL_THREAD option, but\n the effects of the statement remain unchanged. It has no effect\n on the slave I/O thread (and cannot be used with the\n IO_THREAD option)."
},
{
"para": "Issuing START SLAVE on a\n multithreaded slave with gaps in the sequence of transactions\n executed from the relay log generates a warning. In such a\n situation, the solution is to use\n START SLAVE UNTIL\n SQL_AFTER_MTS_GAPS, then issue\n RESET SLAVE to remove any\n remaining relay logs. See\n \n for more information."
},
{
"para": "To change a failed multithreaded slave to single-threaded mode,\n you can issue the following series of statements, in the order\n shown:"
},
{
"programlisting": ">\nSTART SLAVE UNTIL SQL_AFTER_MTS_GAPS;\n\nSET @@GLOBAL.slave_parallel_workers = 0;\n\nSTART SLAVE SQL_THREAD;"
}
],
"id": "START SLAVE",
"syntax": [
{
"programlisting": ">\nSTART SLAVE [thread_types] [until_option] [connection_options] [channel_option]\n\nthread_types:\n [thread_type [, thread_type] ... ]\n\nthread_type:\n IO_THREAD | SQL_THREAD\n\nuntil_option:\n UNTIL { {SQL_BEFORE_GTIDS | SQL_AFTER_GTIDS} = gtid_set\n | MASTER_LOG_FILE = 'log_name', MASTER_LOG_POS = log_pos\n | RELAY_LOG_FILE = 'log_name', RELAY_LOG_POS = log_pos\n | SQL_AFTER_MTS_GAPS }\n\nconnection_options:\n [USER='user_name'] [PASSWORD='user_pass'] [DEFAULT_AUTH='plugin_name'] [PLUGIN_DIR='plugin_dir']\n\n\nchannel_option:\n FOR CHANNEL channel\n\ngtid_set:\n uuid_set [, uuid_set] ...\n | ''\n\nuuid_set:\n uuid:interval[:interval]...\n\nuuid:\n hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh\n\nh:\n [0-9,A-F]\n\ninterval:\n n[-n]\n\n (n >= 1)"
}
]
},
{
"keywords": [
"STOP",
"SLAVE",
"IO_THREAD",
"SQL_THREAD",
"FOR",
"CHANNEL"
],
"description": [
{
"para": "Stops the slave threads. STOP\n SLAVE requires the\n REPLICATION_SLAVE_ADMIN or\n SUPER privilege. Recommended best\n practice is to execute STOP SLAVE on the\n slave before stopping the slave server (see\n , for more information)."
},
{
"para": "When using the row-based logging format:\n You should execute STOP SLAVE or\n STOP SLAVE SQL_THREAD on the slave prior to\n shutting down the slave server if you are replicating any tables\n that use a nontransactional storage engine (see the\n Note later in this section)."
},
{
"para": "Like START SLAVE, this statement\n may be used with the IO_THREAD and\n SQL_THREAD options to name the thread or\n threads to be stopped. Note that the Group Replication applier\n channel (group_replication_applier) has no\n I/O thread, only a SQL thread. Using the\n SQL_THREAD option therefore stops this\n channel completely."
},
{
"para": "STOP SLAVE causes an implicit commit of an\n ongoing transaction. See ."
},
{
"para": "gtid_next must be set to\n AUTOMATIC before issuing this statement."
},
{
"para": "You can control how long STOP SLAVE waits\n before timing out by setting the\n rpl_stop_slave_timeout system\n variable. This can be used to avoid deadlocks between\n STOP SLAVE and other slave SQL statements\n using different client connections to the slave. When the\n timeout value is reached, the issuing client returns an error\n message and stops waiting, but the STOP SLAVE\n instruction remains in effect. Once the slave threads are no\n longer busy, the STOP SLAVE statement is\n executed and the slave stops."
},
{
"para": "Some CHANGE MASTER TO statements are allowed\n while the slave is running, depending on the states of the slave\n SQL and I/O threads. However, using STOP\n SLAVE prior to executing CHANGE MASTER\n TO in such cases is still supported. See\n , and\n , for more\n information."
},
{
"para": "The optional FOR CHANNEL\n channel clause enables you\n to name which replication channel the statement applies to.\n Providing a FOR CHANNEL\n channel clause applies the\n STOP SLAVE statement to a specific\n replication channel. If no channel is named and no extra\n channels exist, the statement applies to the default channel. If\n a STOP SLAVE statement does not name a\n channel when using multiple channels, this statement stops the\n specified threads for all channels. This statement cannot be\n used with the group_replication_recovery\n channel. See for more\n information."
},
{
"para": "When using statement-based replication:\n changing the master while it has open temporary tables is\n potentially unsafe. This is one of the reasons why\n statement-based replication of temporary tables is not\n recommended. You can find out whether there are any temporary\n tables on the slave by checking the value of\n Slave_open_temp_tables; when\n using statement-based replication, this value should be 0 before\n executing CHANGE MASTER TO. If there are any\n temporary tables open on the slave, issuing a CHANGE\n MASTER TO statement after issuing a STOP\n SLAVE causes an\n ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO\n warning."
},
{
"para": "When using a multithreaded slave\n (slave_parallel_workers is a\n nonzero value), any gaps in the sequence of transactions\n executed from the relay log are closed as part of stopping the\n worker threads. If the slave is stopped unexpectedly (for\n example due to an error in a worker thread, or another thread\n issuing KILL) while a\n STOP SLAVE statement is\n executing, the sequence of executed transactions from the relay\n log may become inconsistent. See\n \n for more information."
},
{
"para": "If the current replication event group has modified one or more\n nontransactional tables, STOP SLAVE waits for up to 60 seconds\n for the event group to complete, unless you issue a\n KILL QUERY or\n KILL CONNECTION\n statement for the slave SQL thread. If the event group remains\n incomplete after the timeout, an error message is logged."
}
],
"id": "STOP SLAVE",
"syntax": [
{
"programlisting": ">\nSTOP SLAVE [thread_types] [channel_option]\n\nthread_types:\n [thread_type [, thread_type] ... ]\n\nthread_type: IO_THREAD | SQL_THREAD\n\nchannel_option:\n FOR CHANNEL channel"
}
]
},
{
"keywords": [
"ALTER",
"USER",
"REQUIRE",
"IDENTIFIED",
"BY",
"WITH",
"AS",
"SSL",
"X509",
"CIPHER",
"ISSUER",
"SUBJECT",
"MAX_QUERIES_PER_HOUR",
"MAX_UPDATES_PER_HOUR",
"MAX_CONNECTIONS_PER_HOUR",
"MAX_USER_CONNECTIONS",
"PASSWORD",
"EXPIRE",
"DEFAULT",
"NEVER",
"INTERVAL",
"ACCOUNT",
"LOCK",
"UNLOCK",
"IF",
"EXISTS",
"ROLE",
"NONE",
"ALL",
"REUSE",
"HISTORY",
"DAY",
"REPLACE",
"CURRENT",
"OPTIONAL",
"RETAIN",
"DISCARD",
"OLD",
"RANDOM",
"FAILED_LOGIN_ATTEMPTS",
"PASSWORD_LOCK_TIME",
"UNBOUNDED"
],
"description": [
{
"para": "The ALTER USER statement modifies\n MySQL accounts. It enables authentication, role, SSL/TLS,\n resource-limit, and password-management properties to be\n modified for existing accounts. It can also be used to lock and\n unlock accounts."
},
{
"para": "In most cases, ALTER USER\n requires the global CREATE USER\n privilege, or the UPDATE\n privilege for the mysql system schema. The\n exceptions are:"
},
{
"itemizedlist": [
[
{
"para": "Any client who connects to the server using a nonanonymous\n account can change the password for that account. (In\n particular, you can change your own password.) To see which\n account the server authenticated you as, invoke the\n CURRENT_USER() function:"
},
{
"programlisting": ">\nSELECT CURRENT_USER();"
}
],
[
{
"para": "For DEFAULT ROLE syntax,\n ALTER USER requires these\n privileges:"
},
{
"itemizedlist": [
[
{
"para": "Setting the default roles for another user requires the\n global CREATE USER\n privilege, or the UPDATE\n privilege for the mysql.default_roles\n system table."
}
],
[
{
"para": "Setting the default roles for yourself requires no\n special privileges, as long as the roles you want as the\n default have been granted to you."
}
]
]
}
],
[
{
"para": "Statements that modify secondary passwords require these\n privileges:"
},
{
"itemizedlist": [
[
{
"para": "The\n APPLICATION_PASSWORD_ADMIN\n privilege is required to use the RETAIN CURRENT\n PASSWORD or DISCARD OLD\n PASSWORD clause for ALTER\n USER statements that apply to your own\n account. The privilege is required to manipulate your\n own secondary password because most users require only\n one password."
}
],
[
{
"para": "If an account is to be permitted to manipulate secondary\n passwords for all accounts, it requires the\n CREATE USER privilege\n rather than\n APPLICATION_PASSWORD_ADMIN."
}
]
]
}
]
]
},
{
"para": "When the read_only system\n variable is enabled, ALTER USER\n additionally requires the\n CONNECTION_ADMIN or\n SUPER privilege."
},
{
"para": "By default, an error occurs if you try to modify a user that\n does not exist. If the IF EXISTS clause is\n given, the statement produces a warning for each named user that\n does not exist, rather than an error."
}
],
"id": "ALTER USER",
"syntax": [
{
"programlisting": ">\nALTER USER [IF EXISTS]\n user [auth_option] [, user [auth_option]] ...\n [REQUIRE {NONE | tls_option [[AND] tls_option] ...}]\n [WITH resource_option [resource_option] ...]\n [password_option | lock_option] ...\n\nALTER USER [IF EXISTS] USER() user_func_auth_option\n\nALTER USER [IF EXISTS]\n user DEFAULT ROLE\n {NONE | ALL | role [, role ] ...}\n\nuser:\n (see )\n\nauth_option: {\n IDENTIFIED BY 'auth_string'\n [REPLACE 'current_auth_string']\n [RETAIN CURRENT PASSWORD]\n | IDENTIFIED BY RANDOM PASSWORD\n [REPLACE 'current_auth_string']\n [RETAIN CURRENT PASSWORD]\n | IDENTIFIED WITH auth_plugin\n | IDENTIFIED WITH auth_plugin BY 'auth_string'\n [REPLACE 'current_auth_string']\n [RETAIN CURRENT PASSWORD]\n | IDENTIFIED WITH auth_plugin BY RANDOM PASSWORD\n [REPLACE 'current_auth_string']\n [RETAIN CURRENT PASSWORD]\n | IDENTIFIED WITH auth_plugin AS 'auth_string'\n | DISCARD OLD PASSWORD\n}\n\nuser_func_auth_option: {\n IDENTIFIED BY 'auth_string'\n [REPLACE 'current_auth_string']\n [RETAIN CURRENT PASSWORD]\n | DISCARD OLD PASSWORD\n}\n\ntls_option: {\n SSL\n | X509\n | CIPHER 'cipher'\n | ISSUER 'issuer'\n | SUBJECT 'subject'\n}\n\nresource_option: {\n MAX_QUERIES_PER_HOUR count\n | MAX_UPDATES_PER_HOUR count\n | MAX_CONNECTIONS_PER_HOUR count\n | MAX_USER_CONNECTIONS count\n}\n\npassword_option: {\n PASSWORD EXPIRE [DEFAULT | NEVER | INTERVAL N DAY]\n | PASSWORD HISTORY {DEFAULT | N}\n | PASSWORD REUSE INTERVAL {DEFAULT | N DAY}\n | PASSWORD REQUIRE CURRENT [DEFAULT | OPTIONAL]\n | FAILED_LOGIN_ATTEMPTS N\n | PASSWORD_LOCK_TIME {N | UNBOUNDED}\n}\n\nlock_option: {\n ACCOUNT LOCK\n | ACCOUNT UNLOCK\n}"
}
]
},
{
"keywords": [
"CREATE",
"ROLE",
"IF",
"NOT",
"EXISTS"
],
"description": [
{
"para": "CREATE ROLE creates one or more\n roles, which are named collections of privileges. To use this\n statement, you must have the global CREATE\n ROLE or CREATE USER\n privilege. When the read_only\n system variable is enabled, CREATE\n ROLE additionally requires the\n CONNECTION_ADMIN or\n SUPER privilege."
},
{
"para": "A role when created is locked, has no password, and is assigned\n the default authentication plugin. (These role attributes can be\n changed later with the ALTER USER\n statement, by users who have the global\n CREATE USER privilege.)"
},
{
"para": "CREATE ROLE either succeeds for\n all named roles or rolls back and has no effect if any error\n occurs. By default, an error occurs if you try to create a role\n that already exists. If the IF NOT EXISTS\n clause is given, the statement produces a warning for each named\n role that already exists, rather than an error."
},
{
"para": "The statement is written to the binary log if it succeeds, but\n not if it fails; in that case, rollback occurs and no changes\n are made. A statement written to the binary log includes all\n named roles. If the IF NOT EXISTS clause is\n given, this includes even roles that already exist and were not\n created."
},
{
"para": "Each role name uses the format described in\n . For example:"
},
{
"programlisting": ">\nCREATE ROLE 'administrator', 'developer';\nCREATE ROLE 'webapp'@'localhost';"
},
{
"para": "The host name part of the role name, if omitted, defaults to\n '%'."
},
{
"para": "For role usage examples, see ."
}
],
"id": "CREATE ROLE",
"syntax": [
{
"programlisting": ">\nCREATE ROLE [IF NOT EXISTS] role [, role ] ..."
}
]
},
{
"keywords": [
"CREATE",
"USER",
"REQUIRE",
"IDENTIFIED",
"BY",
"WITH",
"AS",
"SSL",
"X509",
"CIPHER",
"ISSUER",
"SUBJECT",
"MAX_QUERIES_PER_HOUR",
"MAX_UPDATES_PER_HOUR",
"MAX_CONNECTIONS_PER_HOUR",
"MAX_USER_CONNECTIONS",
"PASSWORD",
"EXPIRE",
"DEFAULT",
"NEVER",
"INTERVAL",
"ACCOUNT",
"LOCK",
"UNLOCK",
"IF",
"NOT",
"EXISTS",
"REUSE",
"HISTORY",
"DAY",
"ROLE",
"CURRENT",
"OPTIONAL",
"RANDOM",
"FAILED_LOGIN_ATTEMPTS",
"PASSWORD_LOCK_TIME",
"UNBOUNDED"
],
"description": [
{
"para": "The CREATE USER statement creates\n new MySQL accounts. It enables authentication, role, SSL/TLS,\n resource-limit, and password-management properties to be\n established for new accounts. It also controls whether accounts\n are initially locked or unlocked."
},
{
"para": "To use CREATE USER, you must have\n the global CREATE USER privilege,\n or the INSERT privilege for the\n mysql system schema. When the\n read_only system variable is\n enabled, CREATE USER additionally\n requires the CONNECTION_ADMIN or\n SUPER privilege."
},
{
"para": "CREATE USER either succeeds for\n all named users or rolls back and has no effect if any error\n occurs. By default, an error occurs if you try to create a user\n that already exists. If the IF NOT EXISTS\n clause is given, the statement produces a warning for each named\n user that already exists, rather than an error."
}
],
"id": "CREATE USER",
"syntax": [
{
"programlisting": ">\nCREATE USER [IF NOT EXISTS]\n user [auth_option] [, user [auth_option]] ...\n DEFAULT ROLE role [, role ] ...\n [REQUIRE {NONE | tls_option [[AND] tls_option] ...}]\n [WITH resource_option [resource_option] ...]\n [password_option | lock_option] ...\n\nuser:\n (see )\n\nauth_option: {\n IDENTIFIED BY 'auth_string'\n | IDENTIFIED BY RANDOM PASSWORD\n | IDENTIFIED WITH auth_plugin\n | IDENTIFIED WITH auth_plugin BY 'auth_string'\n | IDENTIFIED WITH auth_plugin BY RANDOM PASSWORD\n | IDENTIFIED WITH auth_plugin AS 'auth_string'\n}\n\ntls_option: {\n SSL\n | X509\n | CIPHER 'cipher'\n | ISSUER 'issuer'\n | SUBJECT 'subject'\n}\n\nresource_option: {\n MAX_QUERIES_PER_HOUR count\n | MAX_UPDATES_PER_HOUR count\n | MAX_CONNECTIONS_PER_HOUR count\n | MAX_USER_CONNECTIONS count\n}\n\npassword_option: {\n PASSWORD EXPIRE [DEFAULT | NEVER | INTERVAL N DAY]\n | PASSWORD HISTORY {DEFAULT | N}\n | PASSWORD REUSE INTERVAL {DEFAULT | N DAY}\n | PASSWORD REQUIRE CURRENT [DEFAULT | OPTIONAL]\n | FAILED_LOGIN_ATTEMPTS N\n | PASSWORD_LOCK_TIME {N | UNBOUNDED}\n}\n\nlock_option: {\n ACCOUNT LOCK\n | ACCOUNT UNLOCK\n}"
}
]
},
{
"keywords": [
"DROP",
"ROLE",
"IF",
"EXISTS"
],
"description": [
{
"para": "DROP ROLE removes one or more\n roles (named collections of privileges). To use this statement,\n you must have the global DROP\n ROLE or CREATE USER\n privilege. When the read_only\n system variable is enabled, DROP\n ROLE additionally requires the\n CONNECTION_ADMIN or\n SUPER privilege."
},
{
"para": "As of MySQL 8.0.16, users who have the\n CREATE USER privilege can use\n this statement to drop accounts that are locked or unlocked.\n Users who have the DROP ROLE\n privilege can use this statement only to drop accounts that are\n locked (unlocked accounts are presumably user accounts used to\n log in to the server and not just as roles)."
},
{
"para": "Roles named in the\n mandatory_roles system variable\n value cannot be dropped."
},
{
"para": "DROP ROLE either succeeds for all\n named roles or rolls back and has no effect if any error occurs.\n By default, an error occurs if you try to drop a role that does\n not exist. If the IF EXISTS clause is given,\n the statement produces a warning for each named role that does\n not exist, rather than an error."
},
{
"para": "The statement is written to the binary log if it succeeds, but\n not if it fails; in that case, rollback occurs and no changes\n are made. A statement written to the binary log includes all\n named roles. If the IF EXISTS clause is\n given, this includes even roles that do not exist and were not\n dropped."
},
{
"para": "Each role name uses the format described in\n . For example:"
},
{
"programlisting": ">\nDROP ROLE 'administrator', 'developer';\nDROP ROLE 'webapp'@'localhost';"
},
{
"para": "The host name part of the role name, if omitted, defaults to\n '%'."
},
{
"para": "A dropped role is automatically revoked from any user account\n (or role) to which the role was granted. Within any current\n session for such an account, its adjusted privileges apply\n beginning with the next statement executed."
}
],
"id": "DROP ROLE",
"syntax": [
{
"programlisting": ">\nDROP ROLE [IF EXISTS] role [, role ] ..."
}
]
},
{
"keywords": [
"DROP",
"USER",
"IF",
"EXISTS"
],
"description": [
{
"para": "The DROP USER statement removes\n one or more MySQL accounts and their privileges. It removes\n privilege rows for the account from all grant tables."
},
{
"para": "Roles named in the\n mandatory_roles system variable\n value cannot be dropped."
},
{
"para": "To use DROP USER, you must have\n the global CREATE USER privilege,\n or the DELETE privilege for the\n mysql system schema. When the\n read_only system variable is\n enabled, DROP USER additionally\n requires the CONNECTION_ADMIN or\n SUPER privilege."
},
{
"para": "DROP USER either succeeds for all\n named users or rolls back and has no effect if any error occurs.\n By default, an error occurs if you try to drop a user that does\n not exist. If the IF EXISTS clause is given,\n the statement produces a warning for each named user that does\n not exist, rather than an error."
},
{
"para": "The statement is written to the binary log if it succeeds, but\n not if it fails; in that case, rollback occurs and no changes\n are made. A statement written to the binary log includes all\n named users. If the IF EXISTS clause is\n given, this includes even users that do not exist and were not\n dropped."
},
{
"para": "Each account name uses the format described in\n . For example:"
},
{
"programlisting": ">\nDROP USER 'jeffrey'@'localhost';"
},
{
"para": "The host name part of the account name, if omitted, defaults to\n '%'."
}
],
"id": "DROP USER",
"syntax": [
{
"programlisting": ">\nDROP USER [IF EXISTS] user [, user] ..."
}
]
},
{
"keywords": [
"ALL",
"ALTER",
"GRANT",
"WITH",
"OPTION",
"CLIENT",
"EXECUTE",
"FILE",
"USAGE",
"SUPER",
"NONE",
"PROCESS",
"PRIVILEGES",
"REFERENCES",
"RELOAD",
"REPLICATION",
"SHUTDOWN",
"ADMIN",
"AS",
"ROLE"
],
"description": [],
"id": "GRANT",
"syntax": [
{
"programlisting": ">\nGRANT\n priv_type [(column_list)]\n [, priv_type [(column_list)]] ...\n ON [object_type] priv_level\n TO user_or_role [, user_or_role] ...\n [WITH GRANT OPTION]\n [AS user\n [WITH ROLE\n DEFAULT\n | NONE\n | ALL\n | ALL EXCEPT role [, role ] ...\n | role [, role ] ...\n ]\n ]\n}\n\nGRANT PROXY ON user_or_role\n TO user_or_role [, user_or_role] ...\n [WITH GRANT OPTION]\n\nGRANT role [, role] ...\n TO user_or_role [, user_or_role] ...\n [WITH ADMIN OPTION]\n\nobject_type: {\n TABLE\n | FUNCTION\n | PROCEDURE\n}\n\npriv_level: {\n *\n | *.*\n | db_name.*\n | db_name.tbl_name\n | tbl_name\n | db_name.routine_name\n}\n\nuser_or_role: {\n user (see )\n | role (see )\n}"
},
{
"para": "The GRANT statement assigns\n privileges and roles to MySQL user accounts and roles. There are\n several aspects to the GRANT\n statement, described under the following topics:"
}
]
},
{
"keywords": [
"RENAME",
"USER"
],
"description": [
{
"para": "The RENAME USER statement renames\n existing MySQL accounts. An error occurs for old accounts that\n do not exist or new accounts that already exist."
},
{
"para": "To use RENAME USER, you must have\n the global CREATE USER privilege,\n or the UPDATE privilege for the\n mysql system schema. When the\n read_only system variable is\n enabled, RENAME USER additionally\n requires the CONNECTION_ADMIN or\n SUPER privilege."
},
{
"para": "Each account name uses the format described in\n . For example:"
},
{
"programlisting": ">\nRENAME USER 'jeffrey'@'localhost' TO 'jeff'@'127.0.0.1';"
},
{
"para": "The host name part of the account name, if omitted, defaults to\n '%'."
},
{
"para": "RENAME USER causes the privileges\n held by the old user to be those held by the new user. However,\n RENAME USER does not\n automatically drop or invalidate databases or objects within\n them that the old user created. This includes stored programs or\n views for which the DEFINER attribute names\n the old user. Attempts to access such objects may produce an\n error if they execute in definer security context. (For\n information about security context, see\n .)"
},
{
"para": "The privilege changes take effect as indicated in\n ."
}
],
"id": "RENAME USER",
"syntax": [
{
"programlisting": ">\nRENAME USER old_user TO new_user\n [, old_user TO new_user] ..."
}
]
},
{
"keywords": [
"REVOKE",
"ALL",
"PRIVILEGES",
"GRANT",
"OPTION",
"PROXY"
],
"description": [
{
"para": "The REVOKE statement enables\n system administrators to revoke privileges and roles, which can\n be revoked from user accounts and roles."
},
{
"para": "For details on the levels at which privileges exist, the\n permissible priv_type,\n priv_level, and\n object_type values, and the syntax\n for specifying users and passwords, see ."
},
{
"para": "For information about roles, see ."
},
{
"para": "When the read_only system\n variable is enabled, REVOKE\n requires the CONNECTION_ADMIN or\n SUPER privilege in addition to\n any other required privileges described in the following\n discussion."
},
{
"para": "REVOKE either succeeds for all\n named users and roles or rolls back and has no effect if any\n error occurs. The statement is written to the binary log only if\n it succeeds for all named users and roles."
},
{
"para": "Each account name uses the format described in\n . Each role name uses the format\n described in . For example:"
},
{
"programlisting": ">\nREVOKE INSERT ON *.* FROM 'jeffrey'@'localhost';\nREVOKE 'role1', 'role2' FROM 'user1'@'localhost', 'user2'@'localhost';\nREVOKE SELECT ON world.* FROM 'role3';"
},
{
"para": "The host name part of the account or role name, if omitted,\n defaults to '%'."
},
{
"para": "To use the first REVOKE syntax,\n you must have the GRANT OPTION\n privilege, and you must have the privileges that you are\n revoking."
},
{
"para": "To revoke all privileges, use the second syntax, which drops all\n global, database, table, column, and routine privileges for the\n named users or roles:"
},
{
"programlisting": ">\nREVOKE ALL PRIVILEGES, GRANT OPTION\n FROM user_or_role [, user_or_role] ..."
},
{
"para": "REVOKE ALL PRIVILEGES, GRANT OPTION does not\n revoke any roles."
},
{
"para": "To use this REVOKE syntax, you\n must have the global CREATE USER\n privilege, or the UPDATE\n privilege for the mysql system schema."
},
{
"para": "The syntax for which the REVOKE\n keyword is followed by one or more role names takes a\n FROM clause indicating one or more users or\n roles from which to revoke the roles."
},
{
"para": "Roles named in the\n mandatory_roles system variable\n value cannot be revoked."
},
{
"para": "A revoked role immediately affects any user account from which\n it was revoked, such that within any current session for the\n account, its privileges are adjusted for the next statement\n executed."
},
{
"para": "Revoking a role revokes the role itself, not the privileges that\n it represents. Suppose that an account is granted a role that\n includes a given privilege, and is also granted the privilege\n explicitly or another role that includes the privilege. In this\n case, the account still possesses that privilege if the first\n role is revoked. For example, if an account is granted two roles\n that each include SELECT, the\n account still can select after either role is revoked."
},
{
"para": "REVOKE ALL ON *.* (at the global level)\n revokes all granted static global privileges and all granted\n dynamic privileges."
},
{
"para": "User accounts and roles from which privileges and roles are to\n be revoked must exist, but the privileges and roles to be\n revoked need not be currently granted to them."
},
{
"para": "A revoked privilege that is granted but not known to the server\n is revoked with a warning. This situtation can occur for dynamic\n privileges. For example, a dynamic privilege can be granted\n while the component that registers it is installed, but if that\n component is subsequently uninstalled, the privilege becomes\n unregistered, although accounts that possess the privilege still\n possess it and it can be revoked from them."
}
],
"id": "REVOKE",
"syntax": [
{
"programlisting": ">\nREVOKE\n priv_type [(column_list)]\n [, priv_type [(column_list)]] ...\n ON [object_type] priv_level\n FROM user_or_role [, user_or_role] ...\n\nREVOKE ALL [PRIVILEGES], GRANT OPTION\n FROM user_or_role [, user_or_role] ...\n\nREVOKE PROXY ON user_or_role\n FROM user_or_role [, user_or_role] ...\n\nREVOKE role [, role ] ...\n FROM user_or_role [, user_or_role ] ...\n\nuser_or_role: {\n user (see )\n | role (see .\n}"
}
]
},
{
"keywords": [
"SET",
"DEFAULT",
"ROLE",
"NONE",
"ALL"
],
"description": [
{
"para": "For each user named immediately after\n the TO keyword, this statement defines which\n roles become active when the user connects to the server and\n authenticates, or when the user executes the\n SET ROLE\n DEFAULT statement during a session."
},
{
"para": "SET DEFAULT ROLE is alternative\n syntax for ALTER\n USER ... DEFAULT ROLE (see\n ). However,\n ALTER USER can set the default\n for only a single user, whereas SET DEFAULT\n ROLE can set the default for multiple users. On the\n other hand, you can specify CURRENT_USER as\n the user name for the ALTER USER\n statement, whereas you cannot for SET\n DEFAULT ROLE."
},
{
"para": "SET DEFAULT ROLE requires these\n privileges:"
},
{
"itemizedlist": [
[
{
"para": "Setting the default roles for another user requires the\n global CREATE USER privilege,\n or the UPDATE privilege for\n the mysql.default_roles system table."
}
],
[
{
"para": "Setting the default roles for yourself requires no special\n privileges, as long as the roles you want as the default\n have been granted to you."
}
]
]
},
{
"para": "Each role name uses the format described in\n . For example:"
},
{
"programlisting": ">\nSET DEFAULT ROLE administrator, developer TO 'joe'@'10.0.0.1';"
},
{
"para": "The host name part of the role name, if omitted, defaults to\n '%'."
},
{
"para": "The clause following the DEFAULT ROLE\n keywords permits these values:"
},
{
"itemizedlist": [
[
{
"para": "NONE: Set the default to\n NONE (no roles)."
}
],
[
{
"para": "ALL: Set the default to all roles granted\n to the account."
}
],
[
{
"para": "role [,\n role ] ...: Set the\n default to the named roles, which must exist and be granted\n to the account at the time SET DEFAULT\n ROLE is executed."
}
]
]
}
],
"id": "SET DEFAULT ROLE",
"syntax": [
{
"programlisting": ">\nSET DEFAULT ROLE\n {NONE | ALL | role [, role ] ...}\n TO user [, user ] ..."
}
]
},
{
"keywords": [
"SET",
"PASSWORD",
"FOR",
"REPLACE",
"RETAIN",
"CURRENT",
"TO",
"RANDOM"
],
"description": [
{
"para": "The SET PASSWORD statement\n assigns a password to a MySQL user account. The password may be\n either explicitly specified in the statement or randomly\n generated by MySQL. The statement may also include a\n password-verification clause that specifies the account current\n password to be replaced, and a clause that manages whether an\n account has a secondary password.\n 'auth_string' and\n 'current_auth_string'\n each represent a cleartext (unencrypted) password."
},
{
"para": "The REPLACE\n 'current_auth_string'\n clause performs password verification and is available as of\n MySQL 8.0.13. If given:"
},
{
"itemizedlist": [
[
{
"para": "REPLACE specifies the account current\n password to be replaced, as a cleartext (unencrypted)\n string."
}
],
[
{
"para": "The clause must be given if password changes for the account\n are required to specify the current password, as\n verification that the user attempting to make the change\n actually knows the current password."
}
],
[
{
"para": "The clause is optional if password changes for the account\n may but need not specify the current password."
}
],
[
{
"para": "The statement fails if the clause is given but does not\n match the current password, even if the clause is optional."
}
],
[
{
"para": "REPLACE can be specified only when\n changing the account password for the current user."
}
]
]
},
{
"para": "For more information about password verification by specifying\n the current password, see ."
},
{
"para": "The RETAIN CURRENT PASSWORD clause implements\n dual-password capability and is available as of MySQL 8.0.14. If\n given:"
},
{
"itemizedlist": [
[
{
"para": "RETAIN CURRENT PASSWORD retains an\n account current password as its secondary password,\n replacing any existing secondary password. The new password\n becomes the primary password, but clients can use the\n account to connect to the server using either the primary or\n secondary password. (Exception: If the new password\n specified by the SET PASSWORD\n statement is empty, the secondary password becomes empty as\n well, even if RETAIN CURRENT PASSWORD is\n given.)"
}
],
[
{
"para": "If you specify RETAIN CURRENT PASSWORD\n for an account that has an empty primary password, the\n statement fails."
}
],
[
{
"para": "If an account has a secondary password and you change its\n primary password without specifying RETAIN CURRENT\n PASSWORD, the secondary password remains\n unchanged."
}
]
]
},
{
"para": "For more information about use of dual passwords, see\n ."
},
{
"para": "SET PASSWORD permits these\n auth_option syntaxes:"
},
{
"itemizedlist": [
[
{
"para": "=\n 'auth_string'"
},
{
"para": "Assigns the account the given literal password."
}
],
[
{
"para": "TO RANDOM"
},
{
"para": "Assigns the account a password randomly generated by MySQL.\n The statement also returns the cleartext password in a\n result set to make it available to the user or application\n executing the statement."
},
{
"para": "For details about the result set and characteristics of\n randomly generated passwords, see\n ."
},
{
"para": "Random password generation is available as of MySQL 8.0.18."
}
]
]
},
{
"para": "SET PASSWORD can be used with or\n without a FOR clause that explicitly names a\n user account:"
},
{
"itemizedlist": [
[
{
"para": "With a FOR\n user clause, the\n statement sets the password for the named account, which\n must exist:"
},
{
"programlisting": ">\nSET PASSWORD FOR 'jeffrey'@'localhost' = 'auth_string';"
}
],
[
{
"para": "With no FOR\n user clause, the\n statement sets the password for the current user:"
},
{
"programlisting": ">\nSET PASSWORD = 'auth_string';"
},
{
"para": "Any client who connects to the server using a nonanonymous\n account can change the password for that account. (In\n particular, you can change your own password.) To see which\n account the server authenticated you as, invoke the\n CURRENT_USER() function:"
},
{
"programlisting": ">\nSELECT CURRENT_USER();"
}
]
]
},
{
"para": "If a FOR user\n clause is given, the account name uses the format described in\n . For example:"
},
{
"programlisting": ">\nSET PASSWORD FOR 'bob'@'%.example.org' = 'auth_string';"
},
{
"para": "The host name part of the account name, if omitted, defaults to\n '%'."
},
{
"para": "SET PASSWORD interprets the\n string as a cleartext string, passes it to the authentication\n plugin associated with the account, and stores the result\n returned by the plugin in the account row in the\n mysql.user system table. (The plugin is given\n the opportunity to hash the value into the encryption format it\n expects. The plugin may use the value as specified, in which\n case no hashing occurs.)"
},
{
"para": "Setting the password for a named account (with a\n FOR clause) requires the\n UPDATE privilege for the\n mysql system schema. Setting the password for\n yourself (for a nonanonymous account with no\n FOR clause) requires no special privileges."
},
{
"para": "Statements that modify secondary passwords require these\n privileges:"
},
{
"itemizedlist": [
[
{
"para": "The\n APPLICATION_PASSWORD_ADMIN\n privilege is required to use the RETAIN CURRENT\n PASSWORD clause for SET\n PASSWORD statements that apply to your own\n account. The privilege is required to manipulate your own\n secondary password because most users require only one\n password."
}
],
[
{
"para": "If an account is to be permitted to manipulate secondary\n passwords for all accounts, it should be granted the\n CREATE USER privilege rather\n than\n APPLICATION_PASSWORD_ADMIN."
}
]
]
},
{
"para": "When the read_only system\n variable is enabled, SET PASSWORD\n requires the CONNECTION_ADMIN or\n SUPER privilege in addition to\n any other required privileges."
}
],
"id": "SET PASSWORD",
"syntax": [
{
"programlisting": ">\nSET PASSWORD [FOR user] auth_option\n [REPLACE 'current_auth_string']\n [RETAIN CURRENT PASSWORD]\n\nauth_option: {\n = 'auth_string'\n | TO RANDOM\n}"
}
]
},
{
"keywords": [
"SET",
"ROLE",
"DEFAULT",
"NONE",
"ALL",
"EXCEPT"
],
"description": [
{
"para": "SET ROLE modifies the current\n user's effective privileges within the current session by\n specifying which of its granted roles are active. Granted roles\n include those granted explicitly to the user and those named in\n the mandatory_roles system\n variable value."
},
{
"para": "Examples:"
},
{
"programlisting": ">\nSET ROLE DEFAULT;\nSET ROLE 'role1', 'role2';\nSET ROLE ALL;\nSET ROLE ALL EXCEPT 'role1', 'role2';"
},
{
"para": "Each role name uses the format described in\n . The host name part of the role\n name, if omitted, defaults to '%'."
},
{
"para": "Privileges that the user has been granted directly (rather than\n through roles) remain unaffected by changes to the active roles."
},
{
"para": "The statement permits these role specifiers:"
},
{
"itemizedlist": [
[
{
"para": "DEFAULT: Activate the account default\n roles. Default roles are those specified with\n SET DEFAULT ROLE."
},
{
"para": "When a user connects to the server and authenticates\n successfully, the server determines which roles to activate\n as the default roles. If the\n activate_all_roles_on_login\n system variable is enabled, the server activates all granted\n roles. Otherwise, the server executes\n SET ROLE\n DEFAULT implicitly. The server activates only\n default roles that can be activated. The server writes\n warnings to its error log for default roles that cannot be\n activated, but the client receives no warnings."
},
{
"para": "If a user executes\n SET ROLE\n DEFAULT during a session, an error occurs if any\n default role cannot be activated (for example, if it does\n not exist or is not granted to the user). In this case, the\n current active roles are not changed."
}
],
[
{
"para": "NONE: Set the active roles to\n NONE (no active roles)."
}
],
[
{
"para": "ALL: Activate all roles granted to the\n account."
}
],
[
{
"para": "ALL EXCEPT role [,\n role ] ...: Activate\n all roles granted to the account except those named. The\n named roles need not exist or be granted to the account."
}
],
[
{
"para": "role [,\n role ] ...: Activate\n the named roles, which must be granted to the account."
}
]
]
}
],
"id": "SET ROLE",
"syntax": [
{
"programlisting": ">\nSET ROLE {\n DEFAULT\n | NONE\n | ALL\n | ALL EXCEPT role [, role ] ...\n | role [, role ] ...\n}"
}
]
},
{
"keywords": [
"ALTER",
"RESOURCE",
"GROUP",
"VCPU",
"THREAD_PRIORITY",
"ENABLE",
"DISABLE",
"FORCE"
],
"description": [
{
"para": "ALTER RESOURCE GROUP is used for\n resource group management (see\n ). This statement alters\n modifiable attributes of an existing resource group. It requires\n the RESOURCE_GROUP_ADMIN\n privilege."
},
{
"para": "group_name identifies which resource\n group to alter. If the group does not exist, an error occurs."
},
{
"para": "The attributes for CPU affinity, priority, and whether the group\n is enabled can be modified with ALTER\n RESOURCE GROUP. These attributes are specified the\n same way as described for CREATE RESOURCE\n GROUP (see ).\n Only the attributes specified are altered. Unspecified\n attributes retain their current values."
},
{
"para": "The FORCE modifier is used with\n DISABLE. It determines statement behavior if\n the resource group has any threads assigned to it:"
},
{
"itemizedlist": [
[
{
"para": "If FORCE is not given, existing threads\n in the group continue to run until they terminate, but new\n threads cannot be assigned to the group."
}
],
[
{
"para": "If FORCE is given, existing threads in\n the group are moved to their respective default group\n (system threads to SYS_default, user\n threads to USR_default)."
}
]
]
},
{
"para": "The name and type attributes are set at group creation time and\n cannot be modified thereafter with ALTER\n RESOURCE GROUP."
},
{
"para": "Examples:"
},
{
"itemizedlist": [
[
{
"para": "Alter a group CPU affinity:"
},
{
"programlisting": ">\nALTER RESOURCE GROUP rg1 VCPU = 0-63;"
}
],
[
{
"para": "Alter a group thread priority:"
},
{
"programlisting": ">\nALTER RESOURCE GROUP rg2 THREAD_PRIORITY = 5;"
}
],
[
{
"para": "Disable a group, moving any threads assigned to it to the\n default groups:"
},
{
"programlisting": ">\nALTER RESOURCE GROUP rg3 DISABLE FORCE;"
}
]
]
},
{
"para": "Resource group management is local to the server on which it\n occurs. ALTER RESOURCE GROUP\n statements are not written to the binary log and are not\n replicated."
}
],
"id": "ALTER RESOURCE GROUP",
"syntax": [
{
"programlisting": ">\nALTER RESOURCE GROUP group_name\n [VCPU [=] vcpu_spec [, vcpu_spec] ...]\n [THREAD_PRIORITY [=] N]\n [ENABLE|DISABLE [FORCE]]\n\nvcpu_spec: {N | M - N}"
}
]
},
{
"keywords": [
"CREATE",
"RESOURCE",
"GROUP",
"TYPE",
"SYSTEM",
"USER",
"VCPU",
"THREAD_PRIORITY",
"ENABLE",
"DISABLE"
],
"description": [
{
"para": "CREATE RESOURCE GROUP is used for\n resource group management (see\n ). This statement creates a new\n resource group and assigns its initial attribute values. It\n requires the RESOURCE_GROUP_ADMIN\n privilege."
},
{
"para": "group_name identifies which resource\n group to create. If the group already exists, an error occurs."
},
{
"para": "The TYPE attribute is required. It should be\n SYSTEM for a system resource group,\n USER for a user resource group. The group\n type affects permitted THREAD_PRIORITY\n values, as described later."
},
{
"para": "The VCPU attribute indicates the CPU\n affinity; that is, the set of virtual CPUs the group can use:"
},
{
"itemizedlist": [
[
{
"para": "If VCPU is not given, the resource group\n has no CPU affinity and can use all available CPUs."
}
],
[
{
"para": "If VCPU is given, the attribute value is\n a list of comma-separated CPU numbers or ranges:"
},
{
"itemizedlist": [
[
{
"para": "Each number must be an integer in the range from 0 to\n the number of CPUs minus 1. For example, on a system\n with 64 CPUs, the number can range from 0 to 63."
}
],
[
{
"para": "A range is given in the form\n M minus\n N, where\n M is less than or equal to\n N and both numbers are in the\n CPU range."
}
],
[
{
"para": "If a CPU number is an integer outside the permitted\n range or is not an integer, an error occurs."
}
]
]
}
]
]
},
{
"para": "Example VCPU specifiers (these are all\n equivalent):"
},
{
"programlisting": ">\nVCPU = 0,1,2,3,9,10\nVCPU = 0-3,9-10\nVCPU = 9,10,0-3\nVCPU = 0,10,1,9,3,2"
},
{
"para": "The THREAD_PRIORITY attribute indicates the\n priority for threads assigned to the group:"
},
{
"itemizedlist": [
[
{
"para": "If THREAD_PRIORITY is not given, the\n default priority is 0."
}
],
[
{
"para": "If THREAD_PRIORITY is given, the\n attribute value must be in the range from -20 (highest\n priority) to 19 (lowest priority). The priority for system\n resource groups must be in the range from -20 to 0. The\n priority for user resource groups must be in the range from\n 0 to 19. Use of different ranges for system and user groups\n ensures that user threads never have a higher priority than\n system threads."
}
]
]
},
{
"para": "ENABLE and DISABLE specify\n that the resource group is initially enabled or disabled. If\n neither is specified, the group is enabled by default. A\n disabled group cannot have threads assigned to it."
},
{
"para": "Examples:"
},
{
"itemizedlist": [
[
{
"para": "Create an enabled user group that has a single CPU and the\n lowest priority:"
},
{
"programlisting": ">\nCREATE RESOURCE GROUP rg1\n TYPE = USER\n VCPU = 0\n THREAD_PRIORITY = 19;"
}
],
[
{
"para": "Create a disabled system group that has no CPU affinity (can\n use all CPUs) and the highest priority:"
},
{
"programlisting": ">\nCREATE RESOURCE GROUP rg2\n TYPE = SYSTEM\n THREAD_PRIORITY = -20\n DISABLE;"
}
]
]
},
{
"para": "Resource group management is local to the server on which it\n occurs. CREATE RESOURCE GROUP\n statements are not written to the binary log and are not\n replicated."
}
],
"id": "CREATE RESOURCE GROUP",
"syntax": [
{
"programlisting": ">\nCREATE RESOURCE GROUP group_name\n TYPE = {SYSTEM|USER}\n [VCPU [=] vcpu_spec [, vcpu_spec] ...]\n [THREAD_PRIORITY [=] N]\n [ENABLE|DISABLE]\n\nvcpu_spec: {N | M - N}"
}
]
},
{
"keywords": [
"DROP",
"RESOURCE",
"GROUP",
"FORCE"
],
"description": [
{
"para": "DROP RESOURCE GROUP is used for\n resource group management (see\n ). This statement drops a\n resource group. It requires the\n RESOURCE_GROUP_ADMIN privilege."
},
{
"para": "group_name identifies which resource\n group to drop. If the group does not exist, an error occurs."
},
{
"para": "The FORCE modifier determines statement\n behavior if the resource group has any threads assigned to it:"
},
{
"itemizedlist": [
[
{
"para": "If FORCE is not given and any threads are\n assigned to the group, an error occurs."
}
],
[
{
"para": "If FORCE is given, existing threads in\n the group are moved to their respective default group\n (system threads to SYS_default, user\n threads to USR_default)."
}
]
]
},
{
"para": "Examples:"
},
{
"itemizedlist": [
[
{
"para": "Drop a group, failing if the group contains any threads:"
},
{
"programlisting": ">\nDROP RESOURCE GROUP rg1;"
}
],
[
{
"para": "Drop a group and move existing threads to the default\n groups:"
},
{
"programlisting": ">\nDROP RESOURCE GROUP rg2 FORCE;"
}
]
]
},
{
"para": "Resource group management is local to the server on which it\n occurs. DROP RESOURCE GROUP\n statements are not written to the binary log and are not\n replicated."
}
],
"id": "DROP RESOURCE GROUP",
"syntax": [
{
"programlisting": ">\nDROP RESOURCE GROUP group_name [FORCE]"
}
]
},
{
"keywords": [
"SET",
"RESOURCE",
"GROUP",
"FOR"
],
"description": [
{
"para": "SET RESOURCE GROUP is used for\n resource group management (see\n ). This statement assigns\n threads to a resource group. It requires the\n RESOURCE_GROUP_ADMIN or\n RESOURCE_GROUP_USER privilege."
},
{
"para": "group_name identifies which resource\n group to be assigned. Any thread_id\n values indicate threads to assign to the group. Thread IDs can\n be determined from the Performance Schema\n threads table. If the resource\n group or any named thread ID does not exist, an error occurs."
},
{
"para": "With no FOR clause, the statement assigns the\n current thread for the session to the resource group."
},
{
"para": "With a FOR clause that names thread IDs, the\n statement assigns those threads to the resource group."
},
{
"para": "For attempts to assign a system thread to a user resource group\n or a user thread to a system resource group, a warning occurs."
},
{
"para": "Examples:"
},
{
"itemizedlist": [
[
{
"para": "Assign the current session thread to a group:"
},
{
"programlisting": ">\nSET RESOURCE GROUP rg1;"
}
],
[
{
"para": "Assign the named threads to a group:"
},
{
"programlisting": ">\nSET RESOURCE GROUP rg2 FOR 14, 78, 4;"
}
]
]
},
{
"para": "Resource group management is local to the server on which it\n occurs. SET RESOURCE GROUP\n statements are not written to the binary log and are not\n replicated."
},
{
"para": "An alternative to SET RESOURCE\n GROUP is the\n RESOURCE_GROUP optimizer hint,\n which assigns individual statements to a resource group. See\n ."
}
],
"id": "SET RESOURCE GROUP",
"syntax": [
{
"programlisting": ">\nSET RESOURCE GROUP group_name\n [FOR thread_id [, thread_id] ...]"
}
]
},
{
"keywords": [
"ANALYZE",
"TABLE",
"NO_WRITE_TO_BINLOG",
"LOCAL"
],
"description": [
{
"para": "ANALYZE TABLE generates table\n statistics:"
},
{
"itemizedlist": [
[
{
"para": "ANALYZE TABLE without either\n HISTOGRAM clause performs a key\n distribution analysis and stores the distribution for the\n named table or tables. For MyISAM tables,\n ANALYZE TABLE for key\n distribution analysis is equivalent to using\n myisamchk --analyze."
}
],
[
{
"para": "ANALYZE TABLE with the\n UPDATE HISTOGRAM clause generates\n histogram statistics for the named table columns and stores\n them in the data dictionary. Only one table name is\n permitted for this syntax."
}
],
[
{
"para": "ANALYZE TABLE with the\n DROP HISTOGRAM clause removes histogram\n statistics for the named table columns from the data\n dictionary. Only one table name is permitted for this\n syntax."
}
]
]
},
{
"para": "This statement requires SELECT\n and INSERT privileges for the\n table."
},
{
"para": "ANALYZE TABLE works with\n InnoDB, NDB, and\n MyISAM tables. It does not work with views."
},
{
"para": "If the innodb_read_only system\n variable is enabled, ANALYZE\n TABLE may fail because it cannot update statistics\n tables in the data dictionary, which use\n InnoDB. For ANALYZE\n TABLE operations that update the key distribution,\n failure may occur even if the operation updates the table itself\n (for example, if it is a MyISAM table). To\n obtain the updated distribution statistics, set\n information_schema_stats_expiry=0."
},
{
"para": "ANALYZE TABLE is supported for\n partitioned tables, and you can use ALTER TABLE ...\n ANALYZE PARTITION to analyze one or more partitions;\n for more information, see , and\n ."
},
{
"para": "During the analysis, the table is locked with a read lock for\n InnoDB and MyISAM."
},
{
"para": "ANALYZE TABLE removes the table\n from the table definition cache, which requires a flush lock. If\n there are long running statements or transactions still using\n the table, subsequent statements and transactions must wait for\n those operations to finish before the flush lock is released.\n Because ANALYZE TABLE itself\n typically finishes quickly, it may not be apparent that delayed\n transactions or statements involving the same table are due to\n the remaining flush lock."
},
{
"para": "By default, the server writes ANALYZE\n TABLE statements to the binary log so that they\n replicate to replication slaves. To suppress logging, specify\n the optional NO_WRITE_TO_BINLOG keyword or\n its alias LOCAL."
}
],
"id": "ANALYZE TABLE",
"syntax": [
{
"programlisting": ">\nANALYZE [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE tbl_name [, tbl_name] ...\n\nANALYZE [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE tbl_name\n UPDATE HISTOGRAM ON col_name [, col_name] ...\n [WITH N BUCKETS]\n\nANALYZE [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE tbl_name\n DROP HISTOGRAM ON col_name [, col_name] ..."
}
]
},
{
"keywords": [
"CHECK",
"TABLE",
"QUICK",
"FAST",
"MEDIUM",
"UPGRADE"
],
"description": [
{
"para": "CHECK TABLE checks a table or\n tables for errors. CHECK TABLE\n can also check views for problems, such as tables that are\n referenced in the view definition that no longer exist."
},
{
"para": "To check a table, you must have some privilege for it."
},
{
"para": "CHECK TABLE works for\n InnoDB,\n MyISAM,\n ARCHIVE, and\n CSV tables."
},
{
"para": "Before running CHECK TABLE on\n InnoDB tables, see\n ."
},
{
"para": "CHECK TABLE is supported for\n partitioned tables, and you can use ALTER TABLE ...\n CHECK PARTITION to check one or more partitions; for\n more information, see , and\n ."
},
{
"para": "CHECK TABLE ignores virtual\n generated columns that are not indexed."
}
],
"id": "CHECK TABLE",
"syntax": [
{
"programlisting": ">\nCHECK TABLE tbl_name [, tbl_name] ... [option] ...\n\noption: {\n FOR UPGRADE\n | QUICK\n | FAST\n | MEDIUM\n | EXTENDED\n | CHANGED\n}"
}
]
},
{
"keywords": [
"CHECKSUM",
"TABLE"
],
"description": [
{
"para": "CHECKSUM TABLE reports a\n checksum for the contents\n of a table. You can use this statement to verify that the\n contents are the same before and after a backup, rollback, or\n other operation that is intended to put the data back to a known\n state."
},
{
"para": "This statement requires the\n SELECT privilege for the table."
},
{
"para": "This statement is not supported for views. If you run\n CHECKSUM TABLE against a view,\n the Checksum value is always\n NULL, and a warning is returned."
},
{
"para": "For a nonexistent table, CHECKSUM\n TABLE returns NULL and generates a\n warning."
},
{
"para": "During the checksum operation, the table is locked with a read\n lock for InnoDB and\n MyISAM."
}
],
"id": "CHECKSUM TABLE",
"syntax": [
{
"programlisting": ">\nCHECKSUM TABLE tbl_name [, tbl_name] ... [QUICK | EXTENDED]"
}
]
},
{
"keywords": [
"OPTIMIZE",
"TABLE",
"NO_WRITE_TO_BINLOG",
"LOCAL"
],
"description": [
{
"para": "OPTIMIZE TABLE reorganizes the\n physical storage of table data and associated index data, to\n reduce storage space and improve I/O efficiency when accessing\n the table. The exact changes made to each table depend on the\n storage engine used\n by that table."
},
{
"para": "Use OPTIMIZE TABLE in these\n cases, depending on the type of table:"
},
{
"itemizedlist": [
[
{
"para": "After doing substantial insert, update, or delete operations\n on an InnoDB table that has its own\n .ibd file because it\n was created with the\n innodb_file_per_table\n option enabled. The table and indexes are reorganized, and\n disk space can be reclaimed for use by the operating system."
}
],
[
{
"para": "After doing substantial insert, update, or delete operations\n on columns that are part of a FULLTEXT\n index in an InnoDB table. Set the\n configuration option\n innodb_optimize_fulltext_only=1\n first. To keep the index maintenance period to a reasonable\n time, set the\n innodb_ft_num_word_optimize\n option to specify how many words to update in the search\n index, and run a sequence of OPTIMIZE\n TABLE statements until the search index is fully\n updated."
}
],
[
{
"para": "After deleting a large part of a MyISAM\n or ARCHIVE table, or making many changes\n to a MyISAM or ARCHIVE\n table with variable-length rows (tables that have\n VARCHAR,\n VARBINARY,\n BLOB, or\n TEXT columns). Deleted rows\n are maintained in a linked list and subsequent\n INSERT operations reuse old\n row positions. You can use OPTIMIZE\n TABLE to reclaim the unused space and to\n defragment the data file. After extensive changes to a\n table, this statement may also improve performance of\n statements that use the table, sometimes significantly."
}
]
]
},
{
"para": "This statement requires SELECT\n and INSERT privileges for the\n table."
},
{
"para": "OPTIMIZE TABLE works for\n InnoDB,\n MyISAM, and\n ARCHIVE tables.\n OPTIMIZE TABLE is also supported\n for dynamic columns of in-memory\n NDB tables. It does not work for\n fixed-width columns of in-memory tables, nor does it work for\n Disk Data tables. The performance of OPTIMIZE\n on NDB Cluster tables can be tuned using\n , which\n controls the length of time to wait between processing batches\n of rows by OPTIMIZE TABLE. For\n more information, see\n ."
},
{
"para": "For NDB Cluster tables, OPTIMIZE\n TABLE can be interrupted by (for example) killing the\n SQL thread performing the OPTIMIZE operation."
},
{
"para": "By default, OPTIMIZE TABLE does\n not work for tables created using any other\n storage engine and returns a result indicating this lack of\n support. You can make OPTIMIZE\n TABLE work for other storage engines by starting\n mysqld with the\n option. In this case,\n OPTIMIZE TABLE is just mapped to\n ALTER TABLE."
},
{
"para": "This statement does not work with views."
},
{
"para": "OPTIMIZE TABLE is supported for\n partitioned tables. For information about using this statement\n with partitioned tables and table partitions, see\n ."
},
{
"para": "By default, the server writes OPTIMIZE\n TABLE statements to the binary log so that they\n replicate to replication slaves. To suppress logging, specify\n the optional NO_WRITE_TO_BINLOG keyword or\n its alias LOCAL."
}
],
"id": "OPTIMIZE TABLE",
"syntax": [
{
"programlisting": ">\nOPTIMIZE [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE tbl_name [, tbl_name] ..."
}
]
},
{
"keywords": [
"REPAIR",
"TABLE",
"USE_FRM",
"QUICK",
"EXTENDED",
"NO_WRITE_TO_BINLOG",
"LOCAL"
],
"description": [
{
"para": "REPAIR TABLE repairs a possibly\n corrupted table, for certain storage engines only."
},
{
"para": "This statement requires SELECT\n and INSERT privileges for the\n table."
},
{
"para": "Although normally you should never have to run\n REPAIR TABLE, if disaster\n strikes, this statement is very likely to get back all your data\n from a MyISAM table. If your tables become\n corrupted often, try to find the reason for it, to eliminate the\n need to use REPAIR TABLE. See\n , and\n ."
},
{
"para": "REPAIR TABLE checks the table to\n see whether an upgrade is required. If so, it performs the\n upgrade, following the same rules as\n CHECK TABLE ... FOR\n UPGRADE. See , for more\n information."
}
],
"id": "REPAIR TABLE",
"syntax": [
{
"programlisting": ">\nREPAIR [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE tbl_name [, tbl_name] ...\n [QUICK] [EXTENDED] [USE_FRM]"
}
]
},
{
"keywords": [
"AGGREGATE",
"CREATE",
"FUNCTION",
"STRING",
"REAL",
"INTEGER",
"DECIMAL",
"RETURNS",
"SONAME"
],
"description": [
{
"para": "A user-defined function (UDF) is a way to extend MySQL with a\n new function that works like a native (built-in) MySQL function\n such as ABS() or\n CONCAT()."
},
{
"para": "function_name is the name that should\n be used in SQL statements to invoke the function. The\n RETURNS clause indicates the type of the\n function's return value. DECIMAL\n is a legal value after RETURNS, but currently\n DECIMAL functions return string\n values and should be written like STRING\n functions."
},
{
"para": "shared_library_name is the base name\n of the shared library file that contains the code that\n implements the function. The file must be located in the plugin\n directory. This directory is given by the value of the\n plugin_dir system variable. For\n more information, see ."
},
{
"para": "To create a function, you must have the\n INSERT privilege for the\n mysql system schema. This is necessary\n because CREATE FUNCTION adds a\n row to the mysql.func system table that\n records the function's name, type, and shared library name."
},
{
"para": "UDFs registered using CREATE\n FUNCTION are listed in the Performance Schema\n user_defined_functions table; see\n ."
}
],
"id": "CREATE FUNCTION UDF",
"syntax": [
{
"programlisting": ">\nCREATE [AGGREGATE] FUNCTION function_name\n RETURNS {STRING|INTEGER|REAL|DECIMAL}\n SONAME shared_library_name"
}
]
},
{
"keywords": [
"DROP",
"FUNCTION"
],
"description": [
{
"para": "This statement drops the user-defined function (UDF) named\n function_name."
},
{
"para": "To drop a function, you must have the\n DELETE privilege for the\n mysql system schema. This is because\n DROP FUNCTION removes a row from\n the mysql.func system table that records the\n function's name, type, and shared library name."
}
],
"id": "DROP FUNCTION UDF",
"syntax": [
{
"programlisting": ">\nDROP FUNCTION function_name"
}
]
},
{
"keywords": [
"INSTALL",
"COMPONENT"
],
"description": [
{
"para": "This statement installs one or more server components, which\n become active immediately. A component provides services that\n are available to the server and other components; see\n .\n INSTALL COMPONENT requires the\n INSERT privilege for the\n mysql.component system table."
},
{
"para": "Example:"
},
{
"programlisting": ">\nINSTALL COMPONENT 'file://component1', 'file://component2';"
},
{
"para": "Component names are URNs that begin with\n file:// and indicate the base name of the\n file that implements the component, located in the directory\n named by the plugin_dir system\n variable. Component names do not include any platform-dependent\n file name suffix such as .so or\n .dll. (These naming details are subject to\n change because component name interpretation is itself performed\n by a service and the component infrastructure makes it possible\n to replace the default service implementation with alternative\n implementations.)"
},
{
"para": "If any error occurs, the statement fails and has no effect. For\n example, this happens if a component name is erroneous, a named\n component does not exist or is already installed, or component\n initialization fails."
},
{
"para": "A loader service handles component loading, which includes\n adding installed components to the\n mysql.component system table that serves as a\n registry. For subsequent server restarts, any components listed\n in mysql.component are loaded by the loader\n service during the startup sequence. This occurs even if the\n server is started with the\n option."
},
{
"para": "If a component depends on services not present in the registry\n and you attempt to install the component without also installing\n the component or components that provide the services on which\n it depends, an error occurs:"
},
{
"programlisting": ">\nERROR 3527 (HY000): Cannot satisfy dependency for service 'component_a'\nrequired by component 'component_b'."
},
{
"para": "To avoid this problem, either install all components in the same\n statement, or install the dependent component after installing\n any components on which it depends."
}
],
"id": "INSTALL COMPONENT",
"syntax": [
{
"programlisting": ">\nINSTALL COMPONENT component_name [, component_name ] ..."
}
]
},
{
"keywords": [
"INSTALL",
"PLUGIN"
],
"description": [
{
"para": "This statement installs a server plugin. It requires the\n INSERT privilege for the\n mysql.plugin system table."
},
{
"para": "plugin_name is the name of the plugin\n as defined in the plugin descriptor structure contained in the\n library file (see ).\n Plugin names are not case-sensitive. For maximal compatibility,\n plugin names should be limited to ASCII letters, digits, and\n underscore because they are used in C source files, shell\n command lines, M4 and Bourne shell scripts, and SQL\n environments."
},
{
"para": "shared_library_name is the name of\n the shared library that contains the plugin code. The name\n includes the file name extension (for example,\n libmyplugin.so,\n libmyplugin.dll, or\n libmyplugin.dylib)."
},
{
"para": "The shared library must be located in the plugin directory (the\n directory named by the\n plugin_dir system variable).\n The library must be in the plugin directory itself, not in a\n subdirectory. By default,\n plugin_dir is the\n plugin directory under the directory named\n by the pkglibdir configuration variable, but\n it can be changed by setting the value of\n plugin_dir at server startup.\n For example, set its value in a my.cnf\n file:"
},
{
"programlisting": ">\n[mysqld]\nplugin_dir=/path/to/plugin/directory"
},
{
"para": "If the value of plugin_dir is a\n relative path name, it is taken to be relative to the MySQL base\n directory (the value of the\n basedir system variable)."
},
{
"para": "INSTALL PLUGIN loads and\n initializes the plugin code to make the plugin available for\n use. A plugin is initialized by executing its initialization\n function, which handles any setup that the plugin must perform\n before it can be used. When the server shuts down, it executes\n the deinitialization function for each plugin that is loaded so\n that the plugin has a chance to perform any final cleanup."
},
{
"para": "INSTALL PLUGIN also registers the\n plugin by adding a line that indicates the plugin name and\n library file name to the mysql.plugin system\n table. At server startup, the server loads and initializes any\n plugin that is listed in mysql.plugin. This\n means that a plugin is installed with\n INSTALL PLUGIN only once, not\n every time the server starts. Plugin loading at startup does not\n occur if the server is started with the\n option."
},
{
"para": "A plugin library can contain multiple plugins. For each of them\n to be installed, use a separate INSTALL\n PLUGIN statement. Each statement names a different\n plugin, but all of them specify the same library name."
}
],
"id": "INSTALL PLUGIN",
"syntax": [
{
"programlisting": ">\nINSTALL PLUGIN plugin_name SONAME 'shared_library_name'"
}
]
},
{
"keywords": [
"UNINSTALL",
"COMPONENT"
],
"description": [
{
"para": "This statement deactivates and uninstalls one or more server\n components. A component provides services that are available to\n the server and other components; see\n .\n UNINSTALL COMPONENT is the\n complement of INSTALL COMPONENT.\n It requires the DELETE privilege\n for the mysql.component system table."
},
{
"para": "Example:"
},
{
"programlisting": ">\nUNINSTALL COMPONENT 'file://component1', 'file://component2';"
},
{
"para": "For information about component naming, see\n ."
},
{
"para": "If any error occurs, the statement fails and has no effect. For\n example, this happens if a component name is erroneous, a named\n component is not installed, or cannot be uninstalled because\n other installed components depend on it."
},
{
"para": "A loader service handles component unloading, which includes\n removing uninstalled components from the\n mysql.component system table that serves as a\n registry. As a result, unloaded components are not loaded during\n the startup sequence for subsequent server restarts."
}
],
"id": "UNINSTALL COMPONENT",
"syntax": [
{
"programlisting": ">\nUNINSTALL COMPONENT component_name [, component_name ] ..."
}
]
},
{
"keywords": [
"UNINSTALL",
"PLUGIN"
],
"description": [
{
"para": "This statement removes an installed server plugin. It requires\n the DELETE privilege for the\n mysql.plugin system table.\n UNINSTALL PLUGIN is the\n complement of INSTALL PLUGIN."
},
{
"para": "plugin_name must be the name of some\n plugin that is listed in the mysql.plugin\n table. The server executes the plugin's deinitialization\n function and removes the row for the plugin from the\n mysql.plugin system table, so that subsequent\n server restarts will not load and initialize the plugin.\n UNINSTALL PLUGIN does not remove\n the plugin's shared library file."
}
],
"id": "UNINSTALL PLUGIN",
"syntax": [
{
"programlisting": ">\nUNINSTALL PLUGIN plugin_name"
}
]
},
{
"keywords": [
"CLONE"
],
"description": [
{
"para": "The CLONE statement is used to\n clone data locally or from a remote MySQL server instance. To use\n CLONE syntax, the clone plugin must\n be installed. See ."
},
{
"para": "CLONE LOCAL DATA\n DIRECTORY syntax clones data from the local MySQL data\n directory to a directory on the same server or node where the\n MySQL server instance runs. The 'clone_dir'\n directory is the full path of the local directory that data is\n cloned to. An absolute path is required. The specified directory\n must not exist, but the specified path must be an existent path.\n The MySQL server requires the necessary write access to create the\n specified directory. For more information, see\n ."
},
{
"para": "CLONE INSTANCE\n syntax clones data from a remote MySQL server instance (the donor)\n and transfers it to the MySQL instance where the cloning operation\n was initiated (the recipient)."
},
{
"itemizedlist": [
[
{
"para": "user is the\n clone user on the donor MySQL server instance."
}
],
[
{
"para": "host is the\n hostname address of the donor\n MySQL server instance. Internet Protocol version 6 (IPv6)\n address format is not supported. An alias to the IPv6 address\n can be used instead. An IPv4 address can be used as is."
}
],
[
{
"para": "port is the\n port number of the donor\n MySQL server instance. (The mysqlxprotocol port specified by\n mysqlx_port is not supported.\n Connecting to the donor MySQL server instance through router\n is also not supported.)"
}
],
[
{
"para": "IDENTIFIED BY\n 'password' specifies the\n password of the clone user on the donor MySQL server instance."
}
],
[
{
"para": "DATA DIRECTORY [=]\n 'clone_dir' is an\n optional clause used to specify a directory on the recipient\n for the data you are cloning. Use this option if you do not\n want to remove existing data in the recipient data directory.\n An absolute path is required, and the directory must not\n exist. The MySQL server must have the necessary write access\n to create the directory."
},
{
"para": "When the optional DATA DIRECTORY [=]\n 'clone_dir' clause is not\n used, a cloning operation removes existing data in the\n recipient data directory, replaces it with the cloned data,\n and automatically restarts the server afterward."
}
],
[
{
"para": "[REQUIRE [NO] SSL] explicitly specifies\n whether an encrypted connection is to be used or not when\n transferring cloned data over the network. An error is\n returned if the explicit specification cannot be satisfied. If\n an SSL clause is not specified, clone attempts to establish an\n encrypted connection by default, falling back to an insecure\n connection if the secure connection attempt fails. A secure\n connection is required when cloning encrypted data regardless\n of whether this clause is specified. For more information, see\n ."
}
]
]
},
{
"para": "For additional information about cloning data from a remote MySQL\n server instance, see ."
}
],
"id": "CLONE",
"syntax": [
{
"programlisting": ">\nCLONE clone_action\n\nclone_action: {\n LOCAL DATA DIRECTORY [=] 'clone_dir';\n | INSTANCE FROM 'user'@'host':port\n IDENTIFIED BY 'password'\n [DATA DIRECTORY [=] 'clone_dir']\n [REQUIRE [NO] SSL]\n}"
}
]
},
{
"keywords": [
"SET",
"GLOBAL",
"SESSION",
"VARIABLE",
"PERSIST",
"PERSIST_ONLY"
],
"description": [
{
"para": "SET\n syntax for variable assignment enables you to assign values to\n different types of variables that affect the operation of the\n server or clients:"
},
{
"itemizedlist": [
[
{
"para": "User-defined variables. See\n ."
}
],
[
{
"para": "Stored procedure and function parameters, and stored program\n local variables. See\n ."
}
],
[
{
"para": "System variables. See\n . System variables\n also can be set at server startup, as described in\n ."
}
]
]
}
],
"id": "SET",
"syntax": [
{
"programlisting": ">\nSET variable = expr [, variable = expr] ...\n\nvariable: {\n user_var_name\n | param_name\n | local_var_name\n | {GLOBAL | @@GLOBAL.} system_var_name\n | {PERSIST | @@PERSIST.} system_var_name\n | {PERSIST_ONLY | @@PERSIST_ONLY.} system_var_name\n | [SESSION | @@SESSION. | @@] system_var_name\n}"
}
]
},
{
"keywords": [
"SET",
"CHARACTER",
"CHARSET"
],
"description": [
{
"para": "This statement maps all strings sent between the server and the\n current client with the given mapping. SET CHARACTER\n SET sets three session system variables:\n character_set_client and\n character_set_results are set\n to the given character set, and\n character_set_connection to the\n value of\n character_set_database. See\n ."
},
{
"para": "charset_name may be quoted or\n unquoted."
},
{
"para": "The default character set mapping can be restored by using the\n value DEFAULT. The default depends on the\n server configuration."
},
{
"para": "Some character sets cannot be used as the client character set.\n Attempting to use them with SET CHARACTER\n SET produces an error. See\n ."
}
],
"id": "SET CHARACTER SET",
"syntax": [
{
"programlisting": ">\nSET {CHARACTER SET | CHARSET}\n {'charset_name' | DEFAULT}"
}
]
},
{
"keywords": [
"SET",
"NAMES"
],
"description": [
{
"para": "This statement sets the three session system variables\n character_set_client,\n character_set_connection, and\n character_set_results to the\n given character set. Setting\n character_set_connection to\n charset_name also sets\n collation_connection to the\n default collation for charset_name. See\n ."
},
{
"para": "The optional COLLATE clause may be used to\n specify a collation explicitly. If given, the collation must one\n of the permitted collations for\n charset_name."
},
{
"para": "charset_name and\n collation_name may be quoted or\n unquoted."
},
{
"para": "The default mapping can be restored by using a value of\n DEFAULT. The default depends on the server\n configuration."
},
{
"para": "Some character sets cannot be used as the client character set.\n Attempting to use them with SET\n NAMES produces an error. See\n ."
}
],
"id": "SET NAMES",
"syntax": [
{
"programlisting": ">\nSET NAMES {'charset_name'\n [COLLATE 'collation_name'] | DEFAULT}"
}
]
},
{
"keywords": [
"SHOW",
"BINARY",
"MASTER",
"LOGS"
],
"description": [
{
"para": "Lists the binary log files on the server. This statement is used\n as part of the procedure described in\n , that shows how to determine\n which logs can be purged. SHOW BINARY\n LOGS requires the REPLICATION\n CLIENT or SUPER\n privilege."
},
{
"para": "Encrypted binary log files have a 512-byte file header that\n stores information required for encryption and decryption of the\n file. This is included in the file size displayed by\n SHOW BINARY LOGS. The\n Encrypted column shows whether or not the\n binary log file is encrypted. Binary log encryption is active if\n binlog_encryption=ON is set for\n the server. Existing binary log files are not encrypted or\n decrypted if binary log encryption is activated or deactivated\n while the server is running."
},
{
"programlisting": ">\nmysql> SHOW BINARY LOGS;\n+---------------+-----------+-----------+\n| Log_name | File_size | Encrypted |\n+---------------+-----------+-----------+\n| binlog.000015 | 724935 | Yes |\n| binlog.000016 | 733481 | Yes |\n+---------------+-----------+-----------+"
}
],
"id": "SHOW BINARY LOGS",
"syntax": [
{
"programlisting": ">\nSHOW BINARY LOGS\nSHOW MASTER LOGS"
}
]
},
{
"keywords": [
"SHOW",
"BINLOG",
"EVENTS",
"LIMIT",
"FROM",
"IN"
],
"description": [
{
"para": "Shows the events in the binary log. If you do not specify\n 'log_name', the\n first binary log is displayed. SHOW BINLOG\n EVENTS requires the REPLICATION\n SLAVE privilege."
}
],
"id": "SHOW BINLOG EVENTS",
"syntax": [
{
"programlisting": ">\nSHOW BINLOG EVENTS\n [IN 'log_name']\n [FROM pos]\n [LIMIT [offset,] row_count]"
}
]
},
{
"keywords": [
"SHOW",
"CHARACTER",
"SET"
],
"description": [
{
"para": "The SHOW CHARACTER SET statement\n shows all available character sets. The\n LIKE clause, if present, indicates\n which character set names to match. The WHERE\n clause can be given to select rows using more general\n conditions, as discussed in . For\n example:"
},
{
"programlisting": ">\nmysql> SHOW CHARACTER SET LIKE 'latin%';\n+---------+-----------------------------+-------------------+--------+\n| Charset | Description | Default collation | Maxlen |\n+---------+-----------------------------+-------------------+--------+\n| latin1 | cp1252 West European | latin1_swedish_ci | 1 |\n| latin2 | ISO 8859-2 Central European | latin2_general_ci | 1 |\n| latin5 | ISO 8859-9 Turkish | latin5_turkish_ci | 1 |\n| latin7 | ISO 8859-13 Baltic | latin7_general_ci | 1 |\n+---------+-----------------------------+-------------------+--------+"
}
],
"id": "SHOW CHARACTER SET",
"syntax": [
{
"programlisting": ">\nSHOW CHARACTER SET\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"COLLATION"
],
"description": [
{
"para": "This statement lists collations supported by the server. By\n default, the output from SHOW\n COLLATION includes all available collations. The\n LIKE clause, if present, indicates\n which collation names to match. The WHERE\n clause can be given to select rows using more general\n conditions, as discussed in . For\n example:"
},
{
"programlisting": ">\nmysql> SHOW COLLATION WHERE Charset = 'latin1';\n+-------------------+---------+----+---------+----------+---------+\n| Collation | Charset | Id | Default | Compiled | Sortlen |\n+-------------------+---------+----+---------+----------+---------+\n| latin1_german1_ci | latin1 | 5 | | Yes | 1 |\n| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 |\n| latin1_danish_ci | latin1 | 15 | | Yes | 1 |\n| latin1_german2_ci | latin1 | 31 | | Yes | 2 |\n| latin1_bin | latin1 | 47 | | Yes | 1 |\n| latin1_general_ci | latin1 | 48 | | Yes | 1 |\n| latin1_general_cs | latin1 | 49 | | Yes | 1 |\n| latin1_spanish_ci | latin1 | 94 | | Yes | 1 |\n+-------------------+---------+----+---------+----------+---------+"
}
],
"id": "SHOW COLLATION",
"syntax": [
{
"programlisting": ">\nSHOW COLLATION\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"COLUMNS",
"FIELDS",
"EXTENDED",
"FULL",
"FROM",
"IN",
"LIKE",
"WHERE"
],
"description": [
{
"para": "SHOW COLUMNS displays information\n about the columns in a given table. It also works for views.\n SHOW COLUMNS displays information\n only for those columns for which you have some privilege."
},
{
"programlisting": ">\nmysql> SHOW COLUMNS FROM City;\n+-------------+----------+------+-----+---------+----------------+\n| Field | Type | Null | Key | Default | Extra |\n+-------------+----------+------+-----+---------+----------------+\n| ID | int(11) | NO | PRI | NULL | auto_increment |\n| Name | char(35) | NO | | | |\n| CountryCode | char(3) | NO | MUL | | |\n| District | char(20) | NO | | | |\n| Population | int(11) | NO | | 0 | |\n+-------------+----------+------+-----+---------+----------------+"
},
{
"para": "An alternative to tbl_name\n FROM db_name syntax is\n db_name.tbl_name. These two\n statements are equivalent:"
},
{
"programlisting": ">\nSHOW COLUMNS FROM mytable FROM mydb;\nSHOW COLUMNS FROM mydb.mytable;"
},
{
"para": "The optional EXTENDED keyword causes the\n output to include information about hidden columns that MySQL\n uses internally and are not accessible by users."
},
{
"para": "The optional FULL keyword causes the output\n to include the column collation and comments, as well as the\n privileges you have for each column."
},
{
"para": "The LIKE clause, if present,\n indicates which column names to match. The\n WHERE clause can be given to select rows\n using more general conditions, as discussed in\n ."
},
{
"para": "The data types may differ from what you expect them to be based\n on a CREATE TABLE statement\n because MySQL sometimes changes data types when you create or\n alter a table. The conditions under which this occurs are\n described in ."
},
{
"para": "SHOW COLUMNS displays the\n following values for each table column:"
},
{
"itemizedlist": [
[
{
"para": "Field"
},
{
"para": "The name of the column."
}
],
[
{
"para": "Type"
},
{
"para": "The column data type."
}
],
[
{
"para": "Collation"
},
{
"para": "The collation for nonbinary string columns, or\n NULL for other columns. This value is\n displayed only if you use the FULL\n keyword."
}
],
[
{
"para": "Null"
},
{
"para": "The column nullability. The value is YES\n if NULL values can be stored in the\n column, NO if not."
}
],
[
{
"para": "Key"
},
{
"para": "Whether the column is indexed:"
},
{
"itemizedlist": [
[
{
"para": "If Key is empty, the column either is\n not indexed or is indexed only as a secondary column in\n a multiple-column, nonunique index."
}
],
[
{
"para": "If Key is PRI, the\n column is a PRIMARY KEY or is one of\n the columns in a multiple-column PRIMARY\n KEY."
}
],
[
{
"para": "If Key is UNI, the\n column is the first column of a\n UNIQUE index. (A\n UNIQUE index permits multiple\n NULL values, but you can tell whether\n the column permits NULL by checking\n the Null field.)"
}
],
[
{
"para": "If Key is MUL, the\n column is the first column of a nonunique index in which\n multiple occurrences of a given value are permitted\n within the column."
}
]
]
},
{
"para": "If more than one of the Key values\n applies to a given column of a table, Key\n displays the one with the highest priority, in the order\n PRI, UNI,\n MUL."
},
{
"para": "A UNIQUE index may be displayed as\n PRI if it cannot contain\n NULL values and there is no\n PRIMARY KEY in the table. A\n UNIQUE index may display as\n MUL if several columns form a composite\n UNIQUE index; although the combination of\n the columns is unique, each column can still hold multiple\n occurrences of a given value."
}
],
[
{
"para": "Default"
},
{
"para": "The default value for the column. This is\n NULL if the column has an explicit\n default of NULL, or if the column\n definition includes no DEFAULT clause."
}
],
[
{
"para": "Extra"
},
{
"para": "Any additional information that is available about a given\n column. The value is nonempty in these cases:"
},
{
"indexterm": "generated columns\n SHOW COLUMNS statement"
},
{
"itemizedlist": [
[
{
"para": "auto_increment for columns that have\n the AUTO_INCREMENT attribute."
}
],
[
{
"para": "on update CURRENT_TIMESTAMP for\n TIMESTAMP or\n DATETIME columns that\n have the ON UPDATE CURRENT_TIMESTAMP\n attribute."
}
],
[
{
"para": "VIRTUAL GENERATED or VIRTUAL\n STORED for generated columns."
}
],
[
{
"para": "DEFAULT_GENERATED for columns that\n have an expression default value."
}
]
]
}
],
[
{
"para": "Privileges"
},
{
"para": "The privileges you have for the column. This value is\n displayed only if you use the FULL\n keyword."
}
],
[
{
"para": "Comment"
},
{
"para": "Any comment included in the column definition. This value is\n displayed only if you use the FULL\n keyword."
}
]
]
},
{
"para": "Table column information is also available from the\n INFORMATION_SCHEMA\n COLUMNS table. See\n . The extended information about\n hidden columns is available only using SHOW EXTENDED\n COLUMNS; it cannot be obtained from the\n COLUMNS table."
},
{
"para": "You can list a table's columns with the mysqlshow\n db_name\n tbl_name command."
},
{
"para": "The DESCRIBE statement provides\n information similar to SHOW\n COLUMNS. See ."
},
{
"para": "The SHOW CREATE TABLE,\n SHOW TABLE STATUS, and\n SHOW INDEX statements also\n provide information about tables. See ."
}
],
"id": "SHOW COLUMNS",
"syntax": [
{
"programlisting": ">\nSHOW [EXTENDED] [FULL] {COLUMNS | FIELDS}\n {FROM | IN} tbl_name\n [{FROM | IN} db_name]\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"DATABASE",
"SCHEMA"
],
"description": [
{
"para": "Shows the CREATE DATABASE\n statement that creates the named database. If the\n SHOW statement includes an IF NOT\n EXISTS clause, the output too includes such a clause.\n SHOW\n CREATE SCHEMA is a synonym for\n SHOW CREATE DATABASE."
}
],
"id": "SHOW CREATE DATABASE",
"syntax": [
{
"programlisting": ">\nSHOW CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] db_name"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"EVENT"
],
"description": [
{
"para": "This statement displays the CREATE\n EVENT statement needed to re-create a given event. It\n requires the EVENT privilege for\n the database from which the event is to be shown. For example\n (using the same event e_daily defined and\n then altered in ):"
}
],
"id": "SHOW CREATE EVENT",
"syntax": [
{
"programlisting": ">\nSHOW CREATE EVENT event_name"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"FUNCTION"
],
"description": [
{
"para": "This statement is similar to SHOW CREATE\n PROCEDURE but for stored functions. See\n ."
}
],
"id": "SHOW CREATE FUNCTION",
"syntax": [
{
"programlisting": ">\nSHOW CREATE FUNCTION func_name"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"PROCEDURE"
],
"description": [
{
"para": "This statement is a MySQL extension. It returns the exact string\n that can be used to re-create the named stored procedure. A\n similar statement, SHOW CREATE\n FUNCTION, displays information about stored functions\n (see )."
},
{
"para": "To use either statement, you must have the global\n SELECT privilege."
}
],
"id": "SHOW CREATE PROCEDURE",
"syntax": [
{
"programlisting": ">\nSHOW CREATE PROCEDURE proc_name"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"TABLE"
],
"description": [
{
"para": "As of MySQL 8.0.16, MySQL implements CHECK\n constraints and SHOW CREATE TABLE\n displays them. All CHECK constraints are\n displayed as table constraints. That is, a\n CHECK constraint originally specified as part\n of a column definition displays as a separate clause not part of\n the column definition. Example:"
},
{
"programlisting": ">\nmysql> CREATE TABLE t1 (\n i1 INT CHECK (i1 <> 0), -- column constraint\n i2 INT,\n CHECK (i2 > i1), -- table constraint\n CHECK (i2 <> 0) NOT ENFORCED -- table constraint, not enforced\n );\n\nmysql> SHOW CREATE TABLE t1\\G\n*************************** 1. row ***************************\n Table: t1\nCreate Table: CREATE TABLE `t1` (\n `i1` int(11) DEFAULT NULL,\n `i2` int(11) DEFAULT NULL,\n CONSTRAINT `t1_chk_1` CHECK ((`i1` <> 0)),\n CONSTRAINT `t1_chk_2` CHECK ((`i2` > `i1`)),\n CONSTRAINT `t1_chk_3` CHECK ((`i2` <> 0)) /*!80016 NOT ENFORCED */\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci"
},
{
"para": "SHOW CREATE TABLE quotes table\n and column names according to the value of the\n sql_quote_show_create option.\n See ."
},
{
"para": "For information about how CREATE\n TABLE statements are stored by MySQL, see\n ."
}
],
"id": "SHOW CREATE TABLE",
"syntax": [
{
"programlisting": ">\nSHOW CREATE TABLE tbl_name"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This statement shows the CREATE\n TRIGGER statement that creates the named trigger. This\n statement requires the TRIGGER\n privilege for the table associated with the trigger."
}
],
"id": "SHOW CREATE TRIGGER",
"syntax": [
{
"programlisting": ">\nSHOW CREATE TRIGGER trigger_name"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"USER"
],
"description": [
{
"para": "This statement shows the CREATE\n USER statement that creates the named user. An error\n occurs if the user does not exist. The statement requires the\n SELECT privilege for the\n mysql system schema, except to see\n information for the current user. For the current user, the\n SELECT privilege for the\n mysql.user system table is required for\n display of the password hash in the IDENTIFIED\n AS clause; otherwise, the hash displays as\n <secret>."
},
{
"para": "To name the account, use the format described in\n . The host name part of the\n account name, if omitted, defaults to '%'. It\n is also possible to specify\n CURRENT_USER or\n CURRENT_USER() to refer to the\n account associated with the current session."
},
{
"para": "Password hash values displayed in the IDENTIFIED\n WITH clause of output from SHOW\n CREATE USER may contain unprintable characters that\n have adverse effects on terminal displays and in other\n environments. Enabling the\n print_identified_with_as_hex\n system variable (available as of MySQL 8.0.17) causes\n SHOW CREATE USER to display such\n hash values as hexadecimal strings rather than as regular string\n literals. Hash values that do not contain unprintable characters\n still display as regular string literals, even with this\n variable enabled."
}
],
"id": "SHOW CREATE USER",
"syntax": [
{
"programlisting": ">\nSHOW CREATE USER user"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This statement shows the CREATE\n VIEW statement that creates the named view."
}
],
"id": "SHOW CREATE VIEW",
"syntax": [
{
"programlisting": ">\nSHOW CREATE VIEW view_name"
}
]
},
{
"keywords": [
"SHOW",
"DATABASES",
"SCHEMAS"
],
"description": [
{
"para": "SHOW DATABASES lists the\n databases on the MySQL server host.\n SHOW\n SCHEMAS is a synonym for SHOW\n DATABASES. The LIKE\n clause, if present, indicates which database names to match. The\n WHERE clause can be given to select rows\n using more general conditions, as discussed in\n ."
},
{
"para": "You see only those databases for which you have some kind of\n privilege, unless you have the global SHOW\n DATABASES privilege. You can also get this list using\n the mysqlshow command."
},
{
"para": "If the server was started with the\n option, you\n cannot use this statement at all unless you have the\n SHOW DATABASES privilege."
},
{
"para": "MySQL implements databases as directories in the data directory,\n so this statement simply lists directories in that location.\n However, the output may include names of directories that do not\n correspond to actual databases."
},
{
"para": "Database information is also available from the\n INFORMATION_SCHEMA\n SCHEMATA table. See\n ."
}
],
"id": "SHOW DATABASES",
"syntax": [
{
"programlisting": ">\nSHOW {DATABASES | SCHEMAS}\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"ENGINE",
"MUTEX",
"STATUS"
],
"description": [
{
"para": "SHOW ENGINE displays operational\n information about a storage engine. It requires the\n PROCESS privilege. The statement\n has these variants:"
},
{
"programlisting": ">\nSHOW ENGINE INNODB STATUS\nSHOW ENGINE INNODB MUTEX\nSHOW ENGINE PERFORMANCE_SCHEMA STATUS"
},
{
"para": "SHOW ENGINE INNODB\n STATUS displays extensive information from the\n standard InnoDB Monitor about the state of\n the InnoDB storage engine. For information\n about the standard monitor and other InnoDB\n Monitors that provide information about\n InnoDB processing, see\n ."
},
{
"para": "SHOW ENGINE INNODB\n MUTEX displays InnoDB\n mutex and\n rw-lock statistics."
},
{
"para": "Mutex statistics collection is configured dynamically using the\n following options:"
},
{
"itemizedlist": [
[
{
"para": "To enable the collection of mutex statistics, run:"
},
{
"programlisting": ">SET GLOBAL innodb_monitor_enable='latch';"
}
],
[
{
"para": "To reset mutex statistics, run:"
},
{
"programlisting": ">SET GLOBAL innodb_monitor_reset='latch';"
}
],
[
{
"para": "To disable the collection of mutex statistics, run:"
},
{
"programlisting": ">SET GLOBAL innodb_monitor_disable='latch';"
}
]
]
},
{
"para": "Collection of mutex statistics for\n SHOW ENGINE INNODB\n MUTEX can also be enabled by setting\n innodb_monitor_enable='all', or\n disabled by setting\n innodb_monitor_disable='all'."
},
{
"para": "SHOW ENGINE INNODB\n MUTEX output has these columns:"
},
{
"itemizedlist": [
[
{
"para": "Type"
},
{
"para": "Always InnoDB."
}
],
[
{
"para": "Name"
},
{
"para": "For mutexes, the Name field reports only\n the mutex name. For rwlocks, the Name\n field reports the source file where the rwlock is\n implemented, and the line number in the file where the\n rwlock is created. The line number is specific to your\n version of MySQL."
}
],
[
{
"para": "Status"
},
{
"para": "The mutex status. This field reports the number of spins,\n waits, and calls. Statistics for low-level operating system\n mutexes, which are implemented outside of\n InnoDB, are not reported."
},
{
"itemizedlist": [
[
{
"para": "spins indicates the number of spins."
}
],
[
{
"para": "waits indicates the number of mutex\n waits."
}
],
[
{
"para": "calls indicates how many times the\n mutex was requested."
}
]
]
}
]
]
},
{
"para": "SHOW ENGINE INNODB MUTEX skips the\n mutexes and\n rw-locks of\n buffer pool blocks, as\n the amount of output can be overwhelming on systems with a large\n buffer pool. (There is one mutex and one rw-lock in each 16K\n buffer pool block, and there are 65,536 blocks per gigabyte.)\n SHOW ENGINE INNODB MUTEX also does not list\n any mutexes or rw-locks that have never been waited on\n (os_waits=0). Thus, SHOW ENGINE\n INNODB MUTEX only displays information about mutexes\n and rw-locks outside of the buffer pool that have caused at\n least one OS-level wait."
},
{
"para": "Use SHOW ENGINE\n PERFORMANCE_SCHEMA STATUS to inspect the internal\n operation of the Performance Schema code:"
},
{
"programlisting": ">\nmysql> SHOW ENGINE PERFORMANCE_SCHEMA STATUS\\G\n...\n*************************** 3. row ***************************\n Type: performance_schema\n Name: events_waits_history.size\nStatus: 76\n*************************** 4. row ***************************\n Type: performance_schema\n Name: events_waits_history.count\nStatus: 10000\n*************************** 5. row ***************************\n Type: performance_schema\n Name: events_waits_history.memory\nStatus: 760000\n...\n*************************** 57. row ***************************\n Type: performance_schema\n Name: performance_schema.memory\nStatus: 26459600\n..."
},
{
"para": "This statement is intended to help the DBA understand the\n effects that different Performance Schema options have on memory\n requirements."
},
{
"para": "Name values consist of two parts, which name\n an internal buffer and a buffer attribute, respectively.\n Interpret buffer names as follows:"
},
{
"itemizedlist": [
[
{
"para": "An internal buffer that is not exposed as a table is named\n within parentheses. Examples:\n (pfs_cond_class).size,\n (pfs_mutex_class).memory."
}
],
[
{
"para": "An internal buffer that is exposed as a table in the\n performance_schema database is named\n after the table, without parentheses. Examples:\n events_waits_history.size,\n mutex_instances.count."
}
],
[
{
"para": "A value that applies to the Performance Schema as a whole\n begins with performance_schema. Example:\n performance_schema.memory."
}
]
]
},
{
"para": "Buffer attributes have these meanings:"
},
{
"itemizedlist": [
[
{
"para": "size is the size of the internal record\n used by the implementation, such as the size of a row in a\n table. size values cannot be changed."
}
],
[
{
"para": "count is the number of internal records,\n such as the number of rows in a table.\n count values can be changed using\n Performance Schema configuration options."
}
],
[
{
"para": "For a table,\n tbl_name.memory\n is the product of size and\n count. For the Performance Schema as a\n whole, performance_schema.memory is the\n sum of all the memory used (the sum of all other\n memory values)."
}
]
]
},
{
"para": "In some cases, there is a direct relationship between a\n Performance Schema configuration parameter and a SHOW\n ENGINE value. For example,\n events_waits_history_long.count corresponds\n to\n performance_schema_events_waits_history_long_size.\n In other cases, the relationship is more complex. For example,\n events_waits_history.count corresponds to\n performance_schema_events_waits_history_size\n (the number of rows per thread) multiplied by\n performance_schema_max_thread_instances\n ( the number of threads)."
},
{
"programlisting": ">\nmysql> SHOW ENGINE NDB STATUS;\n+------------+-----------------------+--------------------------------------------------+\n| Type | Name | Status |\n+------------+-----------------------+--------------------------------------------------+\n| ndbcluster | connection | cluster_node_id=7,\n connected_host=198.51.100.103, connected_port=1186, number_of_data_nodes=4,\n number_of_ready_data_nodes=3, connect_count=0 |\n| ndbcluster | NdbTransaction | created=6, free=0, sizeof=212 |\n| ndbcluster | NdbOperation | created=8, free=8, sizeof=660 |\n| ndbcluster | NdbIndexScanOperation | created=1, free=1, sizeof=744 |\n| ndbcluster | NdbIndexOperation | created=0, free=0, sizeof=664 |\n| ndbcluster | NdbRecAttr | created=1285, free=1285, sizeof=60 |\n| ndbcluster | NdbApiSignal | created=16, free=16, sizeof=136 |\n| ndbcluster | NdbLabel | created=0, free=0, sizeof=196 |\n| ndbcluster | NdbBranch | created=0, free=0, sizeof=24 |\n| ndbcluster | NdbSubroutine | created=0, free=0, sizeof=68 |\n| ndbcluster | NdbCall | created=0, free=0, sizeof=16 |\n| ndbcluster | NdbBlob | created=1, free=1, sizeof=264 |\n| ndbcluster | NdbReceiver | created=4, free=0, sizeof=68 |\n| ndbcluster | binlog | latest_epoch=155467, latest_trans_epoch=148126,\n latest_received_binlog_epoch=0, latest_handled_binlog_epoch=0,\n latest_applied_binlog_epoch=0 |\n+------------+-----------------------+--------------------------------------------------+"
},
{
"para": "The Status column in each of these rows\n provides information about the MySQL server's connection to\n the cluster and about the cluster binary log's status,\n respectively. The Status information is in\n the form of comma-delimited set of name/value pairs."
}
],
"id": "SHOW ENGINE",
"syntax": [
{
"programlisting": ">\nSHOW ENGINE engine_name {STATUS | MUTEX}"
}
]
},
{
"keywords": [
"SHOW",
"ENGINES",
"STORAGE"
],
"description": [
{
"para": "SHOW ENGINES displays status\n information about the server's storage engines. This is\n particularly useful for checking whether a storage engine is\n supported, or to see what the default engine is."
},
{
"para": "For information about MySQL storage engines, see\n , and\n ."
}
],
"id": "SHOW ENGINES",
"syntax": [
{
"programlisting": ">\nSHOW [STORAGE] ENGINES"
}
]
},
{
"keywords": [
"SHOW",
"ERRORS",
"COUNT"
],
"description": [
{
"para": "SHOW ERRORS is a diagnostic\n statement that is similar to SHOW\n WARNINGS, except that it displays information only for\n errors, rather than for errors, warnings, and notes."
},
{
"para": "The LIMIT clause has the same syntax as for\n the SELECT statement. See\n ."
},
{
"para": "The SHOW COUNT(*)\n ERRORS statement displays the number of errors. You\n can also retrieve this number from the\n error_count variable:"
},
{
"programlisting": ">\nSHOW COUNT(*) ERRORS;\nSELECT @@error_count;"
},
{
"para": "SHOW ERRORS and\n error_count apply only to\n errors, not warnings or notes. In other respects, they are\n similar to SHOW WARNINGS and\n warning_count. In particular,\n SHOW ERRORS cannot display\n information for more than\n max_error_count messages, and\n error_count can exceed the\n value of max_error_count if the\n number of errors exceeds\n max_error_count."
}
],
"id": "SHOW ERRORS",
"syntax": [
{
"programlisting": ">\nSHOW ERRORS [LIMIT [offset,] row_count]\nSHOW COUNT(*) ERRORS"
}
]
},
{
"keywords": [
"SHOW",
"EVENTS"
],
"description": [
{
"para": "This statement displays information about Event Manager events,\n which are discussed in . It\n requires the EVENT privilege for\n the database from which the events are to be shown."
},
{
"para": "In its simplest form, SHOW EVENTS\n lists all of the events in the current schema:"
},
{
"programlisting": ">\nmysql> SELECT CURRENT_USER(), SCHEMA();\n+----------------+----------+\n| CURRENT_USER() | SCHEMA() |\n+----------------+----------+\n| jon@ghidora | myschema |\n+----------------+----------+\n1 row in set (0.00 sec)\n\nmysql> SHOW EVENTS\\G\n*************************** 1. row ***************************\n Db: myschema\n Name: e_daily\n Definer: jon@ghidora\n Time zone: SYSTEM\n Type: RECURRING\n Execute at: NULL\n Interval value: 1\n Interval field: DAY\n Starts: 2018-08-08 11:06:34\n Ends: NULL\n Status: ENABLED\n Originator: 1\ncharacter_set_client: utf8mb4\ncollation_connection: utf8mb4_0900_ai_ci\n Database Collation: utf8mb4_0900_ai_ci"
},
{
"para": "To see events for a specific schema, use the\n FROM clause. For example, to see events for\n the test schema, use the following statement:"
},
{
"programlisting": ">\nSHOW EVENTS FROM test;"
},
{
"para": "The LIKE clause, if present,\n indicates which event names to match. The\n WHERE clause can be given to select rows\n using more general conditions, as discussed in\n ."
}
],
"id": "SHOW EVENTS",
"syntax": [
{
"programlisting": ">\nSHOW EVENTS\n [{FROM | IN} schema_name]\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"FUNCTION",
"CODE"
],
"description": [
{
"para": "This statement is similar to SHOW PROCEDURE\n CODE but for stored functions. See\n ."
}
],
"id": "SHOW FUNCTION CODE",
"syntax": [
{
"programlisting": ">\nSHOW FUNCTION CODE func_name"
}
]
},
{
"keywords": [
"SHOW",
"FUNCTION",
"STATUS"
],
"description": [
{
"para": "This statement is similar to SHOW PROCEDURE\n STATUS but for stored functions. See\n ."
}
],
"id": "SHOW FUNCTION STATUS",
"syntax": [
{
"programlisting": ">\nSHOW FUNCTION STATUS\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"GRANTS",
"USING"
],
"description": [
{
"para": "This statement displays the privileges and roles that are\n assigned to a MySQL user account or role, in the form of\n GRANT statements that must be\n executed to duplicate the privilege and role assignments."
},
{
"para": "SHOW GRANTS requires the\n SELECT privilege for the\n mysql system schema, except to display\n privileges and roles for the current user."
},
{
"para": "To name the account or role for SHOW\n GRANTS, use the same format as for the\n GRANT statement (for example,\n 'jeffrey'@'localhost'):"
},
{
"programlisting": ">\nmysql> SHOW GRANTS FOR 'jeffrey'@'localhost';\n+------------------------------------------------------------------+\n| Grants for jeffrey@localhost |\n+------------------------------------------------------------------+\n| GRANT USAGE ON *.* TO `jeffrey`@`localhost` |\n| GRANT SELECT, INSERT, UPDATE ON `db1`.* TO `jeffrey`@`localhost` |\n+------------------------------------------------------------------+"
},
{
"para": "The host part, if omitted, defaults to '%'.\n For additional information about specifying account and role\n names, see , and\n ."
},
{
"para": "To display the privileges granted to the current user (the\n account you are using to connect to the server), you can use any\n of the following statements:"
},
{
"programlisting": ">\nSHOW GRANTS;\nSHOW GRANTS FOR CURRENT_USER;\nSHOW GRANTS FOR CURRENT_USER();"
},
{
"para": "If SHOW GRANTS FOR CURRENT_USER (or any\n equivalent syntax) is used in definer context, such as within a\n stored procedure that executes with definer rather than invoker\n privileges, the grants displayed are those of the definer and\n not the invoker."
},
{
"para": "In MySQL current-series compared to previous series,\n SHOW GRANTS no longer displays\n ALL PRIVILEGES in\n its global-privileges output because the meaning of\n ALL PRIVILEGES at\n the global level varies depending on which dynamic privileges\n are defined. Instead, SHOW GRANTS\n explictly lists each granted global privilege:"
},
{
"programlisting": ">\nmysql> SHOW GRANTS FOR 'root'@'localhost';\n+---------------------------------------------------------------------+\n| Grants for root@localhost |\n+---------------------------------------------------------------------+\n| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, RELOAD, |\n| SHUTDOWN, PROCESS, FILE, REFERENCES, INDEX, ALTER, SHOW DATABASES, |\n| SUPER, CREATE TEMPORARY TABLES, LOCK TABLES, EXECUTE, REPLICATION |\n| SLAVE, REPLICATION CLIENT, CREATE VIEW, SHOW VIEW, CREATE ROUTINE, |\n| ALTER ROUTINE, CREATE USER, EVENT, TRIGGER, CREATE TABLESPACE, |\n| CREATE ROLE, DROP ROLE ON *.* TO `root`@`localhost` WITH GRANT |\n| OPTION |\n| GRANT PROXY ON ''@'' TO 'root'@'localhost' WITH GRANT OPTION |\n+---------------------------------------------------------------------+"
},
{
"para": "Applications that process SHOW\n GRANTS output should be adjusted accordingly."
},
{
"para": "At the global level, GRANT OPTION\n applies to all granted static global privileges if granted for\n any of them, but applies individually to granted dynamic\n privileges. SHOW GRANTS displays\n global privileges this way:"
},
{
"itemizedlist": [
[
{
"para": "One line listing all granted static privileges, if there are\n any, including WITH GRANT OPTION if\n appropriate."
}
],
[
{
"para": "One line listing all granted dynamic privileges for which\n GRANT OPTION is granted, if\n there are any, including WITH GRANT\n OPTION."
}
],
[
{
"para": "One line listing all granted dynamic privileges for which\n GRANT OPTION is not granted,\n if there are any, without WITH GRANT\n OPTION."
}
]
]
},
{
"para": "With the optional USING clause,\n SHOW GRANTS enables you to\n examine the privileges associated with roles for the user. Each\n role named in the USING clause must be\n granted to the user."
},
{
"para": "Suppose that user u1 is assigned roles\n r1 and r2, as follows:"
},
{
"programlisting": ">\nCREATE ROLE 'r1', 'r2';\nGRANT SELECT ON db1.* TO 'r1';\nGRANT INSERT, UPDATE, DELETE ON db1.* TO 'r2';\nCREATE USER 'u1'@'localhost' IDENTIFIED BY 'u1pass';\nGRANT 'r1', 'r2' TO 'u1'@'localhost';"
},
{
"para": "SHOW GRANTS without\n USING shows the granted roles:"
},
{
"programlisting": ">\nmysql> SHOW GRANTS FOR 'u1'@'localhost';\n+---------------------------------------------+\n| Grants for u1@localhost |\n+---------------------------------------------+\n| GRANT USAGE ON *.* TO `u1`@`localhost` |\n| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` |\n+---------------------------------------------+"
},
{
"para": "Adding a USING clause causes the statement to\n also display the privileges associated with each role named in\n the clause:"
},
{
"programlisting": ">\nmysql> SHOW GRANTS FOR 'u1'@'localhost' USING 'r1';\n+---------------------------------------------+\n| Grants for u1@localhost |\n+---------------------------------------------+\n| GRANT USAGE ON *.* TO `u1`@`localhost` |\n| GRANT SELECT ON `db1`.* TO `u1`@`localhost` |\n| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` |\n+---------------------------------------------+\nmysql> SHOW GRANTS FOR 'u1'@'localhost' USING 'r2';\n+-------------------------------------------------------------+\n| Grants for u1@localhost |\n+-------------------------------------------------------------+\n| GRANT USAGE ON *.* TO `u1`@`localhost` |\n| GRANT INSERT, UPDATE, DELETE ON `db1`.* TO `u1`@`localhost` |\n| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` |\n+-------------------------------------------------------------+\nmysql> SHOW GRANTS FOR 'u1'@'localhost' USING 'r1', 'r2';\n+---------------------------------------------------------------------+\n| Grants for u1@localhost |\n+---------------------------------------------------------------------+\n| GRANT USAGE ON *.* TO `u1`@`localhost` |\n| GRANT SELECT, INSERT, UPDATE, DELETE ON `db1`.* TO `u1`@`localhost` |\n| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` |\n+---------------------------------------------------------------------+"
},
{
"para": "MySQL 8.0.16 and higher supports partial revokes of global\n privileges, such that a global privilege can be restricted from\n applying to particular schemas (see\n ). To indicate which global\n schema privileges have been revoked for particular schemas,\n SHOW GRANTS output includes\n REVOKE statements:"
},
{
"programlisting": ">\nmysql> SET PERSIST partial_revokes = ON;\nmysql> CREATE USER u1;\nmysql> GRANT SELECT, INSERT, DELETE ON *.* TO u1;\nmysql> REVOKE SELECT, INSERT ON mysql.* FROM u1;\nmysql> REVOKE DELETE ON world.* FROM u1;\nmysql> SHOW GRANTS FOR u1;\n+--------------------------------------------------+\n| Grants for u1@% |\n+--------------------------------------------------+\n| GRANT SELECT, INSERT, DELETE ON *.* TO `u1`@`%` |\n| REVOKE SELECT, INSERT ON `mysql`.* FROM `u1`@`%` |\n| REVOKE DELETE ON `world`.* FROM `u1`@`%` |\n+--------------------------------------------------+"
},
{
"para": "SHOW GRANTS does not display\n privileges that are available to the named account but are\n granted to a different account. For example, if an anonymous\n account exists, the named account might be able to use its\n privileges, but SHOW GRANTS does\n not display them."
}
],
"id": "SHOW GRANTS",
"syntax": [
{
"programlisting": ">\nSHOW GRANTS\n [FOR user_or_role\n [USING role [, role] ...]]\n\nuser_or_role: {\n user (see )\n | role (see .\n}"
}
]
},
{
"keywords": [
"SHOW",
"INDEX",
"KEYS",
"EXTENDED",
"FROM",
"IN",
"WHERE"
],
"description": [
{
"para": "SHOW INDEX returns table index\n information. The format resembles that of the\n SQLStatistics call in ODBC. This statement\n requires some privilege for any column in the table."
},
{
"programlisting": ">\nmysql> SHOW INDEX FROM City\\G\n*************************** 1. row ***************************\n Table: city\n Non_unique: 0\n Key_name: PRIMARY\n Seq_in_index: 1\n Column_name: ID\n Collation: A\n Cardinality: 4188\n Sub_part: NULL\n Packed: NULL\n Null:\n Index_type: BTREE\n Comment:\nIndex_comment:\n Visible: YES\n Expression: NULL\n*************************** 2. row ***************************\n Table: city\n Non_unique: 1\n Key_name: CountryCode\n Seq_in_index: 1\n Column_name: CountryCode\n Collation: A\n Cardinality: 232\n Sub_part: NULL\n Packed: NULL\n Null:\n Index_type: BTREE\n Comment:\nIndex_comment:\n Visible: YES\n Expression: NULL"
},
{
"para": "An alternative to tbl_name\n FROM db_name syntax is\n db_name.tbl_name.\n These two statements are equivalent:"
},
{
"programlisting": ">\nSHOW INDEX FROM mytable FROM mydb;\nSHOW INDEX FROM mydb.mytable;"
},
{
"para": "The optional EXTENDED keyword causes the\n output to include information about hidden indexes that MySQL\n uses internally and are not accessible by users."
},
{
"para": "The WHERE clause can be given to select rows\n using more general conditions, as discussed in\n ."
},
{
"para": "SHOW INDEX returns the following\n fields:"
},
{
"itemizedlist": [
[
{
"para": "Table"
},
{
"para": "The name of the table."
}
],
[
{
"para": "Non_unique"
},
{
"para": "0 if the index cannot contain duplicates, 1 if it can."
}
],
[
{
"para": "Key_name"
},
{
"para": "The name of the index. If the index is the primary key, the\n name is always PRIMARY."
}
],
[
{
"para": "Seq_in_index"
},
{
"para": "The column sequence number in the index, starting with 1."
}
],
[
{
"para": "Column_name"
},
{
"para": "The column name. See also the description for the\n Expression column."
}
],
[
{
"para": "Collation"
},
{
"indexterm": "displaying\n information\n Collation"
},
{
"para": "How the column is sorted in the index. This can have values\n A (ascending), D\n (descending), or NULL (not sorted)."
}
],
[
{
"para": "Cardinality"
},
{
"indexterm": "displaying\n information\n Cardinality"
},
{
"indexterm": "calculating\n cardinality"
},
{
"para": "An estimate of the number of unique values in the index. To\n update this number, run ANALYZE\n TABLE or (for MyISAM tables)\n myisamchk -a."
},
{
"para": "Cardinality is counted based on\n statistics stored as integers, so the value is not\n necessarily exact even for small tables. The higher the\n cardinality, the greater the chance that MySQL uses the\n index when doing joins."
}
],
[
{
"para": "Sub_part"
},
{
"para": "The index prefix. That is, the number of indexed characters\n if the column is only partly indexed,\n NULL if the entire column is indexed."
},
{
"note": "\n Prefix limits are measured in bytes.\n However, prefix lengths for index\n specifications in CREATE\n TABLE, ALTER\n TABLE, and CREATE\n INDEX statements are interpreted as number of\n characters for nonbinary string types\n (CHAR,\n VARCHAR,\n TEXT) and number of bytes\n for binary string types\n (BINARY,\n VARBINARY,\n BLOB). Take this into\n account when specifying a prefix length for a nonbinary\n string column that uses a multibyte character set.\n "
},
{
"para": "For additional information about index prefixes, see\n , and\n ."
}
],
[
{
"para": "Packed"
},
{
"para": "Indicates how the key is packed. NULL if\n it is not."
}
],
[
{
"para": "Null"
},
{
"para": "Contains YES if the column may contain\n NULL values and '' if\n not."
}
],
[
{
"para": "Index_type"
},
{
"para": "The index method used (BTREE,\n FULLTEXT, HASH,\n RTREE)."
}
],
[
{
"para": "Comment"
},
{
"para": "Information about the index not described in its own column,\n such as disabled if the index is\n disabled."
}
],
[
{
"para": "Index_comment"
},
{
"para": "Any comment provided for the index with a\n COMMENT attribute when the index was\n created."
}
],
[
{
"para": "Visible"
},
{
"para": "Whether the index is visible to the optimizer. See\n ."
}
],
[
{
"para": "Expression"
},
{
"para": "MySQL 8.0.13 and higher supports functional key parts (see\n ), which\n affects both the Column_name and\n Expression columns:"
},
{
"itemizedlist": [
[
{
"para": "For a nonfunctional key part,\n Column_name indicates the column\n indexed by the key part and\n Expression is\n NULL."
}
],
[
{
"para": "For a functional key part,\n Column_name column is\n NULL and\n Expression indicates the expression\n for the key part."
}
]
]
}
]
]
},
{
"para": "Information about table indexes is also available from the\n INFORMATION_SCHEMA\n STATISTICS table. See\n . The extended information\n about hidden indexes is available only using SHOW\n EXTENDED INDEX; it cannot be obtained from the\n STATISTICS table."
},
{
"para": "You can list a table's indexes with the mysqlshow -k\n db_name\n tbl_name command."
}
],
"id": "SHOW INDEX",
"syntax": [
{
"programlisting": ">\nSHOW [EXTENDED] {INDEX | INDEXES | KEYS}\n {FROM | IN} tbl_name\n [{FROM | IN} db_name]\n [WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"MASTER",
"STATUS"
],
"description": [
{
"para": "This statement provides status information about the binary log\n files of the master. It requires either the\n SUPER or\n REPLICATION CLIENT privilege."
},
{
"para": "Example:"
},
{
"programlisting": ">\nmysql> SHOW MASTER STATUS\\G\n*************************** 1. row ***************************\n File: master-bin.000002\n Position: 1307\n Binlog_Do_DB: test\n Binlog_Ignore_DB: manual, mysql\nExecuted_Gtid_Set: 3E11FA47-71CA-11E1-9E33-C80AA9429562:1-5\n1 row in set (0.00 sec)"
}
],
"id": "SHOW MASTER STATUS",
"syntax": [
{
"programlisting": ">\nSHOW MASTER STATUS"
}
]
},
{
"keywords": [
"SHOW",
"OPEN",
"TABLES"
],
"description": [
{
"para": "SHOW OPEN TABLES lists the\n non-TEMPORARY tables that are currently open\n in the table cache. See . The\n FROM clause, if present, restricts the tables\n shown to those present in the db_name\n database. The LIKE clause, if\n present, indicates which table names to match. The\n WHERE clause can be given to select rows\n using more general conditions, as discussed in\n ."
}
],
"id": "SHOW OPEN TABLES",
"syntax": [
{
"programlisting": ">\nSHOW OPEN TABLES\n [{FROM | IN} db_name]\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"PLUGINS"
],
"description": [
{
"para": "SHOW PLUGINS displays information\n about server plugins."
},
{
"para": "Example of SHOW PLUGINS output:"
},
{
"programlisting": ">\nmysql> SHOW PLUGINS\\G\n*************************** 1. row ***************************\n Name: binlog\n Status: ACTIVE\n Type: STORAGE ENGINE\nLibrary: NULL\nLicense: GPL\n*************************** 2. row ***************************\n Name: CSV\n Status: ACTIVE\n Type: STORAGE ENGINE\nLibrary: NULL\nLicense: GPL\n*************************** 3. row ***************************\n Name: MEMORY\n Status: ACTIVE\n Type: STORAGE ENGINE\nLibrary: NULL\nLicense: GPL\n*************************** 4. row ***************************\n Name: MyISAM\n Status: ACTIVE\n Type: STORAGE ENGINE\nLibrary: NULL\nLicense: GPL\n..."
}
],
"id": "SHOW PLUGINS",
"syntax": [
{
"programlisting": ">\nSHOW PLUGINS"
}
]
},
{
"keywords": [
"SHOW",
"PRIVILEGES"
],
"description": [
{
"para": "SHOW PRIVILEGES shows the list of\n system privileges that the MySQL server supports. The privileges\n displayed include all static privileges, and all currently\n registered dynamic privileges."
}
],
"id": "SHOW PRIVILEGES",
"syntax": [
{
"programlisting": ">\nSHOW PRIVILEGES"
}
]
},
{
"keywords": [
"SHOW",
"PROCEDURE",
"CODE"
],
"description": [
{
"para": "This statement is a MySQL extension that is available only for\n servers that have been built with debugging support. It displays\n a representation of the internal implementation of the named\n stored procedure. A similar statement, SHOW\n FUNCTION CODE, displays information about stored\n functions (see )."
},
{
"para": "To use either statement, you must have the global\n SELECT privilege."
},
{
"para": "If the named routine is available, each statement produces a\n result set. Each row in the result set corresponds to one\n instruction in the routine. The first column is\n Pos, which is an ordinal number beginning\n with 0. The second column is Instruction,\n which contains an SQL statement (usually changed from the\n original source), or a directive which has meaning only to the\n stored-routine handler."
}
],
"id": "SHOW PROCEDURE CODE",
"syntax": [
{
"programlisting": ">\nSHOW PROCEDURE CODE proc_name"
}
]
},
{
"keywords": [
"SHOW",
"PROCEDURE",
"STATUS"
],
"description": [
{
"para": "This statement is a MySQL extension. It returns characteristics\n of a stored procedure, such as the database, name, type,\n creator, creation and modification dates, and character set\n information. A similar statement, SHOW\n FUNCTION STATUS, displays information about stored\n functions (see )."
},
{
"para": "The LIKE clause, if present,\n indicates which procedure or function names to match. The\n WHERE clause can be given to select rows\n using more general conditions, as discussed in\n ."
}
],
"id": "SHOW PROCEDURE STATUS",
"syntax": [
{
"programlisting": ">\nSHOW PROCEDURE STATUS\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"PROCESSLIST",
"FULL"
],
"description": [
{
"para": "SHOW PROCESSLIST shows which\n threads are running. If you have the\n PROCESS privilege, you can see\n all threads. Otherwise, you can see only your own threads (that\n is, threads associated with the MySQL account that you are\n using). If you do not use the FULL keyword,\n only the first 100 characters of each statement are shown in the\n Info field."
}
],
"id": "SHOW PROCESSLIST",
"syntax": [
{
"programlisting": ">\nSHOW [FULL] PROCESSLIST"
}
]
},
{
"keywords": [
"SHOW",
"PROFILE"
],
"description": [
{
"para": "The SHOW PROFILE and\n SHOW PROFILES statements display\n profiling information that indicates resource usage for\n statements executed during the course of the current session."
},
{
"para": "To control profiling, use the\n profiling session variable,\n which has a default value of 0 (OFF). Enable\n profiling by setting profiling\n to 1 or ON:"
},
{
"programlisting": ">\nmysql> SET profiling = 1;"
},
{
"para": "SHOW PROFILES displays a list of\n the most recent statements sent to the server. The size of the\n list is controlled by the\n profiling_history_size session\n variable, which has a default value of 15. The maximum value is\n 100. Setting the value to 0 has the practical effect of\n disabling profiling."
},
{
"para": "All statements are profiled except SHOW\n PROFILE and SHOW\n PROFILES, so you will find neither of those statements\n in the profile list. Malformed statements are profiled. For\n example, SHOW PROFILING is an illegal\n statement, and a syntax error occurs if you try to execute it,\n but it will show up in the profiling list."
},
{
"para": "SHOW PROFILE displays detailed\n information about a single statement. Without the FOR\n QUERY n clause, the output\n pertains to the most recently executed statement. If\n FOR QUERY n is\n included, SHOW PROFILE displays\n information for statement n. The\n values of n correspond to the\n Query_ID values displayed by\n SHOW PROFILES."
},
{
"para": "The LIMIT\n row_count clause may be\n given to limit the output to\n row_count rows. If\n LIMIT is given, OFFSET\n offset may be added to\n begin the output offset rows into the\n full set of rows."
},
{
"para": "By default, SHOW PROFILE displays\n Status and Duration\n columns. The Status values are like the\n State values displayed by\n SHOW PROCESSLIST, although there\n might be some minor differences in interpretion for the two\n statements for some status values (see\n )."
},
{
"para": "Optional type values may be specified\n to display specific additional types of information:"
},
{
"itemizedlist": [
[
{
"para": "ALL displays all information"
}
],
[
{
"para": "BLOCK IO displays counts for block input\n and output operations"
}
],
[
{
"para": "CONTEXT SWITCHES displays counts for\n voluntary and involuntary context switches"
}
],
[
{
"para": "CPU displays user and system CPU usage\n times"
}
],
[
{
"para": "IPC displays counts for messages sent and\n received"
}
],
[
{
"para": "MEMORY is not currently implemented"
}
],
[
{
"para": "PAGE FAULTS displays counts for major and\n minor page faults"
}
],
[
{
"para": "SOURCE displays the names of functions\n from the source code, together with the name and line number\n of the file in which the function occurs"
}
],
[
{
"para": "SWAPS displays swap counts"
}
]
]
},
{
"para": "Profiling is enabled per session. When a session ends, its\n profiling information is lost."
}
],
"id": "SHOW PROFILE",
"syntax": [
{
"programlisting": ">\nSHOW PROFILE [type [, type] ... ]\n [FOR QUERY n]\n [LIMIT row_count [OFFSET offset]]\n\ntype: {\n ALL\n | BLOCK IO\n | CONTEXT SWITCHES\n | CPU\n | IPC\n | MEMORY\n | PAGE FAULTS\n | SOURCE\n | SWAPS\n}"
}
]
},
{
"keywords": [
"SHOW",
"PROFILES"
],
"description": [
{
"para": "The SHOW PROFILES statement,\n together with SHOW PROFILE,\n displays profiling information that indicates resource usage for\n statements executed during the course of the current session.\n For more information, see ."
}
],
"id": "SHOW PROFILES",
"syntax": [
{
"programlisting": ">\nSHOW PROFILES"
}
]
},
{
"keywords": [
"SHOW",
"RELAYLOG",
"EVENTS",
"LIMIT",
"FROM",
"IN",
"FOR",
"CHANNEL"
],
"description": [
{
"para": "Shows the events in the relay log of a replication slave. If you\n do not specify\n 'log_name', the\n first relay log is displayed. This statement has no effect on\n the master. SHOW RELAYLOG EVENTS requires the\n REPLICATION SLAVE privilege."
}
],
"id": "SHOW RELAYLOG EVENTS",
"syntax": [
{
"programlisting": ">\nSHOW RELAYLOG EVENTS\n [IN 'log_name']\n [FROM pos]\n [LIMIT [offset,] row_count]\n [channel_option]\n\nchannel_option:\n FOR CHANNEL channel"
}
]
},
{
"keywords": [
"SHOW",
"SLAVE",
"HOSTS"
],
"description": [
{
"para": "Displays a list of replication slaves currently registered with\n the master. SHOW SLAVE HOSTS requires the\n REPLICATION SLAVE privilege."
},
{
"para": "SHOW SLAVE HOSTS should be executed on a\n server that acts as a replication master. The statement displays\n information about servers that are or have been connected as\n replication slaves, with each row of the result corresponding to\n one slave server, as shown here:"
},
{
"programlisting": ">\nmysql> SHOW SLAVE HOSTS;\n+------------+-----------+------+-----------+--------------------------------------+\n| Server_id | Host | Port | Master_id | Slave_UUID |\n+------------+-----------+------+-----------+--------------------------------------+\n| 192168010 | iconnect2 | 3306 | 192168011 | 14cb6624-7f93-11e0-b2c0-c80aa9429562 |\n| 1921680101 | athena | 3306 | 192168011 | 07af4990-f41f-11df-a566-7ac56fdaf645 |\n+------------+-----------+------+-----------+--------------------------------------+"
},
{
"itemizedlist": [
[
{
"para": "Server_id: The unique server ID of the\n slave server, as configured in the slave server's\n option file, or on the command line with\n ."
}
],
[
{
"para": "Host: The host name of the slave server\n as specified on the slave with the\n option. This\n can differ from the machine name as configured in the\n operating system."
}
],
[
{
"para": "User: The slave server user name as,\n specified on the slave with the\n option.\n Statement output includes this column only if the master\n server is started with the\n \n option."
}
],
[
{
"para": "Password: The slave server password as,\n specified on the slave with the\n option.\n Statement output includes this column only if the master\n server is started with the\n \n option."
}
],
[
{
"para": "Port: The port on the master to which the\n slave server is listening, as specified on the slave with\n the option."
},
{
"para": "A zero in this column means that the slave port\n () was not set."
}
],
[
{
"para": "Master_id: The unique server ID of the\n master server that the slave server is replicating from.\n This is the server ID of the server on which SHOW\n SLAVE HOSTS is executed, so this same value is\n listed for each row in the result."
}
],
[
{
"para": "\n auto.cnf file\n and SHOW SLAVE HOSTS statement\n \n\n Slave_UUID: The globally unique ID of\n this slave, as generated on the slave and found in the\n slave's auto.cnf file."
}
]
]
}
],
"id": "SHOW SLAVE HOSTS",
"syntax": [
{
"programlisting": ">\nSHOW SLAVE HOSTS"
}
]
},
{
"keywords": [
"SHOW",
"SLAVE",
"STATUS",
"FOR",
"CHANNEL"
],
"description": [
{
"para": "This statement provides status information on essential\n parameters of the slave threads. It requires either the\n SUPER or\n REPLICATION CLIENT privilege."
},
{
"para": "SHOW SLAVE STATUS is nonblocking. When run\n concurrently with STOP SLAVE,\n SHOW SLAVE STATUS returns without waiting for\n STOP SLAVE to finish shutting down the slave\n SQL thread or slave I/O thread (or both). This permits use in\n monitoring and other applications where getting an immediate\n response from SHOW SLAVE STATUS more\n important than ensuring that it returned the latest data."
},
{
"para": "If you issue this statement using the mysql\n client, you can use a \\G statement terminator\n rather than a semicolon to obtain a more readable vertical\n layout:"
},
{
"programlisting": ">\nmysql> SHOW SLAVE STATUS\\G\n*************************** 1. row ***************************\n Slave_IO_State: Waiting for master to send event\n Master_Host: localhost\n Master_User: repl\n Master_Port: 13000\n Connect_Retry: 60\n Master_Log_File: master-bin.000002\n Read_Master_Log_Pos: 1307\n Relay_Log_File: slave-relay-bin.000003\n Relay_Log_Pos: 1508\n Relay_Master_Log_File: master-bin.000002\n Slave_IO_Running: Yes\n Slave_SQL_Running: Yes\n Replicate_Do_DB:\n Replicate_Ignore_DB:\n Replicate_Do_Table:\n Replicate_Ignore_Table:\n Replicate_Wild_Do_Table:\n Replicate_Wild_Ignore_Table:\n Last_Errno: 0\n Last_Error:\n Skip_Counter: 0\n Exec_Master_Log_Pos: 1307\n Relay_Log_Space: 1858\n Until_Condition: None\n Until_Log_File:\n Until_Log_Pos: 0\n Master_SSL_Allowed: No\n Master_SSL_CA_File:\n Master_SSL_CA_Path:\n Master_SSL_Cert:\n Master_SSL_Cipher:\n Master_SSL_Key:\n Seconds_Behind_Master: 0\nMaster_SSL_Verify_Server_Cert: No\n Last_IO_Errno: 0\n Last_IO_Error:\n Last_SQL_Errno: 0\n Last_SQL_Error:\n Replicate_Ignore_Server_Ids:\n Master_Server_Id: 1\n Master_UUID: 3e11fa47-71ca-11e1-9e33-c80aa9429562\n Master_Info_File: \n SQL_Delay: 0\n SQL_Remaining_Delay: NULL\n Slave_SQL_Running_State: Reading event from the relay log\n Master_Retry_Count: 10\n Master_Bind:\n Last_IO_Error_Timestamp:\n Last_SQL_Error_Timestamp:\n Master_SSL_Crl:\n Master_SSL_Crlpath:\n Retrieved_Gtid_Set: 3e11fa47-71ca-11e1-9e33-c80aa9429562:1-5\n Executed_Gtid_Set: 3e11fa47-71ca-11e1-9e33-c80aa9429562:1-5\n Auto_Position: 1\n Replicate_Rewrite_DB:\n Channel_name:\n Master_TLS_Version: TLSv1.2\n Master_public_key_path: public_key.pem\n Get_master_public_key: 0"
},
{
"para": "The Performance Schema provides tables that expose replication\n information. This is similar to the information available from\n the SHOW SLAVE STATUS statement,\n but represented in table form. For details, see\n ."
}
],
"id": "SHOW SLAVE STATUS",
"syntax": [
{
"programlisting": ">\nSHOW SLAVE STATUS [FOR CHANNEL channel]"
}
]
},
{
"keywords": [
"SHOW",
"STATUS",
"GLOBAL",
"SESSION"
],
"description": [
{
"para": "With a LIKE clause, the statement\n displays only rows for those variables with names that match the\n pattern:"
},
{
"programlisting": ">\nmysql> SHOW STATUS LIKE 'Key%';\n+--------------------+----------+\n| Variable_name | Value |\n+--------------------+----------+\n| Key_blocks_used | 14955 |\n| Key_read_requests | 96854827 |\n| Key_reads | 162040 |\n| Key_write_requests | 7589728 |\n| Key_writes | 3813196 |\n+--------------------+----------+"
}
],
"id": "SHOW STATUS",
"syntax": [
{
"programlisting": ">\nSHOW [GLOBAL | SESSION] STATUS\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"TABLE",
"STATUS"
],
"description": [
{
"para": "SHOW TABLE STATUS works likes\n SHOW TABLES, but provides a lot\n of information about each non-TEMPORARY\n table. You can also get this list using the mysqlshow\n --status db_name command.\n The LIKE clause, if present,\n indicates which table names to match. The\n WHERE clause can be given to select rows\n using more general conditions, as discussed in\n ."
}
],
"id": "SHOW TABLE STATUS",
"syntax": [
{
"programlisting": ">\nSHOW TABLE STATUS\n [{FROM | IN} db_name]\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"TABLES",
"EXTENDED",
"FULL"
],
"description": [
{
"para": "SHOW TABLES lists the\n non-TEMPORARY tables in a given database. You\n can also get this list using the mysqlshow\n db_name command. The\n LIKE clause, if present, indicates\n which table names to match. The WHERE clause\n can be given to select rows using more general conditions, as\n discussed in ."
},
{
"para": "Matching performed by the LIKE clause is\n dependent on the setting of the\n lower_case_table_names system\n variable."
},
{
"para": "The optional EXTENDED modifier causes\n SHOW TABLES to list hidden tables\n created by failed ALTER TABLE\n statements. These temporary tables have names beginning with\n #sql and can be dropped using\n DROP TABLE."
},
{
"para": "This statement also lists any views in the database. The\n optional FULL modifier causes\n SHOW TABLES to display a second\n output column with values of BASE TABLE for a\n table, VIEW for a view, or SYSTEM\n VIEW for an INFORMATION_SCHEMA\n table."
},
{
"para": "If you have no privileges for a base table or view, it does not\n show up in the output from SHOW\n TABLES or mysqlshow db_name."
}
],
"id": "SHOW TABLES",
"syntax": [
{
"programlisting": ">\nSHOW [EXTENDED] [FULL] TABLES\n [{FROM | IN} db_name]\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"TRIGGERS"
],
"description": [
{
"para": "SHOW TRIGGERS lists the triggers\n currently defined for tables in a database (the default database\n unless a FROM clause is given). This\n statement returns results only for databases and tables for\n which you have the TRIGGER\n privilege. The LIKE clause, if\n present, indicates which table names (not trigger names) to\n match and causes the statement to display triggers for those\n tables. The WHERE clause can be given to\n select rows using more general conditions, as discussed in\n ."
},
{
"para": "For the ins_sum trigger defined in\n , the output of\n SHOW TRIGGERS is as shown here:"
},
{
"programlisting": ">\nmysql> SHOW TRIGGERS LIKE 'acc%'\\G\n*************************** 1. row ***************************\n Trigger: ins_sum\n Event: INSERT\n Table: account\n Statement: SET @sum = @sum + NEW.amount\n Timing: BEFORE\n Created: 2018-08-08 10:10:12.61\n sql_mode: ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,\n NO_ZERO_IN_DATE,NO_ZERO_DATE,\n ERROR_FOR_DIVISION_BY_ZERO,\n NO_ENGINE_SUBSTITUTION\n Definer: me@localhost\ncharacter_set_client: utf8mb4\ncollation_connection: utf8mb4_0900_ai_ci\n Database Collation: utf8mb4_0900_ai_ci"
}
],
"id": "SHOW TRIGGERS",
"syntax": [
{
"programlisting": ">\nSHOW TRIGGERS\n [{FROM | IN} db_name]\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"VARIABLES",
"GLOBAL",
"SESSION"
],
"description": [
{
"para": "With a LIKE clause, the statement\n displays only rows for those variables with names that match the\n pattern. To obtain the row for a specific variable, use a\n LIKE clause as shown:"
},
{
"programlisting": ">\nSHOW VARIABLES LIKE 'max_join_size';\nSHOW SESSION VARIABLES LIKE 'max_join_size';"
},
{
"para": "To get a list of variables whose name match a pattern, use the\n % wildcard character in a\n LIKE clause:"
},
{
"programlisting": ">\nSHOW VARIABLES LIKE '%size%';\nSHOW GLOBAL VARIABLES LIKE '%size%';"
},
{
"para": "Wildcard characters can be used in any position within the\n pattern to be matched. Strictly speaking, because\n _ is a wildcard that matches any single\n character, you should escape it as \\_ to\n match it literally. In practice, this is rarely necessary."
}
],
"id": "SHOW VARIABLES",
"syntax": [
{
"programlisting": ">\nSHOW [GLOBAL | SESSION] VARIABLES\n [LIKE 'pattern' | WHERE expr]"
}
]
},
{
"keywords": [
"SHOW",
"WARNINGS",
"COUNT"
],
"description": [
{
"para": "SHOW WARNINGS is a diagnostic\n statement that displays information about the conditions\n (errors, warnings, and notes) resulting from executing a\n statement in the current session. Warnings are generated for DML\n statements such as INSERT,\n UPDATE, and\n LOAD DATA as well as DDL\n statements such as CREATE TABLE\n and ALTER TABLE."
},
{
"para": "The LIMIT clause has the same syntax as for\n the SELECT statement. See\n ."
},
{
"para": "SHOW WARNINGS is also used\n following EXPLAIN, to display the\n extended information generated by\n EXPLAIN. See\n ."
},
{
"para": "SHOW WARNINGS displays\n information about the conditions resulting from execution of the\n most recent nondiagnostic statement in the current session. If\n the most recent statement resulted in an error during parsing,\n SHOW WARNINGS shows the resulting\n conditions, regardless of statement type (diagnostic or\n nondiagnostic)."
},
{
"para": "The SHOW COUNT(*)\n WARNINGS diagnostic statement displays the total\n number of errors, warnings, and notes. You can also retrieve\n this number from the\n warning_count system variable:"
},
{
"programlisting": ">\nSHOW COUNT(*) WARNINGS;\nSELECT @@warning_count;"
},
{
"para": "A difference in these statements is that the first is a\n diagnostic statement that does not clear the message list. The\n second, because it is a SELECT\n statement is considered nondiagnostic and does clear the message\n list."
},
{
"para": "A related diagnostic statement, SHOW\n ERRORS, shows only error conditions (it excludes\n warnings and notes), and\n SHOW COUNT(*)\n ERRORS statement displays the total number of errors.\n See . GET\n DIAGNOSTICS can be used to examine information for\n individual conditions. See ."
}
],
"id": "SHOW WARNINGS",
"syntax": [
{
"programlisting": ">\nSHOW WARNINGS [LIMIT [offset,] row_count]\nSHOW COUNT(*) WARNINGS"
}
]
},
{
"keywords": [
"SHOW",
"CHARACTER",
"SET",
"COLLATION",
"COLUMNS",
"LIKE",
"TABLES",
"OPEN",
"FROM",
"INDEX",
"INDEXES",
"STATUS",
"VARIABLES",
"DATABASE",
"SCHEMA",
"DATABASES",
"SCHEMAS",
"LOGS",
"FULL",
"PROCESSLIST",
"FOR",
"GRANTS",
"TABLE",
"CREATE",
"WARNINGS",
"ERRORS",
"FIELDS",
"HOSTS",
"KEYS",
"ENGINE",
"ENGINES",
"INNODB",
"FUNCTION",
"PROCEDURE",
"PLUGIN",
"MUTEX",
"TRIGGER",
"TRIGGERS"
],
"description": [
{
"para": "SHOW has many forms that provide\n information about databases, tables, columns, or status\n information about the server. This section describes those\n following:"
},
{
"programlisting": ">\nSHOW {BINARY | MASTER} LOGS\nSHOW BINLOG EVENTS [IN 'log_name'] [FROM pos] [LIMIT [offset,] row_count]\nSHOW CHARACTER SET [like_or_where]\nSHOW COLLATION [like_or_where]\nSHOW [FULL] COLUMNS FROM tbl_name [FROM db_name] [like_or_where]\nSHOW CREATE DATABASE db_name\nSHOW CREATE EVENT event_name\nSHOW CREATE FUNCTION func_name\nSHOW CREATE PROCEDURE proc_name\nSHOW CREATE TABLE tbl_name\nSHOW CREATE TRIGGER trigger_name\nSHOW CREATE VIEW view_name\nSHOW DATABASES [like_or_where]\nSHOW ENGINE engine_name {STATUS | MUTEX}\nSHOW [STORAGE] ENGINES\nSHOW ERRORS [LIMIT [offset,] row_count]\nSHOW EVENTS\nSHOW FUNCTION CODE func_name\nSHOW FUNCTION STATUS [like_or_where]\nSHOW GRANTS FOR user\nSHOW INDEX FROM tbl_name [FROM db_name]\nSHOW MASTER STATUS\nSHOW OPEN TABLES [FROM db_name] [like_or_where]\nSHOW PLUGINS\nSHOW PROCEDURE CODE proc_name\nSHOW PROCEDURE STATUS [like_or_where]\nSHOW PRIVILEGES\nSHOW [FULL] PROCESSLIST\nSHOW PROFILE [types] [FOR QUERY n] [OFFSET n] [LIMIT n]\nSHOW PROFILES\nSHOW RELAYLOG EVENTS [IN 'log_name'] [FROM pos] [LIMIT [offset,] row_count]\nSHOW SLAVE HOSTS\nSHOW SLAVE STATUS [FOR CHANNEL channel]\nSHOW [GLOBAL | SESSION] STATUS [like_or_where]\nSHOW TABLE STATUS [FROM db_name] [like_or_where]\nSHOW [FULL] TABLES [FROM db_name] [like_or_where]\nSHOW TRIGGERS [FROM db_name] [like_or_where]\nSHOW [GLOBAL | SESSION] VARIABLES [like_or_where]\nSHOW WARNINGS [LIMIT [offset,] row_count]\n\nlike_or_where:\n LIKE 'pattern'\n | WHERE expr"
},
{
"para": "If the syntax for a given SHOW\n statement includes a LIKE\n 'pattern' part,\n 'pattern' is a\n string that can contain the SQL % and\n _ wildcard characters. The pattern is useful\n for restricting statement output to matching values."
},
{
"para": "Several SHOW statements also accept\n a WHERE clause that provides more flexibility\n in specifying which rows to display. See\n ."
}
],
"id": "SHOW",
"syntax": []
},
{
"keywords": [
"BINLOG"
],
"description": [
{
"para": "BINLOG is an internal-use\n statement. It is generated by the mysqlbinlog\n program as the printable representation of certain events in\n binary log files. (See .) The\n 'str' value is a\n base 64-encoded string the that server decodes to determine the\n data change indicated by the corresponding event."
},
{
"para": "To execute BINLOG statements when\n applying mysqlbinlog output, a user account\n requires the BINLOG_ADMIN or\n SUPER privilege, or the\n REPLICATION_APPLIER privilege\n plus the appropriate privileges to execute each log event."
}
],
"id": "BINLOG",
"syntax": [
{
"programlisting": ">\nBINLOG 'str'"
}
]
},
{
"keywords": [
"CACHE",
"INDEX",
"PARTITION",
"ALL"
],
"description": [
{
"para": "The CACHE INDEX statement assigns\n table indexes to a specific key cache. It applies only to\n MyISAM tables, including partitioned\n MyISAM tables. After the indexes have been\n assigned, they can be preloaded into the cache if desired with\n LOAD INDEX INTO\n CACHE."
},
{
"para": "The following statement assigns indexes from the tables\n t1, t2, and\n t3 to the key cache named\n hot_cache:"
},
{
"programlisting": ">\nmysql> CACHE INDEX t1, t2, t3 IN hot_cache;\n+---------+--------------------+----------+----------+\n| Table | Op | Msg_type | Msg_text |\n+---------+--------------------+----------+----------+\n| test.t1 | assign_to_keycache | status | OK |\n| test.t2 | assign_to_keycache | status | OK |\n| test.t3 | assign_to_keycache | status | OK |\n+---------+--------------------+----------+----------+"
}
],
"id": "CACHE INDEX",
"syntax": [
{
"programlisting": ">\nCACHE INDEX {\n tbl_index_list [, tbl_index_list] ...\n | tbl_name PARTITION (partition_list)\n }\n IN key_cache_name\n\ntbl_index_list:\n tbl_name [{INDEX|KEY} (index_name[, index_name] ...)]\n\npartition_list: {\n partition_name[, partition_name] ...\n | ALL\n}"
}
]
},
{
"keywords": [
"FLUSH",
"LOCAL",
"NO_WRITE_TO_BINLOG",
"BINARY",
"ENGINE",
"ERROR",
"GENERAL",
"HOSTS",
"LOGS",
"PRIVILEGES",
"OPTIMIZER_COSTS",
"RELAY",
"SLOW",
"STATUS",
"TABLES",
"USER_RESOURCES",
"WITH",
"READ",
"LOCK",
"FOR",
"EXPORT",
"CHANNEL"
],
"description": [
{
"para": "The FLUSH statement has several\n variant forms that clear or reload various internal caches,\n flush tables, or acquire locks. To execute\n FLUSH, you must have the\n RELOAD privilege. Specific flush\n options might require additional privileges, as described later."
},
{
"para": "By default, the server writes\n FLUSH statements to the binary\n log so that they replicate to replication slaves. To suppress\n logging, specify the optional\n NO_WRITE_TO_BINLOG keyword or its alias\n LOCAL."
},
{
"para": "The FLUSH statement causes an\n implicit commit. See ."
},
{
"para": "The mysqladmin utility provides a\n command-line interface to some flush operations, using commands\n such as flush-hosts,\n flush-logs,\n flush-privileges,\n flush-status, and\n flush-tables. See\n ."
},
{
"para": "Sending a SIGHUP signal to the server causes\n several flush operations to occur that are similar to various\n forms of the FLUSH statement. See\n ."
},
{
"para": "The RESET statement is similar to\n FLUSH. See\n , for information about using the\n RESET statement with replication."
}
],
"id": "FLUSH",
"syntax": [
{
"programlisting": ">\nFLUSH [NO_WRITE_TO_BINLOG | LOCAL] {\n flush_option [, flush_option] ...\n | tables_option\n}\n\nflush_option: {\n BINARY LOGS\n | ENGINE LOGS\n | ERROR LOGS\n | GENERAL LOGS\n | HOSTS\n | LOGS\n | PRIVILEGES\n | OPTIMIZER_COSTS\n | RELAY LOGS [FOR CHANNEL channel]\n | SLOW LOGS\n | STATUS\n | USER_RESOURCES\n}\n\ntables_option: {\n TABLES\n | TABLES tbl_name [, tbl_name] ...\n | TABLES WITH READ LOCK\n | TABLES tbl_name [, tbl_name] ... WITH READ LOCK\n | TABLES tbl_name [, tbl_name] ... FOR EXPORT\n}"
}
]
},
{
"keywords": [
"KILL",
"CONNECTION",
"QUERY"
],
"description": [
{
"para": "Each connection to mysqld runs in a separate\n thread. You can kill a thread with the KILL\n processlist_id statement."
},
{
"para": "Thread processlist identifiers can be determined from the\n ID column of the\n INFORMATION_SCHEMA\n PROCESSLIST table, the\n Id column of SHOW\n PROCESSLIST output, and the\n PROCESSLIST_ID column of the Performance\n Schema threads table. The value for\n the current thread is returned by the\n CONNECTION_ID() function."
},
{
"para": "KILL permits an optional\n CONNECTION or QUERY\n modifier:"
},
{
"itemizedlist": [
[
{
"para": "KILL\n CONNECTION is the same as\n KILL with no modifier: It\n terminates the connection associated with the given\n processlist_id, after terminating\n any statement the connection is executing."
}
],
[
{
"para": "KILL QUERY\n terminates the statement the connection is currently\n executing, but leaves the connection itself intact."
}
]
]
},
{
"para": "The ability to see which threads are available to be killed\n depends on the PROCESS privilege:"
},
{
"itemizedlist": [
[
{
"para": "Without PROCESS, you can see\n only your own threads."
}
],
[
{
"para": "With PROCESS, you can see all\n threads."
}
]
]
},
{
"para": "The ability to kill threads and statements depends on the\n CONNECTION_ADMIN and\n SUPER privileges:"
},
{
"itemizedlist": [
[
{
"para": "Without CONNECTION_ADMIN or\n SUPER, you can kill only your\n own threads and statements."
}
],
[
{
"para": "With CONNECTION_ADMIN or\n SUPER, you can kill all\n threads and statements, except that to affect a thread or\n statement that is executing with the\n SYSTEM_USER privilege, your\n own session must additionally have the\n SYSTEM_USER privilege."
}
]
]
},
{
"para": "You can also use the mysqladmin processlist\n and mysqladmin kill commands to examine and\n kill threads."
}
],
"id": "KILL",
"syntax": [
{
"programlisting": ">\nKILL [CONNECTION | QUERY] processlist_id"
}
]
},
{
"keywords": [
"LOAD",
"INDEX",
"INTO",
"CACHE",
"PARTITION",
"IGNORE",
"LEAVES",
"ALL"
],
"description": [
{
"para": "The LOAD INDEX INTO\n CACHE statement preloads a table index into the key\n cache to which it has been assigned by an explicit\n CACHE INDEX statement, or into\n the default key cache otherwise."
},
{
"para": "LOAD INDEX INTO\n CACHE applies only to MyISAM\n tables, including partitioned MyISAM tables.\n In addition, indexes on partitioned tables can be preloaded for\n one, several, or all partitions."
},
{
"para": "The IGNORE LEAVES modifier causes only blocks\n for the nonleaf nodes of the index to be preloaded."
},
{
"para": "IGNORE LEAVES is also supported for\n partitioned MyISAM tables."
}
],
"id": "LOAD INDEX",
"syntax": [
{
"programlisting": ">\nLOAD INDEX INTO CACHE\n tbl_index_list [, tbl_index_list] ...\n\ntbl_index_list:\n tbl_name\n [PARTITION (partition_list)]\n [{INDEX|KEY} (index_name[, index_name] ...)]\n [IGNORE LEAVES]\n\npartition_list: {\n partition_name[, partition_name] ...\n | ALL\n}"
}
]
},
{
"keywords": [
"RESET",
"MASTER",
"SLAVE"
],
"description": [
{
"para": "The RESET statement is used to\n clear the state of various server operations. You must have the\n RELOAD privilege to execute\n RESET."
},
{
"para": "For information about the RESET\n PERSIST statement that removes persisted global system\n variables, see ."
},
{
"para": "RESET acts as a stronger version\n of the FLUSH statement. See\n ."
},
{
"para": "The RESET statement causes an\n implicit commit. See ."
},
{
"para": "The following list describes the permitted\n RESET statement\n reset_option values:"
},
{
"itemizedlist": [
[
{
"para": "RESET MASTER"
},
{
"para": "Deletes all binary logs listed in the index file, resets the\n binary log index file to be empty, and creates a new binary\n log file."
}
],
[
{
"para": "RESET SLAVE"
},
{
"para": "Makes the slave forget its replication position in the\n master binary logs. Also resets the relay log by deleting\n any existing relay log files and beginning a new one."
}
]
]
}
],
"id": "RESET",
"syntax": [
{
"programlisting": ">\nRESET reset_option [, reset_option] ...\n\nreset_option: {\n MASTER\n | SLAVE\n}"
}
]
},
{
"keywords": [
"RESET",
"PERSIST",
"IF",
"EXISTS"
],
"description": [
{
"para": "RESET PERSIST removes persisted\n global system variable settings from the\n mysqld-auto.cnf option file in the data\n directory. Removing a persisted system variable causes the\n variable no longer to be initialized from\n mysqld-auto.cnf at server startup. For more\n information about persisting system variables and the\n mysqld-auto.cnf file, see\n ."
},
{
"para": "The privileges required for RESET\n PERSIST depend on the type of system variable to be\n removed:"
},
{
"itemizedlist": [
[
{
"para": "For dynamic system variables, this statement requires the\n SYSTEM_VARIABLES_ADMIN or\n SUPER privilege."
}
],
[
{
"para": "For read-only system variables, this statement requires the\n SYSTEM_VARIABLES_ADMIN and\n PERSIST_RO_VARIABLES_ADMIN\n privileges."
}
]
]
},
{
"para": "See ."
},
{
"para": "Depending on whether the variable name and IF\n EXISTS clauses are present, the\n RESET PERSIST statement has these\n forms:"
},
{
"itemizedlist": [
[
{
"para": "To remove all persisted variables from\n mysqld-auto.cnf, use\n RESET PERSIST without naming\n any system variable:"
},
{
"programlisting": ">\nRESET PERSIST;"
},
{
"para": "You must have privileges for removing both dynamic and\n read-only system variables if\n mysqld-auto.cnf contains both kinds of\n variables."
}
],
[
{
"para": "To remove a specific persisted variable from\n mysqld-auto.cnf, name it in the\n statement:"
},
{
"programlisting": ">\nRESET PERSIST system_var_name;"
},
{
"para": "This includes plugin system variables, even if the plugin is\n not currently installed. If the variable is not present in\n the file, an error occurs."
}
],
[
{
"para": "To remove a specific persisted variable from\n mysqld-auto.cnf, but produce a warning\n rather than an error if the variable is not present in the\n file, add an IF EXISTS clause to the\n previous syntax:"
},
{
"programlisting": ">\nRESET PERSIST IF EXISTS system_var_name;"
}
]
]
}
],
"id": "RESET PERSIST",
"syntax": [
{
"programlisting": ">\nRESET PERSIST [[IF EXISTS] system_var_name]"
}
]
},
{
"keywords": [
"RESTART"
],
"description": [
{
"para": "This statement stops and restarts the MySQL server. It requires\n the SHUTDOWN privilege."
},
{
"para": "One use for RESTART is when it is\n not possible or convenient to gain command-line access to the\n MySQL server on the server host to restart it. For example,\n SET\n PERSIST_ONLY can be used at runtime to make\n configuration changes to system variables that can be set only\n at server startup, but the server must still be restarted for\n those changes to take effect. The\n RESTART statement provides a way\n to do so from within client sessions, without requiring\n command-line access on the server host."
},
{
"para": "A successful RESTART operation\n requires mysqld to be running in an\n environment that has a monitoring process available to detect a\n server shutdown performed for restart purposes:"
},
{
"itemizedlist": [
[
{
"para": "In the presence of a monitoring process,\n RESTART causes\n mysqld to terminate such that the\n monitoring process can determine that it should start a new\n mysqld instance."
}
],
[
{
"para": "If no monitoring process is present,\n RESTART fails with an error."
}
]
]
},
{
"para": "These platforms provide the necessary monitoring support for the\n RESTART statement:"
},
{
"itemizedlist": [
[
{
"para": "Windows, when mysqld is started as a\n Windows service or standalone. (mysqld\n forks, and one process acts as a monitor to the other, which\n acts as the server.)"
}
],
[
{
"para": "Unix and Unix-like systems that use systemd or\n mysqld_safe to manage\n mysqld."
}
]
]
},
{
"para": "To configure a monitoring environment such that\n mysqld enables the\n RESTART statement:"
},
{
"para": "Here is a minimal example as implemented in the\n bash shell:"
},
{
"programlisting": ">\n#!/bin/bash\n\nexport MYSQLD_PARENT_PID=$$\n\nexport MYSQLD_RESTART_EXIT=16\n\nwhile true ; do\n bin/mysqld mysqld options here\n if [ $? -ne $MYSQLD_RESTART_EXIT ]; then\n break\n fi\ndone"
},
{
"para": "On Windows, the forking used to implement\n RESTART makes determining the\n server process to attach to for debugging more difficult. To\n alleviate this, starting the server with\n suppresses forking, in\n addition to its other actions done to set up a debugging\n environment. In non-debug settings,\n may be used for the\n sole purpose of suppressing forking the monitor process. For a\n server started with either \n or , executing\n RESTART causes the server to\n simply exit without restarting."
}
],
"id": "RESTART",
"syntax": [
{
"programlisting": ">\nRESTART"
}
]
},
{
"keywords": [
"SHUTDOWN"
],
"description": [
{
"para": "This statement stops the MySQL server. It requires the\n SHUTDOWN privilege."
},
{
"para": "SHUTDOWN provides an SQL-level\n interface to the same functionality available using the\n mysqladmin shutdown command or the\n mysql_shutdown() C API function."
}
],
"id": "SHUTDOWN",
"syntax": [
{
"programlisting": ">\nSHUTDOWN"
}
]
},
{
"keywords": [
"START",
"TRANSACTION",
"BEGIN",
"WORK",
"COMMIT",
"ROLLBACK",
"SET",
"AUTOCOMMIT",
"CHAIN",
"RELEASE",
"CONSISTENT",
"SNAPSHOT",
"READ",
"WRITE",
"ONLY"
],
"description": [
{
"para": "These statements provide control over use of\n transactions:"
},
{
"itemizedlist": [
[
{
"para": "START TRANSACTION or\n BEGIN start a new transaction."
}
],
[
{
"para": "COMMIT commits the current transaction,\n making its changes permanent."
}
],
[
{
"para": "ROLLBACK rolls back the current\n transaction, canceling its changes."
}
],
[
{
"para": "SET autocommit disables or enables the\n default autocommit mode for the current session."
}
]
]
},
{
"para": "By default, MySQL runs with\n autocommit mode enabled.\n This means that, when not otherwise inside a transaction, each\n statement is atomic, as if it were surrounded by START\n TRANSACTION and COMMIT. You cannot\n use ROLLBACK to undo the effect; however, if an\n error occurs during statement execution, the statement is rolled\n back."
},
{
"para": "To disable autocommit mode implicitly for a single series of\n statements, use the START TRANSACTION\n statement:"
},
{
"programlisting": ">\nSTART TRANSACTION;\nSELECT @A:=SUM(salary) FROM table1 WHERE type=1;\nUPDATE table2 SET summary=@A WHERE type=1;\nCOMMIT;"
},
{
"para": "With START TRANSACTION, autocommit remains\n disabled until you end the transaction with\n COMMIT or ROLLBACK. The\n autocommit mode then reverts to its previous state."
},
{
"para": "START TRANSACTION permits several modifiers\n that control transaction characteristics. To specify multiple\n modifiers, separate them by commas."
},
{
"itemizedlist": [
[
{
"para": "The WITH CONSISTENT SNAPSHOT modifier\n starts a consistent\n read for storage engines that are capable of it. This\n applies only to InnoDB. The effect is the\n same as issuing a START TRANSACTION\n followed by a SELECT from any\n InnoDB table. See\n . The WITH\n CONSISTENT SNAPSHOT modifier does not change the\n current transaction\n isolation level,\n so it provides a consistent snapshot only if the current\n isolation level is one that permits a consistent read. The\n only isolation level that permits a consistent read is\n REPEATABLE READ. For all\n other isolation levels, the WITH CONSISTENT\n SNAPSHOT clause is ignored. A warning is generated\n when the WITH CONSISTENT SNAPSHOT clause is\n ignored."
}
],
[
{
"para": "The READ WRITE and READ\n ONLY modifiers set the transaction access mode. They\n permit or prohibit changes to tables used in the transaction.\n The READ ONLY restriction prevents the\n transaction from modifying or locking both transactional and\n nontransactional tables that are visible to other\n transactions; the transaction can still modify or lock\n temporary tables."
},
{
"para": "MySQL enables extra optimizations for queries on\n InnoDB tables when the transaction is known\n to be read-only. Specifying READ ONLY\n ensures these optimizations are applied in cases where the\n read-only status cannot be determined automatically. See\n for more\n information."
},
{
"para": "If no access mode is specified, the default mode applies.\n Unless the default has been changed, it is read/write. It is\n not permitted to specify both READ WRITE\n and READ ONLY in the same statement."
},
{
"para": "In read-only mode, it remains possible to change tables\n created with the TEMPORARY keyword using\n DML statements. Changes made with DDL statements are not\n permitted, just as with permanent tables."
},
{
"para": "For additional information about transaction access mode,\n including ways to change the default mode, see\n ."
},
{
"para": "If the read_only system\n variable is enabled, explicitly starting a transaction with\n START TRANSACTION READ WRITE requires the\n CONNECTION_ADMIN or\n SUPER privilege."
}
]
]
},
{
"para": "To disable autocommit mode explicitly, use the following\n statement:"
},
{
"programlisting": ">\nSET autocommit=0;"
},
{
"para": "After disabling autocommit mode by setting the\n autocommit variable to zero,\n changes to transaction-safe tables (such as those for\n InnoDB or\n NDB) are not made permanent\n immediately. You must use COMMIT to\n store your changes to disk or ROLLBACK to\n ignore the changes."
},
{
"para": "autocommit is a session variable\n and must be set for each session. To disable autocommit mode for\n each new connection, see the description of the\n autocommit system variable at\n ."
},
{
"para": "BEGIN and BEGIN WORK are\n supported as aliases of START TRANSACTION for\n initiating a transaction. START TRANSACTION is\n standard SQL syntax, is the recommended way to start an ad-hoc\n transaction, and permits modifiers that BEGIN\n does not."
},
{
"para": "The BEGIN statement differs from the use of the\n BEGIN keyword that starts a\n BEGIN ... END\n compound statement. The latter does not begin a transaction. See\n ."
},
{
"para": "The optional WORK keyword is supported for\n COMMIT and ROLLBACK, as are\n the CHAIN and RELEASE\n clauses. CHAIN and RELEASE\n can be used for additional control over transaction completion.\n The value of the completion_type\n system variable determines the default completion behavior. See\n ."
},
{
"para": "The AND CHAIN clause causes a new transaction\n to begin as soon as the current one ends, and the new transaction\n has the same isolation level as the just-terminated transaction.\n The new transaction also uses the same access mode (READ\n WRITE or READ ONLY) as the\n just-terminated transaction. The RELEASE clause\n causes the server to disconnect the current client session after\n terminating the current transaction. Including the\n NO keyword suppresses CHAIN\n or RELEASE completion, which can be useful if\n the completion_type system\n variable is set to cause chaining or release completion by\n default."
}
],
"id": "START TRANSACTION",
"syntax": [
{
"programlisting": ">\nSTART TRANSACTION\n [transaction_characteristic [, transaction_characteristic] ...]\n\ntransaction_characteristic: {\n WITH CONSISTENT SNAPSHOT\n | READ WRITE\n | READ ONLY\n}\n\nBEGIN [WORK]\nCOMMIT [WORK] [AND [NO] CHAIN] [[NO] RELEASE]\nROLLBACK [WORK] [AND [NO] CHAIN] [[NO] RELEASE]\nSET autocommit = {0 | 1}"
}
]
},
{
"keywords": [
"ROLLBACK",
"TO",
"SAVEPOINT",
"RELEASE"
],
"description": [
{
"para": "InnoDB supports the SQL statements\n SAVEPOINT,\n ROLLBACK TO\n SAVEPOINT,\n RELEASE\n SAVEPOINT and the optional WORK\n keyword for\n ROLLBACK."
}
],
"id": "SAVEPOINT",
"syntax": [
{
"programlisting": ">\nSAVEPOINT identifier\nROLLBACK [WORK] TO [SAVEPOINT] identifier\nRELEASE SAVEPOINT identifier"
}
]
},
{
"keywords": [
"LOCK",
"UNLOCK",
"INSTANCE",
"BACKUP"
],
"description": [
{
"para": "LOCK INSTANCE FOR BACKUP acquires an\n instance-level backup lock that permits DML\n during an online backup while preventing operations that could\n result in an inconsistent snapshot."
},
{
"para": "Executing the LOCK INSTANCE FOR BACKUP\n statement requires the BACKUP_ADMIN\n privilege. The BACKUP_ADMIN\n privilege is automatically granted to users with the\n RELOAD privilege when performing an\n in-place upgrade to MySQL current-series from an earlier\n version."
},
{
"para": "Multiple sessions can hold a backup lock simultaneously."
},
{
"para": "UNLOCK INSTANCE releases a backup lock held by\n the current session. A backup lock held by a session is also\n released if the session is terminated."
},
{
"para": "LOCK INSTANCE FOR BACKUP prevents files from\n being created, renamed, or removed. REPAIR\n TABLETRUNCATE TABLE,\n OPTIMIZE TABLE, and account\n management statements are blocked. See\n . Operations that modify\n InnoDB files that are not recorded in the\n InnoDB redo log are also blocked."
},
{
"para": "LOCK INSTANCE FOR BACKUP permits DDL operations\n that only affect user-created temporary tables. In effect, files\n that belong to user-created temporary tables can be created,\n renamed, or removed while a backup lock is held. Creation of\n binary log files is also permitted."
},
{
"para": "A backup lock acquired by LOCK INSTANCE FOR\n BACKUP is independent of transactional locks and locks\n taken by\n FLUSH\n TABLES tbl_name [,\n tbl_name] ... WITH READ LOCK,\n and the following sequences of statements are permitted:"
},
{
"programlisting": ">\nLOCK INSTANCE FOR BACKUP;\nFLUSH TABLES tbl_name [, tbl_name] ... WITH READ LOCK;\nUNLOCK TABLES;\nUNLOCK INSTANCE;"
},
{
"programlisting": ">\nFLUSH TABLES tbl_name [, tbl_name] ... WITH READ LOCK;\nLOCK INSTANCE FOR BACKUP;\nUNLOCK INSTANCE;\nUNLOCK TABLES;"
},
{
"para": "The lock_wait_timeout setting\n defines the amount of time that a LOCK INSTANCE FOR\n BACKUP statement waits to acquire a lock before giving\n up."
}
],
"id": "LOCK INSTANCE FOR BACKUP",
"syntax": [
{
"programlisting": ">\nLOCK INSTANCE FOR BACKUP\n\nUNLOCK INSTANCE"
}
]
},
{
"keywords": [
"LOCK",
"UNLOCK",
"TABLES",
"AS",
"READ",
"LOCAL",
"LOW_PRIORITY",
"WRITE"
],
"description": [
{
"para": "MySQL enables client sessions to acquire table locks explicitly\n for the purpose of cooperating with other sessions for access to\n tables, or to prevent other sessions from modifying tables during\n periods when a session requires exclusive access to them. A\n session can acquire or release locks only for itself. One session\n cannot acquire locks for another session or release locks held by\n another session."
},
{
"para": "Locks may be used to emulate transactions or to get more speed\n when updating tables. This is explained in more detail in\n ."
},
{
"para": "LOCK TABLES explicitly acquires\n table locks for the current client session. Table locks can be\n acquired for base tables or views. You must have the\n LOCK TABLES privilege, and the\n SELECT privilege for each object to\n be locked."
},
{
"para": "For view locking, LOCK TABLES adds\n all base tables used in the view to the set of tables to be locked\n and locks them automatically. If you lock a table explicitly with\n LOCK TABLES, any tables used in\n triggers are also locked implicitly, as described in\n ."
},
{
"para": "If you lock a table explicitly with LOCK\n TABLES, any tables related by a foreign key constraint\n are opened and locked implicitly. For foreign key checks, a shared\n read-only lock (LOCK\n TABLES READ) is taken on related tables. For cascading\n updates, a shared-nothing write lock\n (LOCK TABLES\n WRITE) is taken on related tables that are involved in\n the operation."
},
{
"para": "UNLOCK\n TABLES explicitly releases any table locks held by the\n current session. LOCK TABLES\n implicitly releases any table locks held by the current session\n before acquiring new locks."
},
{
"para": "Another use for\n UNLOCK\n TABLES is to release the global read lock acquired with\n the FLUSH TABLES WITH READ LOCK\n statement, which enables you to lock all tables in all databases.\n See . (This is a very convenient way to get\n backups if you have a file system such as Veritas that can take\n snapshots in time.)"
}
],
"id": "LOCK TABLES",
"syntax": [
{
"programlisting": ">\nLOCK TABLES\n tbl_name [[AS] alias] lock_type\n [, tbl_name [[AS] alias] lock_type] ...\n\nlock_type: {\n READ [LOCAL]\n | [LOW_PRIORITY] WRITE\n}\n\nUNLOCK TABLES"
}
]
},
{
"keywords": [
"TRANSACTION",
"ISOLATION",
"LEVEL",
"GLOBAL",
"SESSION",
"READ",
"COMMITTED",
"UNCOMMITTED",
"REPEATABLE",
"SERIALIZABLE",
"WRITE",
"ONLY"
],
"description": [
{
"para": "This statement specifies\n transaction\n characteristics. It takes a list of one or more characteristic\n values separated by commas. Each characteristic value sets the\n transaction isolation\n level or access mode. The isolation level is used for\n operations on InnoDB tables. The\n access mode specifies whether transactions operate in read/write\n or read-only mode."
},
{
"para": "In addition, SET TRANSACTION can\n include an optional GLOBAL or\n SESSION keyword to indicate the scope of the\n statement."
}
],
"id": "SET TRANSACTION",
"syntax": [
{
"programlisting": ">\nSET [GLOBAL | SESSION] TRANSACTION\n transaction_characteristic [, transaction_characteristic] ...\n\ntransaction_characteristic: {\n ISOLATION LEVEL level\n | access_mode\n}\n\nlevel: {\n REPEATABLE READ\n | READ COMMITTED\n | READ UNCOMMITTED\n | SERIALIZABLE\n}\n\naccess_mode: {\n READ WRITE\n | READ ONLY\n}"
}
]
},
{
"keywords": [
"XA",
"START",
"BEGIN",
"END",
"PREPARE",
"COMMIT",
"ROLLBACK",
"RECOVER",
"RELEASE",
"CONSISTENT",
"SNAPSHOT",
"READ",
"WRITE",
"ONLY"
],
"description": [
{
"para": "For XA\n START, the JOIN and\n RESUME clauses are recognized but have no\n effect."
},
{
"para": "For XA\n END the SUSPEND [FOR MIGRATE]\n clause is recognized but has no effect."
},
{
"para": "Each XA statement begins with the XA keyword,\n and most of them require an xid\n value. An xid is an XA transaction\n identifier. It indicates which transaction the statement applies\n to. xid values are supplied by the\n client, or generated by the MySQL server. An\n xid value has from one to three\n parts:"
},
{
"programlisting": ">\nxid: gtrid [, bqual [, formatID ]]"
},
{
"para": "gtrid is a global transaction\n identifier, bqual is a branch\n qualifier, and formatID is a number\n that identifies the format used by the\n gtrid and\n bqual values. As indicated by the\n syntax, bqual and\n formatID are optional. The default\n bqual value is ''\n if not given. The default formatID\n value is 1 if not given."
},
{
"para": "gtrid and\n bqual must be string literals, each\n up to 64 bytes (not characters) long.\n gtrid and\n bqual can be specified in several\n ways. You can use a quoted string ('ab'), hex\n string (X'6162', 0x6162),\n or bit value\n (b'nnnn')."
},
{
"para": "formatID is an unsigned integer."
},
{
"para": "The gtrid and\n bqual values are interpreted in bytes\n by the MySQL server's underlying XA support routines. However,\n while an SQL statement containing an XA statement is being\n parsed, the server works with some specific character set. To be\n safe, write gtrid and\n bqual as hex strings."
},
{
"para": "xid values typically are generated by\n the Transaction Manager. Values generated by one TM must be\n different from values generated by other TMs. A given TM must be\n able to recognize its own xid values\n in a list of values returned by the\n XA\n RECOVER statement."
},
{
"para": "XA START\n xid starts an XA\n transaction with the given xid value.\n Each XA transaction must have a unique\n xid value, so the value must not\n currently be used by another XA transaction. Uniqueness is\n assessed using the gtrid and\n bqual values. All following XA\n statements for the XA transaction must be specified using the\n same xid value as that given in the\n XA\n START statement. If you use any of those statements\n but specify an xid value that does\n not correspond to some existing XA transaction, an error occurs."
},
{
"para": "One or more XA transactions can be part of the same global\n transaction. All XA transactions within a given global\n transaction must use the same gtrid\n value in the xid value. For this\n reason, gtrid values must be globally\n unique so that there is no ambiguity about which global\n transaction a given XA transaction is part of. The\n bqual part of the\n xid value must be different for each\n XA transaction within a global transaction. (The requirement\n that bqual values be different is a\n limitation of the current MySQL XA implementation. It is not\n part of the XA specification.)"
},
{
"para": "The XA\n RECOVER statement returns information for those XA\n transactions on the MySQL server that are in the\n PREPARED state. (See\n .) The output includes a row for each\n such XA transaction on the server, regardless of which client\n started it."
},
{
"para": "XA\n RECOVER requires the\n XA_RECOVER_ADMIN privilege. This\n privilege requirement prevents users from discovering the XID\n values for outstanding prepared XA transactions other than their\n own. It does not affect normal commit or rollback of an XA\n transaction because the user who started it knows its XID."
},
{
"para": "XA\n RECOVER output rows look like this (for an example\n xid value consisting of the parts\n 'abc', 'def', and\n 7):"
},
{
"programlisting": ">\nmysql> XA RECOVER;\n+----------+--------------+--------------+--------+\n| formatID | gtrid_length | bqual_length | data |\n+----------+--------------+--------------+--------+\n| 7 | 3 | 3 | abcdef |\n+----------+--------------+--------------+--------+"
},
{
"para": "The output columns have the following meanings:"
},
{
"itemizedlist": [
[
{
"para": "formatID is the\n formatID part of the transaction\n xid"
}
],
[
{
"para": "gtrid_length is the length in bytes of\n the gtrid part of the\n xid"
}
],
[
{
"para": "bqual_length is the length in bytes of\n the bqual part of the\n xid"
}
],
[
{
"para": "data is the concatenation of the\n gtrid and\n bqual parts of the\n xid"
}
]
]
},
{
"para": "XID values may contain nonprintable characters.\n XA\n RECOVER permits an optional CONVERT\n XID clause so that clients can request XID values in\n hexadecimal."
}
],
"id": "XA",
"syntax": [
{
"programlisting": ">\nXA {START|BEGIN} xid [JOIN|RESUME]\n\nXA END xid [SUSPEND [FOR MIGRATE]]\n\nXA PREPARE xid\n\nXA COMMIT xid [ONE PHASE]\n\nXA ROLLBACK xid\n\nXA RECOVER [CONVERT XID]"
}
]
},
{
"keywords": [
"DESCRIBE",
"DESC",
"EXPLAIN",
"ANALYZE",
"SELECT",
"FORMAT",
"TRADITIONAL",
"TREE",
"JSON",
"FOR",
"CONNECTION"
],
"description": [
{
"para": "The DESCRIBE and\n EXPLAIN statements are synonyms. In\n practice, the DESCRIBE keyword is\n more often used to obtain information about table structure,\n whereas EXPLAIN is used to obtain a\n query execution plan (that is, an explanation of how MySQL would\n execute a query)."
}
],
"id": "EXPLAIN",
"syntax": [
{
"programlisting": ">\n{EXPLAIN | DESCRIBE | DESC}\n tbl_name [col_name | wild]\n\n{EXPLAIN | DESCRIBE | DESC}\n [explain_type]\n {explainable_stmt | FOR CONNECTION connection_id}\n\n{EXPLAIN | DESCRIBE | DESC} ANALYZE select_statement \n\nexplain_type: {\n FORMAT = format_name\n}\n\nformat_name: {\n TRADITIONAL\n | JSON\n | TREE\n}\n\nexplainable_stmt: {\n SELECT statement\n | DELETE statement\n | INSERT statement\n | REPLACE statement\n | UPDATE statement\n}"
}
]
},
{
"keywords": [
"HELP"
],
"description": [
{
"para": "The HELP statement returns online\n information from the MySQL Reference Manual. Its proper operation\n requires that the help tables in the mysql\n database be initialized with help topic information (see\n )."
},
{
"para": "The HELP statement searches the\n help tables for the given search string and displays the result of\n the search. The search string is not case-sensitive."
},
{
"para": "The search string can contain the wildcard characters\n % and _. These have the same\n meaning as for pattern-matching operations performed with the\n LIKE operator. For example,\n HELP 'rep%' returns a list of topics that begin\n with rep."
}
],
"id": "HELP statement",
"syntax": [
{
"programlisting": ">\nHELP 'search_string'"
}
]
},
{
"keywords": [
"USE"
],
"description": [
{
"para": "The USE statement tells MySQL to\n use the named database as the default (current) database for\n subsequent statements. This statement requires some privilege for\n the database or some object within it."
},
{
"para": "The named database remains the default until the end of the\n session or another USE statement is\n issued:"
},
{
"programlisting": ">\nUSE db1;\nSELECT COUNT(*) FROM mytable; # selects from db1.mytable\nUSE db2;\nSELECT COUNT(*) FROM mytable; # selects from db2.mytable"
},
{
"para": "The database name must be specified on a single line. Newlines in\n database names are not supported."
}
],
"id": "USE",
"syntax": [
{
"programlisting": ">\nUSE db_name"
}
]
},
{
"keywords": [
"SERIAL",
"DEFAULT",
"VALUE"
],
"description": [
{
"para": "The AUTO_INCREMENT attribute can be used to\n generate a unique identity for new rows:"
}
],
"id": "AUTO_INCREMENT",
"syntax": []
}
]
}x
Windows NT KPTV 6.2 build 9200 (Windows Server 2012 Datacenter Edition) i586