File: C:/Program Files/MySQL/MySQL Workbench 8.0/modules/data/sqlide/help-8.0.json
{
"topics": [
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>BIT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>BIT</secondary>\n </indexterm>\n\n <literal role=\"type\">BIT[(<replaceable>M</replaceable>)]</literal>"
},
{
"para": "A bit-value type. <replaceable>M</replaceable> indicates the\n number of bits per value, from 1 to 64. The default is 1 if\n <replaceable>M</replaceable> is omitted."
}
],
"id": "BIT",
"syntax": []
},
{
"keywords": [
"BOOLEAN",
"BOOL",
"ZEROFILL",
"UNSIGNED",
"INT1"
],
"description": [
{
"para": "<indexterm>\n <primary>TINYINT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>TINYINT</secondary>\n </indexterm>\n\n <literal role=\"type\">TINYINT[(<replaceable>M</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "A very small integer. The signed range is\n <literal>-128</literal> to <literal>127</literal>. The\n unsigned range is <literal>0</literal> to\n <literal>255</literal>."
}
],
"id": "TINYINT",
"syntax": []
},
{
"keywords": [
"BOOL"
],
"description": [
{
"para": "<indexterm>\n <primary>BOOLEAN data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>BOOL data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>BOOLEAN</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>BOOL</secondary>\n </indexterm>\n\n <literal role=\"type\">BOOL</literal>,\n <literal role=\"type\">BOOLEAN</literal>"
},
{
"para": "These types are synonyms for\n <literal role=\"type\">TINYINT(1)</literal>. A value of zero\n is considered false. Nonzero values are considered true:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT IF(0, 'true', 'false');</userinput>\n+------------------------+\n| IF(0, 'true', 'false') |\n+------------------------+\n| false |\n+------------------------+\n\nmysql> <userinput>SELECT IF(1, 'true', 'false');</userinput>\n+------------------------+\n| IF(1, 'true', 'false') |\n+------------------------+\n| true |\n+------------------------+\n\nmysql> <userinput>SELECT IF(2, 'true', 'false');</userinput>\n+------------------------+\n| IF(2, 'true', 'false') |\n+------------------------+\n| true |\n+------------------------+"
},
{
"para": "However, the values <literal>TRUE</literal> and\n <literal>FALSE</literal> are merely aliases for\n <literal>1</literal> and <literal>0</literal>, respectively,\n as shown here:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT IF(0 = FALSE, 'true', 'false');</userinput>\n+--------------------------------+\n| IF(0 = FALSE, 'true', 'false') |\n+--------------------------------+\n| true |\n+--------------------------------+\n\nmysql> <userinput>SELECT IF(1 = TRUE, 'true', 'false');</userinput>\n+-------------------------------+\n| IF(1 = TRUE, 'true', 'false') |\n+-------------------------------+\n| true |\n+-------------------------------+\n\nmysql> <userinput>SELECT IF(2 = TRUE, 'true', 'false');</userinput>\n+-------------------------------+\n| IF(2 = TRUE, 'true', 'false') |\n+-------------------------------+\n| false |\n+-------------------------------+\n\nmysql> <userinput>SELECT IF(2 = FALSE, 'true', 'false');</userinput>\n+--------------------------------+\n| IF(2 = FALSE, 'true', 'false') |\n+--------------------------------+\n| false |\n+--------------------------------+"
},
{
"para": "The last two statements display the results shown because\n <literal>2</literal> is equal to neither\n <literal>1</literal> nor <literal>0</literal>."
}
],
"id": "BOOLEAN",
"syntax": []
},
{
"keywords": [
"INT2"
],
"description": [
{
"para": "<indexterm>\n <primary>SMALLINT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>SMALLINT</secondary>\n </indexterm>\n\n <literal role=\"type\">SMALLINT[(<replaceable>M</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "A small integer. The signed range is\n <literal>-32768</literal> to <literal>32767</literal>. The\n unsigned range is <literal>0</literal> to\n <literal>65535</literal>."
}
],
"id": "SMALLINT",
"syntax": []
},
{
"keywords": [
"INT3",
"MIDDLEINT"
],
"description": [
{
"para": "<indexterm>\n <primary>MEDIUMINT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>MEDIUMINT</secondary>\n </indexterm>\n\n <literal role=\"type\">MEDIUMINT[(<replaceable>M</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "A medium-sized integer. The signed range is\n <literal>-8388608</literal> to <literal>8388607</literal>.\n The unsigned range is <literal>0</literal> to\n <literal>16777215</literal>."
}
],
"id": "MEDIUMINT",
"syntax": []
},
{
"keywords": [
"INT4",
"UNSIGNED",
"ZEROFILL",
"INTEGER"
],
"description": [
{
"para": "<indexterm>\n <primary>INT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>INT</secondary>\n </indexterm>\n\n <literal role=\"type\">INT[(<replaceable>M</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "A normal-size integer. The signed range is\n <literal>-2147483648</literal> to\n <literal>2147483647</literal>. The unsigned range is\n <literal>0</literal> to <literal>4294967295</literal>."
}
],
"id": "INT",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>INTEGER data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>INTEGER</secondary>\n </indexterm>\n\n <literal role=\"type\">INTEGER[(<replaceable>M</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "This type is a synonym for\n <literal role=\"type\">INT</literal>."
}
],
"id": "INTEGER",
"syntax": []
},
{
"keywords": [
"UNSIGNED",
"ZEROFILL",
"INT8"
],
"description": [
{
"para": "<indexterm>\n <primary>BIGINT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>BIGINT</secondary>\n </indexterm>\n\n <indexterm>\n <primary>SERIAL</primary>\n </indexterm>\n\n <literal role=\"type\">BIGINT[(<replaceable>M</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "A large integer. The signed range is\n <literal>-9223372036854775808</literal> to\n <literal>9223372036854775807</literal>. The unsigned range\n is <literal>0</literal> to\n <literal>18446744073709551615</literal>."
},
{
"para": "<literal>SERIAL</literal> is an alias for <literal>BIGINT\n UNSIGNED NOT NULL AUTO_INCREMENT UNIQUE</literal>."
}
],
"id": "BIGINT",
"syntax": []
},
{
"keywords": [
"ZEROFILL",
"UNSIGNED",
"NUMERIC",
"DEC",
"FIXED"
],
"description": [
{
"para": "<indexterm>\n <primary>DECIMAL data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>DECIMAL</secondary>\n </indexterm>\n\n <literal role=\"type\">DECIMAL[(<replaceable>M</replaceable>[,<replaceable>D</replaceable>])]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "A packed <quote>exact</quote> fixed-point number.\n <replaceable>M</replaceable> is the total number of digits\n (the precision) and <replaceable>D</replaceable> is the\n number of digits after the decimal point (the scale). The\n decimal point and (for negative numbers) the\n <literal>-</literal> sign are not counted in\n <replaceable>M</replaceable>. If\n <replaceable>D</replaceable> is 0, values have no decimal\n point or fractional part. The maximum number of digits\n (<replaceable>M</replaceable>) for\n <literal role=\"type\">DECIMAL</literal> is 65. The maximum\n number of supported decimals (<replaceable>D</replaceable>)\n is 30. If <replaceable>D</replaceable> is omitted, the\n default is 0. If <replaceable>M</replaceable> is omitted,\n the default is 10."
},
{
"para": "<literal>UNSIGNED</literal>, if specified, disallows\n negative values. As of MySQL 8.0.17, the\n <literal>UNSIGNED</literal> attribute is deprecated for\n columns of type <literal role=\"type\">DECIMAL</literal> (and\n any synonyms) and support for it will be removed in a future\n MySQL version. Consider using a simple\n <literal>CHECK</literal> constraint instead for such\n columns."
},
{
"para": "All basic calculations (<literal>+, -, *, /</literal>) with\n <literal role=\"type\">DECIMAL</literal> columns are done with\n a precision of 65 digits."
}
],
"id": "DECIMAL",
"syntax": []
},
{
"keywords": [
"DECIMAL"
],
"description": [
{
"para": "<indexterm>\n <primary>DEC data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>NUMERIC data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>FIXED data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>DEC</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>NUMERIC</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>FIXED</secondary>\n </indexterm>\n\n <literal role=\"type\">DEC[(<replaceable>M</replaceable>[,<replaceable>D</replaceable>])]\n [UNSIGNED] [ZEROFILL]</literal>,\n <literal role=\"type\">NUMERIC[(<replaceable>M</replaceable>[,<replaceable>D</replaceable>])]\n [UNSIGNED] [ZEROFILL]</literal>,\n <literal role=\"type\">FIXED[(<replaceable>M</replaceable>[,<replaceable>D</replaceable>])]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "These types are synonyms for\n <literal role=\"type\">DECIMAL</literal>. The\n <literal role=\"type\">FIXED</literal> synonym is available\n for compatibility with other database systems."
}
],
"id": "DEC",
"syntax": []
},
{
"keywords": [
"UNSIGNED",
"ZEROFILL",
"FLOAT4"
],
"description": [
{
"para": "<indexterm>\n <primary>FLOAT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>FLOAT</secondary>\n </indexterm>\n\n <literal role=\"type\">FLOAT[(<replaceable>M</replaceable>,<replaceable>D</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "A small (single-precision) floating-point number.\n Permissible values are <literal>-3.402823466E+38</literal>\n to <literal>-1.175494351E-38</literal>,\n <literal>0</literal>, and <literal>1.175494351E-38</literal>\n to <literal>3.402823466E+38</literal>. 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": "<replaceable>M</replaceable> is the total number of digits\n and <replaceable>D</replaceable> is the number of digits\n following the decimal point. If <replaceable>M</replaceable>\n and <replaceable>D</replaceable> 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": "<literal>FLOAT(<replaceable>M</replaceable>,<replaceable>D</replaceable>)</literal>\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": "<literal>UNSIGNED</literal>, if specified, disallows\n negative values. As of MySQL 8.0.17, the\n <literal>UNSIGNED</literal> attribute is deprecated for\n columns of type <literal role=\"type\">FLOAT</literal> (and\n any synonyms) and support for it will be removed in a future\n MySQL version. Consider using a simple\n <literal>CHECK</literal> constraint instead for such\n columns."
},
{
"para": "Using <literal role=\"type\">FLOAT</literal> might give you\n some unexpected problems because all calculations in MySQL\n are done with double precision. See\n <xref linkend=\"no-matching-rows\" />."
}
],
"id": "FLOAT",
"syntax": []
},
{
"keywords": [
"FLOAT8",
"UNSIGNED",
"ZEROFILL",
"PRECISION",
"REAL"
],
"description": [
{
"para": "<indexterm>\n <primary>DOUBLE data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>FLOAT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>DOUBLE</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>FLOAT</secondary>\n </indexterm>\n\n <literal role=\"type\">DOUBLE[(<replaceable>M</replaceable>,<replaceable>D</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "A normal-size (double-precision) floating-point number.\n Permissible values are\n <literal>-1.7976931348623157E+308</literal> to\n <literal>-2.2250738585072014E-308</literal>,\n <literal>0</literal>, and\n <literal>2.2250738585072014E-308</literal> to\n <literal>1.7976931348623157E+308</literal>. 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": "<replaceable>M</replaceable> is the total number of digits\n and <replaceable>D</replaceable> is the number of digits\n following the decimal point. If <replaceable>M</replaceable>\n and <replaceable>D</replaceable> 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": "<literal>DOUBLE(<replaceable>M</replaceable>,<replaceable>D</replaceable>)</literal>\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": "<literal>UNSIGNED</literal>, if specified, disallows\n negative values. As of MySQL 8.0.17, the\n <literal>UNSIGNED</literal> attribute is deprecated for\n columns of type <literal role=\"type\">DOUBLE</literal> (and\n any synonyms) and support for it will be removed in a future\n MySQL version. Consider using a simple\n <literal>CHECK</literal> constraint instead for such\n columns."
}
],
"id": "DOUBLE",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>DOUBLE PRECISION data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>REAL data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>DOUBLE PRECISION</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>REAL</secondary>\n </indexterm>\n\n <literal role=\"type\">DOUBLE\n PRECISION[(<replaceable>M</replaceable>,<replaceable>D</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>,\n <literal role=\"type\">REAL[(<replaceable>M</replaceable>,<replaceable>D</replaceable>)]\n [UNSIGNED] [ZEROFILL]</literal>"
},
{
"para": "These types are synonyms for\n <literal role=\"type\">DOUBLE</literal>. Exception: If the\n <literal role=\"sqlmode\">REAL_AS_FLOAT</literal> SQL mode is\n enabled, <literal role=\"type\">REAL</literal> is a synonym\n for <literal role=\"type\">FLOAT</literal> rather than\n <literal role=\"type\">DOUBLE</literal>."
}
],
"id": "DOUBLE PRECISION",
"syntax": []
},
{
"keywords": [
"DATE"
],
"description": [
{
"para": "<indexterm>\n <primary>DATE data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>DATE</secondary>\n </indexterm>\n\n <literal role=\"type\">DATE</literal>"
},
{
"para": "A date. The supported range is\n <literal>'1000-01-01'</literal> to\n <literal>'9999-12-31'</literal>. MySQL displays\n <literal role=\"type\">DATE</literal> values in\n <literal>'YYYY-MM-DD'</literal> format, but permits\n assignment of values to <literal role=\"type\">DATE</literal>\n columns using either strings or numbers."
}
],
"id": "DATE",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>DATETIME data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>DATETIME</secondary>\n </indexterm>\n\n <literal role=\"type\">DATETIME[(<replaceable>fsp</replaceable>)]</literal>"
},
{
"para": "A date and time combination. The supported range is\n <literal>'1000-01-01 00:00:00.000000'</literal> to\n <literal>'9999-12-31 23:59:59.999999'</literal>. MySQL\n displays <literal role=\"type\">DATETIME</literal> values in\n <literal>'<replaceable>YYYY-MM-DD\n hh:mm:ss</replaceable>[.<replaceable>fraction</replaceable>]'</literal>\n format, but permits assignment of values to\n <literal role=\"type\">DATETIME</literal> columns using either\n strings or numbers."
},
{
"para": "An optional <replaceable>fsp</replaceable> 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 <literal role=\"type\">DATETIME</literal> columns\n can be specified using <literal>DEFAULT</literal> and\n <literal>ON UPDATE</literal> column definition clauses, as\n described in <xref linkend=\"timestamp-initialization\" />."
}
],
"id": "DATETIME",
"syntax": []
},
{
"keywords": [
"TIMESTAMP"
],
"description": [
{
"para": "<indexterm>\n <primary>TIMESTAMP data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>TIMESTAMP</secondary>\n </indexterm>\n\n <literal role=\"type\">TIMESTAMP[(<replaceable>fsp</replaceable>)]</literal>"
},
{
"para": "A timestamp. The range is <literal>'1970-01-01\n 00:00:01.000000'</literal> UTC to <literal>'2038-01-19\n 03:14:07.999999'</literal> UTC.\n <literal role=\"type\">TIMESTAMP</literal> values are stored\n as the number of seconds since the epoch\n (<literal>'1970-01-01 00:00:00'</literal> UTC). A\n <literal role=\"type\">TIMESTAMP</literal> cannot represent\n the value <literal>'1970-01-01 00:00:00'</literal> because\n that is equivalent to 0 seconds from the epoch and the value\n 0 is reserved for representing <literal>'0000-00-00\n 00:00:00'</literal>, the <quote>zero</quote>\n <literal role=\"type\">TIMESTAMP</literal> value."
},
{
"para": "An optional <replaceable>fsp</replaceable> 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 <literal>TIMESTAMP</literal>\n definitions depends on the value of the\n <literal role=\"sysvar\">explicit_defaults_for_timestamp</literal>\n system variable (see\n <xref linkend=\"server-system-variables\" />)."
},
{
"para": "If\n <literal role=\"sysvar\">explicit_defaults_for_timestamp</literal>\n is enabled, there is no automatic assignment of the\n <literal>DEFAULT CURRENT_TIMESTAMP</literal> or <literal>ON\n UPDATE CURRENT_TIMESTAMP</literal> attributes to any\n <literal role=\"type\">TIMESTAMP</literal> column. They must\n be included explicitly in the column definition. Also, any\n <literal role=\"type\">TIMESTAMP</literal> not explicitly\n declared as <literal>NOT NULL</literal> permits\n <literal>NULL</literal> values."
},
{
"para": "If\n <literal role=\"sysvar\">explicit_defaults_for_timestamp</literal>\n is disabled, the server handles <literal>TIMESTAMP</literal>\n as follows:"
},
{
"para": "Unless specified otherwise, the first\n <literal role=\"type\">TIMESTAMP</literal> 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 <literal role=\"type\">TIMESTAMP</literal>\n useful for recording the timestamp of an\n <literal role=\"stmt\">INSERT</literal> or\n <literal role=\"stmt\">UPDATE</literal> operation. You can\n also set any <literal role=\"type\">TIMESTAMP</literal> column\n to the current date and time by assigning it a\n <literal>NULL</literal> value, unless it has been defined\n with the <literal>NULL</literal> attribute to permit\n <literal>NULL</literal> values."
},
{
"para": "Automatic initialization and updating to the current date\n and time can be specified using <literal>DEFAULT\n CURRENT_TIMESTAMP</literal> and <literal>ON UPDATE\n CURRENT_TIMESTAMP</literal> column definition clauses. By\n default, the first <literal role=\"type\">TIMESTAMP</literal>\n column has these properties, as previously noted. However,\n any <literal role=\"type\">TIMESTAMP</literal> column in a\n table can be defined to have these properties."
}
],
"id": "TIMESTAMP",
"syntax": []
},
{
"keywords": [
"TIME"
],
"description": [
{
"para": "<indexterm>\n <primary>TIME data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>TIME</secondary>\n </indexterm>\n\n <literal role=\"type\">TIME[(<replaceable>fsp</replaceable>)]</literal>"
},
{
"para": "A time. The range is <literal>'-838:59:59.000000'</literal>\n to <literal>'838:59:59.000000'</literal>. MySQL displays\n <literal role=\"type\">TIME</literal> values in\n <literal>'<replaceable>hh:mm:ss</replaceable>[.<replaceable>fraction</replaceable>]'</literal>\n format, but permits assignment of values to\n <literal role=\"type\">TIME</literal> columns using either\n strings or numbers."
},
{
"para": "An optional <replaceable>fsp</replaceable> 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": "<indexterm>\n <primary>YEAR data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>YEAR</secondary>\n </indexterm>\n\n <literal role=\"type\">YEAR[(4)]</literal>"
},
{
"para": "A year in 4-digit format. MySQL displays\n <literal role=\"type\">YEAR</literal> values in\n <literal>YYYY</literal> format, but permits assignment of\n values to <literal role=\"type\">YEAR</literal> columns using\n either strings or numbers. Values display as\n <literal>1901</literal> to <literal>2155</literal>, or\n <literal>0000</literal>."
},
{
"para": "For additional information about\n <literal role=\"type\">YEAR</literal> display format and\n interpretation of input values, see <xref linkend=\"year\" />."
}
],
"id": "YEAR data type",
"syntax": []
},
{
"keywords": [
"NATIONAL",
"CHARACTER",
"NCHAR"
],
"description": [
{
"para": "<indexterm>\n <primary>CHAR data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>NATIONAL CHAR data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>NCHAR data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>CHARACTER data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>CHAR</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>NATIONAL CHAR</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>NCHAR</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>CHARACTER</secondary>\n </indexterm>\n\n <literal>[NATIONAL] CHAR[(<replaceable>M</replaceable>)]\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [COLLATE\n <replaceable>collation_name</replaceable>]</literal>"
},
{
"para": "A fixed-length string that is always right-padded with\n spaces to the specified length when stored.\n <replaceable>M</replaceable> represents the column length in\n characters. The range of <replaceable>M</replaceable> is 0\n to 255. If <replaceable>M</replaceable> is omitted, the\n length is 1."
}
],
"id": "CHAR",
"syntax": []
},
{
"keywords": [
"CHAR",
"BYTE"
],
"description": [
{
"para": "The <literal role=\"type\">CHAR BYTE</literal> data type is an\n alias for the <literal role=\"type\">BINARY</literal> data\n type. This is a compatibility feature."
}
],
"id": "CHAR BYTE",
"syntax": []
},
{
"keywords": [
"NATIONAL",
"VARYING",
"CHARACTER",
"VARCHARACTER",
"NVARCHAR"
],
"description": [
{
"para": "<indexterm>\n <primary>VARCHAR data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>CHARACTER VARYING data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>CHAR VARYING data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>VARCHARACTER data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>NATIONAL VARCHAR data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>NVARCHAR data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>VARCHAR</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>CHARACTER VARYING</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>CHAR VARYING</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>VARCHARACTER</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>NATIONAL VARCHAR</secondary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>NVARCHAR</secondary>\n </indexterm>\n\n <literal>[NATIONAL] VARCHAR(<replaceable>M</replaceable>)\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [COLLATE\n <replaceable>collation_name</replaceable>]</literal>"
},
{
"para": "A variable-length string. <replaceable>M</replaceable>\n represents the maximum column length in characters. The\n range of <replaceable>M</replaceable> is 0 to 65,535. The\n effective maximum length of a\n <literal role=\"type\">VARCHAR</literal> 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 <literal>utf8</literal> characters can require up to three\n bytes per character, so a\n <literal role=\"type\">VARCHAR</literal> column that uses the\n <literal>utf8</literal> character set can be declared to be\n a maximum of 21,844 characters. See\n <xref linkend=\"column-count-limit\" />."
},
{
"para": "MySQL stores <literal role=\"type\">VARCHAR</literal> 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 <literal role=\"type\">VARCHAR</literal> 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": "<literal role=\"type\">VARCHAR</literal> is shorthand for\n <literal role=\"type\">CHARACTER VARYING</literal>.\n <literal role=\"type\">NATIONAL VARCHAR</literal> is the\n standard SQL way to define that a\n <literal role=\"type\">VARCHAR</literal> column should use\n some predefined character set. MySQL uses\n <literal>utf8</literal> as this predefined character set.\n <xref linkend=\"charset-national\" />.\n <literal role=\"type\">NVARCHAR</literal> is shorthand for\n <literal role=\"type\">NATIONAL VARCHAR</literal>."
}
],
"id": "VARCHAR",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>BINARY data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>BINARY</secondary>\n </indexterm>\n\n <literal role=\"type\">BINARY[(<replaceable>M</replaceable>)]</literal>"
},
{
"para": "The <literal role=\"type\">BINARY</literal> type is similar to\n the <literal role=\"type\">CHAR</literal> type, but stores\n binary byte strings rather than nonbinary character strings.\n An optional length <replaceable>M</replaceable> represents\n the column length in bytes. If omitted,\n <replaceable>M</replaceable> defaults to 1."
}
],
"id": "BINARY",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>VARBINARY data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>VARBINARY</secondary>\n </indexterm>\n\n <literal role=\"type\">VARBINARY(<replaceable>M</replaceable>)</literal>"
},
{
"para": "The <literal role=\"type\">VARBINARY</literal> type is similar\n to the <literal role=\"type\">VARCHAR</literal> type, but\n stores binary byte strings rather than nonbinary character\n strings. <replaceable>M</replaceable> represents the maximum\n column length in bytes."
}
],
"id": "VARBINARY",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>TINYBLOB data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>TINYBLOB</secondary>\n </indexterm>\n\n <literal role=\"type\">TINYBLOB</literal>"
},
{
"para": "A <literal role=\"type\">BLOB</literal> column with a maximum\n length of 255 (2<superscript>8</superscript> minus 1)\n bytes. Each <literal role=\"type\">TINYBLOB</literal> 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": "<indexterm>\n <primary>TINYTEXT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>TINYTEXT</secondary>\n </indexterm>\n\n <literal condition=\"tinytext\" role=\"type\">TINYTEXT\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [COLLATE\n <replaceable>collation_name</replaceable>]</literal>"
},
{
"para": "A <literal role=\"type\">TEXT</literal> column with a maximum\n length of 255 (2<superscript>8</superscript> minus 1)\n characters. The effective maximum length is less if the\n value contains multibyte characters. Each\n <literal role=\"type\">TINYTEXT</literal> 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": "<indexterm>\n <primary>BLOB data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>BLOB</secondary>\n </indexterm>\n\n <literal role=\"type\">BLOB[(<replaceable>M</replaceable>)]</literal>"
},
{
"para": "A <literal role=\"type\">BLOB</literal> column with a maximum\n length of 65,535 (2<superscript>16</superscript> minus 1)\n bytes. Each <literal role=\"type\">BLOB</literal> value is\n stored using a 2-byte length prefix that indicates the\n number of bytes in the value."
},
{
"para": "An optional length <replaceable>M</replaceable> can be given\n for this type. If this is done, MySQL creates the column as\n the smallest <literal role=\"type\">BLOB</literal> type large\n enough to hold values <replaceable>M</replaceable> bytes\n long."
}
],
"id": "BLOB",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>TEXT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>TEXT</secondary>\n </indexterm>\n\n <literal role=\"type\">TEXT[(<replaceable>M</replaceable>)]\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [COLLATE\n <replaceable>collation_name</replaceable>]</literal>"
},
{
"para": "A <literal role=\"type\">TEXT</literal> column with a maximum\n length of 65,535 (2<superscript>16</superscript> minus 1)\n characters. The effective maximum length is less if the\n value contains multibyte characters. Each\n <literal role=\"type\">TEXT</literal> value is stored using a\n 2-byte length prefix that indicates the number of bytes in\n the value."
},
{
"para": "An optional length <replaceable>M</replaceable> can be given\n for this type. If this is done, MySQL creates the column as\n the smallest <literal role=\"type\">TEXT</literal> type large\n enough to hold values <replaceable>M</replaceable>\n characters long."
}
],
"id": "TEXT",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>MEDIUMBLOB data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>MEDIUMBLOB</secondary>\n </indexterm>\n\n <literal role=\"type\">MEDIUMBLOB</literal>"
},
{
"para": "A <literal role=\"type\">BLOB</literal> column with a maximum\n length of 16,777,215 (2<superscript>24</superscript> minus\n 1) bytes. Each <literal role=\"type\">MEDIUMBLOB</literal>\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": "<indexterm>\n <primary>MEDIUMTEXT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>MEDIUMTEXT</secondary>\n </indexterm>\n\n <literal condition=\"tinytext\" role=\"type\">MEDIUMTEXT\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [COLLATE\n <replaceable>collation_name</replaceable>]</literal>"
},
{
"para": "A <literal role=\"type\">TEXT</literal> column with a maximum\n length of 16,777,215 (2<superscript>24</superscript> minus\n 1) characters. The effective maximum length is less if the\n value contains multibyte characters. Each\n <literal role=\"type\">MEDIUMTEXT</literal> 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": "<indexterm>\n <primary>LONGBLOB data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>LONGBLOB</secondary>\n </indexterm>\n\n <literal role=\"type\">LONGBLOB</literal>"
},
{
"para": "A <literal role=\"type\">BLOB</literal> column with a maximum\n length of 4,294,967,295 or 4GB\n (2<superscript>32</superscript> minus 1) bytes. The\n effective maximum length of\n <literal role=\"type\">LONGBLOB</literal> columns depends on\n the configured maximum packet size in the client/server\n protocol and available memory. Each\n <literal role=\"type\">LONGBLOB</literal> 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": "<indexterm>\n <primary>LONGTEXT data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>LONGTEXT</secondary>\n </indexterm>\n\n <literal condition=\"tinytext\" role=\"type\">LONGTEXT\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [COLLATE\n <replaceable>collation_name</replaceable>]</literal>"
},
{
"para": "A <literal role=\"type\">TEXT</literal> column with a maximum\n length of 4,294,967,295 or 4GB\n (2<superscript>32</superscript> minus 1) characters. The\n effective maximum length is less if the value contains\n multibyte characters. The effective maximum length of\n <literal condition=\"blob\" role=\"type\">LONGTEXT</literal>\n columns also depends on the configured maximum packet size\n in the client/server protocol and available memory. Each\n <literal condition=\"blob\" role=\"type\">LONGTEXT</literal>\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": "<indexterm>\n <primary>ENUM data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>ENUM</secondary>\n </indexterm>\n\n <literal role=\"type\">ENUM('<replaceable>value1</replaceable>','<replaceable>value2</replaceable>',...)\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [COLLATE\n <replaceable>collation_name</replaceable>]</literal>"
},
{
"para": "An enumeration. A string object that can have only one\n value, chosen from the list of values\n <literal>'<replaceable>value1</replaceable>'</literal>,\n <literal>'<replaceable>value2</replaceable>'</literal>,\n <literal>...</literal>, <literal>NULL</literal> or the\n special <literal>''</literal> error value.\n <literal role=\"type\">ENUM</literal> values are represented\n internally as integers."
},
{
"para": "An <literal role=\"type\">ENUM</literal> column can have a\n maximum of 65,535 distinct elements."
},
{
"para": "The maximum supported length of an individual\n <literal>ENUM</literal> element is\n <replaceable>M</replaceable> <= 255 and\n (<replaceable>M</replaceable> x\n <replaceable>w</replaceable>) <= 1020, where\n <literal>M</literal> is the element literal length and\n <replaceable>w</replaceable> is the number of bytes required\n for the maximum-length character in the character set."
}
],
"id": "ENUM",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>SET data type</primary>\n </indexterm>\n\n <indexterm>\n <primary>data type</primary>\n <secondary>SET</secondary>\n </indexterm>\n\n <literal role=\"type\">SET('<replaceable>value1</replaceable>','<replaceable>value2</replaceable>',...)\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [COLLATE\n <replaceable>collation_name</replaceable>]</literal>"
},
{
"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 <literal>'<replaceable>value1</replaceable>'</literal>,\n <literal>'<replaceable>value2</replaceable>'</literal>,\n <literal>...</literal> <literal role=\"type\">SET</literal>\n values are represented internally as integers."
},
{
"para": "A <literal role=\"type\">SET</literal> column can have a\n maximum of 64 distinct members."
},
{
"para": "The maximum supported length of an individual\n <literal>SET</literal> element is\n <replaceable>M</replaceable> <= 255 and\n (<replaceable>M</replaceable> x\n <replaceable>w</replaceable>) <= 1020, where\n <literal>M</literal> is the element literal length and\n <replaceable>w</replaceable> 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 <literal>BLOB</literal> is a binary large object that can hold\n a variable amount of data. The four <literal>BLOB</literal>\n types are <literal>TINYBLOB</literal>, <literal>BLOB</literal>,\n <literal>MEDIUMBLOB</literal>, and <literal>LONGBLOB</literal>.\n These differ only in the maximum length of the values they can\n hold. The four <literal>TEXT</literal> types are\n <literal>TINYTEXT</literal>, <literal>TEXT</literal>,\n <literal>MEDIUMTEXT</literal>, and <literal>LONGTEXT</literal>.\n These correspond to the four <literal>BLOB</literal> types and\n have the same maximum lengths and storage requirements. See\n <xref linkend=\"storage-requirements\" />."
}
],
"id": "BLOB data type",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<literal>Geometry</literal> is the base class. It is an\n abstract class. The instantiable subclasses of\n <literal>Geometry</literal> 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 <literal>Geometry</literal> class has subclasses for\n <literal>Point</literal>, <literal>Curve</literal>,\n <literal>Surface</literal>, and\n <literal>GeometryCollection</literal>:"
},
{
"itemizedlist": [
[
{
"para": "<literal>Point</literal> represents zero-dimensional\n objects."
}
],
[
{
"para": "<literal>Curve</literal> represents one-dimensional\n objects, and has subclass <literal>LineString</literal>,\n with sub-subclasses <literal>Line</literal> and\n <literal>LinearRing</literal>."
}
],
[
{
"para": "<literal>Surface</literal> is designed for two-dimensional\n objects and has subclass <literal>Polygon</literal>."
}
],
[
{
"para": "<literal>GeometryCollection</literal> has specialized\n zero-, one-, and two-dimensional collection classes named\n <literal>MultiPoint</literal>,\n <literal>MultiLineString</literal>, and\n <literal>MultiPolygon</literal> for modeling geometries\n corresponding to collections of <literal>Points</literal>,\n <literal>LineStrings</literal>, and\n <literal>Polygons</literal>, respectively.\n <literal>MultiCurve</literal> and\n <literal>MultiSurface</literal> are introduced as abstract\n superclasses that generalize the collection interfaces to\n handle <literal>Curves</literal> and\n <literal>Surfaces</literal>."
}
]
]
},
{
"para": "<literal>Geometry</literal>, <literal>Curve</literal>,\n <literal>Surface</literal>, <literal>MultiCurve</literal>, and\n <literal>MultiSurface</literal> are defined as noninstantiable\n classes. They define a common set of methods for their\n subclasses and are included for extensibility."
},
{
"para": "<literal>Point</literal>, <literal>LineString</literal>,\n <literal>Polygon</literal>,\n <literal>GeometryCollection</literal>,\n <literal>MultiPoint</literal>,\n <literal>MultiLineString</literal>, and\n <literal>MultiPolygon</literal> are instantiable classes."
}
],
"id": "Geometry hierarchy",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "Its <emphasis role=\"bold\">MBR</emphasis> (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 <literal role=\"stmt\">CREATE\n TABLE</literal> or <literal role=\"stmt\">ALTER TABLE</literal>.\n Spatial columns are supported for\n <literal role=\"se\">MyISAM</literal>,\n <literal role=\"se\">InnoDB</literal>,\n <literal role=\"se\">NDB</literal>, and\n <literal role=\"se\">ARCHIVE</literal> tables. See also the notes\n about spatial indexes under\n <xref linkend=\"creating-spatial-indexes\" />."
},
{
"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 <xref linkend=\"spatial-type-overview\" />."
}
],
"id": "Spatial columns",
"syntax": []
},
{
"keywords": [
"INDEX",
"TABLE",
"ALTER",
"CREATE",
"ADD",
"KEY"
],
"description": [
{
"para": "For <literal>InnoDB</literal> and <literal>MyISAM</literal>\n tables, MySQL can create spatial indexes using syntax similar to\n that for creating regular indexes, but using the\n <literal>SPATIAL</literal> keyword. Columns in spatial indexes\n must be declared <literal>NOT NULL</literal>. The following\n examples demonstrate how to create spatial indexes:"
},
{
"itemizedlist": [
[
{
"para": "With <literal role=\"stmt\">CREATE TABLE</literal>:"
},
{
"programlisting": ">\nCREATE TABLE geom (g GEOMETRY NOT NULL SRID 4326, SPATIAL INDEX(g));"
}
],
[
{
"para": "With <literal role=\"stmt\">ALTER TABLE</literal>:"
},
{
"programlisting": ">\nCREATE TABLE geom (g GEOMETRY NOT NULL SRID 4326);\nALTER TABLE geom ADD SPATIAL INDEX(g);"
}
],
[
{
"para": "With <literal role=\"stmt\">CREATE INDEX</literal>:"
},
{
"programlisting": ">\nCREATE TABLE geom (g GEOMETRY NOT NULL SRID 4326);\nCREATE SPATIAL INDEX g ON geom (g);"
}
]
]
},
{
"para": "<literal>SPATIAL INDEX</literal> 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 <xref linkend=\"spatial-type-overview\" />, and\n <xref linkend=\"spatial-index-optimization\" />."
},
{
"para": "For more information on indexing spatial columns, see\n <xref linkend=\"create-index\" />."
},
{
"para": "To drop spatial indexes, use <literal role=\"stmt\">ALTER\n TABLE</literal> or <literal role=\"stmt\">DROP INDEX</literal>:"
},
{
"itemizedlist": [
[
{
"para": "With <literal role=\"stmt\">ALTER TABLE</literal>:"
},
{
"programlisting": ">\nALTER TABLE geom DROP INDEX g;"
}
],
[
{
"para": "With <literal role=\"stmt\">DROP INDEX</literal>:"
},
{
"programlisting": ">\nDROP INDEX g ON geom;"
}
]
]
},
{
"para": "Example: Suppose that a table <literal>geom</literal> contains\n more than 32,000 geometries, which are stored in the column\n <literal>g</literal> of type <literal>GEOMETRY</literal>. The\n table also has an <literal>AUTO_INCREMENT</literal> column\n <literal>fid</literal> for storing object ID values."
}
],
"id": "SPATIAL indexes",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>= (equal)</primary>\n </indexterm>\n\n <indexterm>\n <primary>equal (=)</primary>\n </indexterm>\n\n <literal condition=\"equal\" role=\"op\">=</literal>"
},
{
"para": "Equal:"
}
],
"id": "=",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<literal>NULL</literal>-safe equal. This operator performs\n an equality comparison like the\n <literal condition=\"equal\" role=\"op\">=</literal> operator,\n but returns <literal>1</literal> rather than\n <literal>NULL</literal> if both operands are\n <literal>NULL</literal>, and <literal>0</literal> rather\n than <literal>NULL</literal> if one operand is\n <literal>NULL</literal>."
},
{
"para": "The\n <literal condition=\"equal-to\" role=\"op\"><=></literal>\n operator is equivalent to the standard SQL <literal>IS NOT\n DISTINCT FROM</literal> operator."
}
],
"id": "<=>",
"syntax": [
{
"para": "<indexterm>\n <primary>NULL</primary>\n <secondary>testing for null</secondary>\n </indexterm>\n\n <indexterm>\n <primary><=> (equal to)</primary>\n </indexterm>\n\n <literal condition=\"equal-to\" role=\"op\"><=></literal>"
}
]
},
{
"keywords": [
"<>"
],
"description": [
{
"para": "Not equal:"
}
],
"id": "!=",
"syntax": [
{
"para": "<indexterm>\n <primary><> (not equal)</primary>\n </indexterm>\n\n <indexterm>\n <primary>not equal (<>)</primary>\n </indexterm>\n\n <indexterm>\n <primary>!= (not equal)</primary>\n </indexterm>\n\n <indexterm>\n <primary>not equal (!=)</primary>\n </indexterm>\n\n <literal condition=\"not-equal\" role=\"op\"><></literal>,\n <literal condition=\"not-equal\" role=\"op\">!=</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Less than or equal:"
}
],
"id": "<=",
"syntax": [
{
"para": "<indexterm>\n <primary><= (less than or equal)</primary>\n </indexterm>\n\n <indexterm>\n <primary>less than or equal (<=)</primary>\n </indexterm>\n\n <literal condition=\"less-than-or-equal\" role=\"op\"><=</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Less than:"
}
],
"id": "<",
"syntax": [
{
"para": "<indexterm>\n <primary>< (less than)</primary>\n </indexterm>\n\n <indexterm>\n <primary>less than (<)</primary>\n </indexterm>\n\n <literal condition=\"less-than\" role=\"op\"><</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Greater than or equal:"
}
],
"id": ">=",
"syntax": [
{
"para": "<indexterm>\n <primary>>= (greater than or equal)</primary>\n </indexterm>\n\n <indexterm>\n <primary>greater than or equal (>=)</primary>\n </indexterm>\n\n <literal condition=\"greater-than-or-equal\" role=\"op\">>=</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Greater than:"
}
],
"id": ">",
"syntax": [
{
"para": "<indexterm>\n <primary>> (greater than)</primary>\n </indexterm>\n\n <indexterm>\n <primary>greater than (>)</primary>\n </indexterm>\n\n <literal condition=\"greater-than\" role=\"op\">></literal>"
}
]
},
{
"keywords": [
"BETWEEN",
"AND"
],
"description": [
{
"para": "If <replaceable>expr</replaceable> is greater than or equal\n to <replaceable>min</replaceable> and\n <replaceable>expr</replaceable> is less than or equal to\n <replaceable>max</replaceable>,\n <literal role=\"op\">BETWEEN</literal> returns\n <literal>1</literal>, otherwise it returns\n <literal>0</literal>. This is equivalent to the expression\n <literal>(<replaceable>min</replaceable> <=\n <replaceable>expr</replaceable> AND\n <replaceable>expr</replaceable> <=\n <replaceable>max</replaceable>)</literal> if all the\n arguments are of the same type. Otherwise type conversion\n takes place according to the rules described in\n <xref linkend=\"type-conversion\" />, but applied to all the\n three arguments."
}
],
"id": "BETWEEN AND",
"syntax": [
{
"para": "<indexterm>\n <primary>BETWEEN ... AND</primary>\n </indexterm>\n\n <literal condition=\"between\" role=\"op\"><replaceable>expr</replaceable>\n BETWEEN <replaceable>min</replaceable> AND\n <replaceable>max</replaceable></literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is the same as <literal>NOT\n (<replaceable>expr</replaceable> BETWEEN\n <replaceable>min</replaceable> AND\n <replaceable>max</replaceable>)</literal>."
}
],
"id": "NOT BETWEEN",
"syntax": [
{
"para": "<indexterm>\n <primary>NOT BETWEEN</primary>\n </indexterm>\n\n <literal condition=\"not-between\" role=\"op\"><replaceable>expr</replaceable>\n NOT BETWEEN <replaceable>min</replaceable> AND\n <replaceable>max</replaceable></literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the first non-<literal>NULL</literal> value in the\n list, or <literal>NULL</literal> if there are no\n non-<literal>NULL</literal> values."
},
{
"para": "The return type of <literal role=\"func\">COALESCE()</literal>\n is the aggregated type of the argument types."
}
],
"id": "COALESCE",
"syntax": [
{
"para": "<indexterm>\n <primary>NULL</primary>\n <secondary>testing for null</secondary>\n </indexterm>\n\n <indexterm>\n <primary>COALESCE()</primary>\n </indexterm>\n\n <literal role=\"func\">COALESCE(<replaceable>value</replaceable>,...)</literal>"
}
]
},
{
"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 <literal role=\"func\">LEAST()</literal>."
}
],
"id": "GREATEST",
"syntax": [
{
"para": "<indexterm>\n <primary>GREATEST()</primary>\n </indexterm>\n\n <literal role=\"func\">GREATEST(<replaceable>value1</replaceable>,<replaceable>value2</replaceable>,...)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns <literal>1</literal> (true) if\n <replaceable>expr</replaceable> is equal to any of the\n values in the <literal>IN()</literal> list, else returns\n <literal>0</literal> (false)."
},
{
"para": "Type conversion takes place according to the rules described\n in <xref linkend=\"type-conversion\" />, applied to all the\n arguments. If no type conversion is needed for the values in\n the <literal>IN()</literal> list, they are all\n non-<literal>JSON</literal> constants of the same type, and\n <replaceable>expr</replaceable> 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 <replaceable>expr</replaceable> is done using a binary\n search, which makes the <literal>IN()</literal> operation\n very quick."
}
],
"id": "IN",
"syntax": [
{
"para": "<indexterm>\n <primary>IN()</primary>\n </indexterm>\n\n <literal condition=\"in\" role=\"op\"><replaceable>expr</replaceable>\n IN (<replaceable>value</replaceable>,...)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is the same as <literal>NOT\n (<replaceable>expr</replaceable> IN\n (<replaceable>value</replaceable>,...))</literal>."
}
],
"id": "NOT IN",
"syntax": [
{
"para": "<indexterm>\n <primary>NOT IN</primary>\n </indexterm>\n\n <literal condition=\"not-in\" role=\"op\"><replaceable>expr</replaceable>\n NOT IN (<replaceable>value</replaceable>,...)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns <literal>0</literal> if <replaceable>N</replaceable>\n < <replaceable>N1</replaceable>, <literal>1</literal> if\n <replaceable>N</replaceable> <\n <replaceable>N2</replaceable> and so on or\n <literal>-1</literal> if <replaceable>N</replaceable> is\n <literal>NULL</literal>. All arguments are treated as\n integers. It is required that <replaceable>N1</replaceable>\n < <replaceable>N2</replaceable> <\n <replaceable>N3</replaceable> < <literal>...</literal>\n < <replaceable>Nn</replaceable> for this function to work\n correctly. This is because a binary search is used (very\n fast)."
}
],
"id": "INTERVAL",
"syntax": [
{
"para": "<indexterm>\n <primary>INTERVAL()</primary>\n </indexterm>\n\n <literal role=\"func\">INTERVAL(<replaceable>N</replaceable>,<replaceable>N1</replaceable>,<replaceable>N2</replaceable>,<replaceable>N3</replaceable>,...)</literal>"
}
]
},
{
"keywords": [
"IS"
],
"description": [
{
"para": "Tests a value against a boolean value, where\n <replaceable>boolean_value</replaceable> can be\n <literal>TRUE</literal>, <literal>FALSE</literal>, or\n <literal>UNKNOWN</literal>."
}
],
"id": "IS",
"syntax": [
{
"para": "<indexterm>\n <primary>TRUE</primary>\n <secondary>testing for</secondary>\n </indexterm>\n\n <indexterm>\n <primary>FALSE</primary>\n <secondary>testing for</secondary>\n </indexterm>\n\n <indexterm>\n <primary>UNKNOWN</primary>\n <secondary>testing for</secondary>\n </indexterm>\n\n <indexterm>\n <primary>IS boolean_value</primary>\n </indexterm>\n\n <literal condition=\"is\" role=\"op\">IS\n <replaceable>boolean_value</replaceable></literal>"
}
]
},
{
"keywords": [
"IS",
"NOT"
],
"description": [
{
"para": "Tests a value against a boolean value, where\n <replaceable>boolean_value</replaceable> can be\n <literal>TRUE</literal>, <literal>FALSE</literal>, or\n <literal>UNKNOWN</literal>."
}
],
"id": "IS NOT",
"syntax": [
{
"para": "<indexterm>\n <primary>TRUE</primary>\n <secondary>testing for</secondary>\n </indexterm>\n\n <indexterm>\n <primary>FALSE</primary>\n <secondary>testing for</secondary>\n </indexterm>\n\n <indexterm>\n <primary>UNKNOWN</primary>\n <secondary>testing for</secondary>\n </indexterm>\n\n <indexterm>\n <primary>IS NOT boolean_value</primary>\n </indexterm>\n\n <literal condition=\"is-not\" role=\"op\">IS NOT\n <replaceable>boolean_value</replaceable></literal>"
}
]
},
{
"keywords": [
"IS",
"NULL"
],
"description": [
{
"para": "Tests whether a value is <literal>NULL</literal>."
}
],
"id": "IS NULL",
"syntax": [
{
"para": "<indexterm>\n <primary>NULL</primary>\n <secondary>testing for null</secondary>\n </indexterm>\n\n <indexterm>\n <primary>IS NULL</primary>\n </indexterm>\n\n <literal condition=\"is-null\" role=\"op\">IS NULL</literal>"
}
]
},
{
"keywords": [
"IS",
"NOT",
"NULL"
],
"description": [
{
"para": "Tests whether a value is not <literal>NULL</literal>."
}
],
"id": "IS NOT NULL",
"syntax": [
{
"para": "<indexterm>\n <primary>NULL</primary>\n <secondary>testing for null</secondary>\n </indexterm>\n\n <indexterm>\n <primary>IS NOT NULL</primary>\n </indexterm>\n\n <literal condition=\"is-null\" role=\"op\">IS NOT NULL</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If <replaceable>expr</replaceable> is\n <literal>NULL</literal>,\n <literal role=\"func\">ISNULL()</literal> returns\n <literal>1</literal>, otherwise it returns\n <literal>0</literal>."
}
],
"id": "ISNULL",
"syntax": [
{
"para": "<indexterm>\n <primary>ISNULL()</primary>\n </indexterm>\n\n <literal role=\"func\">ISNULL(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal>, the result\n is <literal>NULL</literal>. 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 <literal role=\"type\">DECIMAL</literal> value, they are\n compared as <literal role=\"type\">DECIMAL</literal>\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 <literal role=\"func\">LEAST()</literal> is\n the aggregated type of the comparison argument types."
}
],
"id": "LEAST",
"syntax": [
{
"para": "<indexterm>\n <primary>LEAST()</primary>\n </indexterm>\n\n <literal role=\"func\">LEAST(<replaceable>value1</replaceable>,<replaceable>value2</replaceable>,...)</literal>"
}
]
},
{
"keywords": [
"NOT"
],
"description": [
{
"para": "Logical NOT. Evaluates to <literal>1</literal> if the\n operand is <literal>0</literal>, to <literal>0</literal> if\n the operand is nonzero, and <literal>NOT NULL</literal>\n returns <literal>NULL</literal>."
}
],
"id": "!",
"syntax": [
{
"para": "<indexterm>\n <primary>NOT</primary>\n <secondary>logical</secondary>\n </indexterm>\n\n <indexterm>\n <primary>! (logical NOT)</primary>\n </indexterm>\n\n <literal role=\"op\">NOT</literal>,\n <literal condition=\"not\" role=\"op\">!</literal>"
}
]
},
{
"keywords": [
"AND"
],
"description": [
{
"para": "Logical AND. Evaluates to <literal>1</literal> if all\n operands are nonzero and not <literal>NULL</literal>, to\n <literal>0</literal> if one or more operands are\n <literal>0</literal>, otherwise <literal>NULL</literal> is\n returned."
}
],
"id": "AND",
"syntax": [
{
"para": "<indexterm>\n <primary>AND</primary>\n <secondary>logical</secondary>\n </indexterm>\n\n <indexterm>\n <primary>&& (logical AND)</primary>\n </indexterm>\n\n <literal role=\"op\">AND</literal>,\n <literal condition=\"and\" role=\"op\">&&</literal>"
}
]
},
{
"keywords": [
"OR"
],
"description": [
{
"para": "Logical OR. When both operands are\n non-<literal>NULL</literal>, the result is\n <literal>1</literal> if any operand is nonzero, and\n <literal>0</literal> otherwise. With a\n <literal>NULL</literal> operand, the result is\n <literal>1</literal> if the other operand is nonzero, and\n <literal>NULL</literal> otherwise. If both operands are\n <literal>NULL</literal>, the result is\n <literal>NULL</literal>."
}
],
"id": "OR",
"syntax": [
{
"para": "<indexterm>\n <primary>OR</primary>\n <secondary>logical</secondary>\n </indexterm>\n\n <indexterm>\n <primary>|| (logical OR)</primary>\n </indexterm>\n\n <literal role=\"op\">OR</literal>,\n <literal condition=\"or\" role=\"op\">||</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Logical XOR. Returns <literal>NULL</literal> if either\n operand is <literal>NULL</literal>. For\n non-<literal>NULL</literal> operands, evaluates to\n <literal>1</literal> if an odd number of operands is\n nonzero, otherwise <literal>0</literal> is returned."
}
],
"id": "XOR",
"syntax": [
{
"para": "<indexterm>\n <primary>XOR</primary>\n <secondary>logical</secondary>\n </indexterm>\n\n <literal role=\"op\">XOR</literal>"
}
]
},
{
"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 <literal condition=\"set-variable\" role=\"stmt\">SET</literal>\n statement. You can perform multiple assignments in the same\n statement."
},
{
"para": "Unlike\n <literal condition=\"assign-equal\" role=\"op\">=</literal>, the\n <literal condition=\"assign-value\" role=\"op\">:=</literal>\n operator is never interpreted as a comparison operator. This\n means you can use\n <literal condition=\"assign-value\" role=\"op\">:=</literal> in\n any valid SQL statement (not just in\n <literal condition=\"set-variable\" role=\"stmt\">SET</literal>\n statements) to assign a value to a variable."
}
],
"id": "assign-value",
"syntax": [
{
"para": "<indexterm>\n <primary>:= (assignment operator)</primary>\n </indexterm>\n\n <indexterm>\n <primary>assignment operator</primary>\n <secondary>:=</secondary>\n </indexterm>\n\n <literal condition=\"assign-value\" role=\"op\">:=</literal>"
}
]
},
{
"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 <literal condition=\"set-variable\" role=\"stmt\">SET</literal>\n statement, <literal>=</literal> 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 <literal condition=\"set-variable\" role=\"stmt\">SET</literal>\n statement, <literal>=</literal> is treated identically to\n <literal condition=\"assign-value\" role=\"op\">:=</literal>.)\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 <literal condition=\"set-variable\" role=\"stmt\">SET</literal>\n statement."
},
{
"para": "In the <literal>SET</literal> clause of an\n <literal role=\"stmt\">UPDATE</literal> statement,\n <literal>=</literal> 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 <literal>WHERE</literal> conditions that\n are part of the <literal role=\"stmt\">UPDATE</literal> are\n met. You can make multiple assignments in the same\n <literal>SET</literal> clause of an\n <literal role=\"stmt\">UPDATE</literal> statement."
},
{
"para": "In any other context, <literal>=</literal> is treated as a\n <link linkend=\"operator_equal\">comparison operator</link>."
}
],
"id": "assign-equal",
"syntax": [
{
"para": "<indexterm>\n <primary>= (assignment operator)</primary>\n </indexterm>\n\n <indexterm>\n <primary>assignment operator</primary>\n <secondary>=</secondary>\n </indexterm>\n\n <indexterm>\n <primary>SET statement</primary>\n <secondary>assignment operator</secondary>\n </indexterm>\n\n <literal condition=\"assign-equal\" role=\"op\">=</literal>"
}
]
},
{
"keywords": [
"CASE",
"WHEN",
"THEN",
"ELSE",
"END"
],
"description": [
{
"para": "The first <literal role=\"op\">CASE</literal> syntax returns the\n <replaceable>result</replaceable> for the first\n <literal><replaceable>value</replaceable>=<replaceable>compare_value</replaceable></literal>\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 <literal>ELSE</literal> is\n returned, or <literal>NULL</literal> if there is no\n <literal>ELSE</literal> part."
},
{
"para": "The return type of a <literal role=\"op\">CASE</literal>\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 <literal role=\"type\">DECIMAL</literal>, the result is\n <literal role=\"type\">DECIMAL</literal>."
}
],
[
{
"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 <literal role=\"type\">TINYINT</literal>,\n <literal role=\"type\">SMALLINT</literal>,\n <literal role=\"type\">MEDIUMINT</literal>,\n <literal role=\"type\">INT</literal>, or\n <literal role=\"type\">BIGINT</literal>)."
}
],
[
{
"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 <literal role=\"type\">INT</literal> and\n unsigned <literal role=\"type\">INT</literal>, the\n result is signed\n <literal role=\"type\">BIGINT</literal>."
}
],
[
{
"para": "The exception is unsigned\n <literal role=\"type\">BIGINT</literal> combined\n with any signed integer type. The result is\n <literal role=\"type\">DECIMAL</literal> with\n sufficient precision and scale 0."
}
]
]
}
]
]
}
],
[
{
"para": "If all types are <literal role=\"type\">BIT</literal>, the\n result is <literal role=\"type\">BIT</literal>. Otherwise,\n <literal role=\"type\">BIT</literal> arguments are treated\n similar to <literal role=\"type\">BIGINT</literal>."
}
],
[
{
"para": "If all types are <literal role=\"type\">YEAR</literal>, the\n result is <literal role=\"type\">YEAR</literal>. Otherwise,\n <literal>YEAR</literal> arguments are treated similar to\n <literal role=\"type\">INT</literal>."
}
],
[
{
"para": "If all types are character string\n (<literal role=\"type\">CHAR</literal> or\n <literal role=\"type\">VARCHAR</literal>), the result is\n <literal role=\"type\">VARCHAR</literal> 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 <literal role=\"type\">VARBINARY</literal>."
}
],
[
{
"para": "<literal role=\"type\">SET</literal> and\n <literal role=\"type\">ENUM</literal> are treated similar to\n <literal role=\"type\">VARCHAR</literal>; the result is\n <literal role=\"type\">VARCHAR</literal>."
}
],
[
{
"para": "If all types are <literal role=\"type\">JSON</literal>, the\n result is <literal role=\"type\">JSON</literal>."
}
],
[
{
"para": "If all types are temporal, the result is temporal:"
},
{
"itemizedlist": [
[
{
"para": "If all temporal types are\n <literal role=\"type\">DATE</literal>,\n <literal role=\"type\">TIME</literal>, or\n <literal role=\"type\">TIMESTAMP</literal>, the result\n is <literal role=\"type\">DATE</literal>,\n <literal role=\"type\">TIME</literal>, or\n <literal role=\"type\">TIMESTAMP</literal>,\n respectively."
}
],
[
{
"para": "Otherwise, for a mix of temporal types, the result is\n <literal role=\"type\">DATETIME</literal>."
}
]
]
}
],
[
{
"para": "If all types are <literal>GEOMETRY</literal>, the result\n is <literal>GEOMETRY</literal>."
}
],
[
{
"para": "If any type is <literal role=\"type\">BLOB</literal>, the\n result is <literal role=\"type\">BLOB</literal>."
}
],
[
{
"para": "For all other type combinations, the result is\n <literal role=\"type\">VARCHAR</literal>."
}
],
[
{
"para": "Literal <literal>NULL</literal> operands are ignored for\n type aggregation."
}
]
]
}
],
"id": "CASE operator",
"syntax": [
{
"para": "<indexterm>\n <primary>CASE</primary>\n </indexterm>\n\n <literal condition=\"case\" role=\"op\">CASE\n <replaceable>value</replaceable> WHEN\n [<replaceable>compare_value</replaceable>] THEN\n <replaceable>result</replaceable> [WHEN\n [<replaceable>compare_value</replaceable>] THEN\n <replaceable>result</replaceable> ...] [ELSE\n <replaceable>result</replaceable>] END</literal>"
},
{
"para": "<literal condition=\"case\" role=\"op\">CASE WHEN\n [<replaceable>condition</replaceable>] THEN\n <replaceable>result</replaceable> [WHEN\n [<replaceable>condition</replaceable>] THEN\n <replaceable>result</replaceable> ...] [ELSE\n <replaceable>result</replaceable>] END</literal>"
}
]
},
{
"keywords": [
"IF"
],
"description": [
{
"para": "If <replaceable>expr1</replaceable> is <literal>TRUE</literal>\n (<literal><replaceable>expr1</replaceable> <>\n 0</literal> and <literal><replaceable>expr1</replaceable>\n <> NULL</literal>), <literal role=\"func\">IF()</literal>\n returns <replaceable>expr2</replaceable>. Otherwise, it\n returns <replaceable>expr3</replaceable>."
},
{
"para": "If only one of <replaceable>expr2</replaceable> or\n <replaceable>expr3</replaceable> is explicitly\n <literal>NULL</literal>, the result type of the\n <literal role=\"func\">IF()</literal> function is the type of\n the non-<literal>NULL</literal> expression."
},
{
"para": "The default return type of <literal role=\"func\">IF()</literal>\n (which may matter when it is stored into a temporary table) is\n calculated as follows:"
},
{
"itemizedlist": [
[
{
"para": "If <replaceable>expr2</replaceable> or\n <replaceable>expr3</replaceable> produce a string, the\n result is a string."
},
{
"para": "If <replaceable>expr2</replaceable> and\n <replaceable>expr3</replaceable> are both strings, the\n result is case-sensitive if either string is case\n sensitive."
}
],
[
{
"para": "If <replaceable>expr2</replaceable> or\n <replaceable>expr3</replaceable> produce a floating-point\n value, the result is a floating-point value."
}
],
[
{
"para": "If <replaceable>expr2</replaceable> or\n <replaceable>expr3</replaceable> produce an integer, the\n result is an integer."
}
]
]
}
],
"id": "IF function",
"syntax": [
{
"para": "<indexterm>\n <primary>IF()</primary>\n </indexterm>\n\n <literal role=\"func\">IF(<replaceable>expr1</replaceable>,<replaceable>expr2</replaceable>,<replaceable>expr3</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If <replaceable>expr1</replaceable> is not\n <literal>NULL</literal>,\n <literal role=\"func\">IFNULL()</literal> returns\n <replaceable>expr1</replaceable>; otherwise it returns\n <replaceable>expr2</replaceable>."
}
],
"id": "IFNULL",
"syntax": [
{
"para": "<indexterm>\n <primary>NULL</primary>\n <secondary>testing for null</secondary>\n </indexterm>\n\n <indexterm>\n <primary>IFNULL()</primary>\n </indexterm>\n\n <literal role=\"func\">IFNULL(<replaceable>expr1</replaceable>,<replaceable>expr2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns <literal>NULL</literal> if\n <literal><replaceable>expr1</replaceable> =\n <replaceable>expr2</replaceable></literal> is true, otherwise\n returns <replaceable>expr1</replaceable>. This is the same as\n <literal condition=\"case\" role=\"op\">CASE WHEN\n <replaceable>expr1</replaceable> =\n <replaceable>expr2</replaceable> THEN NULL ELSE\n <replaceable>expr1</replaceable> END</literal>."
},
{
"para": "The return value has the same type as the first argument."
}
],
"id": "NULLIF",
"syntax": [
{
"para": "<indexterm>\n <primary>NULLIF()</primary>\n </indexterm>\n\n <literal role=\"func\">NULLIF(<replaceable>expr1</replaceable>,<replaceable>expr2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the numeric value of the leftmost character of the\n string <replaceable>str</replaceable>. Returns\n <literal>0</literal> if <replaceable>str</replaceable> is the\n empty string. Returns <literal>NULL</literal> if\n <replaceable>str</replaceable> is <literal>NULL</literal>.\n <literal role=\"func\">ASCII()</literal> works for 8-bit\n characters."
}
],
"id": "ASCII",
"syntax": [
{
"para": "<indexterm>\n <primary>ASCII()</primary>\n </indexterm>\n\n <literal role=\"func\">ASCII(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string representation of the binary value of\n <replaceable>N</replaceable>, where\n <replaceable>N</replaceable> is a longlong\n (<literal role=\"type\">BIGINT</literal>) number. This is\n equivalent to\n <literal role=\"func\">CONV(<replaceable>N</replaceable>,10,2)</literal>.\n Returns <literal>NULL</literal> if\n <replaceable>N</replaceable> is <literal>NULL</literal>."
}
],
"id": "BIN",
"syntax": [
{
"para": "<indexterm>\n <primary>BIN()</primary>\n </indexterm>\n\n <literal role=\"func\">BIN(<replaceable>N</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the length of the string\n <replaceable>str</replaceable> in bits."
}
],
"id": "BIT_LENGTH",
"syntax": [
{
"para": "<indexterm>\n <primary>BIT_LENGTH()</primary>\n </indexterm>\n\n <literal role=\"func\">BIT_LENGTH(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "By default, <literal role=\"func\">CHAR()</literal> returns a\n binary string. To produce a string in a given character set,\n use the optional <literal>USING</literal> clause:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT CHARSET(CHAR(X'65')), CHARSET(CHAR(X'65' USING utf8));</userinput>\n+----------------------+---------------------------------+\n| CHARSET(CHAR(X'65')) | CHARSET(CHAR(X'65' USING utf8)) |\n+----------------------+---------------------------------+\n| binary | utf8 |\n+----------------------+---------------------------------+"
},
{
"para": "If <literal>USING</literal> 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 <literal role=\"func\">CHAR()</literal> becomes\n <literal>NULL</literal>."
}
],
"id": "CHAR function",
"syntax": [
{
"para": "<indexterm>\n <primary>CHAR()</primary>\n </indexterm>\n\n <literal role=\"func\">CHAR(<replaceable>N</replaceable>,...\n [USING <replaceable>charset_name</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the length of the string\n <replaceable>str</replaceable>, 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 <literal role=\"func\">LENGTH()</literal> returns\n <literal>10</literal>, whereas\n <literal role=\"func\">CHAR_LENGTH()</literal> returns\n <literal>5</literal>."
}
],
"id": "CHAR_LENGTH",
"syntax": [
{
"para": "<indexterm>\n <primary>CHAR_LENGTH()</primary>\n </indexterm>\n\n <literal role=\"func\">CHAR_LENGTH(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">CHARACTER_LENGTH()</literal> is a synonym\n for <literal role=\"func\">CHAR_LENGTH()</literal>."
}
],
"id": "CHARACTER_LENGTH",
"syntax": [
{
"para": "<indexterm>\n <primary>CHARACTER_LENGTH()</primary>\n </indexterm>\n\n <literal role=\"func\">CHARACTER_LENGTH(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"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": "<literal role=\"func\">CONCAT()</literal> returns\n <literal>NULL</literal> if any argument is\n <literal>NULL</literal>."
}
],
"id": "CONCAT",
"syntax": [
{
"para": "<indexterm>\n <primary>CONCAT()</primary>\n </indexterm>\n\n <indexterm>\n <primary>string concatenation</primary>\n </indexterm>\n\n <indexterm>\n <primary>concatenation</primary>\n <secondary>string</secondary>\n </indexterm>\n\n <literal role=\"func\">CONCAT(<replaceable>str1</replaceable>,<replaceable>str2</replaceable>,...)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">CONCAT_WS()</literal> stands for\n Concatenate With Separator and is a special form of\n <literal role=\"func\">CONCAT()</literal>. 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 <literal>NULL</literal>, the result is\n <literal>NULL</literal>."
}
],
"id": "CONCAT_WS",
"syntax": [
{
"para": "<indexterm>\n <primary>CONCAT_WS()</primary>\n </indexterm>\n\n <literal role=\"func\">CONCAT_WS(<replaceable>separator</replaceable>,<replaceable>str1</replaceable>,<replaceable>str2</replaceable>,...)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">ELT()</literal> returns the\n <replaceable>N</replaceable>th element of the list of strings:\n <replaceable>str1</replaceable> if\n <replaceable>N</replaceable> = <literal>1</literal>,\n <replaceable>str2</replaceable> if\n <replaceable>N</replaceable> = <literal>2</literal>, and so\n on. Returns <literal>NULL</literal> if\n <replaceable>N</replaceable> is less than <literal>1</literal>\n or greater than the number of arguments.\n <literal role=\"func\">ELT()</literal> is the complement of\n <literal role=\"func\">FIELD()</literal>."
}
],
"id": "ELT",
"syntax": [
{
"para": "<indexterm>\n <primary>ELT()</primary>\n </indexterm>\n\n <literal role=\"func\">ELT(<replaceable>N</replaceable>,<replaceable>str1</replaceable>,<replaceable>str2</replaceable>,<replaceable>str3</replaceable>,...)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string such that for every bit set in the value\n <replaceable>bits</replaceable>, you get an\n <replaceable>on</replaceable> string and for every bit not set\n in the value, you get an <replaceable>off</replaceable>\n string. Bits in <replaceable>bits</replaceable> 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 <replaceable>separator</replaceable> string (the\n default being the comma character <literal>,</literal>). The\n number of bits examined is given by\n <replaceable>number_of_bits</replaceable>, which has a default\n of 64 if not specified.\n <replaceable>number_of_bits</replaceable> 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": "<indexterm>\n <primary>EXPORT_SET()</primary>\n </indexterm>\n\n <literal role=\"func\">EXPORT_SET(<replaceable>bits</replaceable>,<replaceable>on</replaceable>,<replaceable>off</replaceable>[,<replaceable>separator</replaceable>[,<replaceable>number_of_bits</replaceable>]])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the index (position) of <replaceable>str</replaceable>\n in the <replaceable>str1</replaceable>,\n <replaceable>str2</replaceable>,\n <replaceable>str3</replaceable>, <literal>...</literal> list.\n Returns <literal>0</literal> if <replaceable>str</replaceable>\n is not found."
},
{
"para": "If all arguments to <literal role=\"func\">FIELD()</literal> 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 <replaceable>str</replaceable> is <literal>NULL</literal>,\n the return value is <literal>0</literal> because\n <literal>NULL</literal> fails equality comparison with any\n value. <literal role=\"func\">FIELD()</literal> is the\n complement of <literal role=\"func\">ELT()</literal>."
}
],
"id": "FIELD",
"syntax": [
{
"para": "<indexterm>\n <primary>FIELD()</primary>\n </indexterm>\n\n <literal role=\"func\">FIELD(<replaceable>str</replaceable>,<replaceable>str1</replaceable>,<replaceable>str2</replaceable>,<replaceable>str3</replaceable>,...)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a value in the range of 1 to\n <replaceable>N</replaceable> if the string\n <replaceable>str</replaceable> is in the string list\n <replaceable>strlist</replaceable> consisting of\n <replaceable>N</replaceable> substrings. A string list is a\n string composed of substrings separated by\n <literal>,</literal> characters. If the first argument is a\n constant string and the second is a column of type\n <literal role=\"type\">SET</literal>, the\n <literal role=\"func\">FIND_IN_SET()</literal> function is\n optimized to use bit arithmetic. Returns <literal>0</literal>\n if <replaceable>str</replaceable> is not in\n <replaceable>strlist</replaceable> or if\n <replaceable>strlist</replaceable> is the empty string.\n Returns <literal>NULL</literal> if either argument is\n <literal>NULL</literal>. This function does not work properly\n if the first argument contains a comma (<literal>,</literal>)\n character."
}
],
"id": "FIND_IN_SET",
"syntax": [
{
"para": "<indexterm>\n <primary>FIND_IN_SET()</primary>\n </indexterm>\n\n <literal role=\"func\">FIND_IN_SET(<replaceable>str</replaceable>,<replaceable>strlist</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Formats the number <replaceable>X</replaceable> to a format\n like <literal>'#,###,###.##'</literal>, rounded to\n <replaceable>D</replaceable> decimal places, and returns the\n result as a string. If <replaceable>D</replaceable> is\n <literal>0</literal>, 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 <literal role=\"sysvar\">lc_time_names</literal> system variable\n (see <xref linkend=\"locale-support\" />). If no locale is\n specified, the default is <literal>'en_US'</literal>."
}
],
"id": "FORMAT",
"syntax": [
{
"para": "<indexterm>\n <primary>FORMAT()</primary>\n </indexterm>\n\n <literal role=\"func\">FORMAT(<replaceable>X</replaceable>,<replaceable>D</replaceable>[,<replaceable>locale</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Takes a string encoded with the base-64 encoded rules used by\n <literal role=\"func\">TO_BASE64()</literal> and returns the\n decoded result as a binary string. The result is\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal> or not a valid base-64 string. See the\n description of <literal role=\"func\">TO_BASE64()</literal> for\n details about the encoding and decoding rules."
}
],
"id": "FROM_BASE64",
"syntax": [
{
"para": "<indexterm>\n <primary>FROM_BASE64()</primary>\n </indexterm>\n\n <literal role=\"func\">FROM_BASE64(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "For a string argument <replaceable>str</replaceable>,\n <literal role=\"func\">HEX()</literal> returns a hexadecimal\n string representation of <replaceable>str</replaceable> where\n each byte of each character in <replaceable>str</replaceable>\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 <literal role=\"func\">UNHEX()</literal> function."
},
{
"para": "For a numeric argument <replaceable>N</replaceable>,\n <literal role=\"func\">HEX()</literal> returns a hexadecimal\n string representation of the value of\n <replaceable>N</replaceable> treated as a longlong\n (<literal role=\"type\">BIGINT</literal>) number. This is\n equivalent to\n <literal role=\"func\">CONV(<replaceable>N</replaceable>,10,16)</literal>.\n The inverse of this operation is performed by\n <literal role=\"func\">CONV(HEX(<replaceable>N</replaceable>),16,10)</literal>."
}
],
"id": "HEX",
"syntax": [
{
"para": "<indexterm>\n <primary>HEX()</primary>\n </indexterm>\n\n <literal role=\"func\">HEX(<replaceable>str</replaceable>)</literal>,\n <literal role=\"func\">HEX(<replaceable>N</replaceable>)</literal>"
}
]
},
{
"keywords": [
"INSERT"
],
"description": [
{
"para": "Returns the string <replaceable>str</replaceable>, with the\n substring beginning at position <replaceable>pos</replaceable>\n and <replaceable>len</replaceable> characters long replaced by\n the string <replaceable>newstr</replaceable>. Returns the\n original string if <replaceable>pos</replaceable> is not\n within the length of the string. Replaces the rest of the\n string from position <replaceable>pos</replaceable> if\n <replaceable>len</replaceable> is not within the length of the\n rest of the string. Returns <literal>NULL</literal> if any\n argument is <literal>NULL</literal>."
}
],
"id": "INSERT function",
"syntax": [
{
"para": "<indexterm>\n <primary>INSERT()</primary>\n </indexterm>\n\n <literal role=\"func\">INSERT(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>,<replaceable>newstr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the position of the first occurrence of substring\n <replaceable>substr</replaceable> in string\n <replaceable>str</replaceable>. This is the same as the\n two-argument form of <literal role=\"func\">LOCATE()</literal>,\n except that the order of the arguments is reversed."
}
],
"id": "INSTR",
"syntax": [
{
"para": "<indexterm>\n <primary>INSTR()</primary>\n </indexterm>\n\n <literal role=\"func\">INSTR(<replaceable>str</replaceable>,<replaceable>substr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">LCASE()</literal> is a synonym for\n <literal role=\"func\">LOWER()</literal>."
}
],
"id": "LCASE",
"syntax": [
{
"para": "<indexterm>\n <primary>LCASE()</primary>\n </indexterm>\n\n <literal role=\"func\">LCASE(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the leftmost <replaceable>len</replaceable> characters\n from the string <replaceable>str</replaceable>, or\n <literal>NULL</literal> if any argument is\n <literal>NULL</literal>."
}
],
"id": "LEFT",
"syntax": [
{
"para": "<indexterm>\n <primary>LEFT()</primary>\n </indexterm>\n\n <literal role=\"func\">LEFT(<replaceable>str</replaceable>,<replaceable>len</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the length of the string\n <replaceable>str</replaceable>, measured in bytes. A multibyte\n character counts as multiple bytes. This means that for a\n string containing five 2-byte characters,\n <literal role=\"func\">LENGTH()</literal> returns\n <literal>10</literal>, whereas\n <literal role=\"func\">CHAR_LENGTH()</literal> returns\n <literal>5</literal>."
}
],
"id": "LENGTH",
"syntax": [
{
"para": "<indexterm>\n <primary>LENGTH()</primary>\n </indexterm>\n\n <literal role=\"func\">LENGTH(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"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 <literal role=\"priv\">FILE</literal> privilege.\n The file must be readable by the server and its size less than\n <literal role=\"sysvar\">max_allowed_packet</literal> bytes. If\n the <literal role=\"sysvar\">secure_file_priv</literal> 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 <literal>NULL</literal>."
},
{
"para": "The <literal role=\"sysvar\">character_set_filesystem</literal>\n system variable controls interpretation of file names that are\n given as literal strings."
}
],
"id": "LOAD_FILE",
"syntax": [
{
"para": "<indexterm>\n <primary>FILE</primary>\n </indexterm>\n\n <indexterm>\n <primary>LOAD_FILE()</primary>\n </indexterm>\n\n <literal role=\"func\">LOAD_FILE(<replaceable>file_name</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "The first syntax returns the position of the first occurrence\n of substring <replaceable>substr</replaceable> in string\n <replaceable>str</replaceable>. The second syntax returns the\n position of the first occurrence of substring\n <replaceable>substr</replaceable> in string\n <replaceable>str</replaceable>, starting at position\n <replaceable>pos</replaceable>. Returns <literal>0</literal>\n if <replaceable>substr</replaceable> is not in\n <replaceable>str</replaceable>. Returns\n <literal>NULL</literal> if any argument is\n <literal>NULL</literal>."
}
],
"id": "LOCATE",
"syntax": [
{
"para": "<indexterm>\n <primary>LOCATE()</primary>\n </indexterm>\n\n <literal role=\"func\">LOCATE(<replaceable>substr</replaceable>,<replaceable>str</replaceable>)</literal>,\n <literal role=\"func\">LOCATE(<replaceable>substr</replaceable>,<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string <replaceable>str</replaceable> with all\n characters changed to lowercase according to the current\n character set mapping. The default is\n <literal>utf8mb4</literal>."
},
{
"programlisting": ">\nmysql> <userinput>SELECT LOWER('QUADRATICALLY');</userinput>\n -> 'quadratically'"
},
{
"para": "<literal role=\"func\">LOWER()</literal> (and\n <literal role=\"func\">UPPER()</literal>) are ineffective when\n applied to binary strings\n (<literal role=\"type\">BINARY</literal>,\n <literal role=\"type\">VARBINARY</literal>,\n <literal role=\"type\">BLOB</literal>). To perform lettercase\n conversion, convert the string to a nonbinary string:"
},
{
"programlisting": ">\nmysql> <userinput>SET @str = BINARY 'New York';</userinput>\nmysql> <userinput>SELECT LOWER(@str), LOWER(CONVERT(@str USING utf8mb4));</userinput>\n+-------------+------------------------------------+\n| LOWER(@str) | LOWER(CONVERT(@str USING utf8mb4)) |\n+-------------+------------------------------------+\n| New York | new york |\n+-------------+------------------------------------+"
},
{
"para": "For collations of Unicode character sets,\n <literal role=\"func\">LOWER()</literal> and\n <literal role=\"func\">UPPER()</literal> 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, <literal>utf8mb4_0900_ai_ci</literal>\n and <literal>utf8_unicode_520_ci</literal> work according to\n UCA 9.0.0 and 5.2.0, respectively, whereas\n <literal>utf8_unicode_ci</literal> works according to UCA\n 4.0.0. See <xref linkend=\"charset-unicode-sets\" />."
}
],
"id": "LOWER",
"syntax": [
{
"para": "<indexterm>\n <primary>LOWER()</primary>\n </indexterm>\n\n <literal role=\"func\">LOWER(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string <replaceable>str</replaceable>, left-padded\n with the string <replaceable>padstr</replaceable> to a length\n of <replaceable>len</replaceable> characters. If\n <replaceable>str</replaceable> is longer than\n <replaceable>len</replaceable>, the return value is shortened\n to <replaceable>len</replaceable> characters."
}
],
"id": "LPAD",
"syntax": [
{
"para": "<indexterm>\n <primary>LPAD()</primary>\n </indexterm>\n\n <literal role=\"func\">LPAD(<replaceable>str</replaceable>,<replaceable>len</replaceable>,<replaceable>padstr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string <replaceable>str</replaceable> with leading\n space characters removed."
}
],
"id": "LTRIM",
"syntax": [
{
"para": "<indexterm>\n <primary>LTRIM()</primary>\n </indexterm>\n\n <literal role=\"func\">LTRIM(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a set value (a string containing substrings separated\n by <literal>,</literal> characters) consisting of the strings\n that have the corresponding bit in\n <replaceable>bits</replaceable> set.\n <replaceable>str1</replaceable> corresponds to bit 0,\n <replaceable>str2</replaceable> to bit 1, and so on.\n <literal>NULL</literal> values in\n <replaceable>str1</replaceable>,\n <replaceable>str2</replaceable>, <literal>...</literal> are\n not appended to the result."
}
],
"id": "MAKE_SET",
"syntax": [
{
"para": "<indexterm>\n <primary>MAKE_SET()</primary>\n </indexterm>\n\n <literal role=\"func\">MAKE_SET(<replaceable>bits</replaceable>,<replaceable>str1</replaceable>,<replaceable>str2</replaceable>,...)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">MID(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>)</literal>\n is a synonym for\n <literal role=\"func\">SUBSTRING(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>)</literal>."
}
],
"id": "MID",
"syntax": [
{
"para": "<indexterm>\n <primary>MID()</primary>\n </indexterm>\n\n <literal role=\"func\">MID(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string representation of the octal value of\n <replaceable>N</replaceable>, where\n <replaceable>N</replaceable> is a longlong\n (<literal role=\"type\">BIGINT</literal>) number. This is\n equivalent to\n <literal role=\"func\">CONV(<replaceable>N</replaceable>,10,8)</literal>.\n Returns <literal>NULL</literal> if\n <replaceable>N</replaceable> is <literal>NULL</literal>."
}
],
"id": "OCT",
"syntax": [
{
"para": "<indexterm>\n <primary>OCT()</primary>\n </indexterm>\n\n <literal role=\"func\">OCT(<replaceable>N</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">OCTET_LENGTH()</literal> is a synonym for\n <literal role=\"func\">LENGTH()</literal>."
}
],
"id": "OCTET_LENGTH",
"syntax": [
{
"para": "<indexterm>\n <primary>OCTET_LENGTH()</primary>\n </indexterm>\n\n <literal role=\"func\">OCTET_LENGTH(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If the leftmost character of the string\n <replaceable>str</replaceable> 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 <literal role=\"func\">ORD()</literal> returns the same value as\n the <literal role=\"func\">ASCII()</literal> function."
}
],
"id": "ORD",
"syntax": [
{
"para": "<indexterm>\n <primary>ORD()</primary>\n </indexterm>\n\n <literal role=\"func\">ORD(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">POSITION(<replaceable>substr</replaceable>\n IN <replaceable>str</replaceable>)</literal> is a synonym for\n <literal role=\"func\">LOCATE(<replaceable>substr</replaceable>,<replaceable>str</replaceable>)</literal>."
}
],
"id": "POSITION",
"syntax": [
{
"para": "<indexterm>\n <primary>POSITION()</primary>\n </indexterm>\n\n <literal role=\"func\">POSITION(<replaceable>substr</replaceable>\n IN <replaceable>str</replaceable>)</literal>"
}
]
},
{
"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 (<literal>\\</literal>), single quote\n (<literal>'</literal>), ASCII <literal>NUL</literal>, and\n Control+Z preceded by a backslash. If the argument is\n <literal>NULL</literal>, the return value is the word\n <quote>NULL</quote> without enclosing single quotation marks."
}
],
"id": "QUOTE",
"syntax": [
{
"para": "<indexterm>\n <primary>QUOTE()</primary>\n </indexterm>\n\n <literal role=\"func\">QUOTE(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string consisting of the string\n <replaceable>str</replaceable> repeated\n <replaceable>count</replaceable> times. If\n <replaceable>count</replaceable> is less than 1, returns an\n empty string. Returns <literal>NULL</literal> if\n <replaceable>str</replaceable> or\n <replaceable>count</replaceable> are <literal>NULL</literal>."
}
],
"id": "REPEAT function",
"syntax": [
{
"para": "<indexterm>\n <primary>REPEAT()</primary>\n </indexterm>\n\n <literal role=\"func\">REPEAT(<replaceable>str</replaceable>,<replaceable>count</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string <replaceable>str</replaceable> with all\n occurrences of the string <replaceable>from_str</replaceable>\n replaced by the string <replaceable>to_str</replaceable>.\n <literal role=\"func\">REPLACE()</literal> performs a\n case-sensitive match when searching for\n <replaceable>from_str</replaceable>."
}
],
"id": "REPLACE function",
"syntax": [
{
"para": "<indexterm>\n <primary>REPLACE()</primary>\n </indexterm>\n\n <literal role=\"func\">REPLACE(<replaceable>str</replaceable>,<replaceable>from_str</replaceable>,<replaceable>to_str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string <replaceable>str</replaceable> with the\n order of the characters reversed."
}
],
"id": "REVERSE",
"syntax": [
{
"para": "<indexterm>\n <primary>REVERSE()</primary>\n </indexterm>\n\n <literal role=\"func\">REVERSE(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the rightmost <replaceable>len</replaceable>\n characters from the string <replaceable>str</replaceable>, or\n <literal>NULL</literal> if any argument is\n <literal>NULL</literal>."
}
],
"id": "RIGHT",
"syntax": [
{
"para": "<indexterm>\n <primary>RIGHT()</primary>\n </indexterm>\n\n <literal role=\"func\">RIGHT(<replaceable>str</replaceable>,<replaceable>len</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string <replaceable>str</replaceable>,\n right-padded with the string <replaceable>padstr</replaceable>\n to a length of <replaceable>len</replaceable> characters. If\n <replaceable>str</replaceable> is longer than\n <replaceable>len</replaceable>, the return value is shortened\n to <replaceable>len</replaceable> characters."
}
],
"id": "RPAD",
"syntax": [
{
"para": "<indexterm>\n <primary>RPAD()</primary>\n </indexterm>\n\n <literal role=\"func\">RPAD(<replaceable>str</replaceable>,<replaceable>len</replaceable>,<replaceable>padstr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string <replaceable>str</replaceable> with\n trailing space characters removed."
}
],
"id": "RTRIM",
"syntax": [
{
"para": "<indexterm>\n <primary>RTRIM()</primary>\n </indexterm>\n\n <literal role=\"func\">RTRIM(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a soundex string from <replaceable>str</replaceable>.\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 <literal role=\"func\">SOUNDEX()</literal>\n function returns an arbitrarily long string. You can use\n <literal role=\"func\">SUBSTRING()</literal> on the result to\n get a standard soundex string. All nonalphabetic characters in\n <replaceable>str</replaceable> 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 <literal>utf-8</literal>. See Bug #22638 for\n more information."
}
]
]
}
],
"id": "SOUNDEX",
"syntax": [
{
"para": "<indexterm>\n <primary>SOUNDEX()</primary>\n </indexterm>\n\n <literal role=\"func\">SOUNDEX(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": [
"SOUNDS",
"LIKE"
],
"description": [
{
"para": "This is the same as\n <literal role=\"func\">SOUNDEX(<replaceable>expr1</replaceable>)\n = SOUNDEX(<replaceable>expr2</replaceable>)</literal>."
}
],
"id": "SOUNDS LIKE",
"syntax": [
{
"para": "<indexterm>\n <primary>SOUNDS LIKE</primary>\n </indexterm>\n\n <literal condition=\"sounds-like\" role=\"op\"><replaceable>expr1</replaceable>\n SOUNDS LIKE <replaceable>expr2</replaceable></literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string consisting of <replaceable>N</replaceable>\n space characters."
}
],
"id": "SPACE",
"syntax": [
{
"para": "<indexterm>\n <primary>SPACE()</primary>\n </indexterm>\n\n <literal role=\"func\">SPACE(<replaceable>N</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">SUBSTR()</literal> is a synonym for\n <literal role=\"func\">SUBSTRING()</literal>."
}
],
"id": "SUBSTR",
"syntax": [
{
"para": "<indexterm>\n <primary>SUBSTR()</primary>\n </indexterm>\n\n <literal role=\"func\">SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,\n <literal role=\"func\">SUBSTR(<replaceable>str</replaceable>\n FROM <replaceable>pos</replaceable>)</literal>,\n <literal role=\"func\">SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>)</literal>,\n <literal role=\"func\">SUBSTR(<replaceable>str</replaceable>\n FROM <replaceable>pos</replaceable> FOR\n <replaceable>len</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "The forms without a <replaceable>len</replaceable> argument\n return a substring from string <replaceable>str</replaceable>\n starting at position <replaceable>pos</replaceable>. The forms\n with a <replaceable>len</replaceable> argument return a\n substring <replaceable>len</replaceable> characters long from\n string <replaceable>str</replaceable>, starting at position\n <replaceable>pos</replaceable>. The forms that use\n <literal>FROM</literal> are standard SQL syntax. It is also\n possible to use a negative value for\n <replaceable>pos</replaceable>. In this case, the beginning of\n the substring is <replaceable>pos</replaceable> characters\n from the end of the string, rather than the beginning. A\n negative value may be used for <replaceable>pos</replaceable>\n in any of the forms of this function. A value of 0 for\n <replaceable>pos</replaceable> returns an empty string."
},
{
"para": "For all forms of <literal role=\"func\">SUBSTRING()</literal>,\n the position of the first character in the string from which\n the substring is to be extracted is reckoned as\n <literal>1</literal>."
}
],
"id": "SUBSTRING",
"syntax": [
{
"para": "<indexterm>\n <primary>SUBSTRING()</primary>\n </indexterm>\n\n <literal role=\"func\">SUBSTRING(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,\n <literal role=\"func\">SUBSTRING(<replaceable>str</replaceable>\n FROM <replaceable>pos</replaceable>)</literal>,\n <literal role=\"func\">SUBSTRING(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>)</literal>,\n <literal role=\"func\">SUBSTRING(<replaceable>str</replaceable>\n FROM <replaceable>pos</replaceable> FOR\n <replaceable>len</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the substring from string\n <replaceable>str</replaceable> before\n <replaceable>count</replaceable> occurrences of the delimiter\n <replaceable>delim</replaceable>. If\n <replaceable>count</replaceable> is positive, everything to\n the left of the final delimiter (counting from the left) is\n returned. If <replaceable>count</replaceable> is negative,\n everything to the right of the final delimiter (counting from\n the right) is returned.\n <literal role=\"func\">SUBSTRING_INDEX()</literal> performs a\n case-sensitive match when searching for\n <replaceable>delim</replaceable>."
}
],
"id": "SUBSTRING_INDEX",
"syntax": [
{
"para": "<indexterm>\n <primary>SUBSTRING_INDEX()</primary>\n </indexterm>\n\n <literal role=\"func\">SUBSTRING_INDEX(<replaceable>str</replaceable>,<replaceable>delim</replaceable>,<replaceable>count</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal> if the argument is\n <literal>NULL</literal>. Base-64 encoded strings can be\n decoded using the <literal role=\"func\">FROM_BASE64()</literal>\n function."
}
],
"id": "TO_BASE64",
"syntax": [
{
"para": "<indexterm>\n <primary>TO_BASE64()</primary>\n </indexterm>\n\n <literal role=\"func\">TO_BASE64(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": [
"BOTH",
"LEADING",
"TRAILING",
"FROM"
],
"description": [
{
"para": "Returns the string <replaceable>str</replaceable> with all\n <replaceable>remstr</replaceable> prefixes or suffixes\n removed. If none of the specifiers <literal>BOTH</literal>,\n <literal>LEADING</literal>, or <literal>TRAILING</literal> is\n given, <literal>BOTH</literal> is assumed.\n <replaceable>remstr</replaceable> is optional and, if not\n specified, spaces are removed."
}
],
"id": "TRIM",
"syntax": [
{
"para": "<indexterm>\n <primary>TRIM()</primary>\n </indexterm>\n\n <literal role=\"func\">TRIM([{BOTH | LEADING | TRAILING}\n [<replaceable>remstr</replaceable>] FROM]\n <replaceable>str</replaceable>)</literal>,\n <literal role=\"func\">TRIM([<replaceable>remstr</replaceable>\n FROM] <replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">UCASE()</literal> is a synonym for\n <literal role=\"func\">UPPER()</literal>."
}
],
"id": "UCASE",
"syntax": [
{
"para": "<indexterm>\n <primary>UCASE()</primary>\n </indexterm>\n\n <literal role=\"func\">UCASE(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "For a string argument <replaceable>str</replaceable>,\n <literal role=\"func\">UNHEX(<replaceable>str</replaceable>)</literal>\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": "<indexterm>\n <primary>UNHEX()</primary>\n </indexterm>\n\n <literal role=\"func\">UNHEX(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the string <replaceable>str</replaceable> with all\n characters changed to uppercase according to the current\n character set mapping. The default is\n <literal>utf8mb4</literal>."
},
{
"programlisting": ">\nmysql> <userinput>SELECT UPPER('Hej');</userinput>\n -> 'HEJ'"
},
{
"para": "See the description of <literal role=\"func\">LOWER()</literal>\n for information that also applies to\n <literal role=\"func\">UPPER()</literal>. This included\n information about how to perform lettercase conversion of\n binary strings (<literal role=\"type\">BINARY</literal>,\n <literal role=\"type\">VARBINARY</literal>,\n <literal role=\"type\">BLOB</literal>) for which these functions\n are ineffective, and information about case folding for\n Unicode character sets."
}
],
"id": "UPPER",
"syntax": [
{
"para": "<indexterm>\n <primary>UPPER()</primary>\n </indexterm>\n\n <literal role=\"func\">UPPER(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"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 <literal role=\"func\">WEIGHT_STRING(<replaceable>str1</replaceable>)</literal>\n =\n <literal role=\"func\">WEIGHT_STRING(<replaceable>str2</replaceable>)</literal>,\n then <literal><replaceable>str1</replaceable> =\n <replaceable>str2</replaceable></literal>\n (<replaceable>str1</replaceable> and\n <replaceable>str2</replaceable> are considered equal)"
}
],
[
{
"para": "If\n <literal role=\"func\">WEIGHT_STRING(<replaceable>str1</replaceable>)</literal>\n <\n <literal role=\"func\">WEIGHT_STRING(<replaceable>str2</replaceable>)</literal>,\n then <literal><replaceable>str1</replaceable> <\n <replaceable>str2</replaceable></literal>\n (<replaceable>str1</replaceable> sorts before\n <replaceable>str2</replaceable>)"
}
]
]
},
{
"para": "<literal role=\"func\">WEIGHT_STRING()</literal> 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 <xref linkend=\"adding-collation\" />."
},
{
"para": "This list briefly summarizes the arguments. More details are\n given in the discussion following the list."
},
{
"itemizedlist": [
[
{
"para": "<replaceable>str</replaceable>: The input string\n expression."
}
],
[
{
"para": "<literal>AS</literal> clause: Optional; cast the input\n string to a given type and length."
}
],
[
{
"para": "<replaceable>flags</replaceable>: Optional; unused."
}
]
]
},
{
"para": "The input string, <replaceable>str</replaceable>, is a string\n expression. If the input is a nonbinary (character) string\n such as a <literal role=\"type\">CHAR</literal>,\n <literal role=\"type\">VARCHAR</literal>, or\n <literal role=\"type\">TEXT</literal> 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 <literal role=\"type\">BINARY</literal>,\n <literal role=\"type\">VARBINARY</literal>, or\n <literal role=\"type\">BLOB</literal> 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 <literal>NULL</literal>,\n <literal role=\"func\">WEIGHT_STRING()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "Examples:"
},
{
"programlisting": ">\nmysql> <userinput>SET @s = _utf8mb4 'AB' COLLATE utf8mb4_0900_ai_ci;</userinput>\nmysql> <userinput>SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));</userinput>\n+------+---------+------------------------+\n| @s | HEX(@s) | HEX(WEIGHT_STRING(@s)) |\n+------+---------+------------------------+\n| AB | 4142 | 1C471C60 |\n+------+---------+------------------------+"
},
{
"programlisting": ">\nmysql> <userinput>SET @s = _utf8mb4 'ab' COLLATE utf8mb4_0900_ai_ci;</userinput>\nmysql> <userinput>SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));</userinput>\n+------+---------+------------------------+\n| @s | HEX(@s) | HEX(WEIGHT_STRING(@s)) |\n+------+---------+------------------------+\n| ab | 6162 | 1C471C60 |\n+------+---------+------------------------+"
},
{
"programlisting": ">\nmysql> <userinput>SET @s = CAST('AB' AS BINARY);</userinput>\nmysql> <userinput>SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));</userinput>\n+------+---------+------------------------+\n| @s | HEX(@s) | HEX(WEIGHT_STRING(@s)) |\n+------+---------+------------------------+\n| AB | 4142 | 4142 |\n+------+---------+------------------------+"
},
{
"programlisting": ">\nmysql> <userinput>SET @s = CAST('ab' AS BINARY);</userinput>\nmysql> <userinput>SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));</userinput>\n+------+---------+------------------------+\n| @s | HEX(@s) | HEX(WEIGHT_STRING(@s)) |\n+------+---------+------------------------+\n| ab | 6162 | 6162 |\n+------+---------+------------------------+"
}
],
"id": "WEIGHT_STRING",
"syntax": [
{
"para": "<indexterm>\n <primary>WEIGHT_STRING()</primary>\n </indexterm>\n\n <literal role=\"func\">WEIGHT_STRING(<replaceable>str</replaceable>\n [AS {CHAR|BINARY}(<replaceable>N</replaceable>)]\n [<replaceable>flags</replaceable>])</literal>"
}
]
},
{
"keywords": [
"ESCAPE"
],
"description": [
{
"para": "Pattern matching using an SQL pattern. Returns\n <literal>1</literal> (<literal>TRUE</literal>) or\n <literal>0</literal> (<literal>FALSE</literal>). If either\n <replaceable>expr</replaceable> or\n <replaceable>pat</replaceable> is <literal>NULL</literal>,\n the result is <literal>NULL</literal>."
},
{
"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": "<indexterm>\n <primary>LIKE</primary>\n </indexterm>\n\n <literal condition=\"like\" role=\"op\"><replaceable>expr</replaceable>\n LIKE <replaceable>pat</replaceable> [ESCAPE\n '<replaceable>escape_char</replaceable>']</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is the same as <literal>NOT\n (<replaceable>expr</replaceable> LIKE\n <replaceable>pat</replaceable> [ESCAPE\n '<replaceable>escape_char</replaceable>'])</literal>."
}
],
"id": "NOT LIKE",
"syntax": [
{
"para": "<indexterm>\n <primary>NOT LIKE</primary>\n </indexterm>\n\n <literal condition=\"not-like\" role=\"op\"><replaceable>expr</replaceable>\n NOT LIKE <replaceable>pat</replaceable> [ESCAPE\n '<replaceable>escape_char</replaceable>']</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">STRCMP()</literal> returns\n <literal>0</literal> if the strings are the same,\n <literal>-1</literal> if the first argument is smaller than\n the second according to the current sort order, and\n <literal>1</literal> otherwise."
}
],
"id": "STRCMP",
"syntax": [
{
"para": "<indexterm>\n <primary>STRCMP()</primary>\n </indexterm>\n\n <literal role=\"func\">STRCMP(<replaceable>expr1</replaceable>,<replaceable>expr2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Addition:"
}
],
"id": "+",
"syntax": [
{
"para": "<indexterm>\n <primary>+ (addition)</primary>\n </indexterm>\n\n <indexterm>\n <primary>addition (+)</primary>\n </indexterm>\n\n <literal condition=\"plus\" role=\"op\">+</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Subtraction:"
}
],
"id": "- binary",
"syntax": [
{
"para": "<indexterm>\n <primary>- (subtraction)</primary>\n </indexterm>\n\n <indexterm>\n <primary>subtraction (-)</primary>\n </indexterm>\n\n <literal condition=\"minus\" role=\"op\">-</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Unary minus. This operator changes the sign of the operand."
}
],
"id": "- unary",
"syntax": [
{
"para": "<indexterm>\n <primary>- (unary minus)</primary>\n </indexterm>\n\n <indexterm>\n <primary>minus</primary>\n <secondary>unary (-)</secondary>\n </indexterm>\n\n <indexterm>\n <primary>unary minus (-)</primary>\n </indexterm>\n\n <literal condition=\"unary-minus\" role=\"op\">-</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Multiplication:"
}
],
"id": "*",
"syntax": [
{
"para": "<indexterm>\n <primary>* (multiplication)</primary>\n </indexterm>\n\n <indexterm>\n <primary>multiplication (*)</primary>\n </indexterm>\n\n <literal condition=\"times\" role=\"op\">*</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Division:"
}
],
"id": "/",
"syntax": [
{
"para": "<indexterm>\n <primary>/ (division)</primary>\n </indexterm>\n\n <indexterm>\n <primary>division (/)</primary>\n </indexterm>\n\n <literal condition=\"divide\" role=\"op\">/</literal>"
}
]
},
{
"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 <literal role=\"type\">DECIMAL</literal> and\n divided using <literal role=\"type\">DECIMAL</literal>\n arithmetic before converting the result to\n <literal role=\"type\">BIGINT</literal>. If the result exceeds\n <literal>BIGINT</literal> range, an error occurs."
}
],
"id": "DIV",
"syntax": [
{
"para": "<indexterm>\n <primary>DIV</primary>\n </indexterm>\n\n <literal role=\"op\">DIV</literal>"
}
]
},
{
"keywords": [
"MOD"
],
"description": [
{
"para": "Modulo operation. Returns the remainder of\n <replaceable>N</replaceable> divided by\n <replaceable>M</replaceable>. For more information, see the\n description for the <literal role=\"func\">MOD()</literal>\n function in <xref linkend=\"mathematical-functions\" />."
}
],
"id": "%",
"syntax": [
{
"para": "<indexterm>\n <primary>%</primary>\n </indexterm>\n\n <literal condition=\"mod\" role=\"op\"><replaceable>N</replaceable>\n % <replaceable>M</replaceable></literal>,\n <literal condition=\"mod\" role=\"op\"><replaceable>N</replaceable>\n MOD <replaceable>M</replaceable></literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the absolute value of <replaceable>X</replaceable>."
}
],
"id": "ABS",
"syntax": [
{
"para": "<indexterm>\n <primary>ABS()</primary>\n </indexterm>\n\n <literal role=\"func\">ABS(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the arc cosine of <replaceable>X</replaceable>, that\n is, the value whose cosine is <replaceable>X</replaceable>.\n Returns <literal>NULL</literal> if\n <replaceable>X</replaceable> is not in the range\n <literal>-1</literal> to <literal>1</literal>."
}
],
"id": "ACOS",
"syntax": [
{
"para": "<indexterm>\n <primary>ACOS()</primary>\n </indexterm>\n\n <literal role=\"func\">ACOS(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the arc sine of <replaceable>X</replaceable>, that\n is, the value whose sine is <replaceable>X</replaceable>.\n Returns <literal>NULL</literal> if\n <replaceable>X</replaceable> is not in the range\n <literal>-1</literal> to <literal>1</literal>."
}
],
"id": "ASIN",
"syntax": [
{
"para": "<indexterm>\n <primary>ASIN()</primary>\n </indexterm>\n\n <literal role=\"func\">ASIN(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the arc tangent of <replaceable>X</replaceable>,\n that is, the value whose tangent is\n <replaceable>X</replaceable>."
}
],
"id": "ATAN",
"syntax": [
{
"para": "<indexterm>\n <primary>ATAN()</primary>\n </indexterm>\n\n <literal role=\"func\">ATAN(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the arc tangent of the two variables\n <replaceable>X</replaceable> and\n <replaceable>Y</replaceable>. It is similar to calculating\n the arc tangent of <literal><replaceable>Y</replaceable> /\n <replaceable>X</replaceable></literal>, except that the\n signs of both arguments are used to determine the quadrant\n of the result."
}
],
"id": "ATAN2",
"syntax": [
{
"para": "<indexterm>\n <primary>ATAN2()</primary>\n </indexterm>\n\n <literal condition=\"atan2\" role=\"func\">ATAN(<replaceable>Y</replaceable>,<replaceable>X</replaceable>)</literal>,\n <literal role=\"func\">ATAN2(<replaceable>Y</replaceable>,<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": [
"CEIL"
],
"description": [
{
"para": "<literal role=\"func\">CEIL()</literal> is a synonym for\n <literal role=\"func\">CEILING()</literal>."
}
],
"id": "CEIL",
"syntax": [
{
"para": "<indexterm>\n <primary>CEIL()</primary>\n </indexterm>\n\n <literal role=\"func\">CEIL(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": [
"CEILING"
],
"description": [
{
"para": "Returns the smallest integer value not less than\n <replaceable>X</replaceable>."
}
],
"id": "CEILING",
"syntax": [
{
"para": "<indexterm>\n <primary>CEILING()</primary>\n </indexterm>\n\n <literal role=\"func\">CEILING(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Converts numbers between different number bases. Returns a\n string representation of the number\n <replaceable>N</replaceable>, converted from base\n <replaceable>from_base</replaceable> to base\n <replaceable>to_base</replaceable>. Returns\n <literal>NULL</literal> if any argument is\n <literal>NULL</literal>. The argument\n <replaceable>N</replaceable> is interpreted as an integer,\n but may be specified as an integer or a string. The minimum\n base is <literal>2</literal> and the maximum base is\n <literal>36</literal>. If\n <replaceable>from_base</replaceable> is a negative number,\n <replaceable>N</replaceable> is regarded as a signed number.\n Otherwise, <replaceable>N</replaceable> is treated as\n unsigned. <literal role=\"func\">CONV()</literal> works with\n 64-bit precision."
}
],
"id": "CONV",
"syntax": [
{
"para": "<indexterm>\n <primary>CONV()</primary>\n </indexterm>\n\n <literal role=\"func\">CONV(<replaceable>N</replaceable>,<replaceable>from_base</replaceable>,<replaceable>to_base</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the cosine of <replaceable>X</replaceable>, where\n <replaceable>X</replaceable> is given in radians."
}
],
"id": "COS",
"syntax": [
{
"para": "<indexterm>\n <primary>COS()</primary>\n </indexterm>\n\n <literal role=\"func\">COS(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the cotangent of <replaceable>X</replaceable>."
}
],
"id": "COT",
"syntax": [
{
"para": "<indexterm>\n <primary>COT()</primary>\n </indexterm>\n\n <literal role=\"func\">COT(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Computes a cyclic redundancy check value and returns a\n 32-bit unsigned value. The result is <literal>NULL</literal>\n if the argument is <literal>NULL</literal>. 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": "<indexterm>\n <primary>CRC32()</primary>\n </indexterm>\n\n <literal role=\"func\">CRC32(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the argument <replaceable>X</replaceable>, converted\n from radians to degrees."
}
],
"id": "DEGREES",
"syntax": [
{
"para": "<indexterm>\n <primary>DEGREES()</primary>\n </indexterm>\n\n <literal role=\"func\">DEGREES(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the value of <emphasis>e</emphasis> (the base of\n natural logarithms) raised to the power of\n <replaceable>X</replaceable>. The inverse of this function\n is <literal role=\"func\">LOG()</literal> (using a single\n argument only) or <literal role=\"func\">LN()</literal>."
}
],
"id": "EXP",
"syntax": [
{
"para": "<indexterm>\n <primary>EXP()</primary>\n </indexterm>\n\n <literal role=\"func\">EXP(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the largest integer value not greater than\n <replaceable>X</replaceable>."
}
],
"id": "FLOOR",
"syntax": [
{
"para": "<indexterm>\n <primary>FLOOR()</primary>\n </indexterm>\n\n <literal role=\"func\">FLOOR(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the natural logarithm of\n <replaceable>X</replaceable>; that is, the\n base-<emphasis>e</emphasis> logarithm of\n <replaceable>X</replaceable>. If\n <replaceable>X</replaceable> is less than or equal to 0.0E0,\n the function returns <literal>NULL</literal> and a warning\n <quote>Invalid argument for logarithm</quote> is reported."
}
],
"id": "LN",
"syntax": [
{
"para": "<indexterm>\n <primary>LN()</primary>\n </indexterm>\n\n <literal role=\"func\">LN(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If called with one parameter, this function returns the\n natural logarithm of <replaceable>X</replaceable>. If\n <replaceable>X</replaceable> is less than or equal to 0.0E0,\n the function returns <literal>NULL</literal> and a warning\n <quote>Invalid argument for logarithm</quote> is reported."
},
{
"para": "The inverse of this function (when called with a single\n argument) is the <literal role=\"func\">EXP()</literal>\n function."
}
],
"id": "LOG",
"syntax": [
{
"para": "<indexterm>\n <primary>LOG()</primary>\n </indexterm>\n\n <literal role=\"func\">LOG(<replaceable>X</replaceable>)</literal>,\n <literal role=\"func\">LOG(<replaceable>B</replaceable>,<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the base-2 logarithm of\n <literal><replaceable>X</replaceable></literal>. If\n <replaceable>X</replaceable> is less than or equal to 0.0E0,\n the function returns <literal>NULL</literal> and a warning\n <quote>Invalid argument for logarithm</quote> is reported."
}
],
"id": "LOG2",
"syntax": [
{
"para": "<indexterm>\n <primary>LOG2()</primary>\n </indexterm>\n\n <literal role=\"func\">LOG2(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the base-10 logarithm of\n <replaceable>X</replaceable>. If\n <replaceable>X</replaceable> is less than or equal to 0.0E0,\n the function returns <literal>NULL</literal> and a warning\n <quote>Invalid argument for logarithm</quote> is reported."
}
],
"id": "LOG10",
"syntax": [
{
"para": "<indexterm>\n <primary>LOG10()</primary>\n </indexterm>\n\n <literal role=\"func\">LOG10(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": [
"MOD"
],
"description": [
{
"para": "Modulo operation. Returns the remainder of\n <replaceable>N</replaceable> divided by\n <replaceable>M</replaceable>."
}
],
"id": "MOD",
"syntax": [
{
"para": "<indexterm>\n <primary>MOD()</primary>\n </indexterm>\n\n <indexterm>\n <primary>% (modulo)</primary>\n </indexterm>\n\n <indexterm>\n <primary>MOD (modulo)</primary>\n </indexterm>\n\n <indexterm>\n <primary>modulo (%)</primary>\n </indexterm>\n\n <indexterm>\n <primary>modulo (MOD)</primary>\n </indexterm>\n\n <literal role=\"func\">MOD(<replaceable>N</replaceable>,<replaceable>M</replaceable>)</literal>,\n <literal condition=\"mod\" role=\"op\"><replaceable>N</replaceable>\n % <replaceable>M</replaceable></literal>,\n <literal condition=\"mod\" role=\"op\"><replaceable>N</replaceable>\n MOD <replaceable>M</replaceable></literal>"
}
]
},
{
"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": "<indexterm>\n <primary>PI()</primary>\n </indexterm>\n\n <literal role=\"func\">PI()</literal>"
}
]
},
{
"keywords": [
"POW"
],
"description": [
{
"para": "Returns the value of <replaceable>X</replaceable> raised to\n the power of <replaceable>Y</replaceable>."
}
],
"id": "POW",
"syntax": [
{
"para": "<indexterm>\n <primary>POW()</primary>\n </indexterm>\n\n <literal role=\"func\">POW(<replaceable>X</replaceable>,<replaceable>Y</replaceable>)</literal>"
}
]
},
{
"keywords": [
"POWER"
],
"description": [
{
"para": "This is a synonym for <literal role=\"func\">POW()</literal>."
}
],
"id": "POWER",
"syntax": [
{
"para": "<indexterm>\n <primary>POWER()</primary>\n </indexterm>\n\n <literal role=\"func\">POWER(<replaceable>X</replaceable>,<replaceable>Y</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the argument <replaceable>X</replaceable>, converted\n from degrees to radians. (Note that pi radians equals 180\n degrees.)"
}
],
"id": "RADIANS",
"syntax": [
{
"para": "<indexterm>\n <primary>RADIANS()</primary>\n </indexterm>\n\n <literal role=\"func\">RADIANS(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a random floating-point value\n <replaceable>v</replaceable> in the range\n <literal>0</literal> <= <replaceable>v</replaceable> <\n <literal>1.0</literal>. To obtain a random integer\n <replaceable>R</replaceable> in the range\n <replaceable>i</replaceable> <=\n <replaceable>R</replaceable> <\n <replaceable>j</replaceable>, use the expression\n <literal role=\"func\">FLOOR(<replaceable>i</replaceable>\n plus RAND() * (<replaceable>j</replaceable></literal>\n minus <literal><replaceable>i</replaceable>))</literal>.\n For example, to obtain a random integer in the range the\n range <literal>7</literal> <=\n <replaceable>R</replaceable> < <literal>12</literal>, use\n the following statement:"
},
{
"programlisting": ">\nSELECT FLOOR(7 plus (RAND() * 5));"
},
{
"para": "If an integer argument <replaceable>N</replaceable> 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 <literal role=\"func\">RAND()</literal>."
}
]
]
},
{
"para": "One implication of this behavior is that for equal argument\n values,\n <literal role=\"func\">RAND(<replaceable>N</replaceable>)</literal>\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 <literal>RAND(3)</literal> is the same both places it\n occurs."
}
],
"id": "RAND",
"syntax": [
{
"para": "<indexterm>\n <primary>RAND()</primary>\n </indexterm>\n\n <literal role=\"func\">RAND([<replaceable>N</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Rounds the argument <replaceable>X</replaceable> to\n <replaceable>D</replaceable> decimal places. The rounding\n algorithm depends on the data type of\n <replaceable>X</replaceable>. <replaceable>D</replaceable>\n defaults to 0 if not specified. <replaceable>D</replaceable>\n can be negative to cause <replaceable>D</replaceable> digits\n left of the decimal point of the value\n <replaceable>X</replaceable> to become zero."
}
],
"id": "ROUND",
"syntax": [
{
"para": "<indexterm>\n <primary>ROUND()</primary>\n </indexterm>\n\n <literal role=\"func\">ROUND(<replaceable>X</replaceable>)</literal>,\n <literal role=\"func\">ROUND(<replaceable>X</replaceable>,<replaceable>D</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the sign of the argument as <literal>-1</literal>,\n <literal>0</literal>, or <literal>1</literal>, depending on\n whether <replaceable>X</replaceable> is negative, zero, or\n positive."
}
],
"id": "SIGN",
"syntax": [
{
"para": "<indexterm>\n <primary>SIGN()</primary>\n </indexterm>\n\n <literal role=\"func\">SIGN(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the sine of <replaceable>X</replaceable>, where\n <replaceable>X</replaceable> is given in radians."
}
],
"id": "SIN",
"syntax": [
{
"para": "<indexterm>\n <primary>SIN()</primary>\n </indexterm>\n\n <literal role=\"func\">SIN(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the square root of a nonnegative number\n <replaceable>X</replaceable>."
}
],
"id": "SQRT",
"syntax": [
{
"para": "<indexterm>\n <primary>SQRT()</primary>\n </indexterm>\n\n <literal role=\"func\">SQRT(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the tangent of <replaceable>X</replaceable>, where\n <replaceable>X</replaceable> is given in radians."
}
],
"id": "TAN",
"syntax": [
{
"para": "<indexterm>\n <primary>TAN()</primary>\n </indexterm>\n\n <literal role=\"func\">TAN(<replaceable>X</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the number <replaceable>X</replaceable>, truncated\n to <replaceable>D</replaceable> decimal places. If\n <replaceable>D</replaceable> is <literal>0</literal>, the\n result has no decimal point or fractional part.\n <replaceable>D</replaceable> can be negative to cause\n <replaceable>D</replaceable> digits left of the decimal\n point of the value <replaceable>X</replaceable> to become\n zero."
}
],
"id": "TRUNCATE",
"syntax": [
{
"para": "<indexterm>\n <primary>TRUNCATE()</primary>\n </indexterm>\n\n <literal role=\"func\">TRUNCATE(<replaceable>X</replaceable>,<replaceable>D</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "When invoked with the <literal>INTERVAL</literal> form of the\n second argument, <literal role=\"func\">ADDDATE()</literal> is a\n synonym for <literal role=\"func\">DATE_ADD()</literal>. The\n related function <literal role=\"func\">SUBDATE()</literal> is a\n synonym for <literal role=\"func\">DATE_SUB()</literal>. For\n information on the <literal>INTERVAL</literal>\n <replaceable>unit</replaceable> argument, see\n <xref linkend=\"temporal-intervals\" />."
},
{
"programlisting": ">\nmysql> <userinput>SELECT DATE_ADD('2008-01-02', INTERVAL 31 DAY);</userinput>\n -> '2008-02-02'\nmysql> <userinput>SELECT ADDDATE('2008-01-02', INTERVAL 31 DAY);</userinput>\n -> '2008-02-02'"
},
{
"para": "When invoked with the <replaceable>days</replaceable> form of\n the second argument, MySQL treats it as an integer number of\n days to be added to <replaceable>expr</replaceable>."
}
],
"id": "ADDDATE",
"syntax": [
{
"para": "<indexterm>\n <primary>ADDDATE()</primary>\n </indexterm>\n\n <literal role=\"func\">ADDDATE(<replaceable>date</replaceable>,INTERVAL\n <replaceable>expr</replaceable>\n <replaceable>unit</replaceable>)</literal>,\n <literal role=\"func\">ADDDATE(<replaceable>expr</replaceable>,<replaceable>days</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">ADDTIME()</literal> adds\n <replaceable>expr2</replaceable> to\n <replaceable>expr1</replaceable> and returns the result.\n <replaceable>expr1</replaceable> is a time or datetime\n expression, and <replaceable>expr2</replaceable> is a time\n expression."
}
],
"id": "ADDTIME",
"syntax": [
{
"para": "<indexterm>\n <primary>ADDTIME()</primary>\n </indexterm>\n\n <literal role=\"func\">ADDTIME(<replaceable>expr1</replaceable>,<replaceable>expr2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">CONVERT_TZ()</literal> converts a\n datetime value <replaceable>dt</replaceable> from the time\n zone given by <replaceable>from_tz</replaceable> to the time\n zone given by <replaceable>to_tz</replaceable> and returns the\n resulting value. Time zones are specified as described in\n <xref linkend=\"time-zone-support\" />. This function returns\n <literal>NULL</literal> if the arguments are invalid."
}
],
"id": "CONVERT_TZ",
"syntax": [
{
"para": "<indexterm>\n <primary>CONVERT_TZ()</primary>\n </indexterm>\n\n <literal role=\"func\">CONVERT_TZ(<replaceable>dt</replaceable>,<replaceable>from_tz</replaceable>,<replaceable>to_tz</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current date as a value in\n <replaceable>'YYYY-MM-DD'</replaceable> or\n <replaceable>YYYYMMDD</replaceable> format, depending on\n whether the function is used in a string or numeric context."
}
],
"id": "CURDATE",
"syntax": [
{
"para": "<indexterm>\n <primary>CURDATE()</primary>\n </indexterm>\n\n <literal role=\"func\">CURDATE()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">CURRENT_DATE</literal> and\n <literal role=\"func\">CURRENT_DATE()</literal> are synonyms for\n <literal role=\"func\">CURDATE()</literal>."
}
],
"id": "CURRENT_DATE",
"syntax": [
{
"para": "<indexterm>\n <primary>CURRENT_DATE</primary>\n </indexterm>\n\n <literal role=\"func\">CURRENT_DATE</literal>,\n <literal role=\"func\">CURRENT_DATE()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">CURRENT_TIME</literal> and\n <literal role=\"func\">CURRENT_TIME()</literal> are synonyms for\n <literal role=\"func\">CURTIME()</literal>."
}
],
"id": "CURRENT_TIME",
"syntax": [
{
"para": "<indexterm>\n <primary>CURRENT_TIME</primary>\n </indexterm>\n\n <literal role=\"func\">CURRENT_TIME</literal>,\n <literal role=\"func\">CURRENT_TIME([<replaceable>fsp</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">CURRENT_TIMESTAMP</literal> and\n <literal role=\"func\">CURRENT_TIMESTAMP()</literal> are\n synonyms for <literal role=\"func\">NOW()</literal>."
}
],
"id": "CURRENT_TIMESTAMP",
"syntax": [
{
"para": "<indexterm>\n <primary>CURRENT_TIMESTAMP</primary>\n </indexterm>\n\n <literal role=\"func\">CURRENT_TIMESTAMP</literal>,\n <literal role=\"func\">CURRENT_TIMESTAMP([<replaceable>fsp</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current time as a value in\n <replaceable>'hh:mm:ss'</replaceable> or\n <replaceable>hhmmss</replaceable> 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 <replaceable>fsp</replaceable> 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": "<indexterm>\n <primary>CURTIME()</primary>\n </indexterm>\n\n <literal role=\"func\">CURTIME([<replaceable>fsp</replaceable>])</literal>"
}
]
},
{
"keywords": [
"DATE"
],
"description": [
{
"para": "Extracts the date part of the date or datetime expression\n <replaceable>expr</replaceable>."
}
],
"id": "DATE function",
"syntax": [
{
"para": "<indexterm>\n <primary>DATE()</primary>\n </indexterm>\n\n <literal role=\"func\">DATE(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">DATEDIFF()</literal> returns\n <replaceable>expr1</replaceable> minus\n <replaceable>expr2</replaceable> expressed as a value in days\n from one date to the other. <replaceable>expr1</replaceable>\n and <replaceable>expr2</replaceable> 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": "<indexterm>\n <primary>DATEDIFF()</primary>\n </indexterm>\n\n <literal role=\"func\">DATEDIFF(<replaceable>expr1</replaceable>,<replaceable>expr2</replaceable>)</literal>"
}
]
},
{
"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 <replaceable>date</replaceable> argument specifies the\n starting date or datetime value.\n <replaceable>expr</replaceable> is an expression specifying\n the interval value to be added or subtracted from the starting\n date. <replaceable>expr</replaceable> is evaluated as a\n string; it may start with a <literal>-</literal> for negative\n intervals. <replaceable>unit</replaceable> is a keyword\n indicating the units in which the expression should be\n interpreted."
}
],
"id": "DATE_ADD",
"syntax": [
{
"para": "<indexterm>\n <primary>DATE_ADD()</primary>\n </indexterm>\n\n <indexterm>\n <primary>DATE_SUB()</primary>\n </indexterm>\n\n <literal role=\"func\">DATE_ADD(<replaceable>date</replaceable>,INTERVAL\n <replaceable>expr</replaceable>\n <replaceable>unit</replaceable>)</literal>,\n <literal role=\"func\">DATE_SUB(<replaceable>date</replaceable>,INTERVAL\n <replaceable>expr</replaceable>\n <replaceable>unit</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Formats the <replaceable>date</replaceable> value according to\n the <replaceable>format</replaceable> string."
}
],
"id": "DATE_FORMAT",
"syntax": [
{
"para": "<indexterm>\n <primary>DATE_FORMAT()</primary>\n </indexterm>\n\n <literal role=\"func\">DATE_FORMAT(<replaceable>date</replaceable>,<replaceable>format</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "See the description for\n <literal role=\"func\">DATE_ADD()</literal>."
}
],
"id": "DATE_SUB",
"syntax": [
{
"para": "<indexterm>\n <primary>DATE_SUB()</primary>\n </indexterm>\n\n <literal role=\"func\">DATE_SUB(<replaceable>date</replaceable>,INTERVAL\n <replaceable>expr</replaceable>\n <replaceable>unit</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">DAY()</literal> is a synonym for\n <literal role=\"func\">DAYOFMONTH()</literal>."
}
],
"id": "DAY",
"syntax": [
{
"para": "<indexterm>\n <primary>DAY()</primary>\n </indexterm>\n\n <literal role=\"func\">DAY(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the name of the weekday for\n <replaceable>date</replaceable>. The language used for the\n name is controlled by the value of the\n <literal role=\"sysvar\">lc_time_names</literal> system variable\n (<xref linkend=\"locale-support\" />)."
}
],
"id": "DAYNAME",
"syntax": [
{
"para": "<indexterm>\n <primary>DAYNAME()</primary>\n </indexterm>\n\n <literal role=\"func\">DAYNAME(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the day of the month for\n <replaceable>date</replaceable>, in the range\n <literal>1</literal> to <literal>31</literal>, or\n <literal>0</literal> for dates such as\n <literal>'0000-00-00'</literal> or\n <literal>'2008-00-00'</literal> that have a zero day part."
}
],
"id": "DAYOFMONTH",
"syntax": [
{
"para": "<indexterm>\n <primary>DAYOFMONTH()</primary>\n </indexterm>\n\n <literal role=\"func\">DAYOFMONTH(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the weekday index for <replaceable>date</replaceable>\n (<literal>1</literal> = Sunday, <literal>2</literal> = Monday,\n hellip, <literal>7</literal> = Saturday). These index values\n correspond to the ODBC standard."
}
],
"id": "DAYOFWEEK",
"syntax": [
{
"para": "<indexterm>\n <primary>DAYOFWEEK()</primary>\n </indexterm>\n\n <literal role=\"func\">DAYOFWEEK(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the day of the year for\n <replaceable>date</replaceable>, in the range\n <literal>1</literal> to <literal>366</literal>."
}
],
"id": "DAYOFYEAR",
"syntax": [
{
"para": "<indexterm>\n <primary>DAYOFYEAR()</primary>\n </indexterm>\n\n <literal role=\"func\">DAYOFYEAR(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "The <literal role=\"func\">EXTRACT()</literal> function uses the\n same kinds of <replaceable>unit</replaceable> specifiers as\n <literal role=\"func\">DATE_ADD()</literal> or\n <literal role=\"func\">DATE_SUB()</literal>, but extracts parts\n from the date rather than performing date arithmetic. For\n information on the <replaceable>unit</replaceable> argument,\n see <xref linkend=\"temporal-intervals\" />."
}
],
"id": "EXTRACT",
"syntax": [
{
"para": "<indexterm>\n <primary>EXTRACT()</primary>\n </indexterm>\n\n <literal role=\"func\">EXTRACT(<replaceable>unit</replaceable>\n FROM <replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given a day number <replaceable>N</replaceable>, returns a\n <literal role=\"type\">DATE</literal> value."
}
],
"id": "FROM_DAYS",
"syntax": [
{
"para": "<indexterm>\n <primary>FROM_DAYS()</primary>\n </indexterm>\n\n <literal role=\"func\">FROM_DAYS(<replaceable>N</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a representation of the\n <replaceable>unix_timestamp</replaceable> argument as a value\n in <replaceable>'YYYY-MM-DD hh:mm:ss'</replaceable> or\n <replaceable>YYYYMMDDhhmmss.uuuuuu</replaceable> format,\n depending on whether the function is used in a string or\n numeric context. <replaceable>unix_timestamp</replaceable> is\n an internal timestamp value representing seconds since\n <literal>'1970-01-01 00:00:00'</literal> UTC, such as produced\n by the <literal role=\"func\">UNIX_TIMESTAMP()</literal>\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 <xref linkend=\"time-zone-support\" />.) The\n <replaceable>format</replaceable> string, if given, is used to\n format the result the same way as described in the entry for\n the <literal role=\"func\">DATE_FORMAT()</literal> function."
}
],
"id": "FROM_UNIXTIME",
"syntax": [
{
"para": "<indexterm>\n <primary>FROM_UNIXTIME()</primary>\n </indexterm>\n\n <literal role=\"func\">FROM_UNIXTIME(<replaceable>unix_timestamp</replaceable>[,<replaceable>format</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a format string. This function is useful in\n combination with the\n <literal role=\"func\">DATE_FORMAT()</literal> and the\n <literal role=\"func\">STR_TO_DATE()</literal> functions."
}
],
"id": "GET_FORMAT",
"syntax": [
{
"para": "<indexterm>\n <primary>GET_FORMAT()</primary>\n </indexterm>\n\n <literal role=\"func\">GET_FORMAT({DATE|TIME|DATETIME},\n {'EUR'|'USA'|'JIS'|'ISO'|'INTERNAL'})</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the hour for <replaceable>time</replaceable>. The\n range of the return value is <literal>0</literal> to\n <literal>23</literal> for time-of-day values. However, the\n range of <literal role=\"type\">TIME</literal> values actually\n is much larger, so <literal>HOUR</literal> can return values\n greater than <literal>23</literal>."
}
],
"id": "HOUR",
"syntax": [
{
"para": "<indexterm>\n <primary>HOUR()</primary>\n </indexterm>\n\n <literal role=\"func\">HOUR(<replaceable>time</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal> if the argument is invalid."
}
],
"id": "LAST_DAY",
"syntax": [
{
"para": "<indexterm>\n <primary>LAST_DAY()</primary>\n </indexterm>\n\n <literal role=\"func\">LAST_DAY(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">LOCALTIME</literal> and\n <literal role=\"func\">LOCALTIME()</literal> are synonyms for\n <literal role=\"func\">NOW()</literal>."
}
],
"id": "LOCALTIME",
"syntax": [
{
"para": "<indexterm>\n <primary>LOCALTIME</primary>\n </indexterm>\n\n <literal role=\"func\">LOCALTIME</literal>,\n <literal role=\"func\">LOCALTIME([<replaceable>fsp</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">LOCALTIMESTAMP</literal> and\n <literal role=\"func\">LOCALTIMESTAMP()</literal> are synonyms\n for <literal role=\"func\">NOW()</literal>."
}
],
"id": "LOCALTIMESTAMP",
"syntax": [
{
"para": "<indexterm>\n <primary>LOCALTIMESTAMP</primary>\n </indexterm>\n\n <literal role=\"func\">LOCALTIMESTAMP</literal>,\n <literal role=\"func\">LOCALTIMESTAMP([<replaceable>fsp</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a date, given year and day-of-year values.\n <replaceable>dayofyear</replaceable> must be greater than 0 or\n the result is <literal>NULL</literal>."
}
],
"id": "MAKEDATE",
"syntax": [
{
"para": "<indexterm>\n <primary>MAKEDATE()</primary>\n </indexterm>\n\n <literal role=\"func\">MAKEDATE(<replaceable>year</replaceable>,<replaceable>dayofyear</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a time value calculated from the\n <replaceable>hour</replaceable>,\n <replaceable>minute</replaceable>, and\n <replaceable>second</replaceable> arguments."
},
{
"para": "The <replaceable>second</replaceable> argument can have a\n fractional part."
}
],
"id": "MAKETIME",
"syntax": [
{
"para": "<indexterm>\n <primary>MAKETIME()</primary>\n </indexterm>\n\n <literal role=\"func\">MAKETIME(<replaceable>hour</replaceable>,<replaceable>minute</replaceable>,<replaceable>second</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the microseconds from the time or datetime expression\n <replaceable>expr</replaceable> as a number in the range from\n <literal>0</literal> to <literal>999999</literal>."
}
],
"id": "MICROSECOND",
"syntax": [
{
"para": "<indexterm>\n <primary>MICROSECOND()</primary>\n </indexterm>\n\n <literal role=\"func\">MICROSECOND(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the minute for <replaceable>time</replaceable>, in the\n range <literal>0</literal> to <literal>59</literal>."
}
],
"id": "MINUTE",
"syntax": [
{
"para": "<indexterm>\n <primary>MINUTE()</primary>\n </indexterm>\n\n <literal role=\"func\">MINUTE(<replaceable>time</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the month for <replaceable>date</replaceable>, in the\n range <literal>1</literal> to <literal>12</literal> for\n January to December, or <literal>0</literal> for dates such as\n <literal>'0000-00-00'</literal> or\n <literal>'2008-00-00'</literal> that have a zero month part."
}
],
"id": "MONTH",
"syntax": [
{
"para": "<indexterm>\n <primary>MONTH()</primary>\n </indexterm>\n\n <literal role=\"func\">MONTH(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the full name of the month for\n <replaceable>date</replaceable>. The language used for the\n name is controlled by the value of the\n <literal role=\"sysvar\">lc_time_names</literal> system variable\n (<xref linkend=\"locale-support\" />)."
}
],
"id": "MONTHNAME",
"syntax": [
{
"para": "<indexterm>\n <primary>MONTHNAME()</primary>\n </indexterm>\n\n <literal role=\"func\">MONTHNAME(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current date and time as a value in\n <replaceable>'YYYY-MM-DD hh:mm:ss'</replaceable> or\n <replaceable>YYYYMMDDhhmmss</replaceable> 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 <replaceable>fsp</replaceable> 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": "<indexterm>\n <primary>NOW()</primary>\n </indexterm>\n\n <literal role=\"func\">NOW([<replaceable>fsp</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Adds <replaceable>N</replaceable> months to period\n <replaceable>P</replaceable> (in the format\n <replaceable>YYMM</replaceable> or\n <replaceable>YYYYMM</replaceable>). Returns a value in the\n format <replaceable>YYYYMM</replaceable>."
}
],
"id": "PERIOD_ADD",
"syntax": [
{
"para": "<indexterm>\n <primary>PERIOD_ADD()</primary>\n </indexterm>\n\n <literal role=\"func\">PERIOD_ADD(<replaceable>P</replaceable>,<replaceable>N</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the number of months between periods\n <replaceable>P1</replaceable> and\n <replaceable>P2</replaceable>. <replaceable>P1</replaceable>\n and <replaceable>P2</replaceable> should be in the format\n <replaceable>YYMM</replaceable> or\n <replaceable>YYYYMM</replaceable>. Note that the period\n arguments <replaceable>P1</replaceable> and\n <replaceable>P2</replaceable> are <emphasis>not</emphasis>\n date values."
}
],
"id": "PERIOD_DIFF",
"syntax": [
{
"para": "<indexterm>\n <primary>PERIOD_DIFF()</primary>\n </indexterm>\n\n <literal role=\"func\">PERIOD_DIFF(<replaceable>P1</replaceable>,<replaceable>P2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the quarter of the year for\n <replaceable>date</replaceable>, in the range\n <literal>1</literal> to <literal>4</literal>."
}
],
"id": "QUARTER",
"syntax": [
{
"para": "<indexterm>\n <primary>QUARTER()</primary>\n </indexterm>\n\n <literal role=\"func\">QUARTER(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the second for <replaceable>time</replaceable>, in the\n range <literal>0</literal> to <literal>59</literal>."
}
],
"id": "SECOND",
"syntax": [
{
"para": "<indexterm>\n <primary>SECOND()</primary>\n </indexterm>\n\n <literal role=\"func\">SECOND(<replaceable>time</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the <replaceable>seconds</replaceable> argument,\n converted to hours, minutes, and seconds, as a\n <literal role=\"type\">TIME</literal> value. The range of the\n result is constrained to that of the\n <literal role=\"type\">TIME</literal> data type. A warning\n occurs if the argument corresponds to a value outside that\n range."
}
],
"id": "SEC_TO_TIME",
"syntax": [
{
"para": "<indexterm>\n <primary>SEC_TO_TIME()</primary>\n </indexterm>\n\n <literal role=\"func\">SEC_TO_TIME(<replaceable>seconds</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is the inverse of the\n <literal role=\"func\">DATE_FORMAT()</literal> function. It\n takes a string <replaceable>str</replaceable> and a format\n string <replaceable>format</replaceable>.\n <literal role=\"func\">STR_TO_DATE()</literal> returns a\n <literal role=\"type\">DATETIME</literal> value if the format\n string contains both date and time parts, or a\n <literal role=\"type\">DATE</literal> or\n <literal role=\"type\">TIME</literal> value if the string\n contains only date or time parts. If the date, time, or\n datetime value extracted from <replaceable>str</replaceable>\n is illegal, <literal role=\"func\">STR_TO_DATE()</literal>\n returns <literal>NULL</literal> and produces a warning."
},
{
"para": "The server scans <replaceable>str</replaceable> attempting to\n match <replaceable>format</replaceable> to it. The format\n string can contain literal characters and format specifiers\n beginning with <literal>%</literal>. Literal characters in\n <replaceable>format</replaceable> must match literally in\n <replaceable>str</replaceable>. Format specifiers in\n <replaceable>format</replaceable> must match a date or time\n part in <replaceable>str</replaceable>. For the specifiers\n that can be used in <replaceable>format</replaceable>, see the\n <literal role=\"func\">DATE_FORMAT()</literal> function\n description."
},
{
"programlisting": ">\nmysql> <userinput>SELECT STR_TO_DATE('01,5,2013','%d,%m,%Y');</userinput>\n -> '2013-05-01'\nmysql> <userinput>SELECT STR_TO_DATE('May 1, 2013','%M %d,%Y');</userinput>\n -> '2013-05-01'"
},
{
"para": "Scanning starts at the beginning of\n <replaceable>str</replaceable> and fails if\n <replaceable>format</replaceable> is found not to match. Extra\n characters at the end of <replaceable>str</replaceable> are\n ignored."
},
{
"programlisting": ">\nmysql> <userinput>SELECT STR_TO_DATE('a09:30:17','a%h:%i:%s');</userinput>\n -> '09:30:17'\nmysql> <userinput>SELECT STR_TO_DATE('a09:30:17','%h:%i:%s');</userinput>\n -> NULL\nmysql> <userinput>SELECT STR_TO_DATE('09:30:17a','%h:%i:%s');</userinput>\n -> '09:30:17'"
},
{
"para": "Unspecified date or time parts have a value of 0, so\n incompletely specified values in\n <replaceable>str</replaceable> produce a result with some or\n all parts set to 0:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT STR_TO_DATE('abc','abc');</userinput>\n -> '0000-00-00'\nmysql> <userinput>SELECT STR_TO_DATE('9','%m');</userinput>\n -> '0000-09-00'\nmysql> <userinput>SELECT STR_TO_DATE('9','%s');</userinput>\n -> '00:00:09'"
}
],
"id": "STR_TO_DATE",
"syntax": [
{
"para": "<indexterm>\n <primary>STR_TO_DATE()</primary>\n </indexterm>\n\n <literal role=\"func\">STR_TO_DATE(<replaceable>str</replaceable>,<replaceable>format</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "When invoked with the <literal>INTERVAL</literal> form of the\n second argument, <literal role=\"func\">SUBDATE()</literal> is a\n synonym for <literal role=\"func\">DATE_SUB()</literal>. For\n information on the <literal>INTERVAL</literal>\n <replaceable>unit</replaceable> argument, see the discussion\n for <literal role=\"func\">DATE_ADD()</literal>."
},
{
"programlisting": ">\nmysql> <userinput>SELECT DATE_SUB('2008-01-02', INTERVAL 31 DAY);</userinput>\n -> '2007-12-02'\nmysql> <userinput>SELECT SUBDATE('2008-01-02', INTERVAL 31 DAY);</userinput>\n -> '2007-12-02'"
},
{
"para": "The second form enables the use of an integer value for\n <replaceable>days</replaceable>. In such cases, it is\n interpreted as the number of days to be subtracted from the\n date or datetime expression <replaceable>expr</replaceable>."
},
{
"programlisting": ">\nmysql> <userinput>SELECT SUBDATE('2008-01-02 12:00:00', 31);</userinput>\n -> '2007-12-02 12:00:00'"
}
],
"id": "SUBDATE",
"syntax": [
{
"para": "<indexterm>\n <primary>SUBDATE()</primary>\n </indexterm>\n\n <literal role=\"func\">SUBDATE(<replaceable>date</replaceable>,INTERVAL\n <replaceable>expr</replaceable>\n <replaceable>unit</replaceable>)</literal>,\n <literal role=\"func\">SUBDATE(<replaceable>expr</replaceable>,<replaceable>days</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">SUBTIME()</literal> returns\n <replaceable>expr1</replaceable> minus\n <replaceable>expr2</replaceable> expressed as a value in the\n same format as <replaceable>expr1</replaceable>.\n <replaceable>expr1</replaceable> is a time or datetime\n expression, and <replaceable>expr2</replaceable> is a time\n expression."
}
],
"id": "SUBTIME",
"syntax": [
{
"para": "<indexterm>\n <primary>SUBTIME()</primary>\n </indexterm>\n\n <literal role=\"func\">SUBTIME(<replaceable>expr1</replaceable>,<replaceable>expr2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current date and time as a value in\n <replaceable>'YYYY-MM-DD hh:mm:ss'</replaceable> or\n <replaceable>YYYYMMDDhhmmss</replaceable> format, depending on\n whether the function is used in a string or numeric context."
},
{
"para": "If the <replaceable>fsp</replaceable> 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": "<literal role=\"func\">SYSDATE()</literal> returns the time at\n which it executes. This differs from the behavior for\n <literal role=\"func\">NOW()</literal>, 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 <literal role=\"func\">NOW()</literal> returns the time at which\n the function or triggering statement began to execute.)"
},
{
"programlisting": ">\nmysql> <userinput>SELECT NOW(), SLEEP(2), NOW();</userinput>\n+---------------------+----------+---------------------+\n| NOW() | SLEEP(2) | NOW() |\n+---------------------+----------+---------------------+\n| 2006-04-12 13:47:36 | 0 | 2006-04-12 13:47:36 |\n+---------------------+----------+---------------------+\n\nmysql> <userinput>SELECT SYSDATE(), SLEEP(2), SYSDATE();</userinput>\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 <literal>SET TIMESTAMP</literal> statement\n affects the value returned by\n <literal role=\"func\">NOW()</literal> but not by\n <literal role=\"func\">SYSDATE()</literal>. This means that\n timestamp settings in the binary log have no effect on\n invocations of <literal role=\"func\">SYSDATE()</literal>."
},
{
"para": "Because <literal role=\"func\">SYSDATE()</literal> can return\n different values even within the same statement, and is not\n affected by <literal>SET TIMESTAMP</literal>, 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 role=\"mysqld\">--sysdate-is-now</option> option to\n cause <literal role=\"func\">SYSDATE()</literal> to be an alias\n for <literal role=\"func\">NOW()</literal>. This works if the\n option is used on both the master and the slave."
},
{
"para": "The nondeterministic nature of\n <literal role=\"func\">SYSDATE()</literal> also means that\n indexes cannot be used for evaluating expressions that refer\n to it."
}
],
"id": "SYSDATE",
"syntax": [
{
"para": "<indexterm>\n <primary>SYSDATE()</primary>\n </indexterm>\n\n <literal role=\"func\">SYSDATE([<replaceable>fsp</replaceable>])</literal>"
}
]
},
{
"keywords": [
"TIME"
],
"description": [
{
"para": "Extracts the time part of the time or datetime expression\n <replaceable>expr</replaceable> and returns it as a string."
}
],
"id": "TIME function",
"syntax": [
{
"para": "<indexterm>\n <primary>TIME()</primary>\n </indexterm>\n\n <literal role=\"func\">TIME(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">TIMEDIFF()</literal> returns\n <replaceable>expr1</replaceable> minus\n <replaceable>expr2</replaceable> expressed as a time value.\n <replaceable>expr1</replaceable> and\n <replaceable>expr2</replaceable> are time or date-and-time\n expressions, but both must be of the same type."
},
{
"para": "The result returned by <literal>TIMEDIFF()</literal> is\n limited to the range allowed for\n <literal role=\"type\">TIME</literal> values. Alternatively, you\n can use either of the functions\n <literal role=\"func\">TIMESTAMPDIFF()</literal> and\n <literal role=\"func\">UNIX_TIMESTAMP()</literal>, both of which\n return integers."
}
],
"id": "TIMEDIFF",
"syntax": [
{
"para": "<indexterm>\n <primary>TIMEDIFF()</primary>\n </indexterm>\n\n <literal role=\"func\">TIMEDIFF(<replaceable>expr1</replaceable>,<replaceable>expr2</replaceable>)</literal>"
}
]
},
{
"keywords": [
"TIMESTAMP"
],
"description": [
{
"para": "With a single argument, this function returns the date or\n datetime expression <replaceable>expr</replaceable> as a\n datetime value. With two arguments, it adds the time\n expression <replaceable>expr2</replaceable> to the date or\n datetime expression <replaceable>expr1</replaceable> and\n returns the result as a datetime value."
}
],
"id": "TIMESTAMP function",
"syntax": [
{
"para": "<indexterm>\n <primary>TIMESTAMP()</primary>\n </indexterm>\n\n <literal role=\"func\">TIMESTAMP(<replaceable>expr</replaceable>)</literal>,\n <literal role=\"func\">TIMESTAMP(<replaceable>expr1</replaceable>,<replaceable>expr2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Adds the integer expression\n <replaceable>interval</replaceable> to the date or datetime\n expression <replaceable>datetime_expr</replaceable>. The unit\n for <replaceable>interval</replaceable> is given by the\n <replaceable>unit</replaceable> argument, which should be one\n of the following values: <literal>MICROSECOND</literal>\n (microseconds), <literal>SECOND</literal>,\n <literal>MINUTE</literal>, <literal>HOUR</literal>,\n <literal>DAY</literal>, <literal>WEEK</literal>,\n <literal>MONTH</literal>, <literal>QUARTER</literal>, or\n <literal>YEAR</literal>."
},
{
"para": "The <replaceable>unit</replaceable> value may be specified\n using one of keywords as shown, or with a prefix of\n <literal>SQL_TSI_</literal>. For example,\n <literal>DAY</literal> and <literal>SQL_TSI_DAY</literal> both\n are legal."
}
],
"id": "TIMESTAMPADD",
"syntax": [
{
"para": "<indexterm>\n <primary>TIMESTAMPADD()</primary>\n </indexterm>\n\n <literal role=\"func\">TIMESTAMPADD(<replaceable>unit</replaceable>,<replaceable>interval</replaceable>,<replaceable>datetime_expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns <replaceable>datetime_expr2</replaceable> minus\n <replaceable>datetime_expr1</replaceable>, where\n <replaceable>datetime_expr1</replaceable> and\n <replaceable>datetime_expr2</replaceable> 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 <literal>'00:00:00'</literal> where necessary. The\n unit for the result (an integer) is given by the\n <replaceable>unit</replaceable> argument. The legal values for\n <replaceable>unit</replaceable> are the same as those listed\n in the description of the\n <literal role=\"func\">TIMESTAMPADD()</literal> function."
}
],
"id": "TIMESTAMPDIFF",
"syntax": [
{
"para": "<indexterm>\n <primary>TIMESTAMPDIFF()</primary>\n </indexterm>\n\n <literal role=\"func\">TIMESTAMPDIFF(<replaceable>unit</replaceable>,<replaceable>datetime_expr1</replaceable>,<replaceable>datetime_expr2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This is used like the\n <literal role=\"func\">DATE_FORMAT()</literal> function, but the\n <replaceable>format</replaceable> string may contain format\n specifiers only for hours, minutes, seconds, and microseconds.\n Other specifiers produce a <literal>NULL</literal> value or\n <literal>0</literal>."
}
],
"id": "TIME_FORMAT",
"syntax": [
{
"para": "<indexterm>\n <primary>TIME_FORMAT()</primary>\n </indexterm>\n\n <literal role=\"func\">TIME_FORMAT(<replaceable>time</replaceable>,<replaceable>format</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the <replaceable>time</replaceable> argument,\n converted to seconds."
}
],
"id": "TIME_TO_SEC",
"syntax": [
{
"para": "<indexterm>\n <primary>TIME_TO_SEC()</primary>\n </indexterm>\n\n <literal role=\"func\">TIME_TO_SEC(<replaceable>time</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given a date <replaceable>date</replaceable>, returns a day\n number (the number of days since year 0)."
}
],
"id": "TO_DAYS",
"syntax": [
{
"para": "<indexterm>\n <primary>TO_DAYS()</primary>\n </indexterm>\n\n <literal role=\"func\">TO_DAYS(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given a date or datetime <replaceable>expr</replaceable>,\n returns the number of seconds since the year 0. If\n <replaceable>expr</replaceable> is not a valid date or\n datetime value, returns <literal>NULL</literal>."
}
],
"id": "TO_SECONDS",
"syntax": [
{
"para": "<indexterm>\n <primary>TO_SECONDS()</primary>\n </indexterm>\n\n <literal role=\"func\">TO_SECONDS(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "If <literal role=\"func\">UNIX_TIMESTAMP()</literal> is called\n with no <replaceable>date</replaceable> argument, it returns a\n Unix timestamp representing seconds since <literal>'1970-01-01\n 00:00:00'</literal> UTC."
},
{
"para": "If <literal role=\"func\">UNIX_TIMESTAMP()</literal> is called\n with a <replaceable>date</replaceable> argument, it returns\n the value of the argument as seconds since\n <literal>'1970-01-01 00:00:00'</literal> UTC. The server\n interprets <replaceable>date</replaceable> 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 <xref linkend=\"time-zone-support\" />.) The\n <replaceable>date</replaceable> argument may be a\n <literal role=\"type\">DATE</literal>,\n <literal role=\"type\">DATETIME</literal>, or\n <literal role=\"type\">TIMESTAMP</literal> string, or a number\n in <replaceable>YYMMDD</replaceable>,\n <replaceable>YYMMDDhhmmss</replaceable>,\n <replaceable>YYYYMMDD</replaceable>, or\n <replaceable>YYYYMMDDhhmmss</replaceable> 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 <literal role=\"type\">DECIMAL</literal> if an argument is given\n that includes a fractional seconds part."
},
{
"para": "When the <replaceable>date</replaceable> argument is a\n <literal role=\"type\">TIMESTAMP</literal> column,\n <literal role=\"func\">UNIX_TIMESTAMP()</literal> returns the\n internal timestamp value directly, with no implicit\n <quote>string-to-Unix-timestamp</quote> conversion."
},
{
"para": "The valid range of argument values is the same as for the\n <literal role=\"type\">TIMESTAMP</literal> data type:\n <literal>'1970-01-01 00:00:01.000000'</literal> UTC to\n <literal>'2038-01-19 03:14:07.999999'</literal> UTC. If you\n pass an out-of-range date to\n <literal role=\"func\">UNIX_TIMESTAMP()</literal>, it returns\n <literal>0</literal>."
}
],
"id": "UNIX_TIMESTAMP",
"syntax": [
{
"para": "<indexterm>\n <primary>UNIX_TIMESTAMP()</primary>\n </indexterm>\n\n <literal role=\"func\">UNIX_TIMESTAMP([<replaceable>date</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current UTC date as a value in\n <replaceable>'YYYY-MM-DD'</replaceable> or\n <replaceable>YYYYMMDD</replaceable> format, depending on\n whether the function is used in a string or numeric context."
}
],
"id": "UTC_DATE",
"syntax": [
{
"para": "<indexterm>\n <primary>UTC_DATE()</primary>\n </indexterm>\n\n <literal role=\"func\">UTC_DATE</literal>,\n <literal role=\"func\">UTC_DATE()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current UTC time as a value in\n <replaceable>'hh:mm:ss'</replaceable> or\n <replaceable>hhmmss</replaceable> format, depending on whether\n the function is used in a string or numeric context."
},
{
"para": "If the <replaceable>fsp</replaceable> 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": "<indexterm>\n <primary>UTC_TIME()</primary>\n </indexterm>\n\n <literal role=\"func\">UTC_TIME</literal>,\n <literal role=\"func\">UTC_TIME([<replaceable>fsp</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current UTC date and time as a value in\n <replaceable>'YYYY-MM-DD hh:mm:ss'</replaceable> or\n <replaceable>YYYYMMDDhhmmss</replaceable> format, depending on\n whether the function is used in a string or numeric context."
},
{
"para": "If the <replaceable>fsp</replaceable> 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": "<indexterm>\n <primary>UTC_TIMESTAMP()</primary>\n </indexterm>\n\n <literal role=\"func\">UTC_TIMESTAMP</literal>,\n <literal role=\"func\">UTC_TIMESTAMP([<replaceable>fsp</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function returns the week number for\n <replaceable>date</replaceable>. The two-argument form of\n <literal role=\"func\">WEEK()</literal> 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 <literal>0</literal>\n to <literal>53</literal> or from <literal>1</literal> to\n <literal>53</literal>. If the <replaceable>mode</replaceable>\n argument is omitted, the value of the\n <literal role=\"sysvar\">default_week_format</literal> system\n variable is used. See\n <xref linkend=\"server-system-variables\" />."
}
],
"id": "WEEK",
"syntax": [
{
"para": "<indexterm>\n <primary>WEEK()</primary>\n </indexterm>\n\n <literal role=\"func\">WEEK(<replaceable>date</replaceable>[,<replaceable>mode</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the weekday index for <replaceable>date</replaceable>\n (<literal>0</literal> = Monday, <literal>1</literal> =\n Tuesday, hellip <literal>6</literal> = Sunday)."
}
],
"id": "WEEKDAY",
"syntax": [
{
"para": "<indexterm>\n <primary>WEEKDAY()</primary>\n </indexterm>\n\n <literal role=\"func\">WEEKDAY(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the calendar week of the date as a number in the range\n from <literal>1</literal> to <literal>53</literal>.\n <literal role=\"func\">WEEKOFYEAR()</literal> is a compatibility\n function that is equivalent to\n <literal role=\"func\">WEEK(<replaceable>date</replaceable>,3)</literal>."
}
],
"id": "WEEKOFYEAR",
"syntax": [
{
"para": "<indexterm>\n <primary>WEEKOFYEAR()</primary>\n </indexterm>\n\n <literal role=\"func\">WEEKOFYEAR(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the year for <replaceable>date</replaceable>, in the\n range <literal>1000</literal> to <literal>9999</literal>, or\n <literal>0</literal> for the <quote>zero</quote> date."
}
],
"id": "YEAR",
"syntax": [
{
"para": "<indexterm>\n <primary>YEAR()</primary>\n </indexterm>\n\n <literal role=\"func\">YEAR(<replaceable>date</replaceable>)</literal>"
}
]
},
{
"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 <replaceable>mode</replaceable> argument works exactly\n like the <replaceable>mode</replaceable> argument to\n <literal role=\"func\">WEEK()</literal>. For the single-argument\n syntax, a <replaceable>mode</replaceable> value of 0 is used.\n Unlike <literal role=\"func\">WEEK()</literal>, the value of\n <literal role=\"sysvar\">default_week_format</literal> does not\n influence <literal role=\"func\">YEARWEEK()</literal>."
}
],
"id": "YEARWEEK",
"syntax": [
{
"para": "<indexterm>\n <primary>YEARWEEK()</primary>\n </indexterm>\n\n <literal role=\"func\">YEARWEEK(<replaceable>date</replaceable>)</literal>,\n <literal role=\"func\">YEARWEEK(<replaceable>date</replaceable>,<replaceable>mode</replaceable>)</literal>"
}
]
},
{
"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 <literal>FULLTEXT</literal>."
}
],
[
{
"para": "Full-text indexes can be used only with\n <literal role=\"se\">InnoDB</literal> or\n <literal role=\"se\">MyISAM</literal> tables, and can be created\n only for <literal role=\"type\">CHAR</literal>,\n <literal role=\"type\">VARCHAR</literal>, or\n <literal role=\"type\">TEXT</literal> columns."
}
],
[
{
"para": "<literal>MySQL</literal> 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 <xref linkend=\"fulltext-search-ngram\" />, and\n <xref linkend=\"fulltext-search-mecab\" />."
}
],
[
{
"para": "A <literal>FULLTEXT</literal> index definition can be given in\n the <literal role=\"stmt\">CREATE TABLE</literal> statement when\n a table is created, or added later using\n <literal role=\"stmt\">ALTER TABLE</literal> or\n <literal role=\"stmt\">CREATE INDEX</literal>."
}
],
[
{
"para": "For large data sets, it is much faster to load your data into\n a table that has no <literal>FULLTEXT</literal> index and then\n create the index after that, than to load data into a table\n that has an existing <literal>FULLTEXT</literal> index."
}
]
]
},
{
"para": "Full-text searching is performed using\n <literal role=\"func\">MATCH() ... AGAINST</literal> syntax.\n <literal role=\"func\">MATCH()</literal> takes a comma-separated\n list that names the columns to be searched.\n <literal>AGAINST</literal> 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 <xref linkend=\"fulltext-stopwords\" />."
},
{
"para": "Full-text searches are natural language searches if the\n <literal>IN NATURAL LANGUAGE MODE</literal> modifier is given\n or if no modifier is given. For more information, see\n <xref linkend=\"fulltext-natural-language\" />."
}
],
[
{
"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 <literal>IN BOOLEAN MODE</literal> modifier\n specifies a boolean search. For more information, see\n <xref linkend=\"fulltext-boolean\" />."
}
],
[
{
"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 <literal>IN NATURAL LANGUAGE MODE WITH\n QUERY EXPANSION</literal> or <literal>WITH QUERY\n EXPANSION</literal> modifier specifies a query expansion\n search. For more information, see\n <xref linkend=\"fulltext-query-expansion\" />."
}
]
]
}
],
"id": "MATCH AGAINST",
"syntax": [
{
"para": ">\n <literal condition=\"match\" role=\"func\">MATCH\n (<replaceable>col1</replaceable>,<replaceable>col2</replaceable>,...)\n AGAINST (<replaceable>expr</replaceable>\n [<replaceable>search_modifier</replaceable>])</literal>"
},
{
"programlisting": ">\n<replaceable>search_modifier:</replaceable>\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 <literal role=\"op\">BINARY</literal> operator converts the\n expression to a binary string. A common use for\n <literal role=\"op\">BINARY</literal> 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 <literal role=\"op\">BINARY</literal> operator also causes\n trailing spaces in comparisons to be significant."
}
],
"id": "BINARY operator",
"syntax": [
{
"para": "<indexterm>\n <primary>BINARY</primary>\n </indexterm>\n\n <literal role=\"op\">BINARY</literal>\n <replaceable>expr</replaceable>"
}
]
},
{
"keywords": [
"ARRAY",
"CONVERT"
],
"description": [
{
"para": "The <literal role=\"func\">CAST()</literal> function takes an\n expression of any type and produces a result value of the\n specified type, similar to\n <literal role=\"func\">CONVERT()</literal>. For more\n information, see the description of\n <literal role=\"func\">CONVERT()</literal>."
},
{
"para": "In MySQL 8.0.17 and later, <literal role=\"se\">InnoDB</literal>\n allows the use of an additional <literal>ARRAY</literal>\n keyword for creating a multi-valued index on a\n <literal role=\"type\">JSON</literal> array as part of\n <literal role=\"stmt\">CREATE INDEX</literal>,\n <literal role=\"stmt\">CREATE TABLE</literal>, and\n <literal role=\"stmt\">ALTER TABLE</literal> statements.\n <literal>ARRAY</literal> 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 <literal>JSON</literal>.\n (<literal role=\"func\">CONVERT()</literal> does\n <emphasis>not</emphasis> support multi-valued index creation\n or the <literal>ARRAY</literal> keyword.) The\n <replaceable>type</replaceable> following the\n <literal>AS</literal> keyword may be any of the types\n supported by <literal>CAST()</literal>, with the exception of\n <literal>BINARY</literal> and <literal>JSON</literal>, which\n are not supported for this purpose.\n <xref linkend=\"create-index-multi-valued\" />, provides syntax\n information and examples, as well as other relevant\n information."
},
{
"para": "<literal role=\"func\">CAST()</literal> is standard SQL syntax."
}
],
"id": "CAST",
"syntax": [
{
"para": "<indexterm>\n <primary>CAST</primary>\n </indexterm>\n\n <literal role=\"func\">CAST(<replaceable>expr</replaceable> AS\n <replaceable>type</replaceable> [ARRAY])</literal>"
}
]
},
{
"keywords": [
"CONVERT",
"BINARY",
"CHAR",
"DATE",
"DATETIME",
"DECIMAL",
"INTEGER",
"JSON",
"SIGNED",
"TIME",
"UNSIGNED"
],
"description": [
{
"para": "The <literal role=\"func\">CONVERT()</literal> function takes an\n expression of any type and produces a result value of the\n specified type."
},
{
"para": "Discussion of\n <literal role=\"func\">CONVERT(<replaceable>expr</replaceable>,\n <replaceable>type</replaceable>)</literal> syntax here also\n applies to\n <literal role=\"func\">CAST(<replaceable>expr</replaceable> AS\n <replaceable>type</replaceable>)</literal>, which is\n equivalent."
},
{
"para": "<literal role=\"func\">CONVERT(... USING ...)</literal> is\n standard SQL syntax. The non-<literal>USING</literal> form of\n <literal role=\"func\">CONVERT()</literal> is ODBC syntax."
},
{
"para": "<literal role=\"func\">CONVERT()</literal> with\n <literal>USING</literal> 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 <literal>'abc'</literal> in the\n default character set to the corresponding string in the\n <literal>utf8</literal> character set:"
},
{
"programlisting": ">\nSELECT CONVERT('abc' USING utf8);"
},
{
"para": "<literal role=\"func\">CONVERT()</literal> without\n <literal>USING</literal> and\n <literal role=\"func\">CAST()</literal> take an expression and a\n <replaceable>type</replaceable> value specifying the result\n type. These <replaceable>type</replaceable> values are\n permitted:"
},
{
"itemizedlist": [
[
{
"para": "<literal>BINARY[(<replaceable>N</replaceable>)]</literal>"
},
{
"para": "Produces a string with the\n <literal role=\"type\">BINARY</literal> data type. See\n <xref linkend=\"binary-varbinary\" /> for a description of\n how this affects comparisons. If the optional length\n <replaceable>N</replaceable> is given,\n <literal>BINARY(<replaceable>N</replaceable>)</literal>\n causes the cast to use no more than\n <replaceable>N</replaceable> bytes of the argument. Values\n shorter than <replaceable>N</replaceable> bytes are padded\n with <literal>0x00</literal> bytes to a length of\n <replaceable>N</replaceable>."
}
],
[
{
"para": "<literal>CHAR[(<replaceable>N</replaceable>)]\n [<replaceable>charset_info</replaceable>]</literal>"
},
{
"para": "Produces a string with the\n <literal role=\"type\">CHAR</literal> data type. If the\n optional length <replaceable>N</replaceable> is given,\n <literal>CHAR(<replaceable>N</replaceable>)</literal>\n causes the cast to use no more than\n <replaceable>N</replaceable> characters of the argument.\n No padding occurs for values shorter than\n <replaceable>N</replaceable> characters."
},
{
"para": "With no <replaceable>charset_info</replaceable> clause,\n <literal>CHAR</literal> produces a string with the default\n character set. To specify the character set explicitly,\n these <replaceable>charset_info</replaceable> values are\n permitted:"
},
{
"itemizedlist": [
[
{
"para": "<literal>CHARACTER SET\n <replaceable>charset_name</replaceable></literal>:\n Produces a string with the given character set."
}
],
[
{
"para": "<literal>ASCII</literal>: Shorthand for\n <literal>CHARACTER SET latin1</literal>."
}
],
[
{
"para": "<literal>UNICODE</literal>: Shorthand for\n <literal>CHARACTER SET ucs2</literal>."
}
]
]
},
{
"para": "In all cases, the string has the default collation for the\n character set."
}
],
[
{
"para": "<literal>DATE</literal>"
},
{
"para": "Produces a <literal role=\"type\">DATE</literal> value."
}
],
[
{
"para": "<literal>DATETIME</literal>"
},
{
"para": "Produces a <literal role=\"type\">DATETIME</literal> value."
}
],
[
{
"para": "<literal>DECIMAL[(<replaceable>M</replaceable>[,<replaceable>D</replaceable>])]</literal>"
},
{
"para": "Produces a <literal role=\"type\">DECIMAL</literal> value.\n If the optional <replaceable>M</replaceable> and\n <replaceable>D</replaceable> 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": "<literal>DOUBLE</literal>"
},
{
"para": "Produces a <literal role=\"type\">DOUBLE</literal> result.\n Added in MySQL 8.0.17."
}
],
[
{
"para": "FLOAT[(<replaceable>P</replaceable>)]"
},
{
"para": "If the precision <replaceable>P</replaceable> is not\n specified, produces a result of type\n <literal role=\"type\">FLOAT</literal>. If\n <replaceable>P</replaceable> is provided and 0 <= <\n <replaceable>P</replaceable> <= 24, the result is of\n type <literal>FLOAT</literal>. If 25 <=\n <replaceable>P</replaceable> <= 53, the result is of\n type <literal role=\"type\">DOUBLE</literal>. If\n <replaceable>P</replaceable> < 0 or\n <replaceable>P</replaceable> > 53, an error is\n returned. Added in MySQL 8.0.17."
}
],
[
{
"para": "<literal>JSON</literal>"
},
{
"para": "Produces a <literal role=\"type\">JSON</literal> value. For\n details on the rules for conversion of values between\n <literal role=\"type\">JSON</literal> and other types, see\n <xref linkend=\"json-comparison\" />."
}
],
[
{
"para": "<literal>NCHAR[(<replaceable>N</replaceable>)]</literal>"
},
{
"para": "Like <literal>CHAR</literal>, but produces a string with\n the national character set. See\n <xref linkend=\"charset-national\" />."
},
{
"para": "Unlike <literal>CHAR</literal>, <literal>NCHAR</literal>\n does not permit trailing character set information to be\n specified."
}
],
[
{
"para": "<literal>REAL</literal>"
},
{
"para": "Produces a result of type\n <literal role=\"type\">REAL</literal>. This is actually\n <literal>FLOAT</literal> if\n <literal role=\"sql_mode\">REAL_AS_FLOAT</literal> SQL mode\n is enabled; otherwise the result is of type\n <literal>DOUBLE</literal>."
}
],
[
{
"para": "<literal>SIGNED [INTEGER]</literal>"
},
{
"para": "Produces a signed integer value."
}
],
[
{
"para": "<literal>TIME</literal>"
},
{
"para": "Produces a <literal role=\"type\">TIME</literal> value."
}
],
[
{
"para": "<literal>UNSIGNED [INTEGER]</literal>"
},
{
"para": "Produces an unsigned integer value."
}
]
]
}
],
"id": "CONVERT",
"syntax": [
{
"para": "<indexterm>\n <primary>CONVERT</primary>\n </indexterm>\n\n <literal role=\"func\">CONVERT(<replaceable>expr</replaceable>,<replaceable>type</replaceable>)</literal>,\n <literal role=\"func\">CONVERT(<replaceable>expr</replaceable>\n USING <replaceable>transcoding_name</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">ExtractValue()</literal> takes two string\n arguments, a fragment of XML markup\n <replaceable>xml_frag</replaceable> and an XPath expression\n <replaceable>xpath_expr</replaceable> (also known as a\n <emphasis role=\"firstterm\">locator</emphasis>); it returns the\n text (<literal>CDATA</literal>) 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 <replaceable>xpath_expr</replaceable> after\n appending <literal>/text()</literal>. In other words,\n <literal role=\"func\">ExtractValue('<a><b>Sakila</b></a>',\n '/a/b')</literal> and\n <literal role=\"func\">ExtractValue('<a><b>Sakila</b></a>',\n '/a/b/text()')</literal> 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 <literal>/text()</literal>)mdashfor\n whatever reason, as long as\n <replaceable>xpath_expr</replaceable> is valid, and\n <replaceable>xml_frag</replaceable> 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 <replaceable>xml_frag</replaceable> 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 <literal>count()</literal> function. For example, both of\n these statements return an empty string, as shown here:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT ExtractValue('<a><b/></a>', '/a/b');</userinput>\n+-------------------------------------+\n| ExtractValue('<a><b/></a>', '/a/b') |\n+-------------------------------------+\n| |\n+-------------------------------------+\n1 row in set (0.00 sec)\n\nmysql> <userinput>SELECT ExtractValue('<a><c/></a>', '/a/b');</userinput>\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> <userinput>SELECT ExtractValue('<a><b/></a>', 'count(/a/b)');</userinput>\n+-------------------------------------+\n| ExtractValue('<a><b/></a>', 'count(/a/b)') |\n+-------------------------------------+\n| 1 |\n+-------------------------------------+\n1 row in set (0.00 sec)\n\nmysql> <userinput>SELECT ExtractValue('<a><c/></a>', 'count(/a/b)');</userinput>\n+-------------------------------------+\n| ExtractValue('<a><c/></a>', 'count(/a/b)') |\n+-------------------------------------+\n| 0 |\n+-------------------------------------+\n1 row in set (0.01 sec)"
}
],
"id": "ExtractValue",
"syntax": [
{
"para": "<indexterm>\n <primary>ExtractValue()</primary>\n </indexterm>\n\n <literal role=\"func\">ExtractValue(<replaceable>xml_frag</replaceable>,\n <replaceable>xpath_expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function replaces a single portion of a given fragment of\n XML markup <replaceable>xml_target</replaceable> with a new\n XML fragment <replaceable>new_xml</replaceable>, and then\n returns the changed XML. The portion of\n <replaceable>xml_target</replaceable> that is replaced matches\n an XPath expression <replaceable>xpath_expr</replaceable>\n supplied by the user."
},
{
"para": "If no expression matching\n <replaceable>xpath_expr</replaceable> is found, or if multiple\n matches are found, the function returns the original\n <replaceable>xml_target</replaceable> XML fragment. All three\n arguments should be strings."
}
],
"id": "UpdateXML",
"syntax": [
{
"para": "<indexterm>\n <primary>UpdateXML()</primary>\n </indexterm>\n\n <literal role=\"func\">UpdateXML(<replaceable>xml_target</replaceable>,\n <replaceable>xpath_expr</replaceable>,\n <replaceable>new_xml</replaceable>)</literal>"
}
]
},
{
"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 <literal role=\"func\">AES_ENCRYPT()</literal>."
},
{
"para": "The optional initialization vector argument,\n <replaceable>init_vector</replaceable>. Statements that use\n <literal role=\"func\">AES_DECRYPT()</literal> are unsafe for\n statement-based replication."
}
],
"id": "AES_DECRYPT",
"syntax": [
{
"para": "<indexterm>\n <primary>AES_DECRYPT()</primary>\n </indexterm>\n\n <literal role=\"func\">AES_DECRYPT(<replaceable>crypt_str</replaceable>,<replaceable>key_str</replaceable>[,<replaceable>init_vector</replaceable>])</literal>"
}
]
},
{
"keywords": [
"AES_ENCRYPT"
],
"description": [
{
"para": "<literal role=\"func\">AES_ENCRYPT()</literal> and\n <literal role=\"func\">AES_DECRYPT()</literal> implement\n encryption and decryption of data using the official AES\n (Advanced Encryption Standard) algorithm, previously known as\n <quote>Rijndael.</quote> 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": "<literal role=\"func\">AES_ENCRYPT()</literal> encrypts the\n string <replaceable>str</replaceable> using the key string\n <replaceable>key_str</replaceable> and returns a binary string\n containing the encrypted output.\n <literal role=\"func\">AES_DECRYPT()</literal> decrypts the\n encrypted string <replaceable>crypt_str</replaceable> using\n the key string <replaceable>key_str</replaceable> and returns\n the original plaintext string. If either function argument is\n <literal>NULL</literal>, the function returns\n <literal>NULL</literal>."
},
{
"para": "The <replaceable>str</replaceable> and\n <replaceable>crypt_str</replaceable> arguments can be any\n length, and padding is automatically added to\n <replaceable>str</replaceable> 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 <literal role=\"func\">AES_DECRYPT()</literal> function. The\n length of <replaceable>crypt_str</replaceable> can be\n calculated using this formula:"
},
{
"programlisting": ">\n16 * (trunc(<replaceable>string_length</replaceable> / 16) + 1)"
},
{
"para": "For a key length of 128 bits, the most secure way to pass a\n key to the <replaceable>key_str</replaceable> 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 <replaceable>crypt_str</replaceable>, 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 <literal role=\"func\">AES_DECRYPT()</literal> detects\n invalid data or incorrect padding, it returns\n <literal>NULL</literal>. However, it is possible for\n <literal role=\"func\">AES_DECRYPT()</literal> to return a\n non-<literal>NULL</literal> value (possibly garbage) if the\n input data or the key is invalid."
},
{
"para": "<literal role=\"func\">AES_ENCRYPT()</literal> and\n <literal role=\"func\">AES_DECRYPT()</literal> permit control of\n the block encryption mode and take an optional\n <replaceable>init_vector</replaceable> initialization vector\n argument:"
},
{
"itemizedlist": [
[
{
"para": "The <literal role=\"sysvar\">block_encryption_mode</literal>\n system variable controls the mode for block-based\n encryption algorithms. Its default value is\n <literal>aes-128-ecb</literal>, 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 <xref linkend=\"server-system-variables\" />."
}
],
[
{
"para": "The optional <replaceable>init_vector</replaceable>\n argument provides an initialization vector for block\n encryption modes that require it."
}
]
]
},
{
"para": "For modes that require the optional\n <replaceable>init_vector</replaceable> argument, it must be 16\n bytes or longer (bytes in excess of 16 are ignored). An error\n occurs if <replaceable>init_vector</replaceable> is missing."
},
{
"para": "For modes that do not require\n <replaceable>init_vector</replaceable>, 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 <literal role=\"func\">RANDOM_BYTES(16)</literal>. 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": "<indexterm>\n <primary>AES_ENCRYPT()</primary>\n </indexterm>\n\n <literal role=\"func\">AES_ENCRYPT(<replaceable>str</replaceable>,<replaceable>key_str</replaceable>[,<replaceable>init_vector</replaceable>])</literal>"
}
]
},
{
"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 <literal>zlib</literal>.\n Otherwise, the return value is always <literal>NULL</literal>.\n The compressed string can be uncompressed with\n <literal role=\"func\">UNCOMPRESS()</literal>."
}
],
"id": "COMPRESS",
"syntax": [
{
"para": "<indexterm>\n <primary>COMPRESS()</primary>\n </indexterm>\n\n <literal role=\"func\">COMPRESS(<replaceable>string_to_compress</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3."
},
{
"para": "Consider using <literal role=\"func\">AES_ENCRYPT()</literal>\n and <literal role=\"func\">AES_DECRYPT()</literal> instead."
}
],
"id": "DECODE",
"syntax": [
{
"para": "<indexterm>\n <primary>DECODE()</primary>\n </indexterm>\n\n <literal role=\"func\">DECODE(<replaceable>crypt_str</replaceable>,<replaceable>pass_str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3."
},
{
"para": "Consider using <literal role=\"func\">AES_ENCRYPT()</literal>\n and <literal role=\"func\">AES_DECRYPT()</literal> instead."
}
],
"id": "DES_DECRYPT",
"syntax": [
{
"para": "<indexterm>\n <primary>DES_DECRYPT()</primary>\n </indexterm>\n\n <literal role=\"func\">DES_DECRYPT(<replaceable>crypt_str</replaceable>[,<replaceable>key_str</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3."
},
{
"para": "Consider using <literal role=\"func\">AES_ENCRYPT()</literal>\n and <literal role=\"func\">AES_DECRYPT()</literal> instead."
}
],
"id": "DES_ENCRYPT",
"syntax": [
{
"para": "<indexterm>\n <primary>DES_ENCRYPT()</primary>\n </indexterm>\n\n <literal role=\"func\">DES_ENCRYPT(<replaceable>str</replaceable>[,{<replaceable>key_num</replaceable>|<replaceable>key_str</replaceable>}])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3."
},
{
"para": "Consider using <literal role=\"func\">AES_ENCRYPT()</literal>\n and <literal role=\"func\">AES_DECRYPT()</literal> instead."
}
],
"id": "ENCODE",
"syntax": [
{
"para": "<indexterm>\n <primary>ENCODE()</primary>\n </indexterm>\n\n <literal role=\"func\">ENCODE(<replaceable>str</replaceable>,<replaceable>pass_str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.3. For one-way hashing,\n consider using <literal role=\"func\">SHA2()</literal> instead."
}
],
"id": "ENCRYPT",
"syntax": [
{
"para": "<indexterm>\n <primary>ENCRYPT()</primary>\n </indexterm>\n\n <literal role=\"func\">ENCRYPT(<replaceable>str</replaceable>[,<replaceable>salt</replaceable>])</literal>"
}
]
},
{
"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 <literal>NULL</literal> if the argument was\n <literal>NULL</literal>. 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 <function role=\"func\">MD5()</function> returns\n <literal>NULL</literal>. See <xref linkend=\"fips-mode\" />."
}
],
"id": "MD5",
"syntax": [
{
"para": "<indexterm>\n <primary>MD5()</primary>\n </indexterm>\n\n <literal role=\"func\">MD5(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function was removed in MySQL 8.0.11."
}
],
"id": "PASSWORD",
"syntax": [
{
"para": "<indexterm>\n <primary>PASSWORD()</primary>\n </indexterm>\n\n <literal role=\"func\">PASSWORD(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": [
"RANDOM_BYTES"
],
"description": [
{
"para": "This function returns a binary string of\n <replaceable>len</replaceable> random bytes generated using\n the random number generator of the SSL library. Permitted\n values of <replaceable>len</replaceable> range from 1 to 1024.\n For values outside that range,\n <literal role=\"func\">RANDOM_BYTES()</literal> generates a\n warning and returns <literal>NULL</literal>."
},
{
"para": "<literal role=\"func\">RANDOM_BYTES()</literal> can be used to\n provide the initialization vector for the\n <literal role=\"func\">AES_DECRYPT()</literal> and\n <literal role=\"func\">AES_ENCRYPT()</literal> functions. For\n use in that context, <replaceable>len</replaceable> must be at\n least 16. Larger values are permitted, but bytes in excess of\n 16 are ignored."
},
{
"para": "<literal role=\"func\">RANDOM_BYTES()</literal> 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": "<indexterm>\n <primary>RANDOM_BYTES()</primary>\n </indexterm>\n\n <literal role=\"func\">RANDOM_BYTES(<replaceable>len</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal> if the argument was\n <literal>NULL</literal>. 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 <literal condition=\"sha1\" role=\"func\">SHA()</literal> is\n synonymous with <literal role=\"func\">SHA1()</literal>."
},
{
"para": "The return value is a string in the connection character set."
}
],
"id": "SHA1",
"syntax": [
{
"para": "<indexterm>\n <primary>SHA1()</primary>\n </indexterm>\n\n <indexterm>\n <primary>SHA()</primary>\n </indexterm>\n\n <literal role=\"func\">SHA1(<replaceable>str</replaceable>)</literal>,\n <literal condition=\"sha1\" role=\"func\">SHA(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal> or the hash length\n is not one of the permitted values, the return value is\n <literal>NULL</literal>. 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": "<indexterm>\n <primary>SHA2()</primary>\n </indexterm>\n\n <literal role=\"func\">SHA2(<replaceable>str</replaceable>,\n <replaceable>hash_length</replaceable>)</literal>"
}
]
},
{
"keywords": [
"STATEMENT_DIGEST"
],
"description": [
{
"para": "<literal role=\"func\">STATEMENT_DIGEST(<replaceable>statement</replaceable>)</literal>"
},
{
"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 <literal>NULL</literal> if the argument is\n <literal>NULL</literal>. The related\n <literal role=\"func\">STATEMENT_DIGEST_TEXT()</literal>\n function returns the normalized statement digest. For\n information about statement digesting, see\n <xref linkend=\"performance-schema-statement-digests\" />."
},
{
"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 <literal role=\"sysvar\">max_digest_length</literal> 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": "<literal role=\"func\">STATEMENT_DIGEST_TEXT(<replaceable>statement</replaceable>)</literal>"
},
{
"para": "Given an SQL statement as a string, returns the normalized\n statement digest as a string in the connection character set,\n or <literal>NULL</literal> if the argument is\n <literal>NULL</literal>. For additional discussion and\n examples, see the description of the related\n <literal role=\"func\">STATEMENT_DIGEST()</literal> function."
}
],
"id": "STATEMENT_DIGEST_TEXT",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "Uncompresses a string compressed by the\n <literal role=\"func\">COMPRESS()</literal> function. If the\n argument is not a compressed value, the result is\n <literal>NULL</literal>. This function requires MySQL to have\n been compiled with a compression library such as\n <literal>zlib</literal>. Otherwise, the return value is always\n <literal>NULL</literal>."
}
],
"id": "UNCOMPRESS",
"syntax": [
{
"para": "<indexterm>\n <primary>UNCOMPRESS()</primary>\n </indexterm>\n\n <literal role=\"func\">UNCOMPRESS(<replaceable>string_to_uncompress</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the length that the compressed string had before being\n compressed."
}
],
"id": "UNCOMPRESSED_LENGTH",
"syntax": [
{
"para": "<indexterm>\n <primary>UNCOMPRESSED_LENGTH()</primary>\n </indexterm>\n\n <literal role=\"func\">UNCOMPRESSED_LENGTH(<replaceable>compressed_string</replaceable>)</literal>"
}
]
},
{
"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": "<indexterm>\n <primary>DAY()</primary>\n </indexterm>\n\n <literal role=\"func\">VALIDATE_PASSWORD_STRENGTH(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Tries to obtain a lock with a name given by the string\n <replaceable>str</replaceable>, using a timeout of\n <replaceable>timeout</replaceable> seconds. A negative\n <replaceable>timeout</replaceable> 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 <literal>1</literal> if the lock was obtained\n successfully, <literal>0</literal> if the attempt timed out\n (for example, because another client has previously locked the\n name), or <literal>NULL</literal> if an error occurred (such\n as running out of memory or the thread was killed with\n <command>mysqladmin kill</command>)."
},
{
"para": "A lock obtained with <literal role=\"func\">GET_LOCK()</literal>\n is released explicitly by executing\n <literal role=\"func\">RELEASE_LOCK()</literal> or implicitly\n when your session terminates (either normally or abnormally).\n Locks obtained with <literal role=\"func\">GET_LOCK()</literal>\n are not released when transactions commit or roll back."
},
{
"para": "<literal role=\"func\">GET_LOCK()</literal> is implemented using\n the metadata locking (MDL) subsystem. Multiple simultaneous\n locks can be acquired and\n <literal role=\"func\">GET_LOCK()</literal> 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 <literal role=\"func\">GET_LOCK()</literal> acquires\n a second lock and both\n <literal role=\"func\">RELEASE_LOCK()</literal> 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 <literal role=\"func\">GET_LOCK()</literal> appear in the\n Performance Schema <literal role=\"ps\">metadata_locks</literal>\n table. The <literal>OBJECT_TYPE</literal> column says\n <literal>USER LEVEL LOCK</literal> and the\n <literal>OBJECT_NAME</literal> column indicates the lock name.\n In the case that multiple locks are acquired for the\n <emphasis>same</emphasis> name, only the first lock for the\n name registers a row in the\n <literal role=\"ps\">metadata_locks</literal> table. Subsequent\n locks for the name increment a counter in the lock but do not\n acquire additional metadata locks. The\n <literal role=\"ps\">metadata_locks</literal> 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 <literal role=\"error\">ER_USER_LOCK_DEADLOCK</literal> 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": "<literal role=\"func\">GET_LOCK()</literal> 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, <literal role=\"func\">GET_LOCK()</literal>\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 <replaceable>db_name.str</replaceable> or\n <replaceable>app_name.str</replaceable>."
}
],
"id": "GET_LOCK",
"syntax": [
{
"para": "<indexterm>\n <primary>timeout</primary>\n </indexterm>\n\n <indexterm>\n <primary>GET_LOCK()</primary>\n </indexterm>\n\n <literal role=\"func\">GET_LOCK(<replaceable>str</replaceable>,<replaceable>timeout</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Checks whether the lock named <replaceable>str</replaceable>\n is free to use (that is, not locked). Returns\n <literal>1</literal> if the lock is free (no one is using the\n lock), <literal>0</literal> if the lock is in use, and\n <literal>NULL</literal> if an error occurs (such as an\n incorrect argument)."
}
],
"id": "IS_FREE_LOCK",
"syntax": [
{
"para": "<indexterm>\n <primary>IS_FREE_LOCK()</primary>\n </indexterm>\n\n <literal role=\"func\">IS_FREE_LOCK(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Checks whether the lock named <replaceable>str</replaceable>\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 <literal>NULL</literal>."
}
],
"id": "IS_USED_LOCK",
"syntax": [
{
"para": "<indexterm>\n <primary>IS_USED_LOCK()</primary>\n </indexterm>\n\n <literal role=\"func\">IS_USED_LOCK(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"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": "<indexterm>\n <primary>RELEASE_ALL_LOCKS()</primary>\n </indexterm>\n\n <literal role=\"func\">RELEASE_ALL_LOCKS()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Releases the lock named by the string\n <replaceable>str</replaceable> that was obtained with\n <literal role=\"func\">GET_LOCK()</literal>. Returns\n <literal>1</literal> if the lock was released,\n <literal>0</literal> if the lock was not established by this\n thread (in which case the lock is not released), and\n <literal>NULL</literal> if the named lock did not exist. The\n lock does not exist if it was never obtained by a call to\n <literal role=\"func\">GET_LOCK()</literal> or if it has\n previously been released."
},
{
"para": "The <literal role=\"stmt\">DO</literal> statement is convenient\n to use with <literal role=\"func\">RELEASE_LOCK()</literal>. See\n <xref linkend=\"do\" />."
}
],
"id": "RELEASE_LOCK",
"syntax": [
{
"para": "<indexterm>\n <primary>RELEASE_LOCK()</primary>\n </indexterm>\n\n <literal role=\"func\">RELEASE_LOCK(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "The <literal role=\"func\">BENCHMARK()</literal> function\n executes the expression <replaceable>expr</replaceable>\n repeatedly <replaceable>count</replaceable> times. It may be\n used to time how quickly MySQL processes the expression. The\n result value is <literal>0</literal>, or\n <literal>NULL</literal> for inappropriate arguments such as a\n <literal>NULL</literal> or negative repeat count."
},
{
"para": "The intended use is from within the <command>mysql</command>\n client, which reports query execution times:"
}
],
"id": "BENCHMARK",
"syntax": [
{
"para": "<indexterm>\n <primary>BENCHMARK()</primary>\n </indexterm>\n\n <literal role=\"func\">BENCHMARK(<replaceable>count</replaceable>,<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the character set of the string argument."
}
],
"id": "CHARSET",
"syntax": [
{
"para": "<indexterm>\n <primary>CHARSET()</primary>\n </indexterm>\n\n <literal role=\"func\">CHARSET(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the collation coercibility value of the string\n argument."
}
],
"id": "COERCIBILITY",
"syntax": [
{
"para": "<indexterm>\n <primary>COERCIBILITY()</primary>\n </indexterm>\n\n <literal role=\"func\">COERCIBILITY(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the collation of the string argument."
}
],
"id": "COLLATION",
"syntax": [
{
"para": "<indexterm>\n <primary>COLLATION()</primary>\n </indexterm>\n\n <literal role=\"func\">COLLATION(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"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 <literal role=\"func\">CONNECTION_ID()</literal> is the same\n type of value as displayed in the <literal>ID</literal> column\n of the\n <literal role=\"is\">INFORMATION_SCHEMA.PROCESSLIST</literal>\n table, the <literal>Id</literal> column of\n <literal role=\"stmt\">SHOW PROCESSLIST</literal> output, and\n the <literal>PROCESSLIST_ID</literal> column of the\n Performance Schema <literal role=\"ps\">threads</literal> table."
}
],
"id": "CONNECTION_ID",
"syntax": [
{
"para": "<indexterm>\n <primary>CONNECTION_ID()</primary>\n </indexterm>\n\n <literal role=\"func\">CONNECTION_ID()</literal>"
}
]
},
{
"keywords": [
"CURRENT_ROLE"
],
"description": [
{
"para": "<indexterm>\n <primary>CURRENT_ROLE()</primary>\n </indexterm>\n\n <literal role=\"func\">CURRENT_ROLE()</literal>"
},
{
"para": "Returns a <literal>utf8</literal> string containing the\n current active roles for the current session, separated by\n commas, or <literal>NONE</literal> if there are none. The\n value reflects the setting of the\n <literal role=\"sysvar\">sql_quote_show_create</literal> 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 <literal>utf8</literal>\n character set."
},
{
"para": "The value of <literal role=\"func\">CURRENT_USER()</literal> can\n differ from the value of\n <literal role=\"func\">USER()</literal>."
}
],
"id": "CURRENT_USER",
"syntax": [
{
"para": "<indexterm>\n <primary>CURRENT_USER()</primary>\n </indexterm>\n\n <literal role=\"func\">CURRENT_USER</literal>,\n <literal role=\"func\">CURRENT_USER()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the default (current) database name as a string in the\n <literal>utf8</literal> character set. If there is no default\n database, <literal role=\"func\">DATABASE()</literal> returns\n <literal>NULL</literal>. 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": "<indexterm>\n <primary>DATABASE()</primary>\n </indexterm>\n\n <literal role=\"func\">DATABASE()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "A <literal role=\"stmt\">SELECT</literal> statement may include\n a <literal>LIMIT</literal> 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 <literal>LIMIT</literal>, but without\n running the statement again. To obtain this row count, include\n an <literal>SQL_CALC_FOUND_ROWS</literal> option in the\n <literal role=\"stmt\">SELECT</literal> statement, and then\n invoke <literal role=\"func\">FOUND_ROWS()</literal> afterward:"
}
],
"id": "FOUND_ROWS",
"syntax": [
{
"para": "<indexterm>\n <primary>FOUND_ROWS()</primary>\n </indexterm>\n\n <indexterm>\n <primary>LIMIT</primary>\n </indexterm>\n\n <literal role=\"func\">FOUND_ROWS()</literal>"
}
]
},
{
"keywords": [
"ICU_VERSION"
],
"description": [
{
"para": "<literal role=\"func\">ICU_VERSION()</literal>"
},
{
"para": "The version of the International Components for Unicode (ICU)\n library used to support regular expression operations (see\n <xref linkend=\"regexp\" />). This function is primarily intended\n for use in test cases."
}
],
"id": "ICU_VERSION",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "With no argument,\n <literal role=\"func\">LAST_INSERT_ID()</literal> returns a\n <literal>BIGINT UNSIGNED</literal> (64-bit) value representing\n the first automatically generated value successfully inserted\n for an <literal>AUTO_INCREMENT</literal> column as a result of\n the most recently executed\n <literal role=\"stmt\">INSERT</literal> statement. The value of\n <literal role=\"func\">LAST_INSERT_ID()</literal> remains\n unchanged if no rows are successfully inserted."
},
{
"para": "With an argument,\n <literal role=\"func\">LAST_INSERT_ID()</literal> returns an\n unsigned integer."
},
{
"para": "For example, after inserting a row that generates an\n <literal>AUTO_INCREMENT</literal> value, you can get the value\n like this:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT LAST_INSERT_ID();</userinput>\n -> 195"
},
{
"para": "The currently executing statement does not affect the value of\n <literal role=\"func\">LAST_INSERT_ID()</literal>. Suppose that\n you generate an <literal>AUTO_INCREMENT</literal> value with\n one statement, and then refer to\n <literal role=\"func\">LAST_INSERT_ID()</literal> in a\n multiple-row <literal role=\"stmt\">INSERT</literal> statement\n that inserts rows into a table with its own\n <literal>AUTO_INCREMENT</literal> column. The value of\n <literal role=\"func\">LAST_INSERT_ID()</literal> 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 <literal role=\"func\">LAST_INSERT_ID()</literal> and\n <literal role=\"func\">LAST_INSERT_ID(<replaceable>expr</replaceable>)</literal>,\n the effect is undefined.)"
},
{
"para": "If the previous statement returned an error, the value of\n <literal role=\"func\">LAST_INSERT_ID()</literal> is undefined.\n For transactional tables, if the statement is rolled back due\n to an error, the value of\n <literal role=\"func\">LAST_INSERT_ID()</literal> is left\n undefined. For manual\n <literal condition=\"commit\" role=\"stmt\">ROLLBACK</literal>,\n the value of <literal role=\"func\">LAST_INSERT_ID()</literal>\n is not restored to that before the transaction; it remains as\n it was at the point of the\n <literal condition=\"commit\" role=\"stmt\">ROLLBACK</literal>."
},
{
"para": "Within the body of a stored routine (procedure or function) or\n a trigger, the value of\n <literal role=\"func\">LAST_INSERT_ID()</literal> 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 <literal role=\"func\">LAST_INSERT_ID()</literal> 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 <literal role=\"func\">LAST_INSERT_ID()</literal>,\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": "<indexterm>\n <primary>LAST_INSERT_ID()</primary>\n </indexterm>\n\n <literal role=\"func\">LAST_INSERT_ID()</literal>,\n <literal role=\"func\">LAST_INSERT_ID(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": [
"ROLES_GRAPHML"
],
"description": [
{
"para": "<indexterm>\n <primary>ROLES_GRAPHML()</primary>\n </indexterm>\n\n <literal role=\"func\">ROLES_GRAPHML()</literal>"
},
{
"para": "Returns a <literal>utf8</literal> string containing a GraphML\n document representing memory role subgraphs. The\n <literal role=\"priv\">ROLE_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege is required to\n see content in the <literal><graphml></literal> element.\n Otherwise, the result shows only an empty element:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT ROLES_GRAPHML();</userinput>\n+---------------------------------------------------+\n| ROLES_GRAPHML() |\n+---------------------------------------------------+\n| <?xml version=\"1.0\" encoding=\"UTF-8\"?><graphml /> |\n+---------------------------------------------------+"
}
],
"id": "ROLES_GRAPHML",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<literal>ROW_COUNT()</literal> returns a value as follows:"
},
{
"itemizedlist": [
[
{
"para": "DDL statements: 0. This applies to statements such as\n <literal role=\"stmt\">CREATE TABLE</literal> or\n <literal role=\"stmt\">DROP TABLE</literal>."
}
],
[
{
"para": "DML statements other than\n <literal role=\"stmt\">SELECT</literal>: The number of\n affected rows. This applies to statements such as\n <literal role=\"stmt\">UPDATE</literal>,\n <literal role=\"stmt\">INSERT</literal>, or\n <literal role=\"stmt\">DELETE</literal> (as before), but now\n also to statements such as <literal role=\"stmt\">ALTER\n TABLE</literal> and <literal role=\"stmt\">LOAD\n DATA</literal>."
}
],
[
{
"para": "<literal role=\"stmt\">SELECT</literal>: -1 if the statement\n returns a result set, or the number of rows\n <quote>affected</quote> if it does not. For example, for\n <literal>SELECT * FROM t1</literal>,\n <literal role=\"func\">ROW_COUNT()</literal> returns -1. For\n <literal>SELECT * FROM t1 INTO OUTFILE\n '<replaceable>file_name</replaceable>'</literal>,\n <literal role=\"func\">ROW_COUNT()</literal> returns the\n number of rows written to the file."
}
],
[
{
"para": "<literal role=\"stmt\">SIGNAL</literal> statements: 0."
}
]
]
},
{
"para": "For <literal role=\"stmt\">UPDATE</literal> statements, the\n affected-rows value by default is the number of rows actually\n changed. If you specify the\n <literal>CLIENT_FOUND_ROWS</literal> flag to\n <literal role=\"cfunc\">mysql_real_connect()</literal> when\n connecting to <command>mysqld</command>, the affected-rows\n value is the number of rows <quote>found</quote>; that is,\n matched by the <literal>WHERE</literal> clause."
},
{
"para": "For <literal role=\"stmt\">REPLACE</literal> 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 <literal condition=\"insert-on-duplicate\" role=\"stmt\">INSERT\n ... ON DUPLICATE KEY UPDATE</literal> 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 <literal>CLIENT_FOUND_ROWS</literal> flag, the affected-rows\n value is 1 (not 0) if an existing row is set to its current\n values."
},
{
"para": "The <literal role=\"func\">ROW_COUNT()</literal> value is\n similar to the value from the\n <literal role=\"cfunc\">mysql_affected_rows()</literal> C API\n function and the row count that the <command>mysql</command>\n client displays following statement execution."
}
],
"id": "ROW_COUNT",
"syntax": [
{
"para": "<indexterm>\n <primary>ROW_COUNT()</primary>\n </indexterm>\n\n <literal role=\"func\">ROW_COUNT()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function is a synonym for\n <literal role=\"func\">DATABASE()</literal>."
}
],
"id": "SCHEMA",
"syntax": [
{
"para": "<indexterm>\n <primary>SCHEMA()</primary>\n </indexterm>\n\n <literal role=\"func\">SCHEMA()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">SESSION_USER()</literal> is a synonym for\n <literal role=\"func\">USER()</literal>."
}
],
"id": "SESSION_USER",
"syntax": [
{
"para": "<indexterm>\n <primary>SESSION_USER()</primary>\n </indexterm>\n\n <literal role=\"func\">SESSION_USER()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal role=\"func\">SYSTEM_USER()</literal> is a synonym for\n <literal role=\"func\">USER()</literal>."
}
],
"id": "SYSTEM_USER",
"syntax": [
{
"para": "<indexterm>\n <primary>SYSTEM_USER()</primary>\n </indexterm>\n\n <literal role=\"func\">SYSTEM_USER()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the current MySQL user name and host name as a string\n in the <literal>utf8</literal> character set."
}
],
"id": "USER",
"syntax": [
{
"para": "<indexterm>\n <primary>USER()</primary>\n </indexterm>\n\n <literal role=\"func\">USER()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a string that indicates the MySQL server version. The\n string uses the <literal>utf8</literal> character set. The\n value might have a suffix in addition to the version number.\n See the description of the\n <literal role=\"sysvar\">version</literal> system variable in\n <xref linkend=\"server-system-variables\" />."
}
],
"id": "VERSION",
"syntax": [
{
"para": "<indexterm>\n <primary>VERSION()</primary>\n </indexterm>\n\n <literal role=\"func\">VERSION()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given two sets of global transaction identifiers\n <replaceable>set1</replaceable> and\n <replaceable>set2</replaceable>, returns true if all GTIDs in\n <replaceable>set1</replaceable> are also in\n <replaceable>set2</replaceable>. Returns false otherwise."
}
],
"id": "GTID_SUBSET",
"syntax": [
{
"para": "<indexterm>\n <primary>GTID_SUBSET()</primary>\n </indexterm>\n\n <literal role=\"func\">GTID_SUBSET(<replaceable>set1</replaceable>,<replaceable>set2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Given two sets of global transaction identifiers\n <replaceable>set1</replaceable> and\n <replaceable>set2</replaceable>, returns only those GTIDs from\n <replaceable>set1</replaceable> that are not in\n <replaceable>set2</replaceable>."
}
],
"id": "GTID_SUBTRACT",
"syntax": [
{
"para": "<indexterm>\n <primary>GTID_SUBTRACT()</primary>\n </indexterm>\n\n <literal role=\"func\">GTID_SUBTRACT(<replaceable>set1</replaceable>,<replaceable>set2</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Wait until the server has applied all of the transactions\n whose global transaction identifiers are contained in\n <replaceable>gtid_set</replaceable>; that is, until the\n condition GTID_SUBSET(<replaceable>gtid_subset</replaceable>,\n <literal>@@GLOBAL.gtid_executed</literal>) holds. See\n <xref linkend=\"replication-gtids-concepts\" /> for a definition\n of GTID sets."
},
{
"para": "If a timeout is specified, and\n <replaceable>timeout</replaceable> seconds elapse before all\n of the transactions in the GTID set have been applied, the\n function stops waiting. <replaceable>timeout</replaceable> 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": "<literal>WAIT_FOR_EXECUTED_GTID_SET()</literal> 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 <xref linkend=\"replication-gtids\" />."
}
],
"id": "WAIT_FOR_EXECUTED_GTID_SET",
"syntax": [
{
"para": "<indexterm>\n <primary>WAIT_FOR_EXECUTED_GTID_SET()</primary>\n </indexterm>\n\n <literal role=\"func\">WAIT_FOR_EXECUTED_GTID_SET(<replaceable>gtid_set</replaceable>[,\n <replaceable>timeout</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "<literal>WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()</literal> is\n deprecated. Use\n <literal>WAIT_FOR_EXECUTED_GTID_SET()</literal> 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": "<indexterm>\n <primary>WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()</primary>\n </indexterm>\n\n <literal role=\"func\">WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS(<replaceable>gtid_set</replaceable>[,\n <replaceable>timeout</replaceable>][,<replaceable>channel</replaceable>])</literal>"
}
]
},
{
"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 <literal>NULL</literal>."
},
{
"para": "<replaceable>key_str</replaceable> 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 <literal role=\"func\">ASYMMETRIC_ENCRYPT()</literal> to\n produce the encrypted string.\n <replaceable>algorithm</replaceable> indicates the\n encryption algorithm used to create the key."
},
{
"para": "Supported <replaceable>algorithm</replaceable> values:\n <literal>'RSA'</literal>"
},
{
"para": "For a usage example, see the description of\n <literal role=\"func\">ASYMMETRIC_ENCRYPT()</literal>."
}
],
"id": "ASYMMETRIC_DECRYPT",
"syntax": [
{
"para": "<indexterm>\n <primary>ASYMMETRIC_DECRYPT()</primary>\n </indexterm>\n\n <literal role=\"func\">ASYMMETRIC_DECRYPT(<replaceable>algorithm</replaceable>,\n <replaceable>crypt_str</replaceable>,\n <replaceable>key_str</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal>."
},
{
"para": "<replaceable>pub_key_str</replaceable> and\n <replaceable>priv_key_str</replaceable> 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": "<indexterm>\n <primary>ASYMMETRIC_DERIVE()</primary>\n </indexterm>\n\n <literal role=\"func\">ASYMMETRIC_DERIVE(<replaceable>pub_key_str</replaceable>,\n <replaceable>priv_key_str</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal>."
},
{
"para": "The <replaceable>str</replaceable> length cannot be greater\n than the <replaceable>key_str</replaceable> length minus\n 11, in bytes"
},
{
"para": "<replaceable>key_str</replaceable> must be a valid key\n string in PEM format. <replaceable>algorithm</replaceable>\n indicates the encryption algorithm used to create the key."
},
{
"para": "Supported <replaceable>algorithm</replaceable> values:\n <literal>'RSA'</literal>"
},
{
"para": "To encrypt a string, pass a private or public key string to\n <literal role=\"func\">ASYMMETRIC_ENCRYPT()</literal>. To\n recover the original unencrypted string, pass the encrypted\n string to\n <literal role=\"func\">ASYMMETRIC_DECRYPT()</literal>, 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": "<indexterm>\n <primary>ASYMMETRIC_ENCRYPT()</primary>\n </indexterm>\n\n <literal role=\"func\">ASYMMETRIC_ENCRYPT(<replaceable>algorithm</replaceable>,\n <replaceable>str</replaceable>,\n <replaceable>key_str</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal>."
},
{
"para": "<replaceable>digest_str</replaceable> is the digest string.\n It can be generated by calling\n <literal role=\"func\">CREATE_DIGEST()</literal>.\n <replaceable>digest_type</replaceable> indicates the digest\n algorithm used to generate the digest string."
},
{
"para": "<replaceable>priv_key_str</replaceable> 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 <replaceable>algorithm</replaceable> indicates the\n encryption algorithm used to create the key."
},
{
"para": "Supported <replaceable>algorithm</replaceable> values:\n <literal>'RSA'</literal>, <literal>'DSA'</literal>"
},
{
"para": "Supported <replaceable>digest_type</replaceable> values:\n <literal>'SHA224'</literal>, <literal>'SHA256'</literal>,\n <literal>'SHA384'</literal>, <literal>'SHA512'</literal>"
},
{
"para": "For a usage example, see the description of\n <literal role=\"func\">ASYMMETRIC_VERIFY()</literal>."
}
],
"id": "ASYMMETRIC_SIGN",
"syntax": [
{
"para": "<indexterm>\n <primary>ASYMMETRIC_SIGN()</primary>\n </indexterm>\n\n <literal role=\"func\">ASYMMETRIC_SIGN(<replaceable>algorithm</replaceable>,\n <replaceable>digest_str</replaceable>,\n <replaceable>priv_key_str</replaceable>,\n <replaceable>digest_type</replaceable>)</literal>"
}
]
},
{
"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": "<replaceable>digest_str</replaceable> is the digest string.\n It can be generated by calling\n <literal role=\"func\">CREATE_DIGEST()</literal>.\n <replaceable>digest_type</replaceable> indicates the digest\n algorithm used to generate the digest string."
},
{
"para": "<replaceable>sig_str</replaceable> is the signature string.\n It can be generated by calling\n <literal role=\"func\">ASYMMETRIC_SIGN()</literal>."
},
{
"para": "<replaceable>pub_key_str</replaceable> is the public key\n string of the signer. It corresponds to the private key\n passed to <literal role=\"func\">ASYMMETRIC_SIGN()</literal>\n to generate the signature string and must be a valid key\n string in PEM format. <replaceable>algorithm</replaceable>\n indicates the encryption algorithm used to create the key."
},
{
"para": "Supported <replaceable>algorithm</replaceable> values:\n <literal>'RSA'</literal>, <literal>'DSA'</literal>"
},
{
"para": "Supported <replaceable>digest_type</replaceable> values:\n <literal>'SHA224'</literal>, <literal>'SHA256'</literal>,\n <literal>'SHA384'</literal>, <literal>'SHA512'</literal>"
}
],
"id": "ASYMMETRIC_VERIFY",
"syntax": [
{
"para": "<indexterm>\n <primary>ASYMMETRIC_VERIFY()</primary>\n </indexterm>\n\n <literal role=\"func\">ASYMMETRIC_VERIFY(<replaceable>algorithm</replaceable>,\n <replaceable>digest_str</replaceable>,\n <replaceable>sig_str</replaceable>,\n <replaceable>pub_key_str</replaceable>,\n <replaceable>digest_type</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal>."
},
{
"para": "Supported <replaceable>algorithm</replaceable> values:\n <literal>'RSA'</literal>, <literal>'DSA'</literal>,\n <literal>'DH'</literal>"
},
{
"para": "Supported <replaceable>key_len</replaceable> 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 <xref linkend=\"enterprise-encryption-usage\" />."
},
{
"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 <literal role=\"func\">CREATE_DH_PARAMETERS()</literal>."
}
],
"id": "CREATE_ASYMMETRIC_PRIV_KEY",
"syntax": [
{
"para": "<indexterm>\n <primary>CREATE_ASYMMETRIC_PRIV_KEY()</primary>\n </indexterm>\n\n <literal role=\"func\">CREATE_ASYMMETRIC_PRIV_KEY(<replaceable>algorithm</replaceable>,\n {<replaceable>key_len</replaceable>|<replaceable>dh_secret</replaceable>})</literal>"
}
]
},
{
"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 <literal>NULL</literal>."
},
{
"para": "<replaceable>priv_key_str</replaceable> must be a valid key\n string in PEM format. <replaceable>algorithm</replaceable>\n indicates the encryption algorithm used to create the key."
},
{
"para": "Supported <replaceable>algorithm</replaceable> values:\n <literal>'RSA'</literal>, <literal>'DSA'</literal>,\n <literal>'DH'</literal>"
},
{
"para": "For a usage example, see the description of\n <literal role=\"func\">CREATE_ASYMMETRIC_PRIV_KEY()</literal>."
}
],
"id": "CREATE_ASYMMETRIC_PUB_KEY",
"syntax": [
{
"para": "<indexterm>\n <primary>CREATE_ASYMMETRIC_PUB_KEY()</primary>\n </indexterm>\n\n <literal role=\"func\">CREATE_ASYMMETRIC_PUB_KEY(<replaceable>algorithm</replaceable>,\n <replaceable>priv_key_str</replaceable>)</literal>"
}
]
},
{
"keywords": [
"CREATE_DH_PARAMETERS"
],
"description": [
{
"para": "<indexterm>\n <primary>CREATE_DH_PARAMETERS()</primary>\n </indexterm>\n\n <literal role=\"func\">CREATE_DH_PARAMETERS(<replaceable>key_len</replaceable>)</literal>"
},
{
"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 <literal role=\"func\">CREATE_ASYMMETRIC_PRIV_KEY()</literal>.\n If secret generation fails, the result is null."
},
{
"para": "Supported <replaceable>key_len</replaceable> 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 <xref linkend=\"enterprise-encryption-usage\" />."
},
{
"para": "For an example showing how to use the return value for\n generating symmetric keys, see the description of\n <literal role=\"func\">ASYMMETRIC_DERIVE()</literal>."
}
],
"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 <literal>NULL</literal>."
},
{
"para": "Supported <replaceable>digest_type</replaceable> values:\n <literal>'SHA224'</literal>, <literal>'SHA256'</literal>,\n <literal>'SHA384'</literal>, <literal>'SHA512'</literal>"
}
],
"id": "CREATE_DIGEST",
"syntax": [
{
"para": "<indexterm>\n <primary>CREATE_DIGEST()</primary>\n </indexterm>\n\n <literal role=\"func\">CREATE_DIGEST(<replaceable>digest_type</replaceable>,\n <replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": [
"DISTINCT"
],
"description": [
{
"para": "Returns the average value of\n <literal><replaceable>expr</replaceable></literal>. The\n <literal>DISTINCT</literal> option can be used to return the\n average of the distinct values of\n <replaceable>expr</replaceable>."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">AVG()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />; it cannot be used\n with <literal>DISTINCT</literal>."
}
],
"id": "AVG",
"syntax": [
{
"para": "<indexterm>\n <primary>AVG()</primary>\n </indexterm>\n\n <indexterm>\n <primary>AVG(DISTINCT)</primary>\n </indexterm>\n\n <indexterm>\n <primary>DISTINCT</primary>\n <secondary>AVG()</secondary>\n </indexterm>\n\n <literal role=\"func\">AVG([DISTINCT]\n <replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the bitwise <literal>AND</literal> of all bits in\n <replaceable>expr</replaceable>."
},
{
"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 <literal>NULL</literal> 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 <literal role=\"error\">ER_INVALID_BITWISE_OPERANDS_SIZE</literal>\n error occurs. If the argument size exceeds 511 bytes, an\n <literal role=\"error\">ER_INVALID_BITWISE_AGGREGATE_OPERANDS_SIZE</literal>\n error occurs. Numeric evaluation produces an unsigned\n 64-bit integer."
}
]
]
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">BIT_AND()</literal> returns a neutral\n value (all bits set to 1) having the same length as the\n argument values."
},
{
"para": "<literal>NULL</literal> values do not affect the result\n unless all values are <literal>NULL</literal>. 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 <xref linkend=\"bit-functions\" />."
},
{
"para": "As of MySQL 8.0.12, this function executes as a window\n function if <replaceable>over_clause</replaceable> is\n present. <replaceable>over_clause</replaceable> is as\n described in <xref linkend=\"window-functions-usage\" />."
}
],
"id": "BIT_AND",
"syntax": [
{
"para": "<indexterm>\n <primary>BIT_AND()</primary>\n </indexterm>\n\n <literal role=\"func\">BIT_AND(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the bitwise <literal>OR</literal> of all bits in\n <replaceable>expr</replaceable>."
},
{
"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 <literal>NULL</literal> 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 <literal role=\"error\">ER_INVALID_BITWISE_OPERANDS_SIZE</literal>\n error occurs. If the argument size exceeds 511 bytes, an\n <literal role=\"error\">ER_INVALID_BITWISE_AGGREGATE_OPERANDS_SIZE</literal>\n error occurs. Numeric evaluation produces an unsigned\n 64-bit integer."
}
]
]
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">BIT_OR()</literal> returns a neutral\n value (all bits set to 0) having the same length as the\n argument values."
},
{
"para": "<literal>NULL</literal> values do not affect the result\n unless all values are <literal>NULL</literal>. 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 <xref linkend=\"bit-functions\" />."
},
{
"para": "As of MySQL 8.0.12, this function executes as a window\n function if <replaceable>over_clause</replaceable> is\n present. <replaceable>over_clause</replaceable> is as\n described in <xref linkend=\"window-functions-usage\" />."
}
],
"id": "BIT_OR",
"syntax": [
{
"para": "<indexterm>\n <primary>BIT_OR()</primary>\n </indexterm>\n\n <literal role=\"func\">BIT_OR(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the bitwise <literal role=\"op\">XOR</literal> of all\n bits in <replaceable>expr</replaceable>."
},
{
"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 <literal>NULL</literal> 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 <literal role=\"error\">ER_INVALID_BITWISE_OPERANDS_SIZE</literal>\n error occurs. If the argument size exceeds 511 bytes, an\n <literal role=\"error\">ER_INVALID_BITWISE_AGGREGATE_OPERANDS_SIZE</literal>\n error occurs. Numeric evaluation produces an unsigned\n 64-bit integer."
}
]
]
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">BIT_XOR()</literal> returns a neutral\n value (all bits set to 0) having the same length as the\n argument values."
},
{
"para": "<literal>NULL</literal> values do not affect the result\n unless all values are <literal>NULL</literal>. 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 <xref linkend=\"bit-functions\" />."
},
{
"para": "As of MySQL 8.0.12, this function executes as a window\n function if <replaceable>over_clause</replaceable> is\n present. <replaceable>over_clause</replaceable> is as\n described in <xref linkend=\"window-functions-usage\" />."
}
],
"id": "BIT_XOR",
"syntax": [
{
"para": "<indexterm>\n <primary>BIT_XOR()</primary>\n </indexterm>\n\n <literal role=\"func\">BIT_XOR(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a count of the number of non-<literal>NULL</literal>\n values of <replaceable>expr</replaceable> in the rows\n retrieved by a <literal role=\"stmt\">SELECT</literal>\n statement. The result is a\n <literal role=\"type\">BIGINT</literal> value."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">COUNT()</literal> returns\n <literal>0</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "COUNT",
"syntax": [
{
"para": "<indexterm>\n <primary>COUNT()</primary>\n </indexterm>\n\n <literal role=\"func\">COUNT(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": [
"COUNT",
"DISTINCT"
],
"description": [
{
"para": "Returns a count of the number of rows with different\n non-<literal>NULL</literal> <replaceable>expr</replaceable>\n values."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">COUNT(DISTINCT)</literal> returns\n <literal>0</literal>."
}
],
"id": "COUNT DISTINCT",
"syntax": [
{
"para": "<indexterm>\n <primary>COUNT(DISTINCT)</primary>\n </indexterm>\n\n <indexterm>\n <primary>DISTINCT</primary>\n <secondary>COUNT()</secondary>\n </indexterm>\n\n <literal role=\"func\">COUNT(DISTINCT\n <replaceable>expr</replaceable>,[<replaceable>expr</replaceable>...])</literal>"
}
]
},
{
"keywords": [
"DISTINCT",
"SEPARATOR",
"ORDER",
"BY",
"ASC",
"DESC"
],
"description": [
{
"para": "This function returns a string result with the concatenated\n non-<literal>NULL</literal> values from a group. It returns\n <literal>NULL</literal> if there are no\n non-<literal>NULL</literal> values. The full syntax is as\n follows:"
},
{
"programlisting": ">\nGROUP_CONCAT([DISTINCT] <replaceable>expr</replaceable> [,<replaceable>expr</replaceable> ...]\n [ORDER BY {<replaceable>unsigned_integer</replaceable> | <replaceable>col_name</replaceable> | <replaceable>expr</replaceable>}\n [ASC | DESC] [,<replaceable>col_name</replaceable> ...]]\n [SEPARATOR <replaceable>str_val</replaceable>])"
}
],
"id": "GROUP_CONCAT",
"syntax": [
{
"para": "<indexterm>\n <primary>GROUP_CONCAT()</primary>\n </indexterm>\n\n <literal role=\"func\">GROUP_CONCAT(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": [
"JSON_ARRAYAGG"
],
"description": [
{
"para": "Aggregates a result set as a single\n <literal role=\"type\">JSON</literal> 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 <literal>NULL</literal> 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 <replaceable>over_clause</replaceable> is\n present. <replaceable>over_clause</replaceable> is as\n described in <xref linkend=\"window-functions-usage\" />."
}
],
"id": "JSON_ARRAYAGG",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_ARRAYAGG()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_ARRAYAGG(<replaceable>col_or_expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"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 <literal>NULL</literal> if the result contains no\n rows, or in the event of an error. An error occurs if any\n key name is <literal>NULL</literal> 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 <replaceable>over_clause</replaceable> is\n present. <replaceable>over_clause</replaceable> is as\n described in <xref linkend=\"window-functions-usage\" />."
}
],
"id": "JSON_OBJECTAGG",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_OBJECTAGG()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_OBJECTAGG(<replaceable>key</replaceable>,\n <replaceable>value</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": [
"DISTINCT"
],
"description": [
{
"para": "Returns the maximum value of\n <replaceable>expr</replaceable>.\n <literal role=\"func\">MAX()</literal> may take a string\n argument; in such cases, it returns the maximum string\n value. See <xref linkend=\"mysql-indexes\" />. The\n <literal>DISTINCT</literal> keyword can be used to find the\n maximum of the distinct values of\n <replaceable>expr</replaceable>, however, this produces the\n same result as omitting <literal>DISTINCT</literal>."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">MAX()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />; it cannot be used\n with <literal>DISTINCT</literal>."
}
],
"id": "MAX",
"syntax": [
{
"para": "<indexterm>\n <primary>MAX()</primary>\n </indexterm>\n\n <indexterm>\n <primary>MAX(DISTINCT)</primary>\n </indexterm>\n\n <indexterm>\n <primary>DISTINCT</primary>\n <secondary>MAX()</secondary>\n </indexterm>\n\n <literal role=\"func\">MAX([DISTINCT]\n <replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": [
"DISTINCT"
],
"description": [
{
"para": "Returns the minimum value of\n <replaceable>expr</replaceable>.\n <literal role=\"func\">MIN()</literal> may take a string\n argument; in such cases, it returns the minimum string\n value. See <xref linkend=\"mysql-indexes\" />. The\n <literal>DISTINCT</literal> keyword can be used to find the\n minimum of the distinct values of\n <replaceable>expr</replaceable>, however, this produces the\n same result as omitting <literal>DISTINCT</literal>."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">MIN()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />; it cannot be used\n with <literal>DISTINCT</literal>."
}
],
"id": "MIN",
"syntax": [
{
"para": "<indexterm>\n <primary>MIN()</primary>\n </indexterm>\n\n <indexterm>\n <primary>MIN(DISTINCT)</primary>\n </indexterm>\n\n <indexterm>\n <primary>DISTINCT</primary>\n <secondary>MIN()</secondary>\n </indexterm>\n\n <literal role=\"func\">MIN([DISTINCT]\n <replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": [
"STD"
],
"description": [
{
"para": "Returns the population standard deviation of\n <replaceable>expr</replaceable>.\n <literal role=\"func\">STD()</literal> is a synonym for the\n standard SQL function\n <literal role=\"func\">STDDEV_POP()</literal>, provided as a\n MySQL extension."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">STD()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "STD",
"syntax": [
{
"para": "<indexterm>\n <primary>STD()</primary>\n </indexterm>\n\n <literal role=\"func\">STD(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": [
"STDDEV"
],
"description": [
{
"para": "Returns the population standard deviation of\n <replaceable>expr</replaceable>.\n <literal role=\"func\">STDDEV()</literal> is a synonym for the\n standard SQL function\n <literal role=\"func\">STDDEV_POP()</literal>, provided for\n compatibility with Oracle."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">STDDEV()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "STDDEV",
"syntax": [
{
"para": "<indexterm>\n <primary>STDDEV()</primary>\n </indexterm>\n\n <indexterm>\n <primary>Oracle compatibility</primary>\n </indexterm>\n\n <indexterm>\n <primary>compatibility</primary>\n <secondary>with Oracle</secondary>\n </indexterm>\n\n <literal role=\"func\">STDDEV(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the population standard deviation of\n <replaceable>expr</replaceable> (the square root of\n <literal role=\"func\">VAR_POP()</literal>). You can also use\n <literal role=\"func\">STD()</literal> or\n <literal role=\"func\">STDDEV()</literal>, which are\n equivalent but not standard SQL."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">STDDEV_POP()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "STDDEV_POP",
"syntax": [
{
"para": "<indexterm>\n <primary>STDDEV_POP()</primary>\n </indexterm>\n\n <literal role=\"func\">STDDEV_POP(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the sample standard deviation of\n <replaceable>expr</replaceable> (the square root of\n <literal role=\"func\">VAR_SAMP()</literal>."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">STDDEV_SAMP()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "STDDEV_SAMP",
"syntax": [
{
"para": "<indexterm>\n <primary>STDDEV_SAMP()</primary>\n </indexterm>\n\n <literal role=\"func\">STDDEV_SAMP(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": [
"DISTINCT"
],
"description": [
{
"para": "Returns the sum of <replaceable>expr</replaceable>. If the\n return set has no rows, <literal role=\"func\">SUM()</literal>\n returns <literal>NULL</literal>. The\n <literal>DISTINCT</literal> keyword can be used to sum only\n the distinct values of <replaceable>expr</replaceable>."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">SUM()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />; it cannot be used\n with <literal>DISTINCT</literal>."
}
],
"id": "SUM",
"syntax": [
{
"para": "<indexterm>\n <primary>SUM()</primary>\n </indexterm>\n\n <indexterm>\n <primary>SUM(DISTINCT)</primary>\n </indexterm>\n\n <indexterm>\n <primary>DISTINCT</primary>\n <secondary>SUM()</secondary>\n </indexterm>\n\n <literal role=\"func\">SUM([DISTINCT]\n <replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the population standard variance of\n <replaceable>expr</replaceable>. 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 <literal role=\"func\">VARIANCE()</literal>, which is\n equivalent but is not standard SQL."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">VAR_POP()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "VAR_POP",
"syntax": [
{
"para": "<indexterm>\n <primary>VAR_POP()</primary>\n </indexterm>\n\n <literal role=\"func\">VAR_POP(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the sample variance of\n <replaceable>expr</replaceable>. That is, the denominator is\n the number of rows minus one."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">VAR_SAMP()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "VAR_SAMP",
"syntax": [
{
"para": "<indexterm>\n <primary>VAR_SAMP()</primary>\n </indexterm>\n\n <literal role=\"func\">VAR_SAMP(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the population standard variance of\n <replaceable>expr</replaceable>.\n <literal role=\"func\">VARIANCE()</literal> is a synonym for\n the standard SQL function\n <literal role=\"func\">VAR_POP()</literal>, provided as a\n MySQL extension."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">VARIANCE()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "This function executes as a window function if\n <replaceable>over_clause</replaceable> is present.\n <replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "VARIANCE",
"syntax": [
{
"para": "<indexterm>\n <primary>VARIANCE()</primary>\n </indexterm>\n\n <literal role=\"func\">VARIANCE(<replaceable>expr</replaceable>)\n [<replaceable>over_clause</replaceable>]</literal>"
}
]
},
{
"keywords": [
"CUME_DIST"
],
"description": [
{
"para": "<literal role=\"func\">CUME_DIST()</literal>\n <replaceable>over_clause</replaceable>"
},
{
"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 <literal>ORDER\n BY</literal> to sort partition rows into the desired order.\n Without <literal>ORDER BY</literal>, all rows are peers and\n have value\n <replaceable>N</replaceable>/<replaceable>N</replaceable> =\n 1, where <replaceable>N</replaceable> is the partition size."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "CUME_DIST",
"syntax": []
},
{
"keywords": [
"DENSE_RANK"
],
"description": [
{
"para": "<literal role=\"func\">DENSE_RANK()</literal>\n <replaceable>over_clause</replaceable>"
},
{
"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 <literal role=\"func\">RANK()</literal> function\n description."
},
{
"para": "This function should be used with <literal>ORDER\n BY</literal> to sort partition rows into the desired order.\n Without <literal>ORDER BY</literal>, all rows are peers."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "DENSE_RANK",
"syntax": []
},
{
"keywords": [
"FIRST_VALUE"
],
"description": [
{
"para": "<literal role=\"func\">FIRST_VALUE(<replaceable>expr</replaceable>)</literal>\n [<replaceable>null_treatment</replaceable>]\n <replaceable>over_clause</replaceable>"
},
{
"para": "Returns the value of <replaceable>expr</replaceable> from\n the first row of the window frame."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />.\n <replaceable>null_treatment</replaceable> is as described in\n the section introduction."
}
],
"id": "FIRST_VALUE",
"syntax": []
},
{
"keywords": [
"LAG"
],
"description": [
{
"para": "<literal role=\"func\">LAG(<replaceable>expr</replaceable> [,\n <replaceable>N</replaceable>[,\n <replaceable>default</replaceable>]])</literal>\n [<replaceable>null_treatment</replaceable>]\n <replaceable>over_clause</replaceable>"
},
{
"para": "Returns the value of <replaceable>expr</replaceable> from\n the row that lags (precedes) the current row by\n <replaceable>N</replaceable> rows within its partition. If\n there is no such row, the return value is\n <replaceable>default</replaceable>. For example, if\n <replaceable>N</replaceable> is 3, the return value is\n <replaceable>default</replaceable> for the first two rows.\n If <replaceable>N</replaceable> or\n <replaceable>default</replaceable> are missing, the defaults\n are 1 and <literal>NULL</literal>, respectively."
},
{
"para": "<replaceable>N</replaceable> must be a literal nonnegative\n integer. If <replaceable>N</replaceable> is 0,\n <replaceable>expr</replaceable> is evaluated for the current\n row."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />.\n <replaceable>null_treatment</replaceable> is as described in\n the section introduction."
}
],
"id": "LAG",
"syntax": []
},
{
"keywords": [
"LAST_VALUE"
],
"description": [
{
"para": "<literal role=\"func\">LAST_VALUE(<replaceable>expr</replaceable>)</literal>\n [<replaceable>null_treatment</replaceable>]\n <replaceable>over_clause</replaceable>"
},
{
"para": "Returns the value of <replaceable>expr</replaceable> from\n the last row of the window frame."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />.\n <replaceable>null_treatment</replaceable> is as described in\n the section introduction."
},
{
"para": "For an example, see the\n <literal role=\"func\">FIRST_VALUE()</literal> function\n description."
}
],
"id": "LAST_VALUE",
"syntax": []
},
{
"keywords": [
"LEAD"
],
"description": [
{
"para": "<literal role=\"func\">LEAD(<replaceable>expr</replaceable> [,\n <replaceable>N</replaceable>[,\n <replaceable>default</replaceable>]])</literal>\n [<replaceable>null_treatment</replaceable>]\n <replaceable>over_clause</replaceable>"
},
{
"para": "Returns the value of <replaceable>expr</replaceable> from\n the row that leads (follows) the current row by\n <replaceable>N</replaceable> rows within its partition. If\n there is no such row, the return value is\n <replaceable>default</replaceable>. For example, if\n <replaceable>N</replaceable> is 3, the return value is\n <replaceable>default</replaceable> for the last two rows. If\n <replaceable>N</replaceable> or\n <replaceable>default</replaceable> are missing, the defaults\n are 1 and <literal>NULL</literal>, respectively."
},
{
"para": "<replaceable>N</replaceable> must be a literal nonnegative\n integer. If <replaceable>N</replaceable> is 0,\n <replaceable>expr</replaceable> is evaluated for the current\n row."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />.\n <replaceable>null_treatment</replaceable> is as described in\n the section introduction."
},
{
"para": "For an example, see the <literal role=\"func\">LAG()</literal>\n function description."
}
],
"id": "LEAD",
"syntax": []
},
{
"keywords": [
"NTH_VALUE"
],
"description": [
{
"para": "<literal role=\"func\">NTH_VALUE(<replaceable>expr</replaceable>,\n <replaceable>N</replaceable>)</literal>\n [<replaceable>from_first_last</replaceable>]\n [<replaceable>null_treatment</replaceable>]\n <replaceable>over_clause</replaceable>"
},
{
"para": "Returns the value of <replaceable>expr</replaceable> from\n the <replaceable>N</replaceable>-th row of the window frame.\n If there is no such row, the return value is\n <literal>NULL</literal>."
},
{
"para": "<replaceable>N</replaceable> must be a literal positive\n integer."
},
{
"para": "<replaceable>from_first_last</replaceable> is part of the\n SQL standard, but the MySQL implementation permits only\n <literal>FROM FIRST</literal> (which is also the default).\n This means that calculations begin at the first row of the\n window. <literal>FROM LAST</literal> is parsed, but produces\n an error. To obtain the same effect as <literal>FROM\n LAST</literal> (begin calculations at the last row of the\n window), use <literal>ORDER BY</literal> to sort in reverse\n order."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />.\n <replaceable>null_treatment</replaceable> is as described in\n the section introduction."
},
{
"para": "For an example, see the\n <literal role=\"func\">FIRST_VALUE()</literal> function\n description."
}
],
"id": "NTH_VALUE",
"syntax": []
},
{
"keywords": [
"NTILE"
],
"description": [
{
"para": "<literal role=\"func\">NTILE(<replaceable>N</replaceable>)</literal>\n <replaceable>over_clause</replaceable>"
},
{
"para": "Divides a partition into <replaceable>N</replaceable> 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 <replaceable>N</replaceable> is 4,\n <literal>NTILE()</literal> divides rows into four buckets.\n If <replaceable>N</replaceable> is 100,\n <literal>NTILE()</literal> divides rows into 100 buckets."
},
{
"para": "<replaceable>N</replaceable> must be a literal positive\n integer. Bucket number return values range from 1 to\n <replaceable>N</replaceable>."
},
{
"para": "This function should be used with <literal>ORDER\n BY</literal> to sort partition rows into the desired order."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "NTILE",
"syntax": []
},
{
"keywords": [
"PERCENT_RANK"
],
"description": [
{
"para": "<literal role=\"func\">PERCENT_RANK()</literal>\n <replaceable>over_clause</replaceable>"
},
{
"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 <replaceable>rank</replaceable> is the row rank and\n <replaceable>rows</replaceable> is the number of partition\n rows:"
},
{
"programlisting": ">\n(<replaceable>rank</replaceable> - 1) / (<replaceable>rows</replaceable> - 1)"
},
{
"para": "This function should be used with <literal>ORDER\n BY</literal> to sort partition rows into the desired order.\n Without <literal>ORDER BY</literal>, all rows are peers."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
},
{
"para": "For an example, see the\n <literal role=\"func\">CUME_DIST()</literal> function\n description."
}
],
"id": "PERCENT_RANK",
"syntax": []
},
{
"keywords": [
"RANK"
],
"description": [
{
"para": "<literal role=\"func\">RANK()</literal>\n <replaceable>over_clause</replaceable>"
},
{
"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 <literal>ORDER\n BY</literal> to sort partition rows into the desired order.\n Without <literal>ORDER BY</literal>, all rows are peers."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "RANK",
"syntax": []
},
{
"keywords": [
"ROW_NUMBER"
],
"description": [
{
"para": "<literal role=\"func\">ROW_NUMBER()</literal>\n <replaceable>over_clause</replaceable>"
},
{
"para": "Returns the number of the current row within its partition.\n Rows numbers range from 1 to the number of partition rows."
},
{
"para": "<literal>ORDER BY</literal> affects the order in which rows\n are numbered. Without <literal>ORDER BY</literal>, row\n numbering is nondeterministic."
},
{
"para": "<literal role=\"func\">ROW_NUMBER()</literal> assigns peers\n different row numbers. To assign peers the same value, use\n <literal role=\"func\">RANK()</literal> or\n <literal role=\"func\">DENSE_RANK()</literal>. For an example,\n see the <literal role=\"func\">RANK()</literal> function\n description."
},
{
"para": "<replaceable>over_clause</replaceable> is as described in\n <xref linkend=\"window-functions-usage\" />."
}
],
"id": "ROW_NUMBER",
"syntax": []
},
{
"keywords": [
"FORMAT_BYTES"
],
"description": [
{
"para": "<literal role=\"func\">FORMAT_BYTES(<replaceable>count</replaceable>)</literal>"
},
{
"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": "<literal role=\"func\">FORMAT_PICO_TIME(<replaceable>time_val</replaceable>)</literal>"
},
{
"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": "<literal role=\"func\">PS_CURRENT_THREAD_ID()</literal>"
},
{
"para": "Returns a <literal>BIGINT UNSIGNED</literal> 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 <literal>THREAD_ID</literal> column of Performance Schema\n tables."
},
{
"para": "Performance Schema configuration affects\n <literal role=\"func\">PS_CURRENT_THREAD_ID()</literal> the same\n way as for <literal role=\"func\">PS_THREAD_ID()</literal>. For\n details, see the description of that function."
}
],
"id": "PS_CURRENT_THREAD_ID",
"syntax": []
},
{
"keywords": [
"PS_THREAD_ID"
],
"description": [
{
"para": "<literal role=\"func\">PS_THREAD_ID(<replaceable>connection_id</replaceable>)</literal>"
},
{
"para": "Given a connection ID, returns a <literal>BIGINT\n UNSIGNED</literal> value representing the Performance Schema\n thread ID assigned to the connection ID, or\n <literal>NULL</literal> 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 <literal>PROCESSLIST_ID</literal> column of the Performance\n Schema <literal role=\"ps\">threads</literal> table or the\n <literal>Id</literal> column of <literal role=\"stmt\">SHOW\n PROCESSLIST</literal> output."
},
{
"para": "The thread ID return value is a value of the type given in the\n <literal>THREAD_ID</literal> column of Performance Schema\n tables."
},
{
"para": "Performance Schema configuration affects\n <literal role=\"func\">PS_THREAD_ID()</literal> operation as\n follows. (These remarks also apply to\n <literal role=\"func\">PS_CURRENT_THREAD_ID()</literal>.)"
},
{
"itemizedlist": [
[
{
"para": "Disabling the <literal>thread_instrumentation</literal>\n consumer disables statistics from being collected and\n aggregated at the thread level, but has no effect on\n <literal role=\"func\">PS_THREAD_ID()</literal>."
}
],
[
{
"para": "If\n <literal role=\"sysvar\">performance_schema_max_thread_instances</literal>\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 <literal role=\"func\">PS_THREAD_ID()</literal> returns\n <literal>NULL</literal>; in this case,\n <literal role=\"statvar\">Performance_schema_thread_instances_lost</literal>\n will be nonzero."
}
],
[
{
"para": "If\n <literal role=\"sysvar\">performance_schema_max_thread_instances</literal>\n is 0, the Performance Schema allocates no thread memory\n and <literal role=\"func\">PS_THREAD_ID()</literal> returns\n <literal>NULL</literal>."
}
],
[
{
"para": "If the Performance Schema itself is disabled,\n <literal role=\"func\">PS_THREAD_ID()</literal> produces an\n error."
}
]
]
}
],
"id": "PS_THREAD_ID",
"syntax": []
},
{
"keywords": [
"CAN_ACCESS_COLUMN"
],
"description": [
{
"para": "<literal role=\"func\">CAN_ACCESS_COLUMN(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "CAN_ACCESS_COLUMN",
"syntax": []
},
{
"keywords": [
"CAN_ACCESS_DATABASE"
],
"description": [
{
"para": "<literal role=\"func\">CAN_ACCESS_DATABASE(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "CAN_ACCESS_DATABASE",
"syntax": []
},
{
"keywords": [
"CAN_ACCESS_TABLE"
],
"description": [
{
"para": "<literal role=\"func\">CAN_ACCESS_TABLE(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "CAN_ACCESS_TABLE",
"syntax": []
},
{
"keywords": [
"CAN_ACCESS_VIEW"
],
"description": [
{
"para": "<literal role=\"func\">CAN_ACCESS_VIEW(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "CAN_ACCESS_VIEW",
"syntax": []
},
{
"keywords": [
"GET_DD_COLUMN_PRIVILEGES"
],
"description": [
{
"para": "<literal role=\"func\">GET_DD_COLUMN_PRIVILEGES(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "GET_DD_COLUMN_PRIVILEGES",
"syntax": []
},
{
"keywords": [
"GET_DD_CREATE_OPTIONS"
],
"description": [
{
"para": "<literal role=\"func\">GET_DD_CREATE_OPTIONS(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "GET_DD_CREATE_OPTIONS",
"syntax": []
},
{
"keywords": [
"GET_DD_INDEX_SUB_PART_LENGTH"
],
"description": [
{
"para": "<literal role=\"func\">GET_DD_INDEX_SUB_PART_LENGTH(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "GET_DD_INDEX_SUB_PART_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_AUTO_INCREMENT"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_AUTO_INCREMENT(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_AUTO_INCREMENT",
"syntax": []
},
{
"keywords": [
"INTERNAL_AVG_ROW_LENGTH"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_AVG_ROW_LENGTH(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_AVG_ROW_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_CHECK_TIME"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_CHECK_TIME(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_CHECK_TIME",
"syntax": []
},
{
"keywords": [
"INTERNAL_CHECKSUM"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_CHECKSUM(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_CHECKSUM",
"syntax": []
},
{
"keywords": [
"INTERNAL_DATA_FREE"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_DATA_FREE(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_DATA_FREE",
"syntax": []
},
{
"keywords": [
"INTERNAL_DATA_LENGTH"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_DATA_LENGTH(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_DATA_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_DD_CHAR_LENGTH"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_DD_CHAR_LENGTH(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_DD_CHAR_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_COMMENT_OR_ERROR"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_GET_COMMENT_OR_ERROR(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_GET_COMMENT_OR_ERROR",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_ENABLED_ROLE_JSON"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_GET_ENABLED_ROLE_JSON(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_GET_ENABLED_ROLE_JSON",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_HOSTNAME"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_GET_HOSTNAME(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_GET_HOSTNAME",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_USERNAME"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_GET_USERNAME(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_GET_USERNAME",
"syntax": []
},
{
"keywords": [
"INTERNAL_GET_VIEW_WARNING_OR_ERROR"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_GET_VIEW_WARNING_OR_ERROR(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_GET_VIEW_WARNING_OR_ERROR",
"syntax": []
},
{
"keywords": [
"INTERNAL_INDEX_COLUMN_CARDINALITY"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_INDEX_COLUMN_CARDINALITY(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_INDEX_COLUMN_CARDINALITY",
"syntax": []
},
{
"keywords": [
"INTERNAL_INDEX_LENGTH"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_INDEX_LENGTH(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_INDEX_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_IS_ENABLED_ROLE"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_IS_ENABLED_ROLE(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_IS_ENABLED_ROLE",
"syntax": []
},
{
"keywords": [
"INTERNAL_IS_MANDATORY_ROLE"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_IS_MANDATORY_ROLE(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_IS_MANDATORY_ROLE",
"syntax": []
},
{
"keywords": [
"INTERNAL_KEYS_DISABLED"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_KEYS_DISABLED(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_KEYS_DISABLED",
"syntax": []
},
{
"keywords": [
"INTERNAL_MAX_DATA_LENGTH"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_MAX_DATA_LENGTH(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_MAX_DATA_LENGTH",
"syntax": []
},
{
"keywords": [
"INTERNAL_TABLE_ROWS"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_TABLE_ROWS(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_TABLE_ROWS",
"syntax": []
},
{
"keywords": [
"INTERNAL_UPDATE_TIME"
],
"description": [
{
"para": "<literal role=\"func\">INTERNAL_UPDATE_TIME(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "INTERNAL_UPDATE_TIME",
"syntax": []
},
{
"keywords": [
"IS_VISIBLE_DD_OBJECT"
],
"description": [
{
"para": "<literal role=\"func\">IS_VISIBLE_DD_OBJECT(<replaceable>ARGS</replaceable>)</literal>"
}
],
"id": "IS_VISIBLE_DD_OBJECT",
"syntax": []
},
{
"keywords": [
"ANY_VALUE"
],
"description": [
{
"para": "<indexterm>\n <primary>ANY_VALUE()</primary>\n </indexterm>\n\n <literal role=\"func\">ANY_VALUE(<replaceable>arg</replaceable>)</literal>"
},
{
"para": "This function is useful for <literal>GROUP BY</literal>\n queries when the\n <literal role=\"sqlmode\">ONLY_FULL_GROUP_BY</literal> 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 <literal role=\"sqlmode\">ONLY_FULL_GROUP_BY</literal>\n SQL mode."
},
{
"para": "For example, if <literal>name</literal> is a nonindexed\n column, the following query fails with\n <literal role=\"sqlmode\">ONLY_FULL_GROUP_BY</literal> enabled:"
},
{
"programlisting": ">\n\nmysql> <userinput>SELECT name, address, MAX(age) FROM t GROUP BY name;</userinput>\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 <literal>address</literal> is a\n nonaggregated column that is neither named among\n <literal>GROUP BY</literal> columns nor functionally dependent\n on them. As a result, the <literal>address</literal> value for\n rows within each <literal>name</literal> group is\n nondeterministic. There are multiple ways to cause MySQL to\n accept the query:"
},
{
"itemizedlist": [
[
{
"para": "Alter the table to make <literal>name</literal> a primary\n key or a unique <literal>NOT NULL</literal> column. This\n enables MySQL to determine that <literal>address</literal>\n is functionally dependent on <literal>name</literal>; that\n is, <literal>address</literal> is uniquely determined by\n <literal>name</literal>. (This technique is inapplicable\n if <literal>NULL</literal> must be permitted as a valid\n <literal>name</literal> value.)"
}
],
[
{
"para": "Use <literal role=\"func\">ANY_VALUE()</literal> to refer to\n <literal>address</literal>:"
},
{
"programlisting": ">\nSELECT name, ANY_VALUE(address), MAX(age) FROM t GROUP BY name;"
},
{
"para": "In this case, MySQL ignores the nondeterminism of\n <literal>address</literal> values within each\n <literal>name</literal> 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 <literal role=\"func\">ANY_VALUE()</literal> is not an\n aggregate function, unlike functions such as\n <literal role=\"func\">SUM()</literal> or\n <literal role=\"func\">COUNT()</literal>. It simply acts to\n suppress the test for nondeterminism."
}
],
[
{
"para": "Disable\n <literal role=\"sqlmode\">ONLY_FULL_GROUP_BY</literal>. This\n is equivalent to using\n <literal role=\"func\">ANY_VALUE()</literal> with\n <literal role=\"sqlmode\">ONLY_FULL_GROUP_BY</literal>\n enabled, as described in the previous item."
}
]
]
},
{
"para": "<literal role=\"func\">ANY_VALUE()</literal> is also useful if\n functional dependence exists between columns but MySQL cannot\n determine it. The following query is valid because\n <literal>age</literal> is functionally dependent on the\n grouping column <literal>age-1</literal>, but MySQL cannot\n tell that and rejects the query with\n <literal role=\"sqlmode\">ONLY_FULL_GROUP_BY</literal> enabled:"
},
{
"programlisting": ">\nSELECT age FROM t GROUP BY age-1;"
},
{
"para": "To cause MySQL to accept the query, use\n <literal role=\"func\">ANY_VALUE()</literal>:"
},
{
"programlisting": ">\nSELECT ANY_VALUE(age) FROM t GROUP BY age-1;"
},
{
"para": "<literal role=\"func\">ANY_VALUE()</literal> can be used for\n queries that refer to aggregate functions in the absence of a\n <literal>GROUP BY</literal> clause:"
},
{
"programlisting": ">\n\nmysql> <userinput>SELECT name, MAX(age) FROM t;</userinput>\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 <literal>GROUP BY</literal>, there is a single group\n and it is nondeterministic which <literal>name</literal> value\n to choose for the group.\n <literal role=\"func\">ANY_VALUE()</literal> 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 <literal>GROUP BY</literal>\n column. For example, an application may enforce uniqueness of\n one column with respect to another. In this case, using\n <literal role=\"func\">ANY_VALUE()</literal> for the effectively\n functionally dependent column may make sense."
},
{
"para": "For additional discussion, see\n <xref linkend=\"group-by-handling\" />."
}
],
"id": "ANY_VALUE",
"syntax": []
},
{
"keywords": [
"BIN_TO_UUID"
],
"description": [
{
"para": "<indexterm>\n <primary>BIN_TO_UUID()</primary>\n </indexterm>\n\n <literal role=\"func\">BIN_TO_UUID(<replaceable>binary_uuid</replaceable>)</literal>,\n <literal role=\"func\">BIN_TO_UUID(<replaceable>binary_uuid</replaceable>,\n <replaceable>swap_flag</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">BIN_TO_UUID()</literal> is the inverse of\n <literal role=\"func\">UUID_TO_BIN()</literal>. 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 <literal role=\"type\">VARBINARY(16)</literal> value. The return\n value is a <literal>utf8</literal> string of five hexadecimal\n numbers separated by dashes. (For details about this format,\n see the <literal role=\"func\">UUID()</literal> function\n description.) If the UUID argument is <literal>NULL</literal>,\n the return value is <literal>NULL</literal>. If any argument\n is invalid, an error occurs."
},
{
"para": "<literal role=\"func\">BIN_TO_UUID()</literal> 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 <replaceable>swap_flag</replaceable> 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 <replaceable>swap_flag</replaceable> 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 <literal role=\"func\">UUID_TO_BIN()</literal> 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 <literal role=\"func\">DEFAULT(<replaceable>col_name</replaceable>)</literal>\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": "<indexterm>\n <primary>DEFAULT()</primary>\n </indexterm>\n\n <literal role=\"func\">DEFAULT(<replaceable>col_name</replaceable>)</literal>"
}
]
},
{
"keywords": [
"GROUPING"
],
"description": [
{
"para": "<literal role=\"func\">GROUPING(<replaceable>expr</replaceable>\n [, <replaceable>expr</replaceable>] ...)</literal>"
},
{
"para": "For <literal>GROUP BY</literal> queries that include a\n <literal>WITH ROLLUP</literal> modifier, the\n <literal>ROLLUP</literal> operation produces super-aggregate\n output rows where <literal>NULL</literal> represents the set\n of all values. The <literal role=\"func\">GROUPING()</literal>\n function enables you to distinguish <literal>NULL</literal>\n values for super-aggregate rows from <literal>NULL</literal>\n values in regular grouped rows."
},
{
"para": "<literal role=\"func\">GROUPING()</literal> is permitted only in\n the select list or <literal>HAVING</literal> clause."
},
{
"para": "Each argument to <literal role=\"func\">GROUPING()</literal>\n must be an expression that exactly matches an expression in\n the <literal>GROUP BY</literal> clause. The expression cannot\n be a positional specifier. For each expression,\n <literal role=\"func\">GROUPING()</literal> produces 1 if the\n expression value in the current row is a\n <literal>NULL</literal> representing a super-aggregate value.\n Otherwise, <literal role=\"func\">GROUPING()</literal> produces\n 0, indicating that the expression value is a\n <literal>NULL</literal> for a regular result row or is not\n <literal>NULL</literal>."
},
{
"para": "Suppose that table <literal>t1</literal> contains these rows,\n where <literal>NULL</literal> indicates something like\n <quote>other</quote> or <quote>unknown</quote>:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT * FROM t1;</userinput>\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 <literal>WITH ROLLUP</literal>\n looks like this:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT name, size, SUM(quantity) AS quantity</userinput>\n <userinput>FROM t1</userinput>\n <userinput>GROUP BY name, size;</userinput>\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 <literal>NULL</literal> values, but those\n do not represent super-aggregate rows because the query does\n not include <literal>WITH ROLLUP</literal>."
},
{
"para": "Adding <literal>WITH ROLLUP</literal> produces super-aggregate\n summary rows containing additional <literal>NULL</literal>\n values. However, without comparing this result to the previous\n one, it is not easy to see which <literal>NULL</literal>\n values occur in super-aggregate rows and which occur in\n regular grouped rows:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT name, size, SUM(quantity) AS quantity</userinput>\n <userinput>FROM t1</userinput>\n <userinput>GROUP BY name, size WITH ROLLUP;</userinput>\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 <literal>NULL</literal> values in\n super-aggregate rows from those in regular grouped rows, use\n <literal role=\"func\">GROUPING()</literal>, which returns 1\n only for super-aggregate <literal>NULL</literal> values:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT</userinput>\n <userinput>name, size, SUM(quantity) AS quantity,</userinput>\n <userinput>GROUPING(name) AS grp_name,</userinput>\n <userinput>GROUPING(size) AS grp_size</userinput>\n <userinput>FROM t1</userinput>\n <userinput>GROUP BY name, size WITH ROLLUP;</userinput>\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 <literal role=\"func\">GROUPING()</literal>:"
},
{
"itemizedlist": [
[
{
"para": "Substitute a label for super-aggregate\n <literal>NULL</literal> values:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT</userinput>\n <userinput>IF(GROUPING(name) = 1, 'All items', name) AS name,</userinput>\n <userinput>IF(GROUPING(size) = 1, 'All sizes', size) AS size,</userinput>\n <userinput>SUM(quantity) AS quantity</userinput>\n <userinput>FROM t1</userinput>\n <userinput>GROUP BY name, size WITH ROLLUP;</userinput>\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> <userinput>SELECT name, size, SUM(quantity) AS quantity</userinput>\n <userinput>FROM t1</userinput>\n <userinput>GROUP BY name, size WITH ROLLUP</userinput>\n <userinput>HAVING GROUPING(name) = 1 OR GROUPING(size) = 1;</userinput>\n+------+------+----------+\n| name | size | quantity |\n+------+------+----------+\n| ball | NULL | 35 |\n| hoop | NULL | 23 |\n| NULL | NULL | 58 |\n+------+------+----------+"
}
]
]
},
{
"para": "<literal role=\"func\">GROUPING()</literal> permits multiple\n expression arguments. In this case, the\n <literal role=\"func\">GROUPING()</literal> 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 <literal role=\"func\">GROUPING(<replaceable>expr1</replaceable>,\n <replaceable>expr2</replaceable>,\n <replaceable>expr3</replaceable>)</literal> is evaluated like\n this:"
},
{
"programlisting": ">\n result for GROUPING(<replaceable>expr3</replaceable>)\n+ result for GROUPING(<replaceable>expr2</replaceable>) << 1\n+ result for GROUPING(<replaceable>expr1</replaceable>) << 2"
},
{
"para": "The following query shows how\n <literal role=\"func\">GROUPING()</literal> results for single\n arguments combine for a multiple-argument call to produce a\n bitmask value:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT</userinput>\n <userinput>name, size, SUM(quantity) AS quantity,</userinput>\n <userinput>GROUPING(name) AS grp_name,</userinput>\n <userinput>GROUPING(size) AS grp_size,</userinput>\n <userinput>GROUPING(name, size) AS grp_all</userinput>\n <userinput>FROM t1</userinput>\n <userinput>GROUP BY name, size WITH ROLLUP;</userinput>\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 <literal role=\"func\">GROUPING()</literal> return value is\n nonzero if any expression represents a super-aggregate value.\n Multiple-argument <literal role=\"func\">GROUPING()</literal>\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 <literal role=\"func\">GROUPING()</literal>\n call rather than multiple single-argument calls:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT name, size, SUM(quantity) AS quantity</userinput>\n <userinput>FROM t1</userinput>\n <userinput>GROUP BY name, size WITH ROLLUP</userinput>\n <userinput>HAVING GROUPING(name, size) <> 0;</userinput>\n+------+------+----------+\n| name | size | quantity |\n+------+------+----------+\n| ball | NULL | 35 |\n| hoop | NULL | 23 |\n| NULL | NULL | 58 |\n+------+------+----------+"
},
{
"para": "Use of <literal role=\"func\">GROUPING()</literal> is subject to\n these limitations:"
},
{
"itemizedlist": [
[
{
"para": "Do not use subquery <literal>GROUP BY</literal>\n expressions as <literal role=\"func\">GROUPING()</literal>\n arguments because matching might fail. For example,\n matching fails for this query:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT GROUPING((SELECT MAX(name) FROM t1))</userinput>\n <userinput>FROM t1</userinput>\n <userinput>GROUP BY (SELECT MAX(name) FROM t1) WITH ROLLUP;</userinput>\nERROR 3580 (HY000): Argument #1 of GROUPING function is not in GROUP BY"
}
],
[
{
"para": "<literal>GROUP BY</literal> literal expressions should not\n be used within a <literal>HAVING</literal> clause as\n <literal role=\"func\">GROUPING()</literal> arguments. Due\n to differences between when the optimizer evaluates\n <literal>GROUP BY</literal> and <literal>HAVING</literal>,\n matching may succeed but\n <literal role=\"func\">GROUPING()</literal> 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": "<literal role=\"func\">GROUPING()</literal> is evaluated\n earlier for the literal constant expression than for the\n <literal>HAVING</literal> clause as a whole and returns 0.\n To check whether a query such as this is affected, use\n <literal role=\"stmt\">EXPLAIN</literal> and look for\n <literal>Impossible having</literal> in the\n <literal>Extra</literal> 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). <literal role=\"func\">INET_ATON()</literal> returns\n <literal>NULL</literal> if it does not understand its\n argument."
}
],
"id": "INET_ATON",
"syntax": [
{
"para": "<indexterm>\n <primary>INET_ATON()</primary>\n </indexterm>\n\n <literal role=\"func\">INET_ATON(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"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 <literal role=\"func\">INET_NTOA()</literal> returns\n <literal>NULL</literal> if it does not understand its\n argument."
}
],
"id": "INET_NTOA",
"syntax": [
{
"para": "<indexterm>\n <primary>INET_NTOA()</primary>\n </indexterm>\n\n <literal role=\"func\">INET_NTOA(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"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 <literal role=\"type\">VARBINARY</literal> data type:\n <literal role=\"type\">VARBINARY(16)</literal> for IPv6\n addresses and <literal role=\"type\">VARBINARY(4)</literal> for\n IPv4 addresses. If the argument is not a valid address,\n <literal role=\"func\">INET6_ATON()</literal> returns\n <literal>NULL</literal>."
}
],
"id": "INET6_ATON",
"syntax": [
{
"para": "<indexterm>\n <primary>INET6_ATON()</primary>\n </indexterm>\n\n <literal role=\"func\">INET6_ATON(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"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 <literal role=\"func\">INET6_NTOA()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "<literal role=\"func\">INET6_NTOA()</literal> 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(<replaceable>expr</replaceable>) 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": "<indexterm>\n <primary>INET6_NTOA()</primary>\n </indexterm>\n\n <literal role=\"func\">INET6_NTOA(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"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": "<indexterm>\n <primary>IS_IPV4()</primary>\n </indexterm>\n\n <literal role=\"func\">IS_IPV4(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function takes an IPv6 address represented in numeric\n form as a binary string, as returned by\n <literal role=\"func\">INET6_ATON()</literal>. It returns 1 if\n the argument is a valid IPv4-compatible IPv6 address, 0\n otherwise. IPv4-compatible addresses have the form\n <literal>::<replaceable>ipv4_address</replaceable></literal>."
}
],
"id": "IS_IPV4_COMPAT",
"syntax": [
{
"para": "<indexterm>\n <primary>IS_IPV4_COMPAT()</primary>\n </indexterm>\n\n <literal role=\"func\">IS_IPV4_COMPAT(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This function takes an IPv6 address represented in numeric\n form as a binary string, as returned by\n <literal role=\"func\">INET6_ATON()</literal>. It returns 1 if\n the argument is a valid IPv4-mapped IPv6 address, 0 otherwise.\n IPv4-mapped addresses have the form\n <literal>::ffff:<replaceable>ipv4_address</replaceable></literal>."
}
],
"id": "IS_IPV4_MAPPED",
"syntax": [
{
"para": "<indexterm>\n <primary>IS_IPV4_MAPPED()</primary>\n </indexterm>\n\n <literal role=\"func\">IS_IPV4_MAPPED(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"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": "<indexterm>\n <primary>IS_IPV6()</primary>\n </indexterm>\n\n <literal role=\"func\">IS_IPV6(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": [
"IS_UUID"
],
"description": [
{
"para": "<indexterm>\n <primary>IS_UUID()</primary>\n </indexterm>\n\n <literal role=\"func\">IS_UUID(<replaceable>string_uuid</replaceable>)</literal>"
},
{
"para": "Returns 1 if the argument is a valid string-format UUID, 0 if\n the argument is not a valid UUID, and <literal>NULL</literal>\n if the argument is <literal>NULL</literal>."
},
{
"para": "<quote>Valid</quote> 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 <literal role=\"func\">UUID()</literal> 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 <literal>NULL</literal> 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 <literal>-1</literal> if the timeout has been\n exceeded. If the slave SQL thread stops while\n <literal role=\"func\">MASTER_POS_WAIT()</literal> is waiting,\n the function returns <literal>NULL</literal>. 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 <literal role=\"sysvar\">slave_checkpoint_group</literal> or\n <literal role=\"sysvar\">slave_checkpoint_period</literal>\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 <replaceable>timeout</replaceable> value is specified,\n <literal role=\"func\">MASTER_POS_WAIT()</literal> stops waiting\n when <replaceable>timeout</replaceable> seconds have elapsed.\n <replaceable>timeout</replaceable> must be greater than 0; a\n zero or negative <replaceable>timeout</replaceable> means no\n timeout."
},
{
"para": "The optional <replaceable>channel</replaceable> value enables\n you to name which replication channel the function applies to.\n See <xref linkend=\"replication-channels\" /> for more\n information."
}
],
"id": "MASTER_POS_WAIT",
"syntax": [
{
"para": "<indexterm>\n <primary>MASTER_POS_WAIT()</primary>\n </indexterm>\n\n <literal role=\"func\">MASTER_POS_WAIT(<replaceable>log_name</replaceable>,<replaceable>log_pos</replaceable>[,<replaceable>timeout</replaceable>][,<replaceable>channel</replaceable>])</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the given value. When used to produce a result set\n column, <literal role=\"func\">NAME_CONST()</literal> causes the\n column to have the given name. The arguments should be\n constants."
},
{
"programlisting": ">\nmysql> <userinput>SELECT NAME_CONST('myname', 14);</userinput>\n+--------+\n| myname |\n+--------+\n| 14 |\n+--------+"
}
],
"id": "NAME_CONST",
"syntax": [
{
"para": "<indexterm>\n <primary>NAME_CONST()</primary>\n </indexterm>\n\n <literal role=\"func\">NAME_CONST(<replaceable>name</replaceable>,<replaceable>value</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Sleeps (pauses) for the number of seconds given by the\n <replaceable>duration</replaceable> argument, then returns 0.\n The duration may have a fractional part. If the argument is\n <literal>NULL</literal> or negative,\n <literal role=\"func\">SLEEP()</literal> produces a warning, or\n an error in strict SQL mode."
},
{
"para": "When sleep returns normally (without interruption), it returns\n 0:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT SLEEP(1000);</userinput>\n+-------------+\n| SLEEP(1000) |\n+-------------+\n| 0 |\n+-------------+"
},
{
"para": "When <literal role=\"func\">SLEEP()</literal> 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 <literal condition=\"kill\" role=\"stmt\">KILL QUERY</literal>\n from another session:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT SLEEP(1000);</userinput>\n+-------------+\n| SLEEP(1000) |\n+-------------+\n| 1 |\n+-------------+"
}
],
[
{
"para": "This statement is interrupted by timing out:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT /*+ MAX_EXECUTION_TIME(1) */ SLEEP(1000);</userinput>\n+-------------+\n| SLEEP(1000) |\n+-------------+\n| 1 |\n+-------------+"
}
]
]
},
{
"para": "When <literal role=\"func\">SLEEP()</literal> is only part of a\n query that is interrupted, the query returns an error:"
},
{
"itemizedlist": [
[
{
"para": "This statement is interrupted using\n <literal condition=\"kill\" role=\"stmt\">KILL QUERY</literal>\n from another session:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT 1 FROM t1 WHERE SLEEP(1000);</userinput>\nERROR 1317 (70100): Query execution was interrupted"
}
],
[
{
"para": "This statement is interrupted by timing out:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT /*+ MAX_EXECUTION_TIME(1000) */ 1 FROM t1 WHERE SLEEP(1000);</userinput>\nERROR 3024 (HY000): Query execution was interrupted, maximum statement\nexecution time exceeded"
}
]
]
}
],
"id": "SLEEP",
"syntax": [
{
"para": "<indexterm>\n <primary>SLEEP()</primary>\n </indexterm>\n\n <literal role=\"func\">SLEEP(<replaceable>duration</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a Universal Unique Identifier (UUID) generated\n according to RFC 4122, <quote>A Universally Unique IDentifier\n (UUID) URN Namespace</quote>\n (<ulink url=\"http://www.ietf.org/rfc/rfc4122.txt\" />)."
},
{
"para": "A UUID is designed as a number that is globally unique in\n space and time. Two calls to\n <literal role=\"func\">UUID()</literal> 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": "<literal role=\"func\">UUID()</literal> 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 <literal>utf8</literal>\n string of five hexadecimal numbers in\n <literal>aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee</literal>\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 <emphasis>very</emphasis> 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": "<indexterm>\n <primary>UUID()</primary>\n </indexterm>\n\n <literal role=\"func\">UUID()</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a <quote>short</quote> universal identifier as a\n 64-bit unsigned integer. Values returned by\n <literal role=\"func\">UUID_SHORT()</literal> differ from the\n string-format 128-bit identifiers returned by the\n <literal role=\"func\">UUID()</literal> function and have\n different uniqueness properties. The value of\n <literal role=\"func\">UUID_SHORT()</literal> is guaranteed to\n be unique if the following conditions hold:"
},
{
"itemizedlist": [
[
{
"para": "The <literal role=\"sysvar\">server_id</literal> 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 <command>mysqld</command> restarts"
}
],
[
{
"para": "You invoke <literal role=\"func\">UUID_SHORT()</literal> on\n average fewer than 16 million times per second between\n <command>mysqld</command> restarts"
}
]
]
},
{
"para": "The <literal role=\"func\">UUID_SHORT()</literal> 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": "<indexterm>\n <primary>UUID_SHORT()</primary>\n </indexterm>\n\n <literal role=\"func\">UUID_SHORT()</literal>"
}
]
},
{
"keywords": [
"UUID_TO_BIN"
],
"description": [
{
"para": "<indexterm>\n <primary>UUID_TO_BIN()</primary>\n </indexterm>\n\n <literal role=\"func\">UUID_TO_BIN(<replaceable>string_uuid</replaceable>)</literal>,\n <literal role=\"func\">UUID_TO_BIN(<replaceable>string_uuid</replaceable>,\n <replaceable>swap_flag</replaceable>)</literal>"
},
{
"para": "Converts a string UUID to a binary UUID and returns the\n result. (The <literal role=\"func\">IS_UUID()</literal> function\n description lists the permitted string UUID formats.) The\n return binary UUID is a\n <literal role=\"type\">VARBINARY(16)</literal> value. If the\n UUID argument is <literal>NULL</literal>, the return value is\n <literal>NULL</literal>. If any argument is invalid, an error\n occurs."
},
{
"para": "<literal role=\"func\">UUID_TO_BIN()</literal> 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 <replaceable>swap_flag</replaceable> 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 <replaceable>swap_flag</replaceable> 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 <literal role=\"func\">UUID()</literal> 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 <literal role=\"func\">UUID()</literal> function description."
},
{
"para": "Suppose that you have the following string UUID value:"
},
{
"programlisting": ">\nmysql> <userinput>SET @uuid = '6ccd780c-baba-1026-9564-5b8c656024db';</userinput>"
},
{
"para": "To convert the string UUID to binary with or without time-part\n swapping, use <literal role=\"func\">UUID_TO_BIN()</literal>:"
},
{
"programlisting": ">\n\nmysql> <userinput>SELECT HEX(UUID_TO_BIN(@uuid));</userinput>\n+----------------------------------+\n| HEX(UUID_TO_BIN(@uuid)) |\n+----------------------------------+\n| 6CCD780CBABA102695645B8C656024DB |\n+----------------------------------+\nmysql> <userinput>SELECT HEX(UUID_TO_BIN(@uuid, 0));</userinput>\n+----------------------------------+\n| HEX(UUID_TO_BIN(@uuid, 0)) |\n+----------------------------------+\n| 6CCD780CBABA102695645B8C656024DB |\n+----------------------------------+\nmysql> <userinput>SELECT HEX(UUID_TO_BIN(@uuid, 1));</userinput>\n+----------------------------------+\n| HEX(UUID_TO_BIN(@uuid, 1)) |\n+----------------------------------+\n| 1026BABA6CCD780C95645B8C656024DB |\n+----------------------------------+"
},
{
"para": "To convert a binary UUID returned by\n <literal role=\"func\">UUID_TO_BIN()</literal> to a string UUID,\n use <literal role=\"func\">BIN_TO_UUID()</literal>. If you\n produce a binary UUID by calling\n <literal role=\"func\">UUID_TO_BIN()</literal> with a second\n argument of 1 to swap time parts, you should also pass a\n second argument of 1 to\n <literal role=\"func\">BIN_TO_UUID()</literal> to unswap the\n time parts when converting the binary UUID back to a string\n UUID:"
},
{
"programlisting": ">\n\nmysql> <userinput>SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid));</userinput>\n+--------------------------------------+\n| BIN_TO_UUID(UUID_TO_BIN(@uuid)) |\n+--------------------------------------+\n| 6ccd780c-baba-1026-9564-5b8c656024db |\n+--------------------------------------+\nmysql> <userinput>SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid,0),0);</userinput>\n+--------------------------------------+\n| BIN_TO_UUID(UUID_TO_BIN(@uuid,0),0) |\n+--------------------------------------+\n| 6ccd780c-baba-1026-9564-5b8c656024db |\n+--------------------------------------+\nmysql> <userinput>SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid,1),1);</userinput>\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> <userinput>SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid,0),1);</userinput>\n+--------------------------------------+\n| BIN_TO_UUID(UUID_TO_BIN(@uuid,0),1) |\n+--------------------------------------+\n| baba1026-780c-6ccd-9564-5b8c656024db |\n+--------------------------------------+\nmysql> <userinput>SELECT BIN_TO_UUID(UUID_TO_BIN(@uuid,1),0);</userinput>\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 <literal condition=\"insert-on-duplicate\" role=\"stmt\">INSERT\n ... ON DUPLICATE KEY UPDATE</literal> statement, you can use\n the\n <literal>VALUES(<replaceable>col_name</replaceable>)</literal>\n function in the <literal role=\"stmt\">UPDATE</literal> clause\n to refer to column values from the\n <literal role=\"stmt\">INSERT</literal> portion of the\n statement. In other words,\n <literal>VALUES(<replaceable>col_name</replaceable>)</literal>\n in the <literal role=\"stmt\">UPDATE</literal> clause refers to\n the value of <replaceable>col_name</replaceable> that would be\n inserted, had no duplicate-key conflict occurred. This\n function is especially useful in multiple-row inserts. The\n <literal role=\"func\">VALUES()</literal> function is meaningful\n only in the <literal>ON DUPLICATE KEY UPDATE</literal> clause\n of <literal role=\"stmt\">INSERT</literal> statements and\n returns <literal>NULL</literal> otherwise. See\n <xref linkend=\"insert-on-duplicate\" />."
}
],
"id": "VALUES",
"syntax": [
{
"para": "<indexterm>\n <primary>VALUES()</primary>\n </indexterm>\n\n <literal role=\"func\">VALUES(<replaceable>col_name</replaceable>)</literal>"
}
]
},
{
"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": "<indexterm>\n <primary>JSON_ARRAY()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_ARRAY([<replaceable>val</replaceable>[,\n <replaceable>val</replaceable>] ...])</literal>"
}
]
},
{
"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 <literal>NULL</literal> or the number of\n arguments is odd."
}
],
"id": "JSON_OBJECT",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_OBJECT()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_OBJECT([<replaceable>key</replaceable>,\n <replaceable>val</replaceable>[,\n <replaceable>key</replaceable>,\n <replaceable>val</replaceable>] ...])</literal>"
}
]
},
{
"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 <literal>utf8mb4</literal> string. Returns\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal>."
},
{
"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 <xref linkend=\"json-unquote-character-escape-sequences\" />."
}
],
"id": "JSON_QUOTE",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_QUOTE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_QUOTE(<replaceable>string</replaceable>)</literal>"
}
]
},
{
"keywords": [
"JSON_CONTAINS"
],
"description": [
{
"para": "Indicates by returning 1 or 0 whether a given\n <replaceable>candidate</replaceable> JSON document is\n contained within a <replaceable>target</replaceable> JSON\n document, ormdashif a <replaceable>path</replaceable>\n argument was suppliedmdashwhether the candidate is found at\n a specific path within the target. Returns\n <literal>NULL</literal> if any argument is\n <literal>NULL</literal>, or if the path argument does not\n identify a section of the target document. An error occurs if\n <replaceable>target</replaceable> or\n <replaceable>candidate</replaceable> is not a valid JSON\n document, or if the <replaceable>path</replaceable> argument\n is not a valid path expression or contains a\n <literal>*</literal> or <literal>**</literal> wildcard."
},
{
"para": "To check only whether any data exists at the path, use\n <literal role=\"func\">JSON_CONTAINS_PATH()</literal> 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 <literal role=\"func\">JSON_TYPE()</literal> types, with the\n exception that values of types <literal>INTEGER</literal>\n and <literal>DECIMAL</literal> 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 <literal>JSON_CONTAINS()</literal> on\n <literal role=\"se\">InnoDB</literal> tables can be optimized\n using multi-valued indexes; see\n <xref linkend=\"create-index-multi-valued\" />, for more\n information."
}
],
"id": "JSON_CONTAINS",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_CONTAINS()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_CONTAINS(<replaceable>target</replaceable>,\n <replaceable>candidate</replaceable>[,\n <replaceable>path</replaceable>])</literal>"
}
]
},
{
"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 <literal>NULL</literal>\n if any argument is <literal>NULL</literal>. An error occurs if\n the <replaceable>json_doc</replaceable> argument is not a\n valid JSON document, any <replaceable>path</replaceable>\n argument is not a valid path expression, or\n <replaceable>one_or_all</replaceable> is not\n <literal>'one'</literal> or <literal>'all'</literal>."
},
{
"para": "To check for a specific value at a path, use\n <literal role=\"func\">JSON_CONTAINS()</literal> instead."
},
{
"para": "The return value is 0 if no specified path exists within the\n document. Otherwise, the return value depends on the\n <replaceable>one_or_all</replaceable> argument:"
},
{
"itemizedlist": [
[
{
"para": "<literal>'one'</literal>: 1 if at least one path exists\n within the document, 0 otherwise."
}
],
[
{
"para": "<literal>'all'</literal>: 1 if all paths exist within the\n document, 0 otherwise."
}
]
]
}
],
"id": "JSON_CONTAINS_PATH",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_CONTAINS_PATH()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_CONTAINS_PATH(<replaceable>json_doc</replaceable>,\n <replaceable>one_or_all</replaceable>,\n <replaceable>path</replaceable>[,\n <replaceable>path</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"JSON_EXTRACT"
],
"description": [
{
"para": "Returns data from a JSON document, selected from the parts of\n the document matched by the <replaceable>path</replaceable>\n arguments. Returns <literal>NULL</literal> if any argument is\n <literal>NULL</literal> or no paths locate a value in the\n document. An error occurs if the\n <replaceable>json_doc</replaceable> argument is not a valid\n JSON document or any <replaceable>path</replaceable> argument\n is not a valid path expression."
},
{
"para": "The return value consists of all values matched by the\n <replaceable>path</replaceable> 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": "<indexterm>\n <primary>JSON_EXTRACT()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_EXTRACT(<replaceable>json_doc</replaceable>,\n <replaceable>path</replaceable>[,\n <replaceable>path</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"->",
"(JSON",
"extraction)"
],
"description": [
{
"para": "The\n <literal condition=\"json-column-path\" role=\"op\">-></literal>\n operator serves as an alias for the\n <literal role=\"func\">JSON_EXTRACT()</literal> 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": "<indexterm>\n <primary>-></primary>\n </indexterm>\n\n <literal condition=\"json-column-path\" role=\"op\"><replaceable>column</replaceable>-><replaceable>path</replaceable></literal>"
}
]
},
{
"keywords": [
"->>",
"(JSON",
"inline",
"path)"
],
"description": [
{
"para": "This is an improved, unquoting extraction operator. Whereas\n the <literal>-></literal> operator simply extracts a value,\n the <literal>->></literal> operator in addition unquotes\n the extracted result. In other words, given a\n <literal role=\"type\">JSON</literal> column value\n <replaceable>column</replaceable> and a path expression\n <replaceable>path</replaceable>, the following three\n expressions return the same value:"
},
{
"itemizedlist": [
[
{
"para": "<literal role=\"func\">JSON_UNQUOTE(</literal>\n <literal role=\"func\">JSON_EXTRACT(<replaceable>column</replaceable>,\n <replaceable>path</replaceable>) )</literal>"
}
],
[
{
"para": "<literal>JSON_UNQUOTE(<replaceable>column</replaceable></literal>\n <literal condition=\"json-column-path\" role=\"op\">-></literal>\n <literal><replaceable>path</replaceable>)</literal>"
}
],
[
{
"para": "<literal><replaceable>column</replaceable>->><replaceable>path</replaceable></literal>"
}
]
]
},
{
"para": "The <literal>->></literal> operator can be used wherever\n <literal>JSON_UNQUOTE(JSON_EXTRACT())</literal> would be\n allowed. This includes (but is not limited to)\n <literal>SELECT</literal> lists, <literal>WHERE</literal> and\n <literal>HAVING</literal> clauses, and <literal>ORDER\n BY</literal> and <literal>GROUP BY</literal> clauses."
}
],
"id": "->>",
"syntax": [
{
"para": "<indexterm>\n <primary>->></primary>\n </indexterm>\n\n <literal condition=\"json-inline-path\" role=\"op\"><replaceable>column</replaceable>->><replaceable>path</replaceable></literal>"
}
]
},
{
"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 <replaceable>path</replaceable>\n argument is given, the top-level keys from the selected path.\n Returns <literal>NULL</literal> if any argument is\n <literal>NULL</literal>, the\n <replaceable>json_doc</replaceable> argument is not an object,\n or <replaceable>path</replaceable>, if given, does not locate\n an object. An error occurs if the\n <replaceable>json_doc</replaceable> argument is not a valid\n JSON document or the <replaceable>path</replaceable> argument\n is not a valid path expression or contains a\n <literal>*</literal> or <literal>**</literal> 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": "<indexterm>\n <primary>JSON_KEYS()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_KEYS(<replaceable>json_doc</replaceable>[,\n <replaceable>path</replaceable>])</literal>"
}
]
},
{
"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 <literal role=\"func\">JSON_CONTAINS()</literal>, which requires\n all elements of the array searched for to be present in the\n array searched in. Thus, <literal>JSON_CONTAINS()</literal>\n performs an <literal>AND</literal> operation on search keys,\n while <literal>JSON_OVERLAPS()</literal> performs an\n <literal>OR</literal> operation."
},
{
"para": "Queries on JSON columns of <literal role=\"se\">InnoDB</literal>\n tables using <literal>JSON_OVERLAPS()</literal> in the\n <literal>WHERE</literal> clause can be optimized using\n multi-valued indexes.\n <xref linkend=\"create-index-multi-valued\" />, provides detailed\n information and examples."
}
],
"id": "JSON_OVERLAPS",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_OVERLAPS()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_OVERLAPS(<replaceable>json_doc1</replaceable>,\n <replaceable>json_doc2</replaceable>)</literal>"
}
]
},
{
"keywords": [
"JSON_SEARCH"
],
"description": [
{
"para": "Returns the path to the given string within a JSON document.\n Returns <literal>NULL</literal> if any of the\n <replaceable>json_doc</replaceable>,\n <replaceable>search_str</replaceable>, or\n <replaceable>path</replaceable> arguments are\n <literal>NULL</literal>; no <replaceable>path</replaceable>\n exists within the document; or\n <replaceable>search_str</replaceable> is not found. An error\n occurs if the <replaceable>json_doc</replaceable> argument is\n not a valid JSON document, any <replaceable>path</replaceable>\n argument is not a valid path expression,\n <replaceable>one_or_all</replaceable> is not\n <literal>'one'</literal> or <literal>'all'</literal>, or\n <replaceable>escape_char</replaceable> is not a constant\n expression."
},
{
"para": "The <replaceable>one_or_all</replaceable> argument affects the\n search as follows:"
},
{
"itemizedlist": [
[
{
"para": "<literal>'one'</literal>: The search terminates after the\n first match and returns one path string. It is undefined\n which match is considered first."
}
],
[
{
"para": "<literal>'all'</literal>: 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 <replaceable>search_str</replaceable> search string\n argument, the <literal>%</literal> and <literal>_</literal>\n characters work as for the <literal role=\"op\">LIKE</literal>\n operator: <literal>%</literal> matches any number of\n characters (including zero characters), and\n <literal>_</literal> matches exactly one character."
},
{
"para": "To specify a literal <literal>%</literal> or\n <literal>_</literal> character in the search string, precede\n it by the escape character. The default is\n <literal>\\</literal> if the\n <replaceable>escape_char</replaceable> argument is missing or\n <literal>NULL</literal>. Otherwise,\n <replaceable>escape_char</replaceable> 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 <literal role=\"op\">LIKE</literal> in\n <xref linkend=\"string-comparison-functions\" />. For escape\n character handling, a difference from the\n <literal role=\"op\">LIKE</literal> behavior is that the escape\n character for <literal role=\"func\">JSON_SEARCH()</literal>\n must evaluate to a constant at compile time, not just at\n execution time. For example, if\n <literal role=\"func\">JSON_SEARCH()</literal> is used in a\n prepared statement and the\n <replaceable>escape_char</replaceable> argument is supplied\n using a <literal>?</literal> parameter, the parameter value\n might be constant at execution time, but is not at compile\n time."
}
],
"id": "JSON_SEARCH",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_SEARCH()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_SEARCH(<replaceable>json_doc</replaceable>,\n <replaceable>one_or_all</replaceable>,\n <replaceable>search_str</replaceable>[,\n <replaceable>escape_char</replaceable>[,\n <replaceable>path</replaceable>] ...])</literal>"
}
]
},
{
"keywords": [
"MEMBER",
"OF"
],
"description": [
{
"para": "Returns true (1) if <replaceable>value</replaceable> is an\n element of <replaceable>json_array</replaceable>, otherwise\n returns false (0). <replaceable>value</replaceable> 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 <literal>MEMBER OF()</literal> on JSON columns\n of <literal role=\"se\">InnoDB</literal> tables in the\n <literal>WHERE</literal> clause can be optimized using\n multi-valued indexes. See\n <xref linkend=\"create-index-multi-valued\" />, for detailed\n information and examples."
}
],
"id": "MEMBER OF",
"syntax": [
{
"para": "<indexterm>\n <primary>MEMBER OF()</primary>\n </indexterm>\n\n <literal condition=\"member-of\" role=\"op\"><replaceable>value</replaceable>\n MEMBER OF(<replaceable>json_array</replaceable>)</literal>"
}
]
},
{
"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 <literal>NULL</literal> if any argument is\n <literal>NULL</literal>. An error occurs if the\n <replaceable>json_doc</replaceable> argument is not a valid\n JSON document or any <replaceable>path</replaceable> argument\n is not a valid path expression or contains a\n <literal>*</literal> or <literal>**</literal> 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": "<indexterm>\n <primary>JSON_ARRAY_APPEND()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_ARRAY_APPEND(<replaceable>json_doc</replaceable>,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>[,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>] ...)</literal>"
}
]
},
{
"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 <literal>NULL</literal> if any argument is\n <literal>NULL</literal>. An error occurs if the\n <replaceable>json_doc</replaceable> argument is not a valid\n JSON document or any <replaceable>path</replaceable> argument\n is not a valid path expression or contains a\n <literal>*</literal> or <literal>**</literal> 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": "<indexterm>\n <primary>JSON_ARRAY_INSERT()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_ARRAY_INSERT(<replaceable>json_doc</replaceable>,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>[,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"JSON_INSERT"
],
"description": [
{
"para": "Inserts data into a JSON document and returns the result.\n Returns <literal>NULL</literal> if any argument is\n <literal>NULL</literal>. An error occurs if the\n <replaceable>json_doc</replaceable> argument is not a valid\n JSON document or any <replaceable>path</replaceable> argument\n is not a valid path expression or contains a\n <literal>*</literal> or <literal>**</literal> 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 <literal role=\"func\">JSON_INSERT()</literal>,\n <literal role=\"func\">JSON_REPLACE()</literal>, and\n <literal role=\"func\">JSON_SET()</literal>, see the discussion\n of <literal role=\"func\">JSON_SET()</literal>."
}
],
"id": "JSON_INSERT",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_INSERT()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_INSERT(<replaceable>json_doc</replaceable>,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>[,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"JSON_MERGE"
],
"description": [
{
"para": "Merges two or more JSON documents. Synonym for\n <literal>JSON_MERGE_PRESERVE()</literal>; deprecated in MySQL\n 8.0.3 and subject to removal in a future release."
}
],
"id": "JSON_MERGE",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_MERGE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_MERGE(<replaceable>json_doc</replaceable>,\n <replaceable>json_doc</replaceable>[,\n <replaceable>json_doc</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"JSON_MERGE_PATCH"
],
"description": [
{
"para": "Performs an\n <ulink url=\"https://tools.ietf.org/html/rfc7396\">RFC\n 7396</ulink> 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": "<literal>JSON_MERGE_PATCH()</literal> performs a merge as\n follows:"
},
{
"para": "For additional information, see\n <xref linkend=\"json-normalization\" />."
}
],
"id": "JSON_MERGE_PATCH()",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_MERGE_PATCH()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_MERGE_PATCH(<replaceable>json_doc</replaceable>,\n <replaceable>json_doc</replaceable>[,\n <replaceable>json_doc</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"JSON_MERGE_PRESERVE"
],
"description": [
{
"para": "Merges two or more JSON documents and returns the merged\n result. Returns <literal>NULL</literal> if any argument is\n <literal>NULL</literal>. 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 <xref linkend=\"json-normalization\" />."
},
{
"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": "<indexterm>\n <primary>JSON_MERGE_PRESERVE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_MERGE_PRESERVE(<replaceable>json_doc</replaceable>,\n <replaceable>json_doc</replaceable>[,\n <replaceable>json_doc</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"JSON_REMOVE"
],
"description": [
{
"para": "Removes data from a JSON document and returns the result.\n Returns <literal>NULL</literal> if any argument is\n <literal>NULL</literal>. An error occurs if the\n <replaceable>json_doc</replaceable> argument is not a valid\n JSON document or any <replaceable>path</replaceable> argument\n is not a valid path expression or is <literal>$</literal> or\n contains a <literal>*</literal> or <literal>**</literal>\n wildcard."
},
{
"para": "The <replaceable>path</replaceable> 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": "<indexterm>\n <primary>JSON_REMOVE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_REMOVE(<replaceable>json_doc</replaceable>,\n <replaceable>path</replaceable>[,\n <replaceable>path</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"JSON_REPLACE"
],
"description": [
{
"para": "Replaces existing values in a JSON document and returns the\n result. Returns <literal>NULL</literal> if any argument is\n <literal>NULL</literal>. An error occurs if the\n <replaceable>json_doc</replaceable> argument is not a valid\n JSON document or any <replaceable>path</replaceable> argument\n is not a valid path expression or contains a\n <literal>*</literal> or <literal>**</literal> 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 <literal>JSON</literal> 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 <literal role=\"func\">JSON_REPLACE()</literal> function and\n meets the conditions outlined in\n <xref linkend=\"json-partial-updates\" />."
},
{
"para": "For a comparison of\n <literal role=\"func\">JSON_INSERT()</literal>,\n <literal role=\"func\">JSON_REPLACE()</literal>, and\n <literal role=\"func\">JSON_SET()</literal>, see the discussion\n of <literal role=\"func\">JSON_SET()</literal>."
}
],
"id": "JSON_REPLACE",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_REPLACE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_REPLACE(<replaceable>json_doc</replaceable>,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>[,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"JSON_SET"
],
"description": [
{
"para": "Inserts or updates data in a JSON document and returns the\n result. Returns <literal>NULL</literal> if any argument is\n <literal>NULL</literal> or <replaceable>path</replaceable>, if\n given, does not locate an object. An error occurs if the\n <replaceable>json_doc</replaceable> argument is not a valid\n JSON document or any <replaceable>path</replaceable> argument\n is not a valid path expression or contains a\n <literal>*</literal> or <literal>**</literal> 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 <literal>JSON</literal> 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 <literal role=\"func\">JSON_SET()</literal> function and meets\n the conditions outlined in\n <xref linkend=\"json-partial-updates\" />."
},
{
"para": "The <literal role=\"func\">JSON_SET()</literal>,\n <literal role=\"func\">JSON_INSERT()</literal>, and\n <literal role=\"func\">JSON_REPLACE()</literal> functions are\n related:"
},
{
"itemizedlist": [
[
{
"para": "<literal role=\"func\">JSON_SET()</literal> replaces\n existing values and adds nonexisting values."
}
],
[
{
"para": "<literal role=\"func\">JSON_INSERT()</literal> inserts\n values without replacing existing values."
}
],
[
{
"para": "<literal role=\"func\">JSON_REPLACE()</literal> replaces\n <emphasis>only</emphasis> existing values."
}
]
]
}
],
"id": "JSON_SET",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_SET()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_SET(<replaceable>json_doc</replaceable>,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>[,\n <replaceable>path</replaceable>,\n <replaceable>val</replaceable>] ...)</literal>"
}
]
},
{
"keywords": [
"JSON_UNQUOTE"
],
"description": [
{
"para": "Unquotes JSON value and returns the result as a\n <literal>utf8mb4</literal> string. Returns\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal>. 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": "<indexterm>\n <primary>JSON_UNQUOTE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_UNQUOTE(<replaceable>json_val</replaceable>)</literal>"
}
]
},
{
"keywords": [
"JSON_DEPTH"
],
"description": [
{
"para": "Returns the maximum depth of a JSON document. Returns\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal>. 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": "<indexterm>\n <primary>JSON_DEPTH()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_DEPTH(<replaceable>json_doc</replaceable>)</literal>"
}
]
},
{
"keywords": [
"JSON_LENGTH"
],
"description": [
{
"para": "Returns the length of a JSON document, or, if a\n <replaceable>path</replaceable> argument is given, the length\n of the value within the document identified by the path.\n Returns <literal>NULL</literal> if any argument is\n <literal>NULL</literal> or the <replaceable>path</replaceable>\n argument does not identify a value in the document. An error\n occurs if the <replaceable>json_doc</replaceable> argument is\n not a valid JSON document or the\n <replaceable>path</replaceable> argument is not a valid path\n expression or contains a <literal>*</literal> or\n <literal>**</literal> 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": "<indexterm>\n <primary>JSON_LENGTH()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_LENGTH(<replaceable>json_doc</replaceable>[,\n <replaceable>path</replaceable>])</literal>"
}
]
},
{
"keywords": [
"JSON_TYPE"
],
"description": [
{
"para": "Returns a <literal>utf8mb4</literal> 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> <userinput>SET @j = '{\"a\": [10, true]}';</userinput>\nmysql> <userinput>SELECT JSON_TYPE(@j);</userinput>\n+---------------+\n| JSON_TYPE(@j) |\n+---------------+\n| OBJECT |\n+---------------+\nmysql> <userinput>SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a'));</userinput>\n+------------------------------------+\n| JSON_TYPE(JSON_EXTRACT(@j, '$.a')) |\n+------------------------------------+\n| ARRAY |\n+------------------------------------+\nmysql> <userinput>SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]'));</userinput>\n+---------------------------------------+\n| JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]')) |\n+---------------------------------------+\n| INTEGER |\n+---------------------------------------+\nmysql> <userinput>SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]'));</userinput>\n+---------------------------------------+\n| JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]')) |\n+---------------------------------------+\n| BOOLEAN |\n+---------------------------------------+"
},
{
"para": "<literal role=\"func\">JSON_TYPE()</literal> returns\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal>:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT JSON_TYPE(NULL);</userinput>\n+-----------------+\n| JSON_TYPE(NULL) |\n+-----------------+\n| NULL |\n+-----------------+"
},
{
"para": "An error occurs if the argument is not a valid JSON value:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT JSON_TYPE(1);</userinput>\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-<literal>NULL</literal>, non-error result, the\n following list describes the possible\n <literal role=\"func\">JSON_TYPE()</literal> return values:"
},
{
"itemizedlist": [
[
{
"para": "Purely JSON types:"
},
{
"itemizedlist": [
[
{
"para": "<literal>OBJECT</literal>: JSON objects"
}
],
[
{
"para": "<literal>ARRAY</literal>: JSON arrays"
}
],
[
{
"para": "<literal>BOOLEAN</literal>: The JSON true and false\n literals"
}
],
[
{
"para": "<literal>NULL</literal>: The JSON null literal"
}
]
]
}
],
[
{
"para": "Numeric types:"
},
{
"itemizedlist": [
[
{
"para": "<literal>INTEGER</literal>: MySQL\n <literal role=\"type\">TINYINT</literal>,\n <literal role=\"type\">SMALLINT</literal>,\n <literal role=\"type\">MEDIUMINT</literal> and\n <literal role=\"type\">INT</literal> and\n <literal role=\"type\">BIGINT</literal> scalars"
}
],
[
{
"para": "<literal>DOUBLE</literal>: MySQL\n <literal role=\"type\">DOUBLE</literal>\n <literal role=\"type\">FLOAT</literal> scalars"
}
],
[
{
"para": "<literal>DECIMAL</literal>: MySQL\n <literal role=\"type\">DECIMAL</literal> and\n <literal role=\"type\">NUMERIC</literal> scalars"
}
]
]
}
],
[
{
"para": "Temporal types:"
},
{
"itemizedlist": [
[
{
"para": "<literal>DATETIME</literal>: MySQL\n <literal role=\"type\">DATETIME</literal> and\n <literal role=\"type\">TIMESTAMP</literal> scalars"
}
],
[
{
"para": "<literal>DATE</literal>: MySQL\n <literal role=\"type\">DATE</literal> scalars"
}
],
[
{
"para": "<literal>TIME</literal>: MySQL\n <literal role=\"type\">TIME</literal> scalars"
}
]
]
}
],
[
{
"para": "String types:"
},
{
"itemizedlist": [
[
{
"para": "<literal>STRING</literal>: MySQL\n <literal>utf8</literal> character type scalars:\n <literal role=\"type\">CHAR</literal>,\n <literal role=\"type\">VARCHAR</literal>,\n <literal role=\"type\">TEXT</literal>,\n <literal role=\"type\">ENUM</literal>, and\n <literal role=\"type\">SET</literal>"
}
]
]
}
],
[
{
"para": "Binary types:"
},
{
"itemizedlist": [
[
{
"para": "<literal>BLOB</literal>: MySQL binary type scalars\n including <literal role=\"type\">BINARY</literal>,\n <literal role=\"type\">VARBINARY</literal>,\n <literal role=\"type\">BLOB</literal>, and\n <literal role=\"type\">BIT</literal>"
}
]
]
}
],
[
{
"para": "All other types:"
},
{
"itemizedlist": [
[
{
"para": "<literal>OPAQUE</literal> (raw bits)"
}
]
]
}
]
]
}
],
"id": "JSON_TYPE",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_TYPE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_TYPE(<replaceable>json_val</replaceable>)</literal>"
}
]
},
{
"keywords": [
"JSON_VALID"
],
"description": [
{
"para": "Returns 0 or 1 to indicate whether a value is valid JSON.\n Returns <literal>NULL</literal> if the argument is\n <literal>NULL</literal>."
}
],
"id": "JSON_VALID",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_VALID()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_VALID(<replaceable>val</replaceable>)</literal>"
}
]
},
{
"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 <replaceable>expr</replaceable>,\n <replaceable>path</replaceable> COLUMNS (<replaceable>column_list</replaceable>)\n) [AS] <replaceable>alias</replaceable>\n\n<replaceable>column_list</replaceable>:\n <replaceable>column</replaceable>[, <replaceable>column</replaceable>][, ...]\n\n<replaceable>column</replaceable>:\n <replaceable>name</replaceable> FOR ORDINALITY\n | <replaceable>name</replaceable> <replaceable>type</replaceable> PATH <replaceable>string path</replaceable> [<replaceable>on_empty</replaceable>] [<replaceable>on_error</replaceable>]\n | <replaceable>name</replaceable> <replaceable>type</replaceable> EXISTS PATH <replaceable>string path</replaceable>\n | NESTED [PATH] <replaceable>path</replaceable> COLUMNS (<replaceable>column_list</replaceable>)\n\n<replaceable>on_empty</replaceable>:\n {NULL | ERROR | DEFAULT <replaceable>json_string</replaceable>} ON EMPTY\n\n<replaceable>on_error</replaceable>:\n {NULL | ERROR | DEFAULT <replaceable>json_string</replaceable>} ON ERROR"
},
{
"para": "<replaceable>expr</replaceable>: This is an expression that\n returns JSON data. This can be a constant\n (<literal>'{\"a\":1}'</literal>), a column\n (<literal>t1.json_data</literal>, given table\n <literal>t1</literal> specified prior to\n <literal>JSON_TABLE()</literal> in the <literal>FROM</literal>\n clause), or a function call\n (<literal>JSON_EXTRACT(t1,jsn_data,'$.post.comments')</literal>)."
},
{
"para": "<replaceable>path</replaceable>: A JSON path expression, which\n is applied to the data source. We refer to the JSON value\n matching the path as the <emphasis>row source</emphasis>; this\n is used to generate a row of relational data. The\n <literal>COLUMNS</literal> 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 <replaceable>alias</replaceable> is required. The usual\n rules for table aliases apply (see\n <xref linkend=\"identifiers\" />)."
}
],
"id": "JSON_TABLE",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_TABLE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_TABLE(<replaceable>expr</replaceable>,\n <replaceable>path</replaceable> COLUMNS\n (<replaceable>column_list</replaceable>) [AS]\n <replaceable>alias</replaceable>)</literal>"
}
]
},
{
"keywords": [
"JSON_SCHEMA_VALID"
],
"description": [
{
"para": "<indexterm>\n <primary>JSON_SCHEMA_VALID()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_SCHEMA_VALID(<replaceable>schema</replaceable>,<replaceable>document</replaceable>)</literal>"
},
{
"para": "Validates a JSON <replaceable>document</replaceable> against a\n JSON <replaceable>schema</replaceable>. Both\n <replaceable>schema</replaceable> and\n <replaceable>document</replaceable> 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": "<indexterm>\n <primary>JSON_SCHEMA_VALIDATION_REPORT()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_SCHEMA_VALIDATION_REPORT(<replaceable>schema</replaceable>,<replaceable>document</replaceable>)</literal>"
},
{
"para": "Validates a JSON <replaceable>document</replaceable> against a\n JSON <replaceable>schema</replaceable>. Both\n <replaceable>schema</replaceable> and\n <replaceable>document</replaceable> 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 <literal>valid</literal> 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": "<literal>valid</literal>: Always \"false\" for a failed\n schema validation"
}
],
[
{
"para": "<literal>reason</literal>: A human-readable string\n containing the reason for the failure"
}
],
[
{
"para": "<literal>schema-location</literal>: A JSON pointer URI\n fragment identifier indicating where in the JSON schema\n the validation failed (see Note following this list)"
}
],
[
{
"para": "<literal>document-location</literal>: A JSON pointer URI\n fragment identifier indicating where in the JSON document\n the validation failed (see Note following this list)"
}
],
[
{
"para": "<literal>schema-failed-keyword</literal>: 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": "<indexterm>\n <primary>JSON_PRETTY()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_PRETTY(<replaceable>json_val</replaceable>)</literal>"
},
{
"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 <literal>NULL</literal> value, the function\n returns <literal>NULL</literal>. 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 ('<literal>: </literal>')."
}
],
[
{
"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 <literal role=\"func\">JSON_QUOTE()</literal> function."
}
]
]
}
],
"id": "JSON_PRETTY",
"syntax": []
},
{
"keywords": [
"JSON_STORAGE_FREE"
],
"description": [
{
"para": "<indexterm>\n <primary>JSON_STORAGE_FREE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_STORAGE_FREE(<replaceable>json_val</replaceable>)</literal>"
},
{
"para": "For a <literal role=\"type\">JSON</literal> 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 <literal role=\"func\">JSON_SET()</literal>,\n <literal role=\"func\">JSON_REPLACE()</literal>, or\n <literal role=\"func\">JSON_REMOVE()</literal>. 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 <literal>JSON</literal> 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 <literal>JSON</literal> 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 <literal>NULL</literal> if the argument is\n <literal>NULL</literal>."
},
{
"para": "If <replaceable>json_val</replaceable> is not\n <literal>NULL</literal>, 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": "<indexterm>\n <primary>JSON_STORAGE_SIZE()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_STORAGE_SIZE(<replaceable>json_val</replaceable>)</literal>"
},
{
"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 <literal>JSON</literal> 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. <replaceable>json_val</replaceable> 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 <literal>NULL</literal> if the argument is\n <literal>NULL</literal>."
},
{
"para": "An error results when <replaceable>json_val</replaceable> is\n not <literal>NULL</literal>, and is notmdashor cannot be\n successfully parsed asmdasha JSON document."
}
],
"id": "JSON_STORAGE_SIZE",
"syntax": []
},
{
"keywords": [
"FALSE",
"TRUE"
],
"description": [
{
"para": "The constants <literal>TRUE</literal> and\n <literal>FALSE</literal> evaluate to <literal>1</literal> and\n <literal>0</literal>, respectively. The constant names can be\n written in any lettercase."
},
{
"programlisting": ">\nmysql> <userinput>SELECT TRUE, true, FALSE, false;</userinput>\n -> 1, 1, 0, 0"
}
],
"id": "TRUE",
"syntax": []
},
{
"keywords": [
"ST_GeomCollFromText",
"ST_GeometryCollectionFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_GeomCollFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_GeometryCollectionFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_GeomCollFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-geomcollfromtext\" role=\"func\">ST_GeometryCollectionFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-geomcollfromtext\" role=\"func\">ST_GeomCollFromTxt(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>GeometryCollection</literal> 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": "<indexterm>\n <primary>ST_GeomFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_GeometryFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_GeomFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-geomfromtext\" role=\"func\">ST_GeometryFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"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": "<indexterm>\n <primary>ST_LineFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_LineStringFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_LineFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-linefromtext\" role=\"func\">ST_LineStringFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>LineString</literal> 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": "<indexterm>\n <primary>ST_MLineFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_MultiLineStringFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_MLineFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-mlinefromtext\" role=\"func\">ST_MultiLineStringFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>MultiLineString</literal> 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": "<indexterm>\n <primary>ST_MPointFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_MultiPointFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_MPointFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-mpointfromtext\" role=\"func\">ST_MultiPointFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>MultiPoint</literal> 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": "<indexterm>\n <primary>ST_MPolyFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_MultiPolygonFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_MPolyFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-mpolyfromtext\" role=\"func\">ST_MultiPolygonFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>MultiPolygon</literal> 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": "<indexterm>\n <primary>ST_PointFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_PointFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>Point</literal> value using its WKT\n representation and SRID."
},
{
"para": "<literal role=\"func\">ST_PointFromText()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_PointFromText",
"syntax": []
},
{
"keywords": [
"ST_PolyFromText",
"ST_PolygonFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_PolyFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_PolygonFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_PolyFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-polyfromtext\" role=\"func\">ST_PolygonFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>Polygon</literal> 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": "<indexterm>\n <primary>ST_GeomCollFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_GeometryCollectionFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_GeomCollFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-geomcollfromwkb\" role=\"func\">ST_GeometryCollectionFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>GeometryCollection</literal> 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": "<indexterm>\n <primary>ST_GeomFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_GeometryFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_GeomFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-geomfromwkb\" role=\"func\">ST_GeometryFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"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": "<indexterm>\n <primary>ST_LineFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_LineStringFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_LineFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-linefromwkb\" role=\"func\">ST_LineStringFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>LineString</literal> 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": "<indexterm>\n <primary>ST_MLineFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_MultiLineStringFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_MLineFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-mlinefromwkb\" role=\"func\">ST_MultiLineStringFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>MultiLineString</literal> 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": "<indexterm>\n <primary>ST_MPointFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_MultiPointFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_MPointFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-mpointfromwkb\" role=\"func\">ST_MultiPointFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>MultiPoint</literal> 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": "<indexterm>\n <primary>ST_MPolyFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_MultiPolygonFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_MPolyFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-mpolyfromwkb\" role=\"func\">ST_MultiPolygonFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>MultiPolygon</literal> 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": "<indexterm>\n <primary>ST_PointFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_PointFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>Point</literal> value using its WKB\n representation and SRID."
},
{
"para": "<literal role=\"func\">ST_PointFromWKB()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_PointFromWKB",
"syntax": []
},
{
"keywords": [
"ST_PolyFromWKB",
"ST_PolygonFromWKB"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_PolyFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_PolygonFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_PolyFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>,\n <literal condition=\"st-polyfromwkb\" role=\"func\">ST_PolygonFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Constructs a <literal>Polygon</literal> 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": "<literal role=\"func\">GeomCollection(<replaceable>g</replaceable>\n [, <replaceable>g</replaceable>] ...)</literal>"
},
{
"para": "Constructs a <literal>GeomCollection</literal> value from the\n geometry arguments."
},
{
"para": "<literal role=\"func\">GeomCollection()</literal> returns all\n the proper geometries contained in the arguments even if a\n nonsupported geometry is present."
},
{
"para": "<literal role=\"func\">GeomCollection()</literal> with no\n arguments is permitted as a way to create an empty geometry.\n Also, functions such as\n <literal role=\"func\">ST_GeomFromText()</literal> that accept\n WKT geometry collection arguments understand both OpenGIS\n <literal>'GEOMETRYCOLLECTION EMPTY'</literal> standard syntax\n and MySQL <literal>'GEOMETRYCOLLECTION()'</literal>\n nonstandard syntax."
},
{
"para": "<literal role=\"func\">GeomCollection()</literal> and\n <literal role=\"func\">GeometryCollection()</literal> are\n synonymous, with\n <literal role=\"func\">GeomCollection()</literal> the preferred\n function."
}
],
"id": "GeomCollection",
"syntax": []
},
{
"keywords": [
"GeometryCollection"
],
"description": [
{
"para": "<literal role=\"func\">GeometryCollection(<replaceable>g</replaceable>\n [, <replaceable>g</replaceable>] ...)</literal>"
},
{
"para": "Constructs a <literal>GeomCollection</literal> value from the\n geometry arguments."
},
{
"para": "<literal role=\"func\">GeometryCollection()</literal> returns\n all the proper geometries contained in the arguments even if a\n nonsupported geometry is present."
},
{
"para": "<literal role=\"func\">GeometryCollection()</literal> with no\n arguments is permitted as a way to create an empty geometry.\n Also, functions such as\n <literal role=\"func\">ST_GeomFromText()</literal> that accept\n WKT geometry collection arguments understand both OpenGIS\n <literal>'GEOMETRYCOLLECTION EMPTY'</literal> standard syntax\n and MySQL <literal>'GEOMETRYCOLLECTION()'</literal>\n nonstandard syntax."
},
{
"para": "<literal role=\"func\">GeomCollection()</literal> and\n <literal role=\"func\">GeometryCollection()</literal> are\n synonymous, with\n <literal role=\"func\">GeomCollection()</literal> the preferred\n function."
}
],
"id": "GeometryCollection",
"syntax": []
},
{
"keywords": [
"LineString"
],
"description": [
{
"para": "<literal role=\"func\">LineString(<replaceable>pt</replaceable>\n [, <replaceable>pt</replaceable>] ...)</literal>"
},
{
"para": "Constructs a <literal>LineString</literal> value from a number\n of <literal>Point</literal> or WKB <literal>Point</literal>\n arguments. If the number of arguments is less than two, the\n return value is <literal>NULL</literal>."
}
],
"id": "LineString",
"syntax": []
},
{
"keywords": [
"MultiLineString"
],
"description": [
{
"para": "<literal role=\"func\">MultiLineString(<replaceable>ls</replaceable>\n [, <replaceable>ls</replaceable>] ...)</literal>"
},
{
"para": "Constructs a <literal>MultiLineString</literal> value using\n <literal>LineString</literal> or WKB\n <literal>LineString</literal> arguments."
}
],
"id": "MultiLineString",
"syntax": []
},
{
"keywords": [
"MultiPoint"
],
"description": [
{
"para": "<literal role=\"func\">MultiPoint(<replaceable>pt</replaceable>\n [, <replaceable>pt2</replaceable>] ...)</literal>"
},
{
"para": "Constructs a <literal>MultiPoint</literal> value using\n <literal>Point</literal> or WKB <literal>Point</literal>\n arguments."
}
],
"id": "MultiPoint",
"syntax": []
},
{
"keywords": [
"MultiPolygon"
],
"description": [
{
"para": "<literal role=\"func\">MultiPolygon(<replaceable>poly</replaceable>\n [, <replaceable>poly</replaceable>] ...)</literal>"
},
{
"para": "Constructs a <literal>MultiPolygon</literal> value from a set\n of <literal>Polygon</literal> or WKB\n <literal>Polygon</literal> arguments."
}
],
"id": "MultiPolygon",
"syntax": []
},
{
"keywords": [
"Point"
],
"description": [
{
"para": "<literal role=\"func\">Point(<replaceable>x</replaceable>,\n <replaceable>y</replaceable>)</literal>"
},
{
"para": "Constructs a <literal>Point</literal> using its coordinates."
}
],
"id": "Point",
"syntax": []
},
{
"keywords": [
"Polygon"
],
"description": [
{
"para": "<literal role=\"func\">Polygon(<replaceable>ls</replaceable> [,\n <replaceable>ls</replaceable>] ...)</literal>"
},
{
"para": "Constructs a <literal>Polygon</literal> value from a number of\n <literal>LineString</literal> or WKB\n <literal>LineString</literal> arguments. If any argument does\n not represent a <literal>LinearRing</literal> (that is, not a\n closed and simple <literal>LineString</literal>), the return\n value is <literal>NULL</literal>."
}
],
"id": "Polygon",
"syntax": []
},
{
"keywords": [
"ST_AsBinary",
"ST_AsWKB"
],
"description": [
{
"para": "<literal role=\"func\">ST_AsBinary(<replaceable>g</replaceable>\n [, <replaceable>options</replaceable>])</literal>,\n <literal condition=\"st-asbinary\" role=\"func\">ST_AsWKB(<replaceable>g</replaceable>\n [, <replaceable>options</replaceable>])</literal>"
},
{
"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 <replaceable>options</replaceable> argument may be\n given to override the default axis order."
},
{
"para": "<literal role=\"func\">ST_AsBinary()</literal> and\n <literal condition=\"st-asbinary\" role=\"func\">ST_AsWKB()</literal>\n handle their arguments as described in the introduction to\n this section."
}
],
"id": "ST_AsBinary",
"syntax": []
},
{
"keywords": [
"ST_AsText",
"ST_AsWKT"
],
"description": [
{
"para": "<literal role=\"func\">ST_AsText(<replaceable>g</replaceable> [,\n <replaceable>options</replaceable>])</literal>,\n <literal condition=\"st-astext\" role=\"func\">ST_AsWKT(<replaceable>g</replaceable>\n [, <replaceable>options</replaceable>])</literal>"
},
{
"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 <replaceable>options</replaceable> argument may be\n given to override the default axis order."
},
{
"para": "<literal role=\"func\">ST_AsText()</literal> and\n <literal condition=\"st-astext\" role=\"func\">ST_AsWKT()</literal>\n handle their arguments as described in the introduction to\n this section."
}
],
"id": "ST_AsText",
"syntax": []
},
{
"keywords": [
"ST_SwapXY"
],
"description": [
{
"para": "<literal role=\"func\">ST_SwapXY(<replaceable>g</replaceable>)</literal>"
},
{
"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": "<literal role=\"func\">ST_SwapXY()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_SwapXY",
"syntax": []
},
{
"keywords": [
"ST_Dimension"
],
"description": [
{
"para": "<literal role=\"func\">ST_Dimension(<replaceable>g</replaceable>)</literal>"
},
{
"para": "Returns the inherent dimension of the geometry value\n <replaceable>g</replaceable>. The dimension can be minus1,\n 0, 1, or 2. The meaning of these values is given in\n <xref linkend=\"gis-class-geometry\" />."
},
{
"para": "<literal role=\"func\">ST_Dimension()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Dimension",
"syntax": []
},
{
"keywords": [
"ST_Envelope"
],
"description": [
{
"para": "<literal role=\"func\">ST_Envelope(<replaceable>g</replaceable>)</literal>"
},
{
"para": "Returns the minimum bounding rectangle (MBR) for the\n geometry value <replaceable>g</replaceable>. The result is\n returned as a <literal>Polygon</literal> 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> <userinput>SELECT ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,2 2)')));</userinput>\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, <literal role=\"func\">ST_Envelope()</literal>\n returns the point or the line segment as its MBR rather than\n returning an invalid polygon:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,1 2)')));</userinput>\n+----------------------------------------------------------------+\n| ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,1 2)'))) |\n+----------------------------------------------------------------+\n| LINESTRING(1 1,1 2) |\n+----------------------------------------------------------------+"
},
{
"para": "<literal role=\"func\">ST_Envelope()</literal> 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 <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS</literal>\n error occurs."
}
]
]
}
],
"id": "ST_Envelope",
"syntax": []
},
{
"keywords": [
"ST_GeometryType"
],
"description": [
{
"para": "<literal role=\"func\">ST_GeometryType(<replaceable>g</replaceable>)</literal>"
},
{
"para": "Returns a binary string indicating the name of the geometry\n type of which the geometry instance\n <replaceable>g</replaceable> is a member. The name\n corresponds to one of the instantiable\n <literal>Geometry</literal> subclasses."
},
{
"para": "<literal role=\"func\">ST_GeometryType()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_GeometryType",
"syntax": []
},
{
"keywords": [
"ST_IsEmpty"
],
"description": [
{
"para": "<literal role=\"func\">ST_IsEmpty(<replaceable>g</replaceable>)</literal>"
},
{
"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 <literal>EMPTY</literal> values such as <literal>POINT\n EMPTY</literal>."
},
{
"para": "<literal role=\"func\">ST_IsEmpty()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_IsEmpty",
"syntax": []
},
{
"keywords": [
"ST_IsSimple"
],
"description": [
{
"para": "<literal role=\"func\">ST_IsSimple(<replaceable>g</replaceable>)</literal>"
},
{
"para": "Returns 1 if the geometry value <replaceable>g</replaceable>\n is simple according to the ISO <citetitle>SQL/MM Part 3:\n Spatial</citetitle> standard.\n <literal role=\"func\">ST_IsSimple()</literal> returns 0 if\n the argument is not simple."
},
{
"para": "The descriptions of the instantiable geometric classes given\n under <xref linkend=\"opengis-geometry-model\" /> include the\n specific conditions that cause class instances to be\n classified as not simple."
},
{
"para": "<literal role=\"func\">ST_IsSimple()</literal> 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 <literal role=\"error\">ER_LONGITUDE_OUT_OF_RANGE</literal>\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n <literal role=\"error\">ER_LATITUDE_OUT_OF_RANGE</literal>\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": "<literal role=\"func\">ST_SRID(<replaceable>g</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "With a single argument representing a valid geometry object\n <replaceable>g</replaceable>,\n <literal role=\"func\">ST_SRID()</literal> returns an integer\n indicating the ID of the spatial reference system (SRS)\n associated with <replaceable>g</replaceable>."
},
{
"para": "With the optional second argument representing a valid SRID\n value, <literal role=\"func\">ST_SRID()</literal> 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": "<literal role=\"func\">ST_SRID()</literal> handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "For the single-argument syntax,\n <literal role=\"func\">ST_SRID()</literal> returns the\n geometry SRID even if it refers to an undefined SRS. An\n <literal role=\"error\">ER_SRS_NOT_FOUND</literal> error\n does not occur."
}
]
]
},
{
"para": "<literal role=\"func\">ST_SRID(<replaceable>g</replaceable>,\n <replaceable>target_srid</replaceable>)</literal> and\n <literal role=\"func\">ST_Transform(<replaceable>g</replaceable>,\n <replaceable>target_srid</replaceable>)</literal> differ as\n follows:"
},
{
"itemizedlist": [
[
{
"para": "<literal role=\"func\">ST_SRID()</literal> changes the\n geometry SRID value without transforming its\n coordinates."
}
],
[
{
"para": "<literal role=\"func\">ST_Transform()</literal> transforms\n the geometry coordinates in addition to changing its\n SRID value."
}
]
]
}
],
"id": "ST_SRID",
"syntax": []
},
{
"keywords": [
"ST_Latitude"
],
"description": [
{
"para": "<literal role=\"func\">ST_Latitude(<replaceable>p</replaceable>\n [, <replaceable>new_latitude_val</replaceable>])</literal>"
},
{
"para": "With a single argument representing a valid\n <literal>Point</literal> object <replaceable>p</replaceable>\n that has a geographic spatial reference system (SRS),\n <literal role=\"func\">ST_Latitude()</literal> returns the\n latitude value of <replaceable>p</replaceable> as a\n double-precision number."
},
{
"para": "With the optional second argument representing a valid\n latitude value, <literal role=\"func\">ST_Latitude()</literal>\n returns a <literal>Point</literal> object like the first\n argument with its latitude equal to the second argument."
},
{
"para": "<literal role=\"func\">ST_Latitude()</literal> handles its\n arguments as described in the introduction to this section,\n with the addition that if the <literal>Point</literal>\n object is valid but does not have a geographic SRS, an\n <literal role=\"error\">ER_SRS_NOT_GEOGRAPHIC</literal> error\n occurs."
}
],
"id": "ST_Latitude",
"syntax": []
},
{
"keywords": [
"ST_Longitude"
],
"description": [
{
"para": "<literal role=\"func\">ST_Longitude(<replaceable>p</replaceable>\n [, <replaceable>new_longitude_val</replaceable>])</literal>"
},
{
"para": "With a single argument representing a valid\n <literal>Point</literal> object <replaceable>p</replaceable>\n that has a geographic spatial reference system (SRS),\n <literal role=\"func\">ST_Longitude()</literal> returns the\n longitude value of <replaceable>p</replaceable> as a\n double-precision number."
},
{
"para": "With the optional second argument representing a valid\n longitude value,\n <literal role=\"func\">ST_Longitude()</literal> returns a\n <literal>Point</literal> object like the first argument with\n its longitude equal to the second argument."
},
{
"para": "<literal role=\"func\">ST_Longitude()</literal> handles its\n arguments as described in the introduction to this section,\n with the addition that if the <literal>Point</literal>\n object is valid but does not have a geographic SRS, an\n <literal role=\"error\">ER_SRS_NOT_GEOGRAPHIC</literal> error\n occurs."
}
],
"id": "ST_Longitude",
"syntax": []
},
{
"keywords": [
"ST_X"
],
"description": [
{
"para": "<literal role=\"func\">ST_X(<replaceable>p</replaceable>[,\n <replaceable>new_x_val</replaceable>])</literal>"
},
{
"para": "With a single argument representing a valid\n <literal>Point</literal> object\n <replaceable>p</replaceable>,\n <literal role=\"func\">ST_X()</literal> returns the\n X-coordinate value of <replaceable>p</replaceable> 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 <literal>Point</literal> spatial reference\n system (SRS) definition."
},
{
"para": "With the optional second argument,\n <literal role=\"func\">ST_X()</literal> returns a\n <literal>Point</literal> object like the first argument with\n its X coordinate equal to the second argument. As of MySQL\n 8.0.12, if the <literal>Point</literal> object has a\n geographic SRS, the second argument must be in the proper\n range for longitude or latitude values."
},
{
"para": "<literal role=\"func\">ST_X()</literal> handles its arguments\n as described in the introduction to this section."
}
],
"id": "ST_X",
"syntax": []
},
{
"keywords": [
"ST_Y"
],
"description": [
{
"para": "<literal role=\"func\">ST_Y(<replaceable>p</replaceable>[,\n <replaceable>new_y_val</replaceable>])</literal>"
},
{
"para": "With a single argument representing a valid\n <literal>Point</literal> object\n <replaceable>p</replaceable>,\n <literal role=\"func\">ST_Y()</literal> returns the\n Y-coordinate value of <replaceable>p</replaceable> 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 <literal>Point</literal> spatial reference\n system (SRS) definition."
},
{
"para": "With the optional second argument,\n <literal role=\"func\">ST_Y()</literal> returns a\n <literal>Point</literal> object like the first argument with\n its Y coordinate equal to the second argument. As of MySQL\n 8.0.12, if the <literal>Point</literal> object has a\n geographic SRS, the second argument must be in the proper\n range for longitude or latitude values."
},
{
"para": "<literal role=\"func\">ST_Y()</literal> handles its arguments\n as described in the introduction to this section."
}
],
"id": "ST_Y",
"syntax": []
},
{
"keywords": [
"ST_EndPoint"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_EndPoint()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_EndPoint(<replaceable>ls</replaceable>)</literal>"
},
{
"para": "Returns the <literal>Point</literal> that is the endpoint of\n the <literal>LineString</literal> value\n <replaceable>ls</replaceable>."
},
{
"para": "<literal role=\"func\">ST_EndPoint()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_EndPoint",
"syntax": []
},
{
"keywords": [
"ST_IsClosed"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_IsClosed()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_IsClosed(<replaceable>ls</replaceable>)</literal>"
},
{
"para": "For a <literal>LineString</literal> value\n <replaceable>ls</replaceable>,\n <literal role=\"func\">ST_IsClosed()</literal> returns 1 if\n <replaceable>ls</replaceable> is closed (that is, its\n <literal role=\"func\">ST_StartPoint()</literal> and\n <literal role=\"func\">ST_EndPoint()</literal> values are the\n same)."
},
{
"para": "For a <literal>MultiLineString</literal> value\n <replaceable>ls</replaceable>,\n <literal role=\"func\">ST_IsClosed()</literal> returns 1 if\n <replaceable>ls</replaceable> is closed (that is, the\n <literal role=\"func\">ST_StartPoint()</literal> and\n <literal role=\"func\">ST_EndPoint()</literal> values are the\n same for each <literal>LineString</literal> in\n <replaceable>ls</replaceable>)."
},
{
"para": "<literal role=\"func\">ST_IsClosed()</literal> returns 0 if\n <replaceable>ls</replaceable> is not closed, and\n <literal>NULL</literal> if <replaceable>ls</replaceable> is\n <literal>NULL</literal>."
},
{
"para": "<literal role=\"func\">ST_IsClosed()</literal> 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 <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS</literal>\n error occurs."
}
]
]
}
],
"id": "ST_IsClosed",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>ST_Length()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Length(<replaceable>ls</replaceable>\n [, <replaceable>unit</replaceable>])</literal>"
},
{
"para": "Returns a double-precision number indicating the length of\n the <literal>LineString</literal> or\n <literal>MultiLineString</literal> value\n <replaceable>ls</replaceable> in its associated spatial\n reference system. The length of a\n <literal>MultiLineString</literal> value is equal to the sum\n of the lengths of its elements."
},
{
"para": "<literal role=\"func\">ST_Length()</literal> computes a result\n as follows:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry is a valid <literal>LineString</literal>\n in a Cartesian SRS, the return value is the Cartesian\n length of the geometry."
}
],
[
{
"para": "If the geometry is a valid\n <literal>MultiLineString</literal> 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 <literal>LineString</literal>\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 <literal>MultiLineString</literal> 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": "<literal role=\"func\">ST_Length()</literal> handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "If the geometry is not a <literal>LineString</literal>\n or <literal>MultiLineString</literal>, the return value\n is <literal>NULL</literal>."
}
],
[
{
"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 <literal>+inf</literal>, an\n <literal role=\"error\">ER_DATA_OUT_OF_RANGE</literal>\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 <literal role=\"error\">ER_LONGITUDE_OUT_OF_RANGE</literal>\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n <literal role=\"error\">ER_LATITUDE_OUT_OF_RANGE</literal>\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 <literal role=\"func\">ST_Length()</literal> permits an\n optional <replaceable>unit</replaceable> 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 <literal role=\"error\">ER_UNIT_NOT_FOUND</literal> error\n occurs."
}
],
[
{
"para": "If a supported linear unit is specified and the SRID is\n 0, an\n <literal role=\"error\">ER_GEOMETRY_IN_UNKNOWN_LENGTH_UNIT</literal>\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 <literal>INFORMATION_SCHEMA</literal>\n <literal role=\"is\">ST_UNITS_OF_MEASURE</literal> table. See\n <xref linkend=\"st-units-of-measure-table\" />."
}
],
"id": "ST_Length",
"syntax": []
},
{
"keywords": [
"ST_NumPoints"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_NumPoints()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_NumPoints(<replaceable>ls</replaceable>)</literal>"
},
{
"para": "Returns the number of <literal>Point</literal> objects in\n the <literal>LineString</literal> value\n <replaceable>ls</replaceable>."
},
{
"para": "<literal role=\"func\">ST_NumPoints()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_NumPoints",
"syntax": []
},
{
"keywords": [
"ST_PointN"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_PointN()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_PointN(<replaceable>ls</replaceable>,\n <replaceable>N</replaceable>)</literal>"
},
{
"para": "Returns the <replaceable>N</replaceable>-th\n <literal>Point</literal> in the\n <literal>Linestring</literal> value\n <replaceable>ls</replaceable>. Points are numbered beginning\n with 1."
},
{
"para": "<literal role=\"func\">ST_PointN()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_PointN",
"syntax": []
},
{
"keywords": [
"ST_StartPoint"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_StartPoint()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_StartPoint(<replaceable>ls</replaceable>)</literal>"
},
{
"para": "Returns the <literal>Point</literal> that is the start point\n of the <literal>LineString</literal> value\n <replaceable>ls</replaceable>."
},
{
"para": "<literal role=\"func\">ST_StartPoint()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_StartPoint",
"syntax": []
},
{
"keywords": [
"ST_Area"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Area()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Area({<replaceable>poly</replaceable>|<replaceable>mpoly</replaceable>})</literal>"
},
{
"para": "Returns a double-precision number indicating the area of the\n <literal>Polygon</literal> or\n <literal>MultiPolygon</literal> argument, as measured in its\n spatial reference system."
},
{
"para": "As of MySQL 8.0.13, <literal role=\"func\">ST_Area()</literal>\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 <literal>Polygon</literal> or\n <literal>MultiPolygon</literal> object, an\n <literal role=\"error\">ER_UNEXPECTED_GEOMETRY_TYPE</literal>\n error occurs."
}
],
[
{
"para": "If the geometry is a valid <literal>Polygon</literal> in\n a Cartesian SRS, the result is the Cartesian area of the\n polygon."
}
],
[
{
"para": "If the geometry is a valid\n <literal>MultiPolygon</literal> in a Cartesian SRS, the\n result is the sum of the Cartesian area of the polygons."
}
],
[
{
"para": "If the geometry is a valid <literal>Polygon</literal> 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 <literal>MultiPolygon</literal> 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 <literal>+inf</literal>, an\n <literal role=\"error\">ER_DATA_OUT_OF_RANGE</literal>\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 <literal role=\"error\">ER_LONGITUDE_OUT_OF_RANGE</literal>\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n <literal role=\"error\">ER_LATITUDE_OUT_OF_RANGE</literal>\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 <literal role=\"func\">ST_Area()</literal> 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 <literal>NULL</literal>."
}
],
[
{
"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 <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS</literal>\n error occurs."
}
]
]
}
],
"id": "ST_Area",
"syntax": []
},
{
"keywords": [
"ST_Centroid"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Centroid()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Centroid({<replaceable>poly</replaceable>|<replaceable>mpoly</replaceable>})</literal>"
},
{
"para": "Returns the mathematical centroid for the\n <literal>Polygon</literal> or\n <literal>MultiPolygon</literal> argument as a\n <literal>Point</literal>. The result is not guaranteed to be\n on the <literal>MultiPolygon</literal>."
},
{
"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 <literal>MultiPolygon</literal>,\n <literal>MultiLineString</literal>, or\n <literal>MultiPoint</literal> for centroid computation."
},
{
"para": "<literal role=\"func\">ST_Centroid()</literal> handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "The return value is <literal>NULL</literal> 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 <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS</literal>\n error occurs."
}
]
]
}
],
"id": "ST_Centroid",
"syntax": []
},
{
"keywords": [
"ST_ExteriorRing"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_ExteriorRing()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_ExteriorRing(<replaceable>poly</replaceable>)</literal>"
},
{
"para": "Returns the exterior ring of the <literal>Polygon</literal>\n value <replaceable>poly</replaceable> as a\n <literal>LineString</literal>."
},
{
"para": "<literal role=\"func\">ST_ExteriorRing()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_ExteriorRing",
"syntax": []
},
{
"keywords": [
"ST_InteriorRingN"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_InteriorRingN()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_InteriorRingN(<replaceable>poly</replaceable>,\n <replaceable>N</replaceable>)</literal>"
},
{
"para": "Returns the <replaceable>N</replaceable>-th interior ring\n for the <literal>Polygon</literal> value\n <replaceable>poly</replaceable> as a\n <literal>LineString</literal>. Rings are numbered beginning\n with 1."
},
{
"para": "<literal role=\"func\">ST_InteriorRingN()</literal> handles\n its arguments as described in the introduction to this\n section."
}
],
"id": "ST_InteriorRingN",
"syntax": []
},
{
"keywords": [
"ST_NumInteriorRings",
"ST_NumInteriorRing"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_NumInteriorRings()</primary>\n </indexterm>\n\n <indexterm>\n <primary>ST_NumInteriorRing()</primary>\n </indexterm>\n\n <literal condition=\"st-numinteriorrings\" role=\"func\">ST_NumInteriorRing(<replaceable>poly</replaceable>)</literal>,\n <literal role=\"func\">ST_NumInteriorRings(<replaceable>poly</replaceable>)</literal>"
},
{
"para": "Returns the number of interior rings in the\n <literal>Polygon</literal> value\n <replaceable>poly</replaceable>."
},
{
"para": "<literal condition=\"st-numinteriorrings\" role=\"func\">ST_NumInteriorRing()</literal>\n and <literal role=\"func\">ST_NuminteriorRings()</literal>\n handle their arguments as described in the introduction to\n this section."
}
],
"id": "ST_NumInteriorRings",
"syntax": []
},
{
"keywords": [
"ST_GeometryN"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_GeometryN()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_GeometryN(<replaceable>gc</replaceable>,\n <replaceable>N</replaceable>)</literal>"
},
{
"para": "Returns the <replaceable>N</replaceable>-th geometry in the\n <literal>GeometryCollection</literal> value\n <replaceable>gc</replaceable>. Geometries are numbered\n beginning with 1."
},
{
"para": "<literal role=\"func\">ST_GeometryN()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_GeometryN",
"syntax": []
},
{
"keywords": [
"ST_NumGeometries"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_NumGeometries()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_NumGeometries(<replaceable>gc</replaceable>)</literal>"
},
{
"para": "Returns the number of geometries in the\n <literal>GeometryCollection</literal> value\n <replaceable>gc</replaceable>."
},
{
"para": "<literal role=\"func\">ST_NumGeometries()</literal> handles\n its arguments as described in the introduction to this\n section."
}
],
"id": "ST_NumGeometries",
"syntax": []
},
{
"keywords": [
"ST_Buffer"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Buffer()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Buffer(<replaceable>g</replaceable>,\n <replaceable>d</replaceable>[,\n <replaceable>strategy1</replaceable>[,\n <replaceable>strategy2</replaceable>[,\n <replaceable>strategy3</replaceable>]]])</literal>"
},
{
"para": "Returns a geometry that represents all points whose distance\n from the geometry value <replaceable>g</replaceable> is less\n than or equal to a distance of <replaceable>d</replaceable>."
},
{
"para": "If the geometry argument is empty,\n <literal role=\"func\">ST_Buffer()</literal> returns an empty\n geometry."
},
{
"para": "If the distance is 0,\n <literal role=\"func\">ST_Buffer()</literal> returns the\n geometry argument unchanged:"
},
{
"programlisting": ">\nmysql> <userinput>SET @pt = ST_GeomFromText('POINT(0 0)');</userinput>\nmysql> <userinput>SELECT ST_AsText(ST_Buffer(@pt, 0));</userinput>\n+------------------------------+\n| ST_AsText(ST_Buffer(@pt, 0)) |\n+------------------------------+\n| POINT(0 0) |\n+------------------------------+"
},
{
"para": "<literal role=\"func\">ST_Buffer()</literal> supports negative\n distances for <literal>Polygon</literal> and\n <literal>MultiPolygon</literal> values, and for geometry\n collections containing <literal>Polygon</literal> or\n <literal>MultiPolygon</literal> values. The result may be an\n empty geometry."
},
{
"para": "<literal role=\"func\">ST_Buffer()</literal> 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 <literal role=\"func\">ST_Buffer_Strategy()</literal> function,\n to be used for point, join, and end strategies:"
},
{
"itemizedlist": [
[
{
"para": "Point strategies apply to <literal>Point</literal> and\n <literal>MultiPoint</literal> geometries. If no point\n strategy is specified, the default is\n <literal role=\"func\">ST_Buffer_Strategy('point_circle',\n 32)</literal>."
}
],
[
{
"para": "Join strategies apply to <literal>LineString</literal>,\n <literal>MultiLineString</literal>,\n <literal>Polygon</literal>, and\n <literal>MultiPolygon</literal> geometries. If no join\n strategy is specified, the default is\n <literal role=\"func\">ST_Buffer_Strategy('join_round',\n 32)</literal>."
}
],
[
{
"para": "End strategies apply to <literal>LineString</literal> and\n <literal>MultiLineString</literal> geometries. If no end\n strategy is specified, the default is\n <literal role=\"func\">ST_Buffer_Strategy('end_round',\n 32)</literal>."
}
]
]
},
{
"para": "Up to one strategy of each type may be specified, and they may\n be given in any order."
},
{
"para": "<literal role=\"func\">ST_Buffer()</literal> handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "For a negative distance for <literal>Point</literal>,\n <literal>MultiPoint</literal>,\n <literal>LineString</literal>, and\n <literal>MultiLineString</literal> values, and for\n geometry collections not containing any\n <literal>Polygon</literal> or\n <literal>MultiPolygon</literal> values, an\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs."
}
],
[
{
"para": "If multiple strategies of a given type are specified, an\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs."
}
]
]
}
],
"id": "ST_Buffer",
"syntax": []
},
{
"keywords": [
"ST_BUFFER_STRATEGY"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Buffer_Strategy()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Buffer_Strategy(<replaceable>strategy</replaceable>[,\n <replaceable>points_per_circle</replaceable>])</literal>"
},
{
"para": "This function returns a strategy byte string for use with\n <literal role=\"func\">ST_Buffer()</literal> to influence buffer\n computation."
},
{
"para": "Information about strategies is available at\n <ulink url=\"http://www.boost.org\">Boost.org</ulink>."
},
{
"para": "The first argument must be a string indicating a strategy\n option:"
},
{
"itemizedlist": [
[
{
"para": "For point strategies, permitted values are\n <literal>'point_circle'</literal> and\n <literal>'point_square'</literal>."
}
],
[
{
"para": "For join strategies, permitted values are\n <literal>'join_round'</literal> and\n <literal>'join_miter'</literal>."
}
],
[
{
"para": "For end strategies, permitted values are\n <literal>'end_round'</literal> and\n <literal>'end_flat'</literal>."
}
]
]
},
{
"para": "If the first argument is <literal>'point_circle'</literal>,\n <literal>'join_round'</literal>,\n <literal>'join_miter'</literal>, or\n <literal>'end_round'</literal>, the\n <replaceable>points_per_circle</replaceable> argument must be\n given as a positive numeric value. The maximum\n <replaceable>points_per_circle</replaceable> value is the\n value of the\n <literal role=\"sysvar\">max_points_in_geometry</literal> system\n variable."
},
{
"para": "For examples, see the description of\n <literal role=\"func\">ST_Buffer()</literal>."
},
{
"para": "<literal role=\"func\">ST_Buffer_Strategy()</literal> 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 <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs."
}
],
[
{
"para": "If the first argument is <literal>'point_square'</literal>\n or <literal>'end_flat'</literal>, the\n <replaceable>points_per_circle</replaceable> argument must\n not be given or an\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs."
}
]
]
}
],
"id": "ST_Buffer_Strategy",
"syntax": []
},
{
"keywords": [
"ST_CONVEXHULL"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_ConvexHull()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_ConvexHull(<replaceable>g</replaceable>)</literal>"
},
{
"para": "Returns a geometry that represents the convex hull of the\n geometry value <replaceable>g</replaceable>."
},
{
"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 <literal>MultiPoint</literal> value from them, and computing\n its convex hull."
},
{
"para": "<literal role=\"func\">ST_ConvexHull()</literal> handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "The return value is <literal>NULL</literal> for the\n additional condition that the argument is an empty\n geometry collection."
}
]
]
}
],
"id": "ST_ConvexHull",
"syntax": []
},
{
"keywords": [
"ST_Difference"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Difference()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Difference(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns a geometry that represents the point set difference of\n the geometry values <replaceable>g1</replaceable> and\n <replaceable>g2</replaceable>."
},
{
"para": "<literal role=\"func\">ST_Difference()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Difference",
"syntax": []
},
{
"keywords": [
"ST_Intersection"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Intersection()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Intersection(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns a geometry that represents the point set intersection\n of the geometry values <replaceable>g1</replaceable> and\n <replaceable>g2</replaceable>."
},
{
"para": "<literal role=\"func\">ST_Intersection()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Intersection",
"syntax": []
},
{
"keywords": [
"ST_SymDifference"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_SymDifference()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_SymDifference(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns a geometry that represents the point set symmetric\n difference of the geometry values\n <replaceable>g1</replaceable> and\n <replaceable>g2</replaceable>, which is defined as:"
},
{
"programlisting": ">\n<replaceable>g1</replaceable> symdifference <replaceable>g2</replaceable> := (<replaceable>g1</replaceable> union <replaceable>g2</replaceable>) difference (<replaceable>g1</replaceable> intersection <replaceable>g2</replaceable>)"
},
{
"para": "Or, in function call notation:"
},
{
"programlisting": ">\nST_SymDifference(<replaceable>g1</replaceable>, <replaceable>g2</replaceable>) = ST_Difference(ST_Union(<replaceable>g1</replaceable>, <replaceable>g2</replaceable>), ST_Intersection(<replaceable>g1</replaceable>, <replaceable>g2</replaceable>))"
},
{
"para": "<literal role=\"func\">ST_SymDifference()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_SymDifference",
"syntax": []
},
{
"keywords": [
"ST_TRANSFORM"
],
"description": [
{
"para": "<literal role=\"func\">ST_Transform(<replaceable>g</replaceable>,\n <replaceable>target_srid</replaceable>)</literal>"
},
{
"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, <replaceable>target_srid</replaceable>.\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": "<literal role=\"func\">ST_Transform()</literal> 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 <literal role=\"error\">ER_SRS_NOT_FOUND</literal>\n error occurs."
}
],
[
{
"para": "If the geometry is in an SRS that\n <literal role=\"func\">ST_Transform()</literal> cannot\n transform from, an\n <literal role=\"error\">ER_TRANSFORM_SOURCE_SRS_NOT_SUPPORTED</literal>\n error occurs."
}
],
[
{
"para": "If the target SRID is in an SRS that\n <literal role=\"func\">ST_Transform()</literal> cannot\n transform to, an\n <literal role=\"error\">ER_TRANSFORM_TARGET_SRS_NOT_SUPPORTED</literal>\n error occurs."
}
],
[
{
"para": "If the geometry is in an SRS that is not WGS 84 and has no\n TOWGS84 clause, an\n <literal role=\"error\">ER_TRANSFORM_SOURCE_SRS_MISSING_TOWGS84</literal>\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 <literal role=\"error\">ER_TRANSFORM_TARGET_SRS_MISSING_TOWGS84</literal>\n error occurs."
}
]
]
},
{
"para": "<literal role=\"func\">ST_SRID(<replaceable>g</replaceable>,\n <replaceable>target_srid</replaceable>)</literal> and\n <literal role=\"func\">ST_Transform(<replaceable>g</replaceable>,\n <replaceable>target_srid</replaceable>)</literal> differ as\n follows:"
},
{
"itemizedlist": [
[
{
"para": "<literal role=\"func\">ST_SRID()</literal> changes the\n geometry SRID value without transforming its coordinates."
}
],
[
{
"para": "<literal role=\"func\">ST_Transform()</literal> transforms\n the geometry coordinates in addition to changing its SRID\n value."
}
]
]
}
],
"id": "ST_Transform",
"syntax": []
},
{
"keywords": [
"ST_Union"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Union()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Union(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns a geometry that represents the point set union of the\n geometry values <replaceable>g1</replaceable> and\n <replaceable>g2</replaceable>."
},
{
"para": "<literal role=\"func\">ST_Union()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Union",
"syntax": []
},
{
"keywords": [
"ST_Contains"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Contains()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Contains(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether\n <replaceable>g1</replaceable> completely contains\n <replaceable>g2</replaceable>. This tests the opposite\n relationship as <literal role=\"func\">ST_Within()</literal>."
},
{
"para": "<literal role=\"func\">ST_Contains()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Contains",
"syntax": []
},
{
"keywords": [
"ST_Crosses"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Crosses()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Crosses(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Two geometries <emphasis>spatially cross</emphasis> if their\n spatial relation has the following properties:"
},
{
"itemizedlist": [
[
{
"para": "Unless <literal>g1</literal> and <literal>g2</literal>\n are both of dimension 1: <literal>g1</literal> crosses\n <literal>g2</literal> if the interior of\n <literal>g2</literal> has points in common with the\n interior of <literal>g1</literal>, but\n <literal>g2</literal> does not cover the entire interior\n of <literal>g1</literal>."
}
],
[
{
"para": "If both <literal>g1</literal> and <literal>g2</literal>\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 <replaceable>g1</replaceable> spatially crosses\n <replaceable>g2</replaceable>."
},
{
"para": "<literal role=\"func\">ST_Crosses()</literal> handles its\n arguments as described in the introduction to this section\n except that the return value is <literal>NULL</literal> for\n these additional conditions:"
},
{
"itemizedlist": [
[
{
"para": "<literal>g1</literal> is of dimension 2\n (<literal>Polygon</literal> or\n <literal>MultiPolygon</literal>)."
}
],
[
{
"para": "<replaceable>g2</replaceable> is of dimension 1\n (<literal>Point</literal> or\n <literal>MultiPoint</literal>)."
}
]
]
}
],
"id": "ST_Crosses",
"syntax": []
},
{
"keywords": [
"ST_Disjoint"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Disjoint()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Disjoint(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether\n <replaceable>g1</replaceable> is spatially disjoint from\n (does not intersect) <replaceable>g2</replaceable>."
},
{
"para": "<literal role=\"func\">ST_Disjoint()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Disjoint",
"syntax": []
},
{
"keywords": [
"ST_Distance"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Distance()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Distance(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable> [,\n <replaceable>unit</replaceable>])</literal>"
},
{
"para": "Returns the distance between <replaceable>g1</replaceable>\n and <replaceable>g2</replaceable>, 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 <replaceable>unit</replaceable> 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": "<literal role=\"func\">ST_Distance()</literal> handles its\n geometry arguments as described in the introduction to this\n section, with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "<literal role=\"func\">ST_Distance()</literal> 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 <literal role=\"func\">ST_Distance()</literal> 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 <literal>Point</literal> and <literal>Point</literal>,\n or <literal>Point</literal> and\n <literal>MultiPoint</literal> (in any argument order).\n If called with other geometry type argument combinations\n in a geographic SRS, an\n <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS</literal>\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 <literal>NaN</literal> or a negative number, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal>\n error occurs."
}
]
]
},
{
"para": "As of MySQL 8.0.14,\n <literal role=\"func\">ST_Distance()</literal> permits an\n optional <replaceable>unit</replaceable> 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 <literal role=\"error\">ER_UNIT_NOT_FOUND</literal> error\n occurs."
}
],
[
{
"para": "If a supported linear unit is specified and the SRID is\n 0, an\n <literal role=\"error\">ER_GEOMETRY_IN_UNKNOWN_LENGTH_UNIT</literal>\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 <literal>INFORMATION_SCHEMA</literal>\n <literal role=\"is\">ST_UNITS_OF_MEASURE</literal> table. See\n <xref linkend=\"st-units-of-measure-table\" />."
}
],
"id": "ST_Distance",
"syntax": []
},
{
"keywords": [
"ST_Equals"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Equals()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Equals(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether\n <replaceable>g1</replaceable> is spatially equal to\n <replaceable>g2</replaceable>."
},
{
"para": "<literal role=\"func\">ST_Equals()</literal> handles its\n arguments as described in the introduction to this section,\n except that it does not return <literal>NULL</literal> for\n empty geometry arguments."
}
],
"id": "ST_Equals",
"syntax": []
},
{
"keywords": [
"ST_Intersects"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Intersects()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Intersects(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether\n <replaceable>g1</replaceable> spatially intersects\n <replaceable>g2</replaceable>."
},
{
"para": "<literal role=\"func\">ST_Intersects()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Intersects",
"syntax": []
},
{
"keywords": [
"ST_Overlaps"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Overlaps()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Overlaps(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Two geometries <emphasis>spatially overlap</emphasis> 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 <replaceable>g1</replaceable> spatially overlaps\n <replaceable>g2</replaceable>."
},
{
"para": "<literal role=\"func\">ST_Overlaps()</literal> handles its\n arguments as described in the introduction to this section\n except that the return value is <literal>NULL</literal> 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": "<indexterm>\n <primary>ST_Touches()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Touches(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Two geometries <emphasis>spatially touch</emphasis> 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 <replaceable>g1</replaceable> spatially touches\n <replaceable>g2</replaceable>."
},
{
"para": "<literal role=\"func\">ST_Touches()</literal> handles its\n arguments as described in the introduction to this section\n except that the return value is <literal>NULL</literal> for\n the additional condition that both geometries are of\n dimension 0 (<literal>Point</literal> or\n <literal>MultiPoint</literal>)."
}
],
"id": "ST_Touches",
"syntax": []
},
{
"keywords": [
"ST_Within"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Within()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Within(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether\n <replaceable>g1</replaceable> is spatially within\n <replaceable>g2</replaceable>. This tests the opposite\n relationship as\n <literal role=\"func\">ST_Contains()</literal>."
},
{
"para": "<literal role=\"func\">ST_Within()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_Within",
"syntax": []
},
{
"keywords": [
"MBRContains"
],
"description": [
{
"para": "<indexterm>\n <primary>MBRContains()</primary>\n </indexterm>\n\n <literal role=\"func\">MBRContains(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangle of <replaceable>g1</replaceable> contains the\n minimum bounding rectangle of <replaceable>g2</replaceable>.\n This tests the opposite relationship as\n <literal role=\"func\">MBRWithin()</literal>."
},
{
"para": "<literal role=\"func\">MBRContains()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRContains",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>MBRCoveredBy()</primary>\n </indexterm>\n\n <literal role=\"func\">MBRCoveredBy(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangle of <replaceable>g1</replaceable> is covered by the\n minimum bounding rectangle of <replaceable>g2</replaceable>.\n This tests the opposite relationship as\n <literal role=\"func\">MBRCovers()</literal>."
},
{
"para": "<literal role=\"func\">MBRCoveredBy()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRCoveredBy",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>MBRCovers()</primary>\n </indexterm>\n\n <literal role=\"func\">MBRCovers(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangle of <replaceable>g1</replaceable> covers the\n minimum bounding rectangle of <replaceable>g2</replaceable>.\n This tests the opposite relationship as\n <literal role=\"func\">MBRCoveredBy()</literal>. See the\n description of <literal role=\"func\">MBRCoveredBy()</literal>\n for examples."
},
{
"para": "<literal role=\"func\">MBRCovers()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRCovers",
"syntax": []
},
{
"keywords": [
"MBRDisjoint"
],
"description": [
{
"para": "<indexterm>\n <primary>MBRDisjoint()</primary>\n </indexterm>\n\n <literal role=\"func\">MBRDisjoint(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangles of the two geometries\n <replaceable>g1</replaceable> and\n <replaceable>g2</replaceable> are disjoint (do not\n intersect)."
},
{
"para": "<literal role=\"func\">MBRDisjoint()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRDisjoint",
"syntax": []
},
{
"keywords": null,
"description": [
{
"para": "<indexterm>\n <primary>MBREquals()</primary>\n </indexterm>\n\n <literal role=\"func\">MBREquals(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangles of the two geometries\n <replaceable>g1</replaceable> and\n <replaceable>g2</replaceable> are the same."
},
{
"para": "<literal role=\"func\">MBREquals()</literal> handles its\n arguments as described in the introduction to this section,\n except that it does not return <literal>NULL</literal> for\n empty geometry arguments."
}
],
"id": "MBREquals",
"syntax": []
},
{
"keywords": [
"MBRIntersects"
],
"description": [
{
"para": "<indexterm>\n <primary>MBRIntersects()</primary>\n </indexterm>\n\n <literal role=\"func\">MBRIntersects(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangles of the two geometries\n <replaceable>g1</replaceable> and\n <replaceable>g2</replaceable> intersect."
},
{
"para": "<literal role=\"func\">MBRIntersects()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRIntersects",
"syntax": []
},
{
"keywords": [
"MBROverlaps"
],
"description": [
{
"para": "<indexterm>\n <primary>MBROverlaps()</primary>\n </indexterm>\n\n <literal role=\"func\">MBROverlaps(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Two geometries <emphasis>spatially overlap</emphasis> 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 <replaceable>g1</replaceable> and\n <replaceable>g2</replaceable> overlap."
},
{
"para": "<literal role=\"func\">MBROverlaps()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBROverlaps",
"syntax": []
},
{
"keywords": [
"MBRTouches"
],
"description": [
{
"para": "<indexterm>\n <primary>MBRTouches()</primary>\n </indexterm>\n\n <literal role=\"func\">MBRTouches(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Two geometries <emphasis>spatially touch</emphasis> 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 <replaceable>g1</replaceable> and\n <replaceable>g2</replaceable> touch."
},
{
"para": "<literal role=\"func\">MBRTouches()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRTouches",
"syntax": []
},
{
"keywords": [
"MBRWithin"
],
"description": [
{
"para": "<indexterm>\n <primary>MBRWithin()</primary>\n </indexterm>\n\n <literal role=\"func\">MBRWithin(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "Returns 1 or 0 to indicate whether the minimum bounding\n rectangle of <replaceable>g1</replaceable> is within the\n minimum bounding rectangle of <replaceable>g2</replaceable>.\n This tests the opposite relationship as\n <literal role=\"func\">MBRContains()</literal>."
},
{
"para": "<literal role=\"func\">MBRWithin()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "MBRWithin",
"syntax": []
},
{
"keywords": [
"ST_GEOHASH"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_GeoHash()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_GeoHash(<replaceable>longitude</replaceable>,\n <replaceable>latitude</replaceable>,\n <replaceable>max_length</replaceable>)</literal>,\n <literal role=\"func\">ST_GeoHash(<replaceable>point</replaceable>,\n <replaceable>max_length</replaceable>)</literal>"
},
{
"para": "Returns a geohash string in the connection character set and\n collation."
},
{
"para": "For the first syntax, the <replaceable>longitude</replaceable>\n must be a number in the range [minus180, 180], and the\n <replaceable>latitude</replaceable> must be a number in the\n range [minus90, 90]. For the second syntax, a\n <literal>POINT</literal> 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 <replaceable>max_length</replaceable> characters, which has an\n upper limit of 100. The string might be shorter than\n <replaceable>max_length</replaceable> 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 <replaceable>max_length</replaceable>\n characters, whichever comes first."
},
{
"para": "<literal role=\"func\">ST_GeoHash()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_GeoHash",
"syntax": []
},
{
"keywords": [
"ST_LATFROMGEOHASH"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_LatFromGeoHash()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_LatFromGeoHash(<replaceable>geohash_str</replaceable>)</literal>"
},
{
"para": "Returns the latitude from a geohash string value, as a\n double-precision number in the range [minus90, 90]."
},
{
"para": "The <literal role=\"func\">ST_LatFromGeoHash()</literal>\n decoding function reads no more than 433 characters from the\n <replaceable>geohash_str</replaceable> 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": "<literal role=\"func\">ST_LatFromGeoHash()</literal> handles its\n arguments as described in the introduction to this section."
}
],
"id": "ST_LatFromGeoHash",
"syntax": []
},
{
"keywords": [
"ST_LONGFROMGEOHASH"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_LongFromGeoHash()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_LongFromGeoHash(<replaceable>geohash_str</replaceable>)</literal>"
},
{
"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 <literal role=\"func\">ST_LatFromGeoHash()</literal> regarding\n the maximum number of characters processed from the\n <replaceable>geohash_str</replaceable> argument also apply to\n <literal role=\"func\">ST_LongFromGeoHash()</literal>."
},
{
"para": "<literal role=\"func\">ST_LongFromGeoHash()</literal> handles\n its arguments as described in the introduction to this\n section."
}
],
"id": "ST_LongFromGeoHash",
"syntax": []
},
{
"keywords": [
"ST_POINTFROMGEOHASH"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_PointFromGeoHash()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_PointFromGeoHash(<replaceable>geohash_str</replaceable>,\n <replaceable>srid</replaceable>)</literal>"
},
{
"para": "Returns a <literal>POINT</literal> 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 <replaceable>srid</replaceable> argument is an 32-bit\n unsigned integer."
},
{
"para": "The remarks in the description of\n <literal role=\"func\">ST_LatFromGeoHash()</literal> regarding\n the maximum number of characters processed from the\n <replaceable>geohash_str</replaceable> argument also apply to\n <literal role=\"func\">ST_PointFromGeoHash()</literal>."
},
{
"para": "<literal role=\"func\">ST_PointFromGeoHash()</literal> handles\n its arguments as described in the introduction to this\n section."
}
],
"id": "ST_PointFromGeoHash",
"syntax": []
},
{
"keywords": [
"ST_ASGEOJSON"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_AsGeoJSON()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_AsGeoJSON(<replaceable>g</replaceable>\n [, <replaceable>max_dec_digits</replaceable> [,\n <replaceable>options</replaceable>]])</literal>"
},
{
"para": "Generates a GeoJSON object from the geometry\n <replaceable>g</replaceable>. The object string has the\n connection character set and collation."
},
{
"para": "If any argument is <literal>NULL</literal>, the return value\n is <literal>NULL</literal>. If any non-<literal>NULL</literal>\n argument is invalid, an error occurs."
}
],
"id": "ST_AsGeoJSON",
"syntax": []
},
{
"keywords": [
"ST_GEOMFROMGEOJSON"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_GeomFromGeoJSON()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_GeomFromGeoJSON(<replaceable>str</replaceable>\n [, <replaceable>options</replaceable> [,\n <replaceable>srid</replaceable>]])</literal>"
},
{
"para": "Parses a string <replaceable>str</replaceable> representing a\n GeoJSON object and returns a geometry."
},
{
"para": "If any argument is <literal>NULL</literal>, the return value\n is <literal>NULL</literal>. If any non-<literal>NULL</literal>\n argument is invalid, an error occurs."
}
],
"id": "ST_GeomFromGeoJSON",
"syntax": []
},
{
"keywords": [
"ST_DISTANCE_SPHERE"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Distance_Sphere()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Distance_Sphere(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable> [,\n <replaceable>radius</replaceable>])</literal>"
},
{
"para": "Returns the mimimum spherical distance between\n <literal>Point</literal> or <literal>MultiPoint</literal>\n arguments on a sphere, in meters. (For general-purpose\n distance calculations, see the\n <literal role=\"func\">ST_Distance()</literal> function.) The\n optional <replaceable>radius</replaceable> argument should be\n given in meters."
},
{
"para": "If both geometry parameters are valid Cartesian\n <literal>Point</literal> or <literal>MultiPoint</literal>\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 <literal>Point</literal>\n or <literal>MultiPoint</literal> 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": "<literal role=\"func\">ST_Distance_Sphere()</literal> handles\n its arguments as described in the introduction to this\n section, with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "Supported geometry argument combinations are\n <literal>Point</literal> and <literal>Point</literal>, or\n <literal>Point</literal> and <literal>MultiPoint</literal>\n (in any argument order). If at least one of the geometries\n is neither <literal>Point</literal> nor\n <literal>MultiPoint</literal>, and its SRID is 0, an\n <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_CARTESIAN_SRS</literal>\n error occurs. If at least one of the geometries is neither\n <literal>Point</literal> nor\n <literal>MultiPoint</literal>, and its SRID refers to a\n geographic SRS, an\n <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS</literal>\n error occurs. If any geometry refers to a projected SRS,\n an\n <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_PROJECTED_SRS</literal>\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 <literal role=\"error\">ER_LONGITUDE_OUT_OF_RANGE</literal>\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n <literal role=\"error\">ER_LATITUDE_OUT_OF_RANGE</literal>\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 <replaceable>radius</replaceable> argument is\n present but not positive, an\n <literal role=\"error\">ER_NONPOSITIVE_RADIUS</literal>\n error occurs."
}
],
[
{
"para": "If the distance exceeds the range of a double-precision\n number, an\n <literal role=\"error\">ER_STD_OVERFLOW_ERROR</literal>\n error occurs."
}
]
]
}
],
"id": "ST_Distance_Sphere",
"syntax": []
},
{
"keywords": [
"ST_ISVALID"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_IsValid()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_IsValid(<replaceable>g</replaceable>)</literal>"
},
{
"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 <literal role=\"func\">ST_IsValid()</literal> returns 1 in this\n case. MySQL does not support GIS <literal>EMPTY</literal>\n values such as <literal>POINT EMPTY</literal>."
},
{
"para": "<literal role=\"func\">ST_IsValid()</literal> 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 <literal role=\"error\">ER_LONGITUDE_OUT_OF_RANGE</literal>\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n <literal role=\"error\">ER_LATITUDE_OUT_OF_RANGE</literal>\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": "<indexterm>\n <primary>ST_MakeEnvelope()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_MakeEnvelope(<replaceable>pt1</replaceable>,\n <replaceable>pt2</replaceable>)</literal>"
},
{
"para": "Returns the rectangle that forms the envelope around two\n points, as a <literal>Point</literal>,\n <literal>LineString</literal>, or <literal>Polygon</literal>."
},
{
"para": "Calculations are done using the Cartesian coordinate system\n rather than on a sphere, spheroid, or on earth."
},
{
"para": "Given two points <replaceable>pt1</replaceable> and\n <replaceable>pt2</replaceable>,\n <literal role=\"func\">ST_MakeEnvelope()</literal> creates the\n result geometry on an abstract plane like this:"
},
{
"itemizedlist": [
[
{
"para": "If <replaceable>pt1</replaceable> and\n <replaceable>pt2</replaceable> are equal, the result is\n the point <replaceable>pt1</replaceable>."
}
],
[
{
"para": "Otherwise, if <literal>(<replaceable>pt1</replaceable>,\n <replaceable>pt2</replaceable>)</literal> is a vertical or\n horizontal line segment, the result is the line segment\n <literal>(<replaceable>pt1</replaceable>,\n <replaceable>pt2</replaceable>)</literal>."
}
],
[
{
"para": "Otherwise, the result is a polygon using\n <replaceable>pt1</replaceable> and\n <replaceable>pt2</replaceable> as diagonal points."
}
]
]
},
{
"para": "The result geometry has an SRID of 0."
},
{
"para": "<literal role=\"func\">ST_MakeEnvelope()</literal> handles its\n arguments as described in the introduction to this section,\n with these exceptions:"
},
{
"itemizedlist": [
[
{
"para": "If the arguments are not <literal>Point</literal> values,\n an <literal role=\"error\">ER_WRONG_ARGUMENTS</literal>\n error occurs."
}
],
[
{
"para": "An <literal role=\"error\">ER_GIS_INVALID_DATA</literal>\n error occurs for the additional condition that any\n coordinate value of the two points is infinite or\n <literal>NaN</literal>."
}
],
[
{
"para": "If any geometry has an SRID value for a geographic spatial\n reference system (SRS), an\n <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS</literal>\n error occurs."
}
]
]
}
],
"id": "ST_MakeEnvelope",
"syntax": []
},
{
"keywords": [
"ST_SIMPLIFY"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Simplify()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Simplify(<replaceable>g</replaceable>,\n <replaceable>max_distance</replaceable>)</literal>"
},
{
"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 <replaceable>max_distance</replaceable> 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 <literal role=\"func\">ST_IsValid()</literal>."
},
{
"para": "<literal role=\"func\">ST_Simplify()</literal> handles its\n arguments as described in the introduction to this section,\n with this exception:"
},
{
"itemizedlist": [
[
{
"para": "If the <replaceable>max_distance</replaceable> argument is\n not positive, or is <literal>NaN</literal>, an\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs."
}
]
]
}
],
"id": "ST_Simplify",
"syntax": []
},
{
"keywords": [
"ST_VALIDATE"
],
"description": [
{
"para": "<literal role=\"func\">ST_Validate(<replaceable>g</replaceable>)</literal>"
},
{
"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: <literal>POLYGON((0 0, 0 0, 0 0, 0 0, 0\n 0))</literal>"
},
{
"para": "<literal role=\"func\">ST_Validate()</literal> returns the\n geometry if it is syntactically well-formed and is\n geometrically valid, <literal>NULL</literal> if the argument\n is not syntactically well-formed or is not geometrically valid\n or is <literal>NULL</literal>."
},
{
"para": "<literal role=\"func\">ST_Validate()</literal> 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 <literal>Polygon</literal> or\n <literal>MultiPolygon</literal> 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 <literal role=\"func\">ST_Validate()</literal> returns it\n directly without further checks in this case."
},
{
"para": "As of MySQL 8.0.13,\n <literal role=\"func\">ST_Validate()</literal> 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 <literal role=\"error\">ER_LONGITUDE_OUT_OF_RANGE</literal>\n error occurs."
}
],
[
{
"para": "If any latitude argument is not in the range\n [minus90, 90], an\n <literal role=\"error\">ER_LATITUDE_OUT_OF_RANGE</literal>\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 <literal role=\"func\">ST_Validate()</literal> 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 <literal>NULL</literal>. An\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal> error\n does not occur."
}
],
[
{
"para": "If the geometry has an SRID value for a geographic spatial\n reference system (SRS), an\n <literal role=\"error\">ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS</literal>\n error occurs."
}
]
]
}
],
"id": "ST_Validate",
"syntax": []
},
{
"keywords": [
"BEGIN",
"END"
],
"description": [
{
"para": "<literal condition=\"begin-end\" role=\"stmt\">BEGIN ... END</literal>\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 <literal>BEGIN</literal> and\n <literal>END</literal> keywords.\n <replaceable>statement_list</replaceable> represents a list of one\n or more statements, each terminated by a semicolon\n (<literal>;</literal>) statement delimiter. The\n <replaceable>statement_list</replaceable> itself is optional, so\n the empty compound statement (<literal>BEGIN END</literal>) is\n legal."
},
{
"para": "<literal condition=\"begin-end\" role=\"stmt\">BEGIN ... END</literal>\n blocks can be nested."
},
{
"para": "Use of multiple statements requires that a client is able to send\n statement strings containing the <literal>;</literal> statement\n delimiter. In the <command>mysql</command> command-line client,\n this is handled with the <literal>delimiter</literal> command.\n Changing the <literal>;</literal> end-of-statement delimiter (for\n example, to <literal>//</literal>) permit <literal>;</literal> to\n be used in a program body. For an example, see\n <xref linkend=\"stored-programs-defining\" />."
},
{
"para": "A <literal condition=\"begin-end\" role=\"stmt\">BEGIN ...\n END</literal> block can be labeled. See\n <xref linkend=\"statement-labels\" />."
}
],
"id": "BEGIN END",
"syntax": [
{
"programlisting": ">\n[<replaceable>begin_label</replaceable>:] BEGIN\n [<replaceable>statement_list</replaceable>]\nEND [<replaceable>end_label</replaceable>]"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Labels are permitted for\n <literal condition=\"begin-end\" role=\"stmt\">BEGIN ... END</literal>\n blocks and for the <literal role=\"stmt\">LOOP</literal>,\n <literal role=\"stmt\">REPEAT</literal>, and\n <literal role=\"stmt\">WHILE</literal> statements. Label use for\n those statements follows these rules:"
},
{
"itemizedlist": [
[
{
"para": "<replaceable>begin_label</replaceable> must be followed by a\n colon."
}
],
[
{
"para": "<replaceable>begin_label</replaceable> can be given without\n <replaceable>end_label</replaceable>. If\n <replaceable>end_label</replaceable> is present, it must be\n the same as <replaceable>begin_label</replaceable>."
}
],
[
{
"para": "<replaceable>end_label</replaceable> cannot be given without\n <replaceable>begin_label</replaceable>."
}
],
[
{
"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 <literal role=\"stmt\">ITERATE</literal> or\n <literal role=\"stmt\">LEAVE</literal> 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 <xref linkend=\"declare-handler\" />."
}
],
"id": "labels",
"syntax": [
{
"programlisting": ">\n[<replaceable>begin_label</replaceable>:] BEGIN\n [<replaceable>statement_list</replaceable>]\nEND [<replaceable>end_label</replaceable>]\n\n[<replaceable>begin_label</replaceable>:] LOOP\n <replaceable>statement_list</replaceable>\nEND LOOP [<replaceable>end_label</replaceable>]\n\n[<replaceable>begin_label</replaceable>:] REPEAT\n <replaceable>statement_list</replaceable>\nUNTIL <replaceable>search_condition</replaceable>\nEND REPEAT [<replaceable>end_label</replaceable>]\n\n[<replaceable>begin_label</replaceable>:] WHILE <replaceable>search_condition</replaceable> DO\n <replaceable>statement_list</replaceable>\nEND WHILE [<replaceable>end_label</replaceable>]"
}
]
},
{
"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 <literal>DEFAULT</literal> clause. The value can be specified as\n an expression; it need not be a constant. If the\n <literal>DEFAULT</literal> clause is missing, the initial value\n is <literal>NULL</literal>."
},
{
"para": "Local variables are treated like stored routine parameters with\n respect to data type and overflow checking. See\n <xref linkend=\"create-procedure\" />."
},
{
"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 <xref linkend=\"identifiers\" />."
},
{
"para": "The scope of a local variable is the\n <literal condition=\"begin-end\" role=\"stmt\">BEGIN ...\n END</literal> 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 <xref linkend=\"local-variable-scope\" />."
}
],
"id": "DECLARE variable",
"syntax": [
{
"programlisting": ">\nDECLARE <replaceable>var_name</replaceable> [, <replaceable>var_name</replaceable>] ... <replaceable>type</replaceable> [DEFAULT <replaceable>value</replaceable>]"
}
]
},
{
"keywords": [
"CASE",
"WHEN",
"THEN",
"ELSE",
"END"
],
"description": [
{
"para": "The <literal role=\"stmt\">CASE</literal> statement for stored\n programs implements a complex conditional construct."
},
{
"para": "For the first syntax, <replaceable>case_value</replaceable> is\n an expression. This value is compared to the\n <replaceable>when_value</replaceable> expression in each\n <literal>WHEN</literal> clause until one of them is equal. When\n an equal <replaceable>when_value</replaceable> is found, the\n corresponding <literal>THEN</literal> clause\n <replaceable>statement_list</replaceable> executes. If no\n <replaceable>when_value</replaceable> is equal, the\n <literal>ELSE</literal> clause\n <replaceable>statement_list</replaceable> executes, if there is\n one."
},
{
"para": "This syntax cannot be used to test for equality with\n <literal>NULL</literal> because <literal>NULL = NULL</literal>\n is false. See <xref linkend=\"working-with-null\" />."
},
{
"para": "For the second syntax, each <literal>WHEN</literal> clause\n <replaceable>search_condition</replaceable> expression is\n evaluated until one is true, at which point its corresponding\n <literal>THEN</literal> clause\n <replaceable>statement_list</replaceable> executes. If no\n <replaceable>search_condition</replaceable> is equal, the\n <literal>ELSE</literal> clause\n <replaceable>statement_list</replaceable> executes, if there is\n one."
},
{
"para": "If no <replaceable>when_value</replaceable> or\n <replaceable>search_condition</replaceable> matches the value\n tested and the <literal role=\"stmt\">CASE</literal> statement\n contains no <literal>ELSE</literal> clause, a <errortext>Case\n not found for CASE statement</errortext> error results."
},
{
"para": "Each <replaceable>statement_list</replaceable> consists of one\n or more SQL statements; an empty\n <replaceable>statement_list</replaceable> is not permitted."
},
{
"para": "To handle situations where no value is matched by any\n <literal>WHEN</literal> clause, use an <literal>ELSE</literal>\n containing an empty\n <literal condition=\"begin-end\" role=\"stmt\">BEGIN ...\n END</literal> block, as shown in this example. (The indentation\n used here in the <literal>ELSE</literal> 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 <replaceable>case_value</replaceable>\n WHEN <replaceable>when_value</replaceable> THEN <replaceable>statement_list</replaceable>\n [WHEN <replaceable>when_value</replaceable> THEN <replaceable>statement_list</replaceable>] ...\n [ELSE <replaceable>statement_list</replaceable>]\nEND CASE"
},
{
"para": "Or:"
},
{
"programlisting": ">\nCASE\n WHEN <replaceable>search_condition</replaceable> THEN <replaceable>statement_list</replaceable>\n [WHEN <replaceable>search_condition</replaceable> THEN <replaceable>statement_list</replaceable>] ...\n [ELSE <replaceable>statement_list</replaceable>]\nEND CASE"
}
]
},
{
"keywords": [
"IF",
"THEN",
"ELSEIF",
"END"
],
"description": [
{
"para": "The <literal role=\"stmt\">IF</literal> statement for stored\n programs implements a basic conditional construct."
},
{
"para": "If a given <replaceable>search_condition</replaceable> evaluates\n to true, the corresponding <literal>THEN</literal> or\n <literal>ELSEIF</literal> clause\n <replaceable>statement_list</replaceable> executes. If no\n <replaceable>search_condition</replaceable> matches, the\n <literal>ELSE</literal> clause\n <replaceable>statement_list</replaceable> executes."
},
{
"para": "Each <replaceable>statement_list</replaceable> consists of one\n or more SQL statements; an empty\n <replaceable>statement_list</replaceable> is not permitted."
}
],
"id": "IF statement",
"syntax": [
{
"programlisting": ">\nIF <replaceable>search_condition</replaceable> THEN <replaceable>statement_list</replaceable>\n [ELSEIF <replaceable>search_condition</replaceable> THEN <replaceable>statement_list</replaceable>] ...\n [ELSE <replaceable>statement_list</replaceable>]\nEND IF"
}
]
},
{
"keywords": [
"ITERATE"
],
"description": [
{
"para": "<literal role=\"stmt\">ITERATE</literal> can appear only within\n <literal role=\"stmt\">LOOP</literal>,\n <literal role=\"stmt\">REPEAT</literal>, and\n <literal role=\"stmt\">WHILE</literal> statements.\n <literal role=\"stmt\">ITERATE</literal> means <quote>start the\n loop again.</quote>"
}
],
"id": "ITERATE",
"syntax": [
{
"programlisting": ">\nITERATE <replaceable>label</replaceable>"
}
]
},
{
"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, <literal role=\"stmt\">LEAVE</literal> exits the\n program."
},
{
"para": "<literal role=\"stmt\">LEAVE</literal> can be used within\n <literal condition=\"begin-end\" role=\"stmt\">BEGIN ...\n END</literal> or loop constructs\n (<literal role=\"stmt\">LOOP</literal>,\n <literal role=\"stmt\">REPEAT</literal>,\n <literal role=\"stmt\">WHILE</literal>)."
}
],
"id": "LEAVE",
"syntax": [
{
"programlisting": ">\nLEAVE <replaceable>label</replaceable>"
}
]
},
{
"keywords": [
"LOOP",
"END"
],
"description": [
{
"para": "<literal role=\"stmt\">LOOP</literal> 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 (<literal>;</literal>) statement delimiter. The\n statements within the loop are repeated until the loop is\n terminated. Usually, this is accomplished with a\n <literal role=\"stmt\">LEAVE</literal> statement. Within a stored\n function, <literal role=\"stmt\">RETURN</literal> 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 <literal role=\"stmt\">LOOP</literal> statement can be labeled.\n For the rules regarding label use, see\n <xref linkend=\"statement-labels\" />."
}
],
"id": "LOOP",
"syntax": [
{
"programlisting": ">\n[<replaceable>begin_label</replaceable>:] LOOP\n <replaceable>statement_list</replaceable>\nEND LOOP [<replaceable>end_label</replaceable>]"
}
]
},
{
"keywords": [
"REPEAT",
"UNTIL",
"END"
],
"description": [
{
"para": "The statement list within a\n <literal role=\"stmt\">REPEAT</literal> statement is repeated\n until the <replaceable>search_condition</replaceable> expression\n is true. Thus, a <literal role=\"stmt\">REPEAT</literal> always\n enters the loop at least once.\n <replaceable>statement_list</replaceable> consists of one or\n more statements, each terminated by a semicolon\n (<literal>;</literal>) statement delimiter."
},
{
"para": "A <literal role=\"stmt\">REPEAT</literal> statement can be\n labeled. For the rules regarding label use, see\n <xref linkend=\"statement-labels\" />."
}
],
"id": "REPEAT loop",
"syntax": [
{
"programlisting": ">\n[<replaceable>begin_label</replaceable>:] REPEAT\n <replaceable>statement_list</replaceable>\nUNTIL <replaceable>search_condition</replaceable>\nEND REPEAT [<replaceable>end_label</replaceable>]"
}
]
},
{
"keywords": [
"RETURN"
],
"description": [
{
"para": "The <literal role=\"stmt\">RETURN</literal> statement terminates\n execution of a stored function and returns the value\n <replaceable>expr</replaceable> to the function caller. There\n must be at least one <literal role=\"stmt\">RETURN</literal>\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 <literal role=\"stmt\">LEAVE</literal> statement can\n be used to exit a stored program of those types."
}
],
"id": "RETURN",
"syntax": [
{
"programlisting": ">\nRETURN <replaceable>expr</replaceable>"
}
]
},
{
"keywords": [
"WHILE",
"DO",
"END"
],
"description": [
{
"para": "The statement list within a <literal role=\"stmt\">WHILE</literal>\n statement is repeated as long as the\n <replaceable>search_condition</replaceable> expression is true.\n <replaceable>statement_list</replaceable> consists of one or\n more SQL statements, each terminated by a semicolon\n (<literal>;</literal>) statement delimiter."
},
{
"para": "A <literal role=\"stmt\">WHILE</literal> statement can be labeled.\n For the rules regarding label use, see\n <xref linkend=\"statement-labels\" />."
}
],
"id": "WHILE",
"syntax": [
{
"programlisting": ">\n[<replaceable>begin_label</replaceable>:] WHILE <replaceable>search_condition</replaceable> DO\n <replaceable>statement_list</replaceable>\nEND WHILE [<replaceable>end_label</replaceable>]"
}
]
},
{
"keywords": [
"CLOSE"
],
"description": [
{
"para": "This statement closes a previously opened cursor. For an\n example, see <xref linkend=\"cursors\" />."
},
{
"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 <literal condition=\"begin-end\" role=\"stmt\">BEGIN ...\n END</literal> block in which it was declared."
}
],
"id": "CLOSE",
"syntax": [
{
"programlisting": ">\nCLOSE <replaceable>cursor_name</replaceable>"
}
]
},
{
"keywords": [
"DECLARE",
"CURSOR",
"FOR"
],
"description": [
{
"para": "This statement declares a cursor and associates it with a\n <literal role=\"stmt\">SELECT</literal> statement that retrieves\n the rows to be traversed by the cursor. To fetch the rows later,\n use a <literal role=\"stmt\">FETCH</literal> statement. The number\n of columns retrieved by the\n <literal role=\"stmt\">SELECT</literal> statement must match the\n number of output variables specified in the\n <literal role=\"stmt\">FETCH</literal> statement."
},
{
"para": "The <literal role=\"stmt\">SELECT</literal> statement cannot have\n an <literal>INTO</literal> 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 <xref linkend=\"cursors\" />."
},
{
"para": "For information available through\n <literal role=\"stmt\">SHOW</literal> statements, it is possible\n in many cases to obtain equivalent information by using a cursor\n with an <literal>INFORMATION_SCHEMA</literal> table."
}
],
"id": "DECLARE CURSOR",
"syntax": [
{
"programlisting": ">\nDECLARE <replaceable>cursor_name</replaceable> CURSOR FOR <replaceable>select_statement</replaceable>"
}
]
},
{
"keywords": [
"FETCH"
],
"description": [
{
"para": "This statement fetches the next row for the\n <literal role=\"stmt\">SELECT</literal> 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 <literal role=\"stmt\">SELECT</literal> statement must match the\n number of output variables specified in the\n <literal role=\"stmt\">FETCH</literal> statement."
},
{
"para": "If no more rows are available, a No Data condition occurs with\n SQLSTATE value <literal>'02000'</literal>. To detect this\n condition, you can set up a handler for it (or for a\n <literal>NOT FOUND</literal> condition). For an example, see\n <xref linkend=\"cursors\" />."
},
{
"para": "Be aware that another operation, such as a\n <literal>SELECT</literal> or another <literal>FETCH</literal>,\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 <literal condition=\"begin-end\" role=\"stmt\">BEGIN ...\n END</literal> block so that it can be associated with its own\n handler."
}
],
"id": "FETCH",
"syntax": [
{
"programlisting": ">\nFETCH [[NEXT] FROM] <replaceable>cursor_name</replaceable> INTO <replaceable>var_name</replaceable> [, <replaceable>var_name</replaceable>] ..."
}
]
},
{
"keywords": [
"OPEN"
],
"description": [
{
"para": "This statement opens a previously declared cursor. For an\n example, see <xref linkend=\"cursors\" />."
}
],
"id": "OPEN",
"syntax": [
{
"programlisting": ">\nOPEN <replaceable>cursor_name</replaceable>"
}
]
},
{
"keywords": [
"DECLARE",
"CONDITION",
"FOR"
],
"description": [
{
"para": "The <literal condition=\"declare-condition\" role=\"stmt\">DECLARE\n ... CONDITION</literal> 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 <literal condition=\"declare-handler\" role=\"stmt\">DECLARE ...\n HANDLER</literal> statement (see\n <xref linkend=\"declare-handler\" />)."
},
{
"para": "Condition declarations must appear before cursor or handler\n declarations."
},
{
"para": "The <replaceable>condition_value</replaceable> for\n <literal condition=\"declare-condition\" role=\"stmt\">DECLARE ...\n CONDITION</literal> indicates the specific condition or class of\n conditions to associate with the condition name. It can take the\n following forms:"
},
{
"itemizedlist": [
[
{
"para": "<replaceable>mysql_error_code</replaceable>: 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 <xref linkend=\"server-error-reference\" />."
}
],
[
{
"para": "SQLSTATE [VALUE] <replaceable>sqlstate_value</replaceable>:\n A 5-character string literal indicating an SQLSTATE value."
},
{
"para": "Do not use SQLSTATE values that begin with\n <literal>'00'</literal> because those indicate success\n rather than an error condition. For a list of SQLSTATE\n values, see <xref linkend=\"server-error-reference\" />."
}
]
]
},
{
"para": "Condition names referred to in\n <literal role=\"stmt\">SIGNAL</literal> or use\n <literal role=\"stmt\">RESIGNAL</literal> statements must be\n associated with SQLSTATE values, not MySQL error codes."
}
],
"id": "DECLARE CONDITION",
"syntax": [
{
"programlisting": ">\nDECLARE <replaceable>condition_name</replaceable> CONDITION FOR <replaceable>condition_value</replaceable>\n\n<replaceable>condition_value</replaceable>: {\n <replaceable>mysql_error_code</replaceable>\n | SQLSTATE [VALUE] <replaceable>sqlstate_value</replaceable>\n}"
}
]
},
{
"keywords": [
"DECLARE",
"HANDLER",
"FOR",
"CONTINUE",
"EXIT",
"UNDO"
],
"description": [
{
"para": "The <literal condition=\"declare-handler\" role=\"stmt\">DECLARE ...\n HANDLER</literal> statement specifies a handler that deals with\n one or more conditions. If one of these conditions occurs, the\n specified <replaceable>statement</replaceable> executes.\n <replaceable>statement</replaceable> can be a simple statement\n such as <literal>SET <replaceable>var_name</replaceable> =\n <replaceable>value</replaceable></literal>, or a compound\n statement written using <literal>BEGIN</literal> and\n <literal>END</literal> (see <xref linkend=\"begin-end\" />)."
},
{
"para": "Handler declarations must appear after variable or condition\n declarations."
},
{
"para": "The <replaceable>handler_action</replaceable> value indicates\n what action the handler takes after execution of the handler\n statement:"
},
{
"itemizedlist": [
[
{
"para": "<literal>CONTINUE</literal>: Execution of the current\n program continues."
}
],
[
{
"para": "<literal>EXIT</literal>: Execution terminates for the\n <literal condition=\"begin-end\" role=\"stmt\">BEGIN ...\n END</literal> compound statement in which the handler is\n declared. This is true even if the condition occurs in an\n inner block."
}
],
[
{
"para": "<literal>UNDO</literal>: Not supported."
}
]
]
},
{
"para": "The <replaceable>condition_value</replaceable> for\n <literal condition=\"declare-handler\" role=\"stmt\">DECLARE ...\n HANDLER</literal> indicates the specific condition or class of\n conditions that activates the handler. It can take the following\n forms:"
},
{
"itemizedlist": [
[
{
"para": "<replaceable>mysql_error_code</replaceable>: An integer\n literal indicating a MySQL error code, such as 1051 to\n specify <quote>unknown table</quote>:"
},
{
"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 <xref linkend=\"server-error-reference\" />."
}
],
[
{
"para": "SQLSTATE [VALUE] <replaceable>sqlstate_value</replaceable>:\n A 5-character string literal indicating an SQLSTATE value,\n such as <literal>'42S01'</literal> to specify <quote>unknown\n table</quote>:"
},
{
"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 <literal>'00'</literal> because those indicate success\n rather than an error condition. For a list of SQLSTATE\n values, see <xref linkend=\"server-error-reference\" />."
}
],
[
{
"para": "<replaceable>condition_name</replaceable>: A condition name\n previously specified with\n <literal condition=\"declare-condition\" role=\"stmt\">DECLARE\n ... CONDITION</literal>. A condition name can be associated\n with a MySQL error code or SQLSTATE value. See\n <xref linkend=\"declare-condition\" />."
}
],
[
{
"para": "<literal>SQLWARNING</literal>: Shorthand for the class of\n SQLSTATE values that begin with <literal>'01'</literal>."
},
{
"programlisting": ">\nDECLARE CONTINUE HANDLER FOR SQLWARNING\n BEGIN\n -- body of handler\n END;"
}
],
[
{
"para": "<literal>NOT FOUND</literal>: Shorthand for the class of\n SQLSTATE values that begin with <literal>'02'</literal>.\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 <literal>'02000'</literal>. To\n detect this condition, you can set up a handler for it or\n for a <literal>NOT FOUND</literal> condition."
},
{
"programlisting": ">\nDECLARE CONTINUE HANDLER FOR NOT FOUND\n BEGIN\n -- body of handler\n END;"
},
{
"para": "For another example, see <xref linkend=\"cursors\" />. The\n <literal>NOT FOUND</literal> condition also occurs for\n <literal>SELECT ... INTO\n <replaceable>var_list</replaceable></literal> statements\n that retrieve no rows."
}
],
[
{
"para": "<literal>SQLEXCEPTION</literal>: Shorthand for the class of\n SQLSTATE values that do not begin with\n <literal>'00'</literal>, <literal>'01'</literal>, or\n <literal>'02'</literal>."
},
{
"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 <xref linkend=\"handler-scope\" />."
},
{
"para": "If a condition occurs for which no handler has been declared,\n the action taken depends on the condition class:"
},
{
"itemizedlist": [
[
{
"para": "For <literal>SQLEXCEPTION</literal> conditions, the stored\n program terminates at the statement that raised the\n condition, as if there were an <literal>EXIT</literal>\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 <literal>SQLWARNING</literal> conditions, the program\n continues executing, as if there were a\n <literal>CONTINUE</literal> handler."
}
],
[
{
"para": "For <literal>NOT FOUND</literal> conditions, if the\n condition was raised normally, the action is\n <literal>CONTINUE</literal>. If it was raised by\n <literal role=\"stmt\">SIGNAL</literal> or\n <literal role=\"stmt\">RESIGNAL</literal>, the action is\n <literal>EXIT</literal>."
}
]
]
}
],
"id": "DECLARE HANDLER",
"syntax": [
{
"programlisting": ">\nDECLARE <replaceable>handler_action</replaceable> HANDLER\n FOR <replaceable>condition_value</replaceable> [, <replaceable>condition_value</replaceable>] ...\n <replaceable>statement</replaceable>\n\n<replaceable>handler_action</replaceable>: {\n CONTINUE\n | EXIT\n | UNDO\n}\n\n<replaceable>condition_value</replaceable>: {\n <replaceable>mysql_error_code</replaceable>\n | SQLSTATE [VALUE] <replaceable>sqlstate_value</replaceable>\n | <replaceable>condition_name</replaceable>\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 <literal role=\"stmt\">GET\n DIAGNOSTICS</literal> statement enables applications to inspect\n this information. (You can also use <literal role=\"stmt\">SHOW\n WARNINGS</literal> or <literal role=\"stmt\">SHOW ERRORS</literal>\n to see conditions or errors.)"
},
{
"para": "No special privileges are required to execute\n <literal role=\"stmt\">GET DIAGNOSTICS</literal>."
},
{
"para": "The keyword <literal>CURRENT</literal> means to retrieve\n information from the current diagnostics area. The keyword\n <literal>STACKED</literal> 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 <literal role=\"stmt\">GET DIAGNOSTICS</literal> statement is\n typically used in a handler within a stored program. It is a\n MySQL extension that\n <literal condition=\"get-diagnostics\" role=\"stmt\">GET [CURRENT]\n DIAGNOSTICS</literal> is permitted outside handler context to\n check the execution of any SQL statement. For example, if you\n invoke the <command>mysql</command> client program, you can\n enter these statements at the prompt:"
},
{
"programlisting": ">\nmysql> <userinput>DROP TABLE test.no_such_table;</userinput>\nERROR 1051 (42S02): Unknown table 'test.no_such_table'\nmysql> <userinput>GET DIAGNOSTICS CONDITION 1</userinput>\n <userinput>@p1 = RETURNED_SQLSTATE, @p2 = MESSAGE_TEXT;</userinput>\nmysql> <userinput>SELECT @p1, @p2;</userinput>\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 <literal>GET STACKED DIAGNOSTICS</literal> is permitted only if\n the current context is a condition handler. If that is not the\n case, a <literal>GET STACKED DIAGNOSTICS when handler not\n active</literal> error occurs."
},
{
"para": "For a description of the diagnostics area, see\n <xref linkend=\"diagnostics-area\" />. 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": "<literal role=\"stmt\">GET DIAGNOSTICS</literal> 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 <literal role=\"stmt\">GET DIAGNOSTICS</literal> assigns the\n number of available conditions and the rows-affected count\n to the user variables <literal>@p1</literal> and\n <literal>@p2</literal>:"
},
{
"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 <literal role=\"stmt\">GET\n DIAGNOSTICS</literal> assigns the SQLSTATE value and error\n message to the user variables <literal>@p3</literal> and\n <literal>@p4</literal>:"
},
{
"programlisting": ">\nGET DIAGNOSTICS CONDITION 1\n @p3 = RETURNED_SQLSTATE, @p4 = MESSAGE_TEXT;"
}
]
]
},
{
"para": "The retrieval list specifies one or more\n <literal><replaceable>target</replaceable> =\n <replaceable>item_name</replaceable></literal> assignments,\n separated by commas. Each assignment names a target variable and\n either a\n <replaceable>statement_information_item_name</replaceable> or\n <replaceable>condition_information_item_name</replaceable>\n designator, depending on whether the statement retrieves\n statement or condition information."
},
{
"para": "Valid <replaceable>target</replaceable> designators for storing\n item information can be stored procedure or function parameters,\n stored program local variables declared with\n <literal role=\"stmt\">DECLARE</literal>, or user-defined\n variables."
},
{
"para": "Valid <replaceable>condition_number</replaceable> designators\n can be stored procedure or function parameters, stored program\n local variables declared with\n <literal role=\"stmt\">DECLARE</literal>, user-defined variables,\n system variables, or literals. A character literal may include a\n <replaceable>_charset</replaceable> 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 <literal role=\"stmt\">GET\n DIAGNOSTICS</literal>. For example:"
},
{
"programlisting": ">\nmysql> <userinput>GET DIAGNOSTICS CONDITION 1</userinput>\n <userinput>@p5 = SCHEMA_NAME, @p6 = TABLE_NAME;</userinput>\nmysql> <userinput>SELECT @p5, @p6;</userinput>\n+------+------+\n| @p5 | @p6 |\n+------+------+\n| | |\n+------+------+"
},
{
"para": "In standard SQL, if there are multiple conditions, the first\n condition relates to the <literal>SQLSTATE</literal> 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 <xref linkend=\"diagnostics-area-information-items\" />."
},
{
"para": "Here is an example that uses <literal role=\"stmt\">GET\n DIAGNOSTICS</literal> 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 <literal role=\"stmt\">GET DIAGNOSTICS</literal> to get the\n rows-affected count. This shows that you can use\n <literal role=\"stmt\">GET DIAGNOSTICS</literal> 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 <literal>t1.int_col</literal> is an integer column\n that is declared as <literal>NOT NULL</literal>. The procedure\n produces these results when invoked to insert\n non-<literal>NULL</literal> and <literal>NULL</literal> values,\n respectively:"
},
{
"programlisting": ">\nmysql> <userinput>CALL do_insert(1);</userinput>\n+---------------------------------+\n| result |\n+---------------------------------+\n| insert succeeded, row count = 1 |\n+---------------------------------+\n\nmysql> <userinput>CALL do_insert(NULL);</userinput>\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 <replaceable>statement_information_item</replaceable>\n [, <replaceable>statement_information_item</replaceable>] ...\n | CONDITION <replaceable>condition_number</replaceable>\n <replaceable>condition_information_item</replaceable>\n [, <replaceable>condition_information_item</replaceable>] ...\n}\n\n<replaceable>statement_information_item</replaceable>:\n <replaceable>target</replaceable> = <replaceable>statement_information_item_name</replaceable>\n\n<replaceable>condition_information_item</replaceable>:\n <replaceable>target</replaceable> = <replaceable>condition_information_item_name</replaceable>\n\n<replaceable>statement_information_item_name</replaceable>:\n NUMBER\n | ROW_COUNT\n\n<replaceable>condition_information_item_name</replaceable>: {\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\n<replaceable>condition_number</replaceable>, <replaceable>target</replaceable>:\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": "<literal role=\"stmt\">RESIGNAL</literal> 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 <literal role=\"stmt\">RESIGNAL</literal> may change some or all\n information before passing it on.\n <literal role=\"stmt\">RESIGNAL</literal> is related to\n <literal role=\"stmt\">SIGNAL</literal>, but instead of\n originating a condition as <literal role=\"stmt\">SIGNAL</literal>\n does, <literal role=\"stmt\">RESIGNAL</literal> relays existing\n condition information, possibly after modifying it."
},
{
"para": "<literal role=\"stmt\">RESIGNAL</literal> 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 <literal role=\"stmt\">RESIGNAL</literal> also can make some\n procedures shorter if a given handler can handle part of a\n situation, then pass the condition <quote>up the line</quote> to\n another handler."
},
{
"para": "No privileges are required to execute the\n <literal role=\"stmt\">RESIGNAL</literal> statement."
},
{
"para": "All forms of <literal role=\"stmt\">RESIGNAL</literal> require\n that the current context be a condition handler. Otherwise,\n <literal role=\"stmt\">RESIGNAL</literal> is illegal and a\n <literal>RESIGNAL when handler not active</literal> error\n occurs."
},
{
"para": "To retrieve information from the diagnostics area, use the\n <literal role=\"stmt\">GET DIAGNOSTICS</literal> statement (see\n <xref linkend=\"get-diagnostics\" />). For information about the\n diagnostics area, see <xref linkend=\"diagnostics-area\" />."
}
],
"id": "RESIGNAL",
"syntax": [
{
"programlisting": ">\nRESIGNAL [<replaceable>condition_value</replaceable>]\n [SET <replaceable>signal_information_item</replaceable>\n [, <replaceable>signal_information_item</replaceable>] ...]\n\n<replaceable>condition_value</replaceable>: {\n SQLSTATE [VALUE] <replaceable>sqlstate_value</replaceable>\n | <replaceable>condition_name</replaceable>\n}\n\n<replaceable>signal_information_item</replaceable>:\n <replaceable>condition_information_item_name</replaceable> = <replaceable>simple_value_specification</replaceable>\n\n<replaceable>condition_information_item_name</replaceable>: {\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\n<replaceable>condition_name</replaceable>, <replaceable>simple_value_specification</replaceable>:\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": "<literal role=\"stmt\">SIGNAL</literal> is the way to\n <quote>return</quote> an error.\n <literal role=\"stmt\">SIGNAL</literal> 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, <literal>SQLSTATE</literal>\n value, message). Without <literal role=\"stmt\">SIGNAL</literal>,\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 <literal role=\"stmt\">SIGNAL</literal> statement."
},
{
"para": "To retrieve information from the diagnostics area, use the\n <literal role=\"stmt\">GET DIAGNOSTICS</literal> statement (see\n <xref linkend=\"get-diagnostics\" />). For information about the\n diagnostics area, see <xref linkend=\"diagnostics-area\" />."
}
],
"id": "SIGNAL",
"syntax": [
{
"programlisting": ">\nSIGNAL <replaceable>condition_value</replaceable>\n [SET <replaceable>signal_information_item</replaceable>\n [, <replaceable>signal_information_item</replaceable>] ...]\n\n<replaceable>condition_value</replaceable>: {\n SQLSTATE [VALUE] <replaceable>sqlstate_value</replaceable>\n | <replaceable>condition_name</replaceable>\n}\n\n<replaceable>signal_information_item</replaceable>:\n <replaceable>condition_information_item_name</replaceable> = <replaceable>simple_value_specification</replaceable>\n\n<replaceable>condition_information_item_name</replaceable>: {\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\n<replaceable>condition_name</replaceable>, <replaceable>simple_value_specification</replaceable>:\n (see following discussion)"
}
]
},
{
"keywords": [
"ALTER",
"DATABASE",
"SCHEMA",
"DEFAULT",
"CHARACTER",
"SET",
"COLLATE",
"ENCRYPTION"
],
"description": [
{
"para": "<literal role=\"stmt\">ALTER DATABASE</literal> enables you to\n change the overall characteristics of a database. These\n characteristics are stored in the data dictionary. To use\n <literal role=\"stmt\">ALTER DATABASE</literal>, you need the\n <literal role=\"priv\">ALTER</literal> privilege on the database.\n <literal condition=\"alter-database\" role=\"stmt\">ALTER\n SCHEMA</literal> is a synonym for <literal role=\"stmt\">ALTER\n DATABASE</literal>."
},
{
"para": "The database name can be omitted from the first syntax, in which\n case the statement applies to the default database."
},
{
"para": "The <literal>CHARACTER SET</literal> clause changes the default\n database character set. The <literal>COLLATE</literal> clause\n changes the default database collation. <xref linkend=\"charset\" />,\n discusses character set and collation names."
},
{
"para": "You can see what character sets and collations are available\n using, respectively, the <literal role=\"stmt\">SHOW CHARACTER\n SET</literal> and <literal role=\"stmt\">SHOW COLLATION</literal>\n statements. See <xref linkend=\"show-character-set\" />, and\n <xref linkend=\"show-collation\" />, 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 <xref linkend=\"create-procedure\" />.)"
},
{
"para": "The <literal>DEFAULT ENCRYPTION</literal> 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 <literal>ALTER\n DATABASE</literal> statement executed without a <literal>DEFAULT\n ENCRYPTION</literal> clause retains the existing default database\n encryption. If the\n <literal role=\"sysvar\">table_encryption_privilege_check</literal>\n variable is enabled, the\n <literal role=\"priv\">TABLE_ENCRYPTION_ADMIN</literal> privilege is\n required to specify a default encryption setting that differs from\n the <literal role=\"sysvar\">default_table_encryption</literal>\n setting. For more information, see\n <xref linkend=\"innodb-schema-tablespace-encryption-default\" />."
}
],
"id": "ALTER DATABASE",
"syntax": [
{
"programlisting": ">\nALTER {DATABASE | SCHEMA} [<replaceable>db_name</replaceable>]\n <replaceable>alter_specification</replaceable> ...\n\n<replaceable>alter_specification</replaceable>:\n [DEFAULT] CHARACTER SET [=] <replaceable>charset_name</replaceable>\n | [DEFAULT] COLLATE [=] <replaceable>collation_name</replaceable>\n | DEFAULT ENCRYPTION [=] {'Y' | 'N'}"
}
]
},
{
"keywords": [
"ALTER",
"EVENT",
"DEFINER",
"CURRENT_USER",
"SCHEDULE",
"RENAME",
"COMPLETION",
"PRESERVE",
"ENABLE",
"DISABLE",
"ON",
"SLAVE",
"COMMENT",
"DO"
],
"description": [
{
"para": "The <literal role=\"stmt\">ALTER EVENT</literal> 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 <literal>DEFINER</literal>, <literal>ON SCHEDULE</literal>,\n <literal>ON COMPLETION</literal>, <literal>COMMENT</literal>,\n <literal>ENABLE</literal> / <literal>DISABLE</literal>, and\n <literal role=\"stmt\">DO</literal> clauses is exactly the same as\n when used with <literal role=\"stmt\">CREATE EVENT</literal>. (See\n <xref linkend=\"create-event\" />.)"
},
{
"para": "Any user can alter an event defined on a database for which that\n user has the <literal role=\"priv\">EVENT</literal> privilege. When\n a user executes a successful <literal role=\"stmt\">ALTER\n EVENT</literal> statement, that user becomes the definer for the\n affected event."
},
{
"para": "<literal role=\"stmt\">ALTER EVENT</literal> works only with an\n existing event:"
},
{
"programlisting": ">\nmysql> <userinput>ALTER EVENT no_such_event </userinput>\n > <userinput>ON SCHEDULE </userinput>\n > <userinput>EVERY '2:3' DAY_HOUR;</userinput>\n<errortext>ERROR 1517 (HY000): Unknown event 'no_such_event'</errortext>"
}
],
"id": "ALTER EVENT",
"syntax": [
{
"programlisting": ">\nALTER\n [DEFINER = <replaceable>user</replaceable>]\n EVENT <replaceable>event_name</replaceable>\n [ON SCHEDULE <replaceable>schedule</replaceable>]\n [ON COMPLETION [NOT] PRESERVE]\n [RENAME TO <replaceable>new_event_name</replaceable>]\n [ENABLE | DISABLE | DISABLE ON SLAVE]\n [COMMENT '<replaceable>string</replaceable>']\n [DO <replaceable>event_body</replaceable>]"
}
]
},
{
"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 <literal role=\"stmt\">ALTER FUNCTION</literal> 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 <literal role=\"stmt\">DROP\n FUNCTION</literal> and <literal role=\"stmt\">CREATE\n FUNCTION</literal>."
},
{
"para": "You must have the <literal role=\"priv\">ALTER ROUTINE</literal>\n privilege for the function. (That privilege is granted\n automatically to the function creator.) If binary logging is\n enabled, the <literal role=\"stmt\">ALTER FUNCTION</literal>\n statement might also require the\n <literal role=\"priv\">SUPER</literal> privilege, as described in\n <xref linkend=\"stored-programs-logging\" />."
}
],
"id": "ALTER FUNCTION",
"syntax": [
{
"programlisting": ">\nALTER FUNCTION <replaceable>func_name</replaceable> [<replaceable>characteristic</replaceable> ...]\n\n<replaceable>characteristic</replaceable>:\n COMMENT '<replaceable>string</replaceable>'\n | LANGUAGE SQL\n | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }\n | SQL SECURITY { DEFINER | INVOKER }"
}
]
},
{
"keywords": [
"ALTER",
"INSTANCE"
],
"description": [
{
"para": "<literal>ALTER INSTANCE</literal> defines actions applicable to a\n MySQL server instance. The statement supports these actions:"
},
{
"itemizedlist": [
[
{
"para": "<literal>ALTER INSTANCE ROTATE INNODB MASTER KEY</literal>"
},
{
"para": "This action rotates the master encryption key used for\n <literal>InnoDB</literal> tablespace encryption. Key rotation\n requires the\n <literal role=\"priv\">ENCRYPTION_KEY_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege. To perform\n this action, a keyring plugin must be installed and\n configured. For instructions, see <xref linkend=\"keyring\" />."
},
{
"para": "<literal>ALTER INSTANCE ROTATE INNODB MASTER KEY</literal>\n supports concurrent DML. However, it cannot be run\n concurrently with\n <literal condition=\"create-table\" role=\"stmt\">CREATE TABLE ...\n ENCRYPTION</literal> or\n <literal condition=\"alter-table\" role=\"stmt\">ALTER TABLE ...\n ENCRYPTION</literal> 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": "<literal>ALTER INSTANCE ROTATE INNODB MASTER KEY</literal>\n statements are written to the binary log so that they can be\n executed on replicated servers."
},
{
"para": "For additional <literal>ALTER INSTANCE ROTATE INNODB MASTER\n KEY</literal> usage information, see\n <xref linkend=\"innodb-data-encryption\" />."
}
],
[
{
"para": "<literal>ALTER INSTANCE ROTATE BINLOG MASTER KEY</literal>"
},
{
"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 <literal role=\"priv\">BINLOG_ENCRYPTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege. The statement\n cannot be used if the\n <literal role=\"sysvar\">binlog_encryption</literal> system\n variable is set to <literal>OFF</literal>. To perform this\n action, a keyring plugin must be installed and configured. For\n instructions, see <xref linkend=\"keyring\" />."
},
{
"para": "<literal>ALTER INSTANCE ROTATE BINLOG MASTER KEY</literal>\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 <literal>ALTER INSTANCE ROTATE BINLOG\n MASTER KEY</literal> statement using a\n <literal role=\"stmt\">CREATE EVENT</literal> 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 <literal>ALTER INSTANCE ROTATE BINLOG MASTER\n KEY</literal> 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 <xref linkend=\"replication-binlog-encryption\" />."
}
],
[
{
"para": "<literal>ALTER INSTANCE RELOAD TLS</literal>"
},
{
"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 <literal role=\"priv\">CONNECTION_ADMIN</literal> privilege."
},
{
"para": "By default, the <literal>RELOAD TLS</literal> 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 <literal>NO ROLLBACK ON ERROR</literal> 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": "<literal>ALTER INSTANCE RELOAD TLS</literal> 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 <xref linkend=\"using-encrypted-connections-server-side-runtime-configuration\" />."
}
]
]
}
],
"id": "ALTER INSTANCE",
"syntax": [
{
"programlisting": ">\nALTER INSTANCE <replaceable>instance_action</replaceable>\n\n<replaceable>instance_action</replaceable>: {\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 <literal>UNDO</literal> file named\n '<replaceable>file_name</replaceable>' to an existing log file\n group <replaceable>logfile_group</replaceable>. An\n <literal role=\"stmt\">ALTER LOGFILE GROUP</literal> statement has\n one and only one <literal>ADD UNDOFILE</literal> clause. No\n <literal>DROP UNDOFILE</literal> clause is currently supported."
},
{
"para": "The optional <literal>INITIAL_SIZE</literal> parameter sets the\n <literal>UNDO</literal> file's initial size in bytes; if not\n specified, the initial size defaults to 134217728 (128 MB). You\n may optionally follow <replaceable>size</replaceable> with a\n one-letter abbreviation for an order of magnitude, similar to\n those used in <filename>my.cnf</filename>. Generally, this is one\n of the letters <literal>M</literal> (megabytes) or\n <literal>G</literal> (gigabytes). (Bug #13116514, Bug #16104705,\n Bug #62858)"
},
{
"para": "On 32-bit systems, the maximum supported value for\n <literal>INITIAL_SIZE</literal> is 4294967296 (4 GB). (Bug #29186)"
},
{
"para": "The minimum allowed value for <literal>INITIAL_SIZE</literal> is\n 1048576 (1 MB). (Bug #29574)"
},
{
"para": "The <literal>ENGINE</literal> parameter (required) determines the\n storage engine which is used by this log file group, with\n <replaceable>engine_name</replaceable> being the name of the\n storage engine. Currently, the only accepted values for\n <replaceable>engine_name</replaceable> are\n <quote><literal role=\"se\">NDBCLUSTER</literal></quote> and\n <quote><literal role=\"se\">NDB</literal></quote>. The two values\n are equivalent."
}
],
"id": "ALTER LOGFILE GROUP",
"syntax": [
{
"programlisting": ">\nALTER LOGFILE GROUP <replaceable>logfile_group</replaceable>\n ADD UNDOFILE '<replaceable>file_name</replaceable>'\n [INITIAL_SIZE [=] <replaceable>size</replaceable>]\n [WAIT]\n ENGINE [=] <replaceable>engine_name</replaceable>"
}
]
},
{
"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 <literal role=\"stmt\">ALTER PROCEDURE</literal> 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 <literal role=\"stmt\">DROP\n PROCEDURE</literal> and <literal role=\"stmt\">CREATE\n PROCEDURE</literal>."
},
{
"para": "You must have the <literal role=\"priv\">ALTER ROUTINE</literal>\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 <literal role=\"sysvar\">automatic_sp_privileges</literal> system\n variable. See <xref linkend=\"stored-routines-privileges\" />."
}
],
"id": "ALTER PROCEDURE",
"syntax": [
{
"programlisting": ">\nALTER PROCEDURE <replaceable>proc_name</replaceable> [<replaceable>characteristic</replaceable> ...]\n\n<replaceable>characteristic</replaceable>:\n COMMENT '<replaceable>string</replaceable>'\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 <literal><replaceable>server_name</replaceable></literal>,\n adjusting any of the options permitted in the\n <literal role=\"stmt\">CREATE SERVER</literal> statement. The\n corresponding fields in the <literal>mysql.servers</literal> table\n are updated accordingly. This statement requires the\n <literal role=\"priv\">SUPER</literal> privilege."
}
],
"id": "ALTER SERVER",
"syntax": [
{
"programlisting": ">\nALTER SERVER <replaceable>server_name</replaceable>\n OPTIONS (<replaceable>option</replaceable> [, <replaceable>option</replaceable>] ...)"
}
]
},
{
"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": "<literal role=\"stmt\">ALTER TABLE</literal> 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 <literal role=\"stmt\">ALTER TABLE</literal>, you need\n <literal role=\"priv\">ALTER</literal>,\n <literal role=\"priv\">CREATE</literal>, and\n <literal role=\"priv\">INSERT</literal> privileges for the\n table. Renaming a table requires\n <literal role=\"priv\">ALTER</literal> and\n <literal role=\"priv\">DROP</literal> on the old table,\n <literal role=\"priv\">ALTER</literal>,\n <literal role=\"priv\">CREATE</literal>, and\n <literal role=\"priv\">INSERT</literal> on the new table."
}
],
[
{
"para": "Following the table name, specify the alterations to be made.\n If none are given, <literal role=\"stmt\">ALTER TABLE</literal>\n does nothing."
}
],
[
{
"para": "The syntax for many of the permissible alterations is similar\n to clauses of the <literal role=\"stmt\">CREATE TABLE</literal>\n statement. <replaceable>column_definition</replaceable>\n clauses use the same syntax for <literal>ADD</literal> and\n <literal>CHANGE</literal> as for <literal role=\"stmt\">CREATE\n TABLE</literal>. For more information, see\n <xref linkend=\"create-table\" />."
}
],
[
{
"para": "The word <literal>COLUMN</literal> is optional and can be\n omitted, except for <literal>RENAME COLUMN</literal> (to\n distinguish a column-renaming operation from the\n <literal>RENAME</literal> table-renaming operation)."
}
],
[
{
"para": "Multiple <literal>ADD</literal>, <literal>ALTER</literal>,\n <literal>DROP</literal>, and <literal>CHANGE</literal> clauses\n are permitted in a single <literal role=\"stmt\">ALTER\n TABLE</literal> statement, separated by commas. This is a\n MySQL extension to standard SQL, which permits only one of\n each clause per <literal role=\"stmt\">ALTER TABLE</literal>\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 <literal role=\"stmt\">ALTER TABLE</literal> operation, a\n warning may result. Such warnings can be displayed with\n <literal role=\"stmt\">SHOW WARNINGS</literal>. See\n <xref linkend=\"show-warnings\" />. For information on\n troubleshooting <literal role=\"stmt\">ALTER TABLE</literal>,\n see <xref linkend=\"alter-table-problems\" />."
}
],
[
{
"para": "For information about generated columns, see\n <xref linkend=\"alter-table-generated-columns\" />."
}
],
[
{
"para": "For usage examples, see\n <xref linkend=\"alter-table-examples\" />."
}
],
[
{
"para": "<literal>InnoDB</literal> in MySQL 8.0.17 and later supports\n addition of multi-valued indexes on JSON columns using a\n <replaceable>key_part</replaceable> specification can take the\n form <literal>(CAST <replaceable>json_path</replaceable> AS\n <replaceable>type</replaceable> ARRAY)</literal>. See\n <xref linkend=\"create-index-multi-valued\" />, 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 <literal role=\"cfunc\">mysql_info()</literal> C API\n function, you can find out how many rows were copied by\n <literal role=\"stmt\">ALTER TABLE</literal>. See\n <xref linkend=\"mysql-info\" />."
},
{
"indexterm": "<primary>mysql_info()</primary>"
}
]
]
}
],
"id": "ALTER TABLE",
"syntax": [
{
"programlisting": ">\nALTER TABLE <replaceable>tbl_name</replaceable>\n [<replaceable>alter_specification</replaceable> [, <replaceable>alter_specification</replaceable>] ...]\n [<replaceable>partition_options</replaceable>]\n\n<replaceable>alter_specification</replaceable>:\n <replaceable>table_options</replaceable>\n | ADD [COLUMN] <replaceable>col_name</replaceable> <replaceable>column_definition</replaceable>\n [FIRST | AFTER <replaceable>col_name</replaceable>]\n | ADD [COLUMN] (<replaceable>col_name</replaceable> <replaceable>column_definition</replaceable>,...)\n | ADD {INDEX|KEY} [<replaceable>index_name</replaceable>]\n [<replaceable>index_type</replaceable>] (<replaceable>key_part</replaceable>,...) [<replaceable>index_option</replaceable>] ...\n | ADD {FULLTEXT|SPATIAL} [INDEX|KEY] [<replaceable>index_name</replaceable>]\n (<replaceable>key_part</replaceable>,...) [<replaceable>index_option</replaceable>] ...\n | ADD [CONSTRAINT [<replaceable>symbol</replaceable>]] PRIMARY KEY\n [<replaceable>index_type</replaceable>] (<replaceable>key_part</replaceable>,...)\n [<replaceable>index_option</replaceable>] ...\n | ADD [CONSTRAINT [<replaceable>symbol</replaceable>]] UNIQUE [INDEX|KEY]\n [<replaceable>index_name</replaceable>] [<replaceable>index_type</replaceable>] (<replaceable>key_part</replaceable>,...)\n [<replaceable>index_option</replaceable>] ...\n | ADD [CONSTRAINT [<replaceable>symbol</replaceable>]] FOREIGN KEY\n [<replaceable>index_name</replaceable>] (<replaceable>col_name</replaceable>,...)\n <replaceable>reference_definition</replaceable>\n | ADD [CONSTRAINT [<replaceable>symbol</replaceable>]] CHECK (<replaceable>expr</replaceable>) [[NOT] ENFORCED]\n | DROP {CHECK|CONSTRAINT} <replaceable>symbol</replaceable>\n | ALTER {CHECK|CONSTRAINT} <replaceable>symbol</replaceable> [NOT] ENFORCED\n | ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}\n | ALTER [COLUMN] <replaceable>col_name</replaceable>\n {SET DEFAULT {<replaceable>literal</replaceable> | (<replaceable>expr</replaceable>)} | DROP DEFAULT}\n | ALTER INDEX <replaceable>index_name</replaceable> {VISIBLE | INVISIBLE}\n | CHANGE [COLUMN] <replaceable>old_col_name</replaceable> <replaceable>new_col_name</replaceable> <replaceable>column_definition</replaceable>\n [FIRST|AFTER <replaceable>col_name</replaceable>]\n | [DEFAULT] CHARACTER SET [=] <replaceable>charset_name</replaceable> [COLLATE [=] <replaceable>collation_name</replaceable>]\n | CONVERT TO CHARACTER SET <replaceable>charset_name</replaceable> [COLLATE <replaceable>collation_name</replaceable>]\n | {DISABLE|ENABLE} KEYS\n | {DISCARD|IMPORT} TABLESPACE\n | DROP [COLUMN] <replaceable>col_name</replaceable>\n | DROP {INDEX|KEY} <replaceable>index_name</replaceable>\n | DROP PRIMARY KEY\n | DROP FOREIGN KEY <replaceable>fk_symbol</replaceable>\n | FORCE\n | LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}\n | MODIFY [COLUMN] <replaceable>col_name</replaceable> <replaceable>column_definition</replaceable>\n [FIRST | AFTER <replaceable>col_name</replaceable>]\n | ORDER BY <replaceable>col_name</replaceable> [, <replaceable>col_name</replaceable>] ...\n | RENAME COLUMN <replaceable>old_col_name</replaceable> TO <replaceable>new_col_name</replaceable>\n | RENAME {INDEX|KEY} <replaceable>old_index_name</replaceable> TO <replaceable>new_index_name</replaceable>\n | RENAME [TO|AS] <replaceable>new_tbl_name</replaceable>\n | {WITHOUT|WITH} VALIDATION\n\n<replaceable>partition_options</replaceable>:\n <replaceable>partition_option</replaceable> [<replaceable>partition_option</replaceable>] ...\n\n<replaceable>partition_option</replaceable>:\n ADD PARTITION (<replaceable>partition_definition</replaceable>)\n | DROP PARTITION <replaceable>partition_names</replaceable>\n | DISCARD PARTITION {<replaceable>partition_names</replaceable> | ALL} TABLESPACE\n | IMPORT PARTITION {<replaceable>partition_names</replaceable> | ALL} TABLESPACE\n | TRUNCATE PARTITION {<replaceable>partition_names</replaceable> | ALL}\n | COALESCE PARTITION <replaceable>number</replaceable>\n | REORGANIZE PARTITION <replaceable>partition_names</replaceable> INTO (<replaceable>partition_definitions</replaceable>)\n | EXCHANGE PARTITION <replaceable>partition_name</replaceable> WITH TABLE <replaceable>tbl_name</replaceable> [{WITH|WITHOUT} VALIDATION]\n | ANALYZE PARTITION {<replaceable>partition_names</replaceable> | ALL}\n | CHECK PARTITION {<replaceable>partition_names</replaceable> | ALL}\n | OPTIMIZE PARTITION {<replaceable>partition_names</replaceable> | ALL}\n | REBUILD PARTITION {<replaceable>partition_names</replaceable> | ALL}\n | REPAIR PARTITION {<replaceable>partition_names</replaceable> | ALL}\n | REMOVE PARTITIONING\n\n<replaceable>key_part</replaceable>: {<replaceable>col_name</replaceable> [(<replaceable>length</replaceable>)] | (<replaceable>expr</replaceable>)} [ASC | DESC]\n\n<replaceable>index_type</replaceable>:\n USING {BTREE | HASH}\n\n<replaceable>index_option</replaceable>:\n KEY_BLOCK_SIZE [=] <replaceable>value</replaceable>\n | <replaceable>index_type</replaceable>\n | WITH PARSER <replaceable>parser_name</replaceable>\n | COMMENT '<replaceable>string</replaceable>'\n | {VISIBLE | INVISIBLE}\n\n<replaceable>table_options</replaceable>:\n <replaceable>table_option</replaceable> [[,] <replaceable>table_option</replaceable>] ...\n\n<replaceable>table_option</replaceable>:\n AUTO_INCREMENT [=] <replaceable>value</replaceable>\n | AVG_ROW_LENGTH [=] <replaceable>value</replaceable>\n | [DEFAULT] CHARACTER SET [=] <replaceable>charset_name</replaceable>\n | CHECKSUM [=] {0 | 1}\n | [DEFAULT] COLLATE [=] <replaceable>collation_name</replaceable>\n | COMMENT [=] '<replaceable>string</replaceable>'\n | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'}\n | CONNECTION [=] '<replaceable>connect_string</replaceable>'\n | {DATA|INDEX} DIRECTORY [=] '<replaceable>absolute path to directory</replaceable>'\n | DELAY_KEY_WRITE [=] {0 | 1}\n | ENCRYPTION [=] {'Y' | 'N'}\n | ENGINE [=] <replaceable>engine_name</replaceable>\n | INSERT_METHOD [=] { NO | FIRST | LAST }\n | KEY_BLOCK_SIZE [=] <replaceable>value</replaceable>\n | MAX_ROWS [=] <replaceable>value</replaceable>\n | MIN_ROWS [=] <replaceable>value</replaceable>\n | PACK_KEYS [=] {0 | 1 | DEFAULT}\n | PASSWORD [=] '<replaceable>string</replaceable>'\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 [=] <replaceable>value</replaceable>\n | TABLESPACE <replaceable>tablespace_name</replaceable> [STORAGE {DISK|MEMORY}]\n | UNION [=] (<replaceable>tbl_name</replaceable>[,<replaceable>tbl_name</replaceable>]...)\n\n<replaceable>partition_options</replaceable>:\n (see <literal role=\"stmt\">CREATE TABLE</literal> options)"
}
]
},
{
"keywords": [
"ALTER",
"UNDO",
"TABLESPACE",
"ADD",
"DROP",
"DATAFILE",
"INITIAL_SIZE",
"WAIT",
"RENAME",
"TO",
"ENGINE"
],
"description": [
{
"para": "This statement is used with <literal>NDB</literal> and\n <literal>InnoDB</literal> tablespaces. It can be used to add a new\n data file to, or to drop a data file from an\n <literal>NDB</literal> tablespace. It can also be used to rename\n an NDB Cluster Disk Data tablespace, rename an\n <literal>InnoDB</literal> general tablespace, encrypt an\n <literal>InnoDB</literal> general tablespace, or mark an\n <literal>InnoDB</literal> undo tablespace as active or inactive."
},
{
"para": "The <literal>UNDO</literal> keyword, introduced in MySQL 8.0.14,\n is used with the <literal>SET {ACTIVE|INACTIVE}</literal> clause\n to mark an <literal>InnoDB</literal> undo tablespace as active or\n inactive. For more information, see\n <xref linkend=\"innodb-undo-tablespaces\" />."
},
{
"para": "The <literal>ADD DATAFILE</literal> variant enables you to specify\n an initial size for an <literal>NDB</literal> Disk Data tablespace\n using an <literal>INITIAL_SIZE</literal> clause, where\n <replaceable>size</replaceable> is measured in bytes; the default\n value is 134217728 (128 MB). You may optionally follow\n <replaceable>size</replaceable> with a one-letter abbreviation for\n an order of magnitude, similar to those used in\n <filename>my.cnf</filename>. Generally, this is one of the letters\n <literal>M</literal> (megabytes) or <literal>G</literal>\n (gigabytes)."
},
{
"para": "On 32-bit systems, the maximum supported value for\n <literal>INITIAL_SIZE</literal> is 4294967296 (4 GB). (Bug #29186)"
},
{
"para": "<literal>INITIAL_SIZE</literal> is rounded, explicitly, as for\n <literal role=\"stmt\">CREATE TABLESPACE</literal>."
},
{
"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 <literal>ALTER TABLESPACE ... ADD DATAFILE</literal>\n statements."
},
{
"para": "When <literal>ALTER TABLESPACE ... ADD DATAFILE</literal> is used\n with <literal>ENGINE = NDB</literal>, a data file is created on\n each Cluster data node, but only one row is generated in the\n <literal role=\"is\">INFORMATION_SCHEMA.FILES</literal> table. See\n the description of this table, as well as\n <xref linkend=\"mysql-cluster-disk-data-objects\" />, for more\n information. <literal>ADD DATAFILE</literal> is not supported with\n <literal>InnoDB</literal> tablespaces."
},
{
"para": "Using <literal>DROP DATAFILE</literal> with\n <literal role=\"stmt\">ALTER TABLESPACE</literal> drops the data\n file '<replaceable>file_name</replaceable>' 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 <xref linkend=\"mysql-cluster-disk-data-objects\" />. In addition,\n any data file to be dropped must previously have been added to the\n tablespace with <literal role=\"stmt\">CREATE TABLESPACE</literal>\n or <literal role=\"stmt\">ALTER TABLESPACE</literal>. <literal>DROP\n DATAFILE</literal> is not supported with <literal>InnoDB</literal>\n tablespaces."
},
{
"para": "<literal>WAIT</literal> is parsed but otherwise ignored. It is\n intended for future expansion."
},
{
"para": "The <literal>ENGINE</literal> 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 <literal>ENGINE</literal> 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 <replaceable>engine_name</replaceable> compatible with\n <literal role=\"se\">NDB</literal> tablespaces are\n <literal>NDB</literal> and <literal>NDBCLUSTER</literal>."
},
{
"para": "<literal>RENAME TO</literal> operations are implicitly performed\n in <literal role=\"sysvar\">autocommit</literal> mode, regardless of\n the <literal role=\"sysvar\">autocommit</literal> setting."
},
{
"para": "A <literal>RENAME TO</literal> operation cannot be performed while\n <literal role=\"stmt\">LOCK TABLES</literal> or\n <literal condition=\"flush\" role=\"stmt\">FLUSH TABLES WITH READ\n LOCK</literal> is in effect for tables that reside in the\n tablespace."
},
{
"para": "Exclusive <link linkend=\"glos_metadata_lock\">metadata locks</link>\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 <literal role=\"priv\">CREATE TABLESPACE</literal> privilege is\n required to rename an <literal>InnoDB</literal> general\n tablespace."
},
{
"para": "The <literal>ENCRYPTION</literal> clause enables or disables\n page-level data encryption for an <literal>InnoDB</literal>\n general tablespace or the <literal>mysql</literal> system\n tablespace. Encryption support for general tablespaces was\n introduced in MySQL 8.0.13. Encryption support for the\n <literal>mysql</literal> 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 <literal role=\"sysvar\">table_encryption_privilege_check</literal>\n variable is enabled, the\n <literal role=\"priv\">TABLE_ENCRYPTION_ADMIN</literal> privilege is\n required to alter a general tablespace with an\n <literal>ENCRYPTION</literal> clause setting that differs from the\n <literal role=\"sysvar\">default_table_encryption</literal> setting."
},
{
"para": "Enabling encryption for a general tablespace fails if any table in\n the tablespace belongs to a schema defined with\n <literal condition=\"create-database\" role=\"stmt\">DEFAULT\n ENCRYPTION='N'</literal>. Similarly, disabling encryption fails if\n any table in the general tablespace belongs to a schema defined\n with <literal condition=\"create-database\" role=\"stmt\">DEFAULT\n ENCRYPTION='Y'</literal>. The\n <literal condition=\"create-database\" role=\"stmt\">DEFAULT\n ENCRYPTION</literal> schema option was introduced in MySQL 8.0.16."
},
{
"para": "If an <literal role=\"stmt\">ALTER TABLESPACE</literal> statement\n executed on a general tablespace does not include an\n <literal>ENCRYPTION</literal> clause, the tablespace retains its\n current encryption status, regardless of the\n <literal role=\"sysvar\">default_table_encryption</literal> setting."
},
{
"para": "When a general tablespace or the <literal>mysql</literal> 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 <literal>INPLACE</literal> algorithm is used when altering the\n <literal>ENCRYPTION</literal> attribute of a general tablespace or\n the <literal>mysql</literal> system tablespace. The\n <literal>INPLACE</literal> algorithm permits concurrent DML on\n tables that reside in the tablespace. Concurrent DDL is blocked."
},
{
"para": "For more information, see\n <xref linkend=\"innodb-data-encryption\" />."
}
],
"id": "ALTER TABLESPACE",
"syntax": [
{
"programlisting": ">\nALTER [UNDO] TABLESPACE <replaceable>tablespace_name</replaceable>\n <emphasis>NDB only:</emphasis> \n {ADD|DROP} DATAFILE '<replaceable>file_name</replaceable>'\n [INITIAL_SIZE [=] size]\n [WAIT]\n <emphasis>InnoDB and NDB:</emphasis>\n [RENAME TO <replaceable>tablespace_name</replaceable>] \n <emphasis>InnoDB only:</emphasis>\n [SET {ACTIVE|INACTIVE}]\n [ENCRYPTION [=] {'Y' | 'N'}]\n <emphasis>InnoDB and NDB:</emphasis>\n [ENGINE [=] <replaceable>engine_name</replaceable>]"
}
]
},
{
"keywords": [
"ALTER",
"VIEW"
],
"description": [
{
"para": "This statement changes the definition of a view, which must exist.\n The syntax is similar to that for <literal role=\"stmt\">CREATE\n VIEW</literal> see <xref linkend=\"create-view\" />). This statement\n requires the <literal role=\"priv\">CREATE VIEW</literal> and\n <literal role=\"priv\">DROP</literal> privileges for the view, and\n some privilege for each column referred to in the\n <literal role=\"stmt\">SELECT</literal> statement.\n <literal role=\"stmt\">ALTER VIEW</literal> is permitted only to the\n definer or users with the\n <literal role=\"priv\">SET_USER_ID</literal> or\n <literal role=\"priv\">SUPER</literal> privilege."
}
],
"id": "ALTER VIEW",
"syntax": [
{
"programlisting": ">\nALTER\n [ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}]\n [DEFINER = <replaceable>user</replaceable>]\n [SQL SECURITY { DEFINER | INVOKER }]\n VIEW <replaceable>view_name</replaceable> [(<replaceable>column_list</replaceable>)]\n AS <replaceable>select_statement</replaceable>\n [WITH [CASCADED | LOCAL] CHECK OPTION]"
}
]
},
{
"keywords": [
"CREATE",
"DATABASE",
"SCHEMA",
"IF",
"EXISTS",
"NOT",
"DEFAULT",
"CHARACTER",
"SET",
"COLLATE",
"ENCRYPTION"
],
"description": [
{
"para": "<literal role=\"stmt\">CREATE DATABASE</literal> creates a database\n with the given name. To use this statement, you need the\n <literal role=\"priv\">CREATE</literal> privilege for the database.\n <literal condition=\"create-database\" role=\"stmt\">CREATE\n SCHEMA</literal> is a synonym for <literal role=\"stmt\">CREATE\n DATABASE</literal>."
}
],
"id": "CREATE DATABASE",
"syntax": [
{
"programlisting": ">\nCREATE {DATABASE | SCHEMA} [IF NOT EXISTS] <replaceable>db_name</replaceable>\n [<replaceable>create_specification</replaceable>] ...\n\n<replaceable>create_specification</replaceable>:\n [DEFAULT] CHARACTER SET [=] <replaceable>charset_name</replaceable>\n | [DEFAULT] COLLATE [=] <replaceable>collation_name</replaceable>\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 <xref linkend=\"events-configuration\" />."
},
{
"para": "<literal role=\"stmt\">CREATE EVENT</literal> requires the\n <literal role=\"priv\">EVENT</literal> privilege for the schema in\n which the event is to be created. If the\n <literal>DEFINER</literal> clause is present, the privileges\n required depend on the <replaceable>user</replaceable> value, as\n discussed in <xref linkend=\"stored-objects-security\" />."
},
{
"para": "The minimum requirements for a valid <literal role=\"stmt\">CREATE\n EVENT</literal> statement are as follows:"
},
{
"itemizedlist": [
[
{
"para": "The keywords <literal role=\"stmt\">CREATE EVENT</literal> plus\n an event name, which uniquely identifies the event in a\n database schema."
}
],
[
{
"para": "An <literal>ON SCHEDULE</literal> clause, which determines\n when and how often the event executes."
}
],
[
{
"para": "A <literal role=\"stmt\">DO</literal> clause, which contains the\n SQL statement to be executed by an event."
}
]
]
},
{
"para": "This is an example of a minimal <literal role=\"stmt\">CREATE\n EVENT</literal> 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 <literal>myevent</literal>. This event executes oncemdashone\n hour following its creationmdashby running an SQL statement that\n increments the value of the <literal>myschema.mytable</literal>\n table's <literal>mycol</literal> column by 1."
},
{
"para": "The <replaceable>event_name</replaceable> 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 <literal>myevent</literal> and <literal>MyEvent</literal> 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 <xref linkend=\"identifiers\" />."
},
{
"para": "An event is associated with a schema. If no schema is indicated as\n part of <replaceable>event_name</replaceable>, 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 <literal><replaceable>schema_name</replaceable>.<replaceable>event_name</replaceable></literal>\n syntax."
}
],
"id": "CREATE EVENT",
"syntax": [
{
"programlisting": ">\nCREATE\n [DEFINER = <replaceable>user</replaceable>]\n EVENT\n [IF NOT EXISTS]\n <replaceable>event_name</replaceable>\n ON SCHEDULE <replaceable>schedule</replaceable>\n [ON COMPLETION [NOT] PRESERVE]\n [ENABLE | DISABLE | DISABLE ON SLAVE]\n [COMMENT '<replaceable>string</replaceable>']\n DO <replaceable>event_body</replaceable>;\n\n<replaceable>schedule</replaceable>:\n AT <replaceable>timestamp</replaceable> [+ INTERVAL <replaceable>interval</replaceable>] ...\n | EVERY <replaceable>interval</replaceable>\n [STARTS <replaceable>timestamp</replaceable> [+ INTERVAL <replaceable>interval</replaceable>] ...]\n [ENDS <replaceable>timestamp</replaceable> [+ INTERVAL <replaceable>interval</replaceable>] ...]\n\n<replaceable>interval</replaceable>:\n <replaceable>quantity</replaceable> {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 <literal role=\"stmt\">CREATE\n TABLE</literal>. See <xref linkend=\"create-table\" />. This\n guideline is especially important for\n <literal role=\"se\">InnoDB</literal> tables, where the primary key\n determines the physical layout of rows in the data file.\n <literal role=\"stmt\">CREATE INDEX</literal> enables you to add\n indexes to existing tables."
},
{
"para": "<literal role=\"stmt\">CREATE INDEX</literal> is mapped to an\n <literal role=\"stmt\">ALTER TABLE</literal> statement to create\n indexes. See <xref linkend=\"alter-table\" />.\n <literal role=\"stmt\">CREATE INDEX</literal> cannot be used to\n create a <literal>PRIMARY KEY</literal>; use\n <literal role=\"stmt\">ALTER TABLE</literal> instead. For more\n information about indexes, see <xref linkend=\"mysql-indexes\" />."
}
],
"id": "CREATE INDEX",
"syntax": [
{
"programlisting": ">\nCREATE [UNIQUE | FULLTEXT | SPATIAL] INDEX <replaceable>index_name</replaceable>\n [<replaceable>index_type</replaceable>]\n ON <replaceable>tbl_name</replaceable> (<replaceable>key_part</replaceable>,...)\n [<replaceable>index_option</replaceable>]\n [<replaceable>algorithm_option</replaceable> | <replaceable>lock_option</replaceable>] ...\n\n<replaceable>key_part</replaceable>: {<replaceable>col_name</replaceable> [(<replaceable>length</replaceable>)] | (<replaceable>expr</replaceable>)} [ASC | DESC]\n\n<replaceable>index_option</replaceable>:\n KEY_BLOCK_SIZE [=] <replaceable>value</replaceable>\n | <replaceable>index_type</replaceable>\n | WITH PARSER <replaceable>parser_name</replaceable>\n | COMMENT '<replaceable>string</replaceable>'\n | {VISIBLE | INVISIBLE}\n\n<replaceable>index_type</replaceable>:\n USING {BTREE | HASH}\n\n<replaceable>algorithm_option</replaceable>:\n ALGORITHM [=] {DEFAULT | INPLACE | COPY}\n\n<replaceable>lock_option</replaceable>:\n LOCK [=] {DEFAULT | NONE | SHARED | EXCLUSIVE}"
}
]
},
{
"keywords": [
"CREATE",
"LOGFILE",
"GROUP"
],
"description": [
{
"para": "This statement creates a new log file group named\n <replaceable>logfile_group</replaceable> having a single\n <literal>UNDO</literal> file named\n '<replaceable>undo_file</replaceable>'. A\n <literal role=\"stmt\">CREATE LOGFILE GROUP</literal> statement has\n one and only one <literal>ADD UNDOFILE</literal> clause. For rules\n covering the naming of log file groups, see\n <xref linkend=\"identifiers\" />."
},
{
"para": "There can be only one log file group per NDB Cluster instance at\n any given time."
},
{
"para": "The optional <literal>INITIAL_SIZE</literal> parameter sets the\n <literal>UNDO</literal> file's initial size; if not specified, it\n defaults to <literal>128M</literal> (128 megabytes). The optional\n <literal>UNDO_BUFFER_SIZE</literal> parameter sets the size used\n by the <literal>UNDO</literal> buffer for the log file group; The\n default value for <literal>UNDO_BUFFER_SIZE</literal> is\n <literal>8M</literal> (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 <filename>my.cnf</filename>. Generally,\n this is one of the letters <literal>M</literal> (for megabytes)\n or <literal>G</literal> (for gigabytes)."
},
{
"para": "Memory used for <literal>UNDO_BUFFER_SIZE</literal> comes from the\n global pool whose size is determined by the value of the\n <literal role=\"ndbparam:ndbd\">SharedGlobalMemory</literal> data\n node configuration parameter. This includes any default value\n implied for this option by the setting of the\n <literal role=\"ndbparam:ndbd\">InitialLogFileGroup</literal> data\n node configuration parameter."
},
{
"para": "The maximum permitted for <literal>UNDO_BUFFER_SIZE</literal> is\n 629145600 (600 MB)."
},
{
"para": "On 32-bit systems, the maximum supported value for\n <literal>INITIAL_SIZE</literal> is 4294967296 (4 GB). (Bug #29186)"
},
{
"para": "The minimum allowed value for <literal>INITIAL_SIZE</literal> is\n 1048576 (1 MB)."
},
{
"para": "The <literal>ENGINE</literal> option determines the storage engine\n to be used by this log file group, with\n <replaceable>engine_name</replaceable> being the name of the\n storage engine. In MySQL current-series, this must be\n <literal role=\"se\">NDB</literal> (or\n <literal role=\"se\">NDBCLUSTER</literal>). If\n <literal>ENGINE</literal> is not set, MySQL tries to use the\n engine specified by the\n <literal role=\"sysvar\">default_storage_engine</literal> server\n system variable (formerly\n <literal role=\"sysvar\">storage_engine</literal>). In any case, if\n the engine is not specified as <literal role=\"se\">NDB</literal> or\n <literal role=\"se\">NDBCLUSTER</literal>, the <literal>CREATE\n LOGFILE GROUP</literal> statement appears to succeed but actually\n fails to create the log file group, as shown here:"
},
{
"programlisting": ">\nmysql> <userinput>CREATE LOGFILE GROUP lg1</userinput>\n -> <userinput>ADD UNDOFILE 'undo.dat' INITIAL_SIZE = 10M;</userinput>\nQuery OK, 0 rows affected, 1 warning (0.00 sec)\n\nmysql> <userinput>SHOW WARNINGS;</userinput>\n+-------+------+------------------------------------------------------------------------------------------------+\n| Level | Code | Message |\n+-------+------+------------------------------------------------------------------------------------------------+\n| Error | 1478 | <errortext>Table storage engine 'InnoDB' does not support the create option 'TABLESPACE or LOGFILE GROUP'</errortext> |\n+-------+------+------------------------------------------------------------------------------------------------+\n1 row in set (0.00 sec)\n\nmysql> <userinput>DROP LOGFILE GROUP lg1 ENGINE = NDB;</userinput> \n<errortext>ERROR 1529 (HY000): Failed to drop LOGFILE GROUP</errortext>\n\nmysql> <userinput>CREATE LOGFILE GROUP lg1</userinput>\n -> <userinput>ADD UNDOFILE 'undo.dat' INITIAL_SIZE = 10M</userinput>\n -> <userinput>ENGINE = NDB;</userinput>\nQuery OK, 0 rows affected (2.97 sec)"
},
{
"para": "The fact that the <literal>CREATE LOGFILE GROUP</literal>\n statement does not actually return an error when a\n non-<literal>NDB</literal> 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": "<replaceable>REDO_BUFFER_SIZE</replaceable>,\n <literal>NODEGROUP</literal>, <literal>WAIT</literal>, and\n <literal>COMMENT</literal> 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 <literal>ENGINE [=] NDB</literal>, a log file group\n and associated <literal>UNDO</literal> log file are created on\n each Cluster data node. You can verify that the\n <literal>UNDO</literal> files were created and obtain information\n about them by querying the\n <literal role=\"is\">INFORMATION_SCHEMA.FILES</literal> table. For\n example:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT LOGFILE_GROUP_NAME, LOGFILE_GROUP_NUMBER, EXTRA</userinput>\n -> <userinput>FROM INFORMATION_SCHEMA.FILES</userinput>\n -> <userinput>WHERE FILE_NAME = 'undo_10.dat';</userinput>\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": "<literal role=\"stmt\">CREATE LOGFILE GROUP</literal> is useful only\n with Disk Data storage for NDB Cluster. See\n <xref linkend=\"mysql-cluster-disk-data\" />."
}
],
"id": "CREATE LOGFILE GROUP",
"syntax": [
{
"programlisting": ">\nCREATE LOGFILE GROUP <replaceable>logfile_group</replaceable>\n ADD UNDOFILE '<replaceable>undo_file</replaceable>'\n [INITIAL_SIZE [=] <replaceable>initial_size</replaceable>]\n [UNDO_BUFFER_SIZE [=] <replaceable>undo_buffer_size</replaceable>]\n [REDO_BUFFER_SIZE [=] <replaceable>redo_buffer_size</replaceable>]\n [NODEGROUP [=] <replaceable>nodegroup_id</replaceable>]\n [WAIT]\n [COMMENT [=] '<replaceable>string</replaceable>']\n ENGINE [=] <replaceable>engine_name</replaceable>"
}
]
},
{
"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 <replaceable>db_name.sp_name</replaceable> when you create it."
},
{
"para": "The <literal role=\"stmt\">CREATE FUNCTION</literal> statement is\n also used in MySQL to support UDFs (user-defined functions). See\n <xref linkend=\"adding-functions\" />. A UDF can be regarded as an\n external stored function. Stored functions share their namespace\n with UDFs. See <xref linkend=\"function-resolution\" />, 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 <literal role=\"stmt\">CALL</literal> statement (see\n <xref linkend=\"call\" />). To invoke a stored function, refer to it\n in an expression. The function returns a value during expression\n evaluation."
},
{
"para": "<literal role=\"stmt\">CREATE PROCEDURE</literal> and\n <literal role=\"stmt\">CREATE FUNCTION</literal> require the\n <literal role=\"priv\">CREATE ROUTINE</literal> privilege. If the\n <literal>DEFINER</literal> clause is present, the privileges\n required depend on the <replaceable>user</replaceable> value, as\n discussed in <xref linkend=\"stored-objects-security\" />. If binary\n logging is enabled, <literal role=\"stmt\">CREATE FUNCTION</literal>\n might require the <literal role=\"priv\">SUPER</literal> privilege,\n as discussed in <xref linkend=\"stored-programs-logging\" />."
},
{
"para": "By default, MySQL automatically grants the\n <literal role=\"priv\">ALTER ROUTINE</literal> and\n <literal role=\"priv\">EXECUTE</literal> privileges to the routine\n creator. This behavior can be changed by disabling the\n <literal role=\"sysvar\">automatic_sp_privileges</literal> system\n variable. See <xref linkend=\"stored-routines-privileges\" />."
},
{
"para": "The <literal>DEFINER</literal> and <literal>SQL SECURITY</literal>\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 <literal role=\"sqlmode\">IGNORE_SPACE</literal> 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 <literal role=\"sqlmode\">IGNORE_SPACE</literal> 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 <literal>()</literal> should be used. Parameter names are not case\n sensitive."
},
{
"para": "Each parameter is an <literal>IN</literal> parameter by default.\n To specify otherwise for a parameter, use the keyword\n <literal>OUT</literal> or <literal>INOUT</literal> before the\n parameter name."
},
{
"para": "An <literal>IN</literal> 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 <literal>OUT</literal> parameter passes a value from\n the procedure back to the caller. Its initial value is\n <literal>NULL</literal> within the procedure, and its value is\n visible to the caller when the procedure returns. An\n <literal>INOUT</literal> 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 <literal>OUT</literal> or <literal>INOUT</literal>\n parameter, pass a user-defined variable in the\n <literal role=\"stmt\">CALL</literal> 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 <literal>OUT</literal>\n or <literal>INOUT</literal> parameter. If you are calling the\n procedure from within a trigger, you can also pass\n <literal>NEW.<replaceable>col_name</replaceable></literal> as an\n <literal>OUT</literal> or <literal>INOUT</literal> parameter."
},
{
"para": "For information about the effect of unhandled conditions on\n procedure parameters, see\n <xref linkend=\"conditions-and-parameters\" />."
},
{
"para": "Routine parameters cannot be referenced in statements prepared\n within the routine; see\n <xref linkend=\"stored-program-restrictions\" />."
},
{
"para": "The following example shows a simple stored procedure that uses an\n <literal>OUT</literal> parameter:"
},
{
"programlisting": ">\nmysql> <userinput>delimiter //</userinput>\n\nmysql> <userinput>CREATE PROCEDURE simpleproc (OUT param1 INT)</userinput>\n -> <userinput>BEGIN</userinput>\n -> <userinput>SELECT COUNT(*) INTO param1 FROM t;</userinput>\n -> <userinput>END//</userinput>\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> <userinput>delimiter ;</userinput>\n\nmysql> <userinput>CALL simpleproc(@a);</userinput>\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> <userinput>SELECT @a;</userinput>\n+------+\n| @a |\n+------+\n| 3 |\n+------+\n1 row in set (0.00 sec)"
},
{
"para": "The example uses the <command>mysql</command> client\n <literal>delimiter</literal> command to change the statement\n delimiter from <literal>;</literal> to <literal>//</literal> while\n the procedure is being defined. This enables the\n <literal>;</literal> delimiter used in the procedure body to be\n passed through to the server rather than being interpreted by\n <command>mysql</command> itself. See\n <xref linkend=\"stored-programs-defining\" />."
},
{
"para": "The <literal>RETURNS</literal> clause may be specified only for a\n <literal>FUNCTION</literal>, for which it is mandatory. It\n indicates the return type of the function, and the function body\n must contain a <literal>RETURN\n <replaceable>value</replaceable></literal> statement. If the\n <literal role=\"stmt\">RETURN</literal> 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 <literal role=\"type\">ENUM</literal> or\n <literal role=\"type\">SET</literal> value in the\n <literal>RETURNS</literal> clause, but the\n <literal role=\"stmt\">RETURN</literal> statement returns an\n integer, the value returned from the function is the string for\n the corresponding <literal role=\"type\">ENUM</literal> member of\n set of <literal role=\"type\">SET</literal> 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 <literal>delimiter</literal>\n because the function definition contains no internal\n <literal>;</literal> statement delimiters:"
},
{
"programlisting": ">\nmysql> <userinput>CREATE FUNCTION hello (s CHAR(20))</userinput>\nmysql> <userinput>RETURNS CHAR(50) DETERMINISTIC</userinput>\n -> <userinput>RETURN CONCAT('Hello, ',s,'!');</userinput>\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> <userinput>SELECT hello('world');</userinput>\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 <literal>COLLATE</literal> attribute can\n be used if preceded by a <literal>CHARACTER SET</literal>\n specification."
},
{
"para": "The <replaceable>routine_body</replaceable> consists of a valid\n SQL routine statement. This can be a simple statement such as\n <literal role=\"stmt\">SELECT</literal> or\n <literal role=\"stmt\">INSERT</literal>, or a compound statement\n written using <literal>BEGIN</literal> and <literal>END</literal>.\n Compound statements can contain declarations, loops, and other\n control structure statements. The syntax for these statements is\n described in <xref linkend=\"sql-compound-statements\" />. In\n practice, stored functions tend to use compound statements, unless\n the body consists of a single\n <literal role=\"stmt\">RETURN</literal> statement."
},
{
"para": "MySQL permits routines to contain DDL statements, such as\n <literal>CREATE</literal> and <literal>DROP</literal>. MySQL also\n permits stored procedures (but not stored functions) to contain\n SQL transaction statements such as\n <literal role=\"stmt\">COMMIT</literal>. 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 <literal role=\"stmt\">SELECT</literal> statements that do\n not have an <literal>INTO\n <replaceable>var_list</replaceable></literal> clause and other\n statements such as <literal role=\"stmt\">SHOW</literal>,\n <literal role=\"stmt\">EXPLAIN</literal>, and\n <literal role=\"stmt\">CHECK TABLE</literal>. For statements that\n can be determined at function definition time to return a result\n set, a <literal>Not allowed to return a result set from a\n function</literal> error occurs\n (<literal role=\"error\">ER_SP_NO_RETSET</literal>). For statements\n that can be determined only at runtime to return a result set, a\n <literal>PROCEDURE %s can't return a result set in the given\n context</literal> error occurs\n (<literal role=\"error\">ER_SP_BADSELECT</literal>)."
},
{
"para": "<literal role=\"stmt\">USE</literal> statements within stored\n routines are not permitted. When a routine is invoked, an implicit\n <literal>USE <replaceable>db_name</replaceable></literal> 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 <xref linkend=\"stored-program-restrictions\" />."
},
{
"para": "For information about invoking stored procedures from within\n programs written in a language that has a MySQL interface, see\n <xref linkend=\"call\" />."
},
{
"para": "MySQL stores the <literal role=\"sysvar\">sql_mode</literal> 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 <emphasis>regardless of the current server SQL mode when the\n routine begins executing</emphasis>."
},
{
"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 = <replaceable>user</replaceable>]\n PROCEDURE <replaceable>sp_name</replaceable> ([<replaceable>proc_parameter</replaceable>[,...]])\n [<replaceable>characteristic</replaceable> ...] <replaceable>routine_body</replaceable>\n\nCREATE\n [DEFINER = <replaceable>user</replaceable>]\n FUNCTION <replaceable>sp_name</replaceable> ([<replaceable>func_parameter</replaceable>[,...]])\n RETURNS <replaceable>type</replaceable>\n [<replaceable>characteristic</replaceable> ...] <replaceable>routine_body</replaceable>\n\n<replaceable>proc_parameter</replaceable>:\n [ IN | OUT | INOUT ] <replaceable>param_name</replaceable> <replaceable>type</replaceable>\n\n<replaceable>func_parameter</replaceable>:\n <replaceable>param_name</replaceable> <replaceable>type</replaceable>\n\n<replaceable>type</replaceable>:\n <replaceable>Any valid MySQL data type</replaceable>\n\n<replaceable>characteristic</replaceable>:\n COMMENT '<replaceable>string</replaceable>'\n | LANGUAGE SQL\n | [NOT] DETERMINISTIC\n | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }\n | SQL SECURITY { DEFINER | INVOKER }\n\n<replaceable>routine_body</replaceable>:\n <replaceable>Valid SQL routine statement</replaceable>"
}
]
},
{
"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 <literal>FEDERATED</literal> storage engine. The <literal>CREATE\n SERVER</literal> statement creates a new row in the\n <literal>servers</literal> table in the <literal>mysql</literal>\n database. This statement requires the\n <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "The <literal><replaceable>server_name</replaceable></literal>\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 <literal><replaceable>server_name</replaceable></literal> 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 <literal><replaceable>wrapper_name</replaceable></literal> is\n an identifier and may be quoted with single quotation marks."
},
{
"para": "For each <literal><replaceable>option</replaceable></literal> 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 <literal>CREATE SERVER</literal> statement creates an entry in\n the <literal>mysql.servers</literal> table that can later be used\n with the <literal role=\"stmt\">CREATE TABLE</literal> statement\n when creating a <literal>FEDERATED</literal> table. The options\n that you specify will be used to populate the columns in the\n <literal>mysql.servers</literal> table. The table columns are\n <literal>Server_name</literal>, <literal>Host</literal>,\n <literal>Db</literal>, <literal>Username</literal>,\n <literal>Password</literal>, <literal>Port</literal> and\n <literal>Socket</literal>."
}
],
"id": "CREATE SERVER",
"syntax": [
{
"programlisting": ">\nCREATE SERVER <replaceable>server_name</replaceable>\n FOREIGN DATA WRAPPER <replaceable>wrapper_name</replaceable>\n OPTIONS (<replaceable>option</replaceable> [, <replaceable>option</replaceable>] ...)\n\n<replaceable>option</replaceable>:\n { HOST <replaceable>character-literal</replaceable>\n | DATABASE <replaceable>character-literal</replaceable>\n | USER <replaceable>character-literal</replaceable>\n | PASSWORD <replaceable>character-literal</replaceable>\n | SOCKET <replaceable>character-literal</replaceable>\n | OWNER <replaceable>character-literal</replaceable>\n | PORT <replaceable>numeric-literal</replaceable> }"
}
]
},
{
"keywords": [
"CREATE",
"SPATIAL",
"REFERENCE",
"SYSTEM",
"OR",
"REPLACE",
"IF",
"NOT",
"EXISTS",
"NAME",
"DEFINITION",
"ORGANIZATION",
"DESCRIPTION"
],
"description": [
{
"para": "This statement creates a\n <link linkend=\"spatial-reference-systems\">spatial reference\n system</link> (SRS) definition and stores it in the data\n dictionary. The definition can be inspected using the\n <literal>INFORMATION_SCHEMA</literal>\n <literal role=\"is\">ST_SPATIAL_REFERENCE_SYSTEMS</literal> table.\n This statement requires the <literal role=\"priv\">SUPER</literal>\n privilege."
},
{
"para": "If neither <literal>OR REPLACE</literal> nor <literal>IF NOT\n EXISTS</literal> is specified, an error occurs if an SRS\n definition with the SRID value already exists."
},
{
"para": "With <literal>CREATE OR REPLACE</literal> 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> <userinput>CREATE OR REPLACE SPATIAL REFERENCE SYSTEM 4326 ...;</userinput>\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 <literal>CREATE ... IF NOT EXISTS</literal> 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 <replaceable>srid</replaceable> <replaceable>srs_attribute</replaceable> ...\n\nCREATE SPATIAL REFERENCE SYSTEM\n [IF NOT EXISTS]\n <replaceable>srid</replaceable> <replaceable>srs_attribute</replaceable> ...\n\n<replaceable>srs_attribute</replaceable>: {\n NAME '<replaceable>srs_name</replaceable>'\n | DEFINITION '<replaceable>definition</replaceable>'\n | ORGANIZATION '<replaceable>org_name</replaceable>' IDENTIFIED BY <replaceable>org_id</replaceable>\n | DESCRIPTION '<replaceable>description</replaceable>'\n}\n\n<replaceable>srid</replaceable>, <replaceable>org_id</replaceable>: <replaceable>32-bit unsigned integer</replaceable>"
}
]
},
{
"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 <literal role=\"stmt\">CREATE TABLE</literal> or\n <literal role=\"stmt\">ALTER TABLE</literal> statement includes\n the following:"
},
{
"programlisting": ">\n[CONSTRAINT [<replaceable>symbol</replaceable>]] FOREIGN KEY\n [<replaceable>index_name</replaceable>] (<replaceable>col_name</replaceable>, ...)\n REFERENCES <replaceable>tbl_name</replaceable> (<replaceable>col_name</replaceable>,...)\n [ON DELETE <replaceable>reference_option</replaceable>]\n [ON UPDATE <replaceable>reference_option</replaceable>]\n\n<replaceable>reference_option</replaceable>:\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": "<literal role=\"stmt\">CREATE TABLE</literal> creates a table with\n the given name. You must have the\n <literal role=\"priv\">CREATE</literal> privilege for the table."
},
{
"para": "By default, tables are created in the default database, using the\n <literal role=\"se\">InnoDB</literal> 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. <literal>InnoDB</literal> permits up to 4 billion\n tables."
},
{
"para": "For information about the physical representation of a table, see\n <xref linkend=\"create-table-files\" />."
}
],
"id": "CREATE TABLE",
"syntax": [
{
"programlisting": ">\nCREATE [TEMPORARY] TABLE [IF NOT EXISTS] <replaceable>tbl_name</replaceable>\n (<replaceable>create_definition</replaceable>,...)\n [<replaceable>table_options</replaceable>]\n [<replaceable>partition_options</replaceable>]\n\nCREATE [TEMPORARY] TABLE [IF NOT EXISTS] <replaceable>tbl_name</replaceable>\n [(<replaceable>create_definition</replaceable>,...)]\n [<replaceable>table_options</replaceable>]\n [<replaceable>partition_options</replaceable>]\n [IGNORE | REPLACE]\n [AS] <replaceable>query_expression</replaceable>\n\nCREATE [TEMPORARY] TABLE [IF NOT EXISTS] <replaceable>tbl_name</replaceable>\n { LIKE <replaceable>old_tbl_name</replaceable> | (LIKE <replaceable>old_tbl_name</replaceable>) }\n\n<replaceable>create_definition</replaceable>:\n <replaceable>col_name</replaceable> <replaceable>column_definition</replaceable>\n | {INDEX|KEY} [<replaceable>index_name</replaceable>] [<replaceable>index_type</replaceable>] (<replaceable>key_part</replaceable>,...)\n [<replaceable>index_option</replaceable>] ...\n | {FULLTEXT|SPATIAL} [INDEX|KEY] [<replaceable>index_name</replaceable>] (<replaceable>key_part</replaceable>,...)\n [<replaceable>index_option</replaceable>] ...\n | [CONSTRAINT [<replaceable>symbol</replaceable>]] PRIMARY KEY\n [<replaceable>index_type</replaceable>] (<replaceable>key_part</replaceable>,...)\n [<replaceable>index_option</replaceable>] ...\n | [CONSTRAINT [<replaceable>symbol</replaceable>]] UNIQUE [INDEX|KEY]\n [<replaceable>index_name</replaceable>] [<replaceable>index_type</replaceable>] (<replaceable>key_part</replaceable>,...)\n [<replaceable>index_option</replaceable>] ...\n | [CONSTRAINT [<replaceable>symbol</replaceable>]] FOREIGN KEY\n [<replaceable>index_name</replaceable>] (<replaceable>col_name</replaceable>,...)\n <replaceable>reference_definition</replaceable>\n | <replaceable>check_constraint_definition</replaceable>\n\n<replaceable>column_definition</replaceable>:\n <replaceable>data_type</replaceable> [NOT NULL | NULL] [DEFAULT {<replaceable>literal</replaceable> | (<replaceable>expr</replaceable>)} ]\n [AUTO_INCREMENT] [UNIQUE [KEY]] [[PRIMARY] KEY]\n [COMMENT '<replaceable>string</replaceable>']\n [COLLATE <replaceable>collation_name</replaceable>]\n [COLUMN_FORMAT {FIXED|DYNAMIC|DEFAULT}]\n [STORAGE {DISK|MEMORY}]\n [<replaceable>reference_definition</replaceable>]\n [<replaceable>check_constraint_definition</replaceable>]\n | <replaceable>data_type</replaceable>\n [COLLATE <replaceable>collation_name</replaceable>]\n [GENERATED ALWAYS] AS (<replaceable>expr</replaceable>)\n [VIRTUAL | STORED] [NOT NULL | NULL]\n [UNIQUE [KEY]] [[PRIMARY] KEY]\n [COMMENT '<replaceable>string</replaceable>']\n [<replaceable>reference_definition</replaceable>]\n [<replaceable>check_constraint_definition</replaceable>]\n\n<replaceable>data_type</replaceable>:\n (see <xref linkend=\"data-types\" />)\n\n<replaceable>key_part</replaceable>: {<replaceable>col_name</replaceable> [(<replaceable>length</replaceable>)] | (<replaceable>expr</replaceable>)} [ASC | DESC]\n\n<replaceable>index_type</replaceable>:\n USING {BTREE | HASH}\n\n<replaceable>index_option</replaceable>:\n KEY_BLOCK_SIZE [=] <replaceable>value</replaceable>\n | <replaceable>index_type</replaceable>\n | WITH PARSER <replaceable>parser_name</replaceable>\n | COMMENT '<replaceable>string</replaceable>'\n | {VISIBLE | INVISIBLE}\n\n<replaceable>check_constraint_definition</replaceable>:\n [CONSTRAINT [<replaceable>symbol</replaceable>]] CHECK (<replaceable>expr</replaceable>) [[NOT] ENFORCED]\n\n<replaceable>reference_definition</replaceable>:\n REFERENCES <replaceable>tbl_name</replaceable> (<replaceable>key_part</replaceable>,...)\n [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE]\n [ON DELETE <replaceable>reference_option</replaceable>]\n [ON UPDATE <replaceable>reference_option</replaceable>]\n\n<replaceable>reference_option</replaceable>:\n RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT\n\n<replaceable>table_options</replaceable>:\n <replaceable>table_option</replaceable> [[,] <replaceable>table_option</replaceable>] ...\n\n<replaceable>table_option</replaceable>:\n AUTO_INCREMENT [=] <replaceable>value</replaceable>\n | AVG_ROW_LENGTH [=] <replaceable>value</replaceable>\n | [DEFAULT] CHARACTER SET [=] <replaceable>charset_name</replaceable>\n | CHECKSUM [=] {0 | 1}\n | [DEFAULT] COLLATE [=] <replaceable>collation_name</replaceable>\n | COMMENT [=] '<replaceable>string</replaceable>'\n | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'}\n | CONNECTION [=] '<replaceable>connect_string</replaceable>'\n | {DATA|INDEX} DIRECTORY [=] '<replaceable>absolute path to directory</replaceable>'\n | DELAY_KEY_WRITE [=] {0 | 1}\n | ENCRYPTION [=] {'Y' | 'N'}\n | ENGINE [=] <replaceable>engine_name</replaceable>\n | INSERT_METHOD [=] { NO | FIRST | LAST }\n | KEY_BLOCK_SIZE [=] <replaceable>value</replaceable>\n | MAX_ROWS [=] <replaceable>value</replaceable>\n | MIN_ROWS [=] <replaceable>value</replaceable>\n | PACK_KEYS [=] {0 | 1 | DEFAULT}\n | PASSWORD [=] '<replaceable>string</replaceable>'\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 [=] <replaceable>value</replaceable>\n | TABLESPACE <replaceable>tablespace_name</replaceable> [STORAGE {DISK|MEMORY}]\n | UNION [=] (<replaceable>tbl_name</replaceable>[,<replaceable>tbl_name</replaceable>]...)\n\n<replaceable>partition_options</replaceable>:\n PARTITION BY\n { [LINEAR] HASH(<replaceable>expr</replaceable>)\n | [LINEAR] KEY [ALGORITHM={1|2}] (<replaceable>column_list</replaceable>)\n | RANGE{(<replaceable>expr</replaceable>) | COLUMNS(<replaceable>column_list</replaceable>)}\n | LIST{(<replaceable>expr</replaceable>) | COLUMNS(<replaceable>column_list</replaceable>)} }\n [PARTITIONS <replaceable>num</replaceable>]\n [SUBPARTITION BY\n { [LINEAR] HASH(<replaceable>expr</replaceable>)\n | [LINEAR] KEY [ALGORITHM={1|2}] (<replaceable>column_list</replaceable>) }\n [SUBPARTITIONS <replaceable>num</replaceable>]\n ]\n [(<replaceable>partition_definition</replaceable> [, <replaceable>partition_definition</replaceable>] ...)]\n\n<replaceable>partition_definition</replaceable>:\n PARTITION <replaceable>partition_name</replaceable>\n [VALUES\n {LESS THAN {(<replaceable>expr</replaceable> | <replaceable>value_list</replaceable>) | MAXVALUE}\n |\n IN (<replaceable>value_list</replaceable>)}]\n [[STORAGE] ENGINE [=] <replaceable>engine_name</replaceable>]\n [COMMENT [=] '<replaceable>string</replaceable>' ]\n [DATA DIRECTORY [=] '<filename><replaceable>data_dir</replaceable></filename>']\n [INDEX DIRECTORY [=] '<filename><replaceable>index_dir</replaceable></filename>']\n [MAX_ROWS [=] <replaceable>max_number_of_rows</replaceable>]\n [MIN_ROWS [=] <replaceable>min_number_of_rows</replaceable>]\n [TABLESPACE [=] tablespace_name]\n [(<replaceable>subpartition_definition</replaceable> [, <replaceable>subpartition_definition</replaceable>] ...)]\n\n<replaceable>subpartition_definition</replaceable>:\n SUBPARTITION <replaceable>logical_name</replaceable>\n [[STORAGE] ENGINE [=] <replaceable>engine_name</replaceable>]\n [COMMENT [=] '<replaceable>string</replaceable>' ]\n [DATA DIRECTORY [=] '<filename><replaceable>data_dir</replaceable></filename>']\n [INDEX DIRECTORY [=] '<filename><replaceable>index_dir</replaceable></filename>']\n [MAX_ROWS [=] <replaceable>max_number_of_rows</replaceable>]\n [MIN_ROWS [=] <replaceable>min_number_of_rows</replaceable>]\n [TABLESPACE [=] tablespace_name]\n\n<replaceable>query_expression:</replaceable>\n SELECT ... (<replaceable>Some valid select or union statement</replaceable>)"
}
]
},
{
"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 <literal role=\"se\">InnoDB</literal>\n tablespace. MySQL NDB Cluster also supports tablespaces using the\n <literal role=\"se\">NDB</literal> storage engine."
},
{
"para": "<literal role=\"stmt\">CREATE TABLESPACE</literal> syntax is used to\n create general tablespaces or undo tablespaces. The\n <literal>UNDO</literal> 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 <literal>InnoDB</literal> general tablespace,\n use <literal condition=\"create-table\" role=\"stmt\">CREATE TABLE\n <replaceable>tbl_name</replaceable> ... TABLESPACE [=]\n <replaceable>tablespace_name</replaceable></literal> or\n <literal condition=\"alter-table\" role=\"stmt\">ALTER TABLE\n <replaceable>tbl_name</replaceable> TABLESPACE [=]\n <replaceable>tablespace_name</replaceable></literal> to add tables\n to the tablespace. For more information, see\n <xref linkend=\"general-tablespaces\" />."
},
{
"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 <xref linkend=\"innodb-undo-tablespaces\" />."
},
{
"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 <xref linkend=\"mysql-cluster-disk-data\" />).\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 <literal role=\"stmt\">ALTER TABLESPACE</literal>\n statement (see <xref linkend=\"alter-tablespace\" />)."
},
{
"para": "A log file group of one or more <literal>UNDO</literal> log files\n must be assigned to the tablespace to be created with the\n <literal>USE LOGFILE GROUP</literal> clause.\n <replaceable>logfile_group</replaceable> must be an existing log\n file group created with <literal role=\"stmt\">CREATE LOGFILE\n GROUP</literal> (see <xref linkend=\"create-logfile-group\" />).\n Multiple tablespaces may use the same log file group for\n <literal>UNDO</literal> logging."
},
{
"para": "When setting <literal>EXTENT_SIZE</literal> or\n <literal>INITIAL_SIZE</literal>, you may optionally follow the\n number with a one-letter abbreviation for an order of magnitude,\n similar to those used in <filename>my.cnf</filename>. Generally,\n this is one of the letters <literal>M</literal> (for megabytes) or\n <literal>G</literal> (for gigabytes)."
},
{
"para": "<literal>INITIAL_SIZE</literal> and <literal>EXTENT_SIZE</literal>\n are subject to rounding as follows:"
},
{
"itemizedlist": [
[
{
"para": "<literal>EXTENT_SIZE</literal> is rounded up to the nearest\n whole multiple of 32K."
}
],
[
{
"para": "<literal>INITIAL_SIZE</literal> is rounded\n <emphasis>down</emphasis> to the nearest whole multiple of\n 32K; this result is rounded up to the nearest whole multiple\n of <literal>EXTENT_SIZE</literal> (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 <literal role=\"is\">INFORMATION_SCHEMA.FILES</literal> 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 <literal role=\"stmt\">CREATE TABLESPACE</literal> is used with\n <literal>ENGINE [=] NDB</literal>, 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 <literal role=\"is\">INFORMATION_SCHEMA.FILES</literal> table. (See\n the example later in this section.)"
},
{
"para": "(See <xref linkend=\"files-table\" />.)"
},
{
"itemizedlist": [
[
{
"para": "<literal>ADD DATAFILE</literal>: Defines the name of a\n tablespace data file. The <literal>ADD DATAFILE</literal>\n clause is required when creating undo tablespaces. Otherwise,\n it is optional as of MySQL 8.0.14."
},
{
"para": "An <literal>InnoDB</literal> tablespace supports only a single\n data file, whose name must include a <literal>.ibd</literal>\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 <literal role=\"stmt\">ALTER TABLESPACE</literal>\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 <literal role=\"sysvar\">innodb_undo_directory</literal>\n variable. If the\n <literal role=\"sysvar\">innodb_undo_directory</literal>\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 <literal>InnoDB</literal> prior to creating the tablespace. To\n make a directory known to <literal>InnoDB</literal>, add it to\n the <literal role=\"sysvar\">innodb_directories</literal> value\n or to one of the variables whose values are appended to the\n <literal role=\"sysvar\">innodb_directories</literal> value.\n <literal role=\"sysvar\">innodb_directories</literal> is a\n read-only variable. Configuring it requires restarting the\n server."
},
{
"para": "The <literal><replaceable>file_name</replaceable></literal>,\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 <literal>ADD DATAFILE</literal> 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 (<replaceable>aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee</replaceable>).\n A file extension is added if required by the storage engine.\n An <filename>.ibd</filename> file extension is added for\n <literal>InnoDB</literal> 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 <literal>ADD DATAFILE</literal> clause\n does not permit circular directory references when creating an\n <literal>InnoDB</literal> tablespace. For example, the\n circular directory reference (<literal>/../</literal>) in the\n following statement is not permitted:"
},
{
"programlisting": ">\nCREATE TABLESPACE ts1 ADD DATAFILE ts1.ibd '<replaceable>any_directory</replaceable>/../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 <replaceable>any_directory</replaceable> is a symbolic link.\n (It is still permitted for data file paths to begin with\n '<literal>../</literal>'.)"
}
],
[
{
"para": "<literal>FILE_BLOCK_SIZE</literal>: This optionmdashwhich is\n specific to <literal>InnoDB</literal> general tablespaces, and\n is ignored by <literal>NDB</literal>mdashdefines 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, <literal>FILE_BLOCK_SIZE</literal> defaults to the\n <literal role=\"sysvar\">innodb_page_size</literal> value.\n <literal>FILE_BLOCK_SIZE</literal> is required when you intend\n to use the tablespace for storing compressed\n <literal>InnoDB</literal> tables\n (<literal>ROW_FORMAT=COMPRESSED</literal>). In this case, you\n must define the tablespace <literal>FILE_BLOCK_SIZE</literal>\n when creating the tablespace."
},
{
"para": "If <literal>FILE_BLOCK_SIZE</literal> is equal the\n <literal role=\"sysvar\">innodb_page_size</literal> value, the\n tablespace can contain only tables having an uncompressed row\n format (<literal>COMPACT</literal>,\n <literal>REDUNDANT</literal>, and <literal>DYNAMIC</literal>).\n Tables with a <literal>COMPRESSED</literal> 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 <literal>FILE_BLOCK_SIZE</literal> must be specified, and the\n <literal>FILE_BLOCK_SIZE</literal> value must be a valid\n compressed page size in relation to the\n <literal role=\"sysvar\">innodb_page_size</literal> value. Also,\n the physical page size of the compressed table\n (<literal>KEY_BLOCK_SIZE</literal>) must be equal to\n <literal>FILE_BLOCK_SIZE/1024</literal>. For example, if\n <literal role=\"sysvar\">innodb_page_size=16K</literal>, and\n <literal>FILE_BLOCK_SIZE=8K</literal>, the\n <literal>KEY_BLOCK_SIZE</literal> of the table must be 8. For\n more information, see <xref linkend=\"general-tablespaces\" />."
}
],
[
{
"para": "<literal>USE LOGFILE GROUP</literal>: Required for\n <literal>NDB</literal>, this is the name of a log file group\n previously created using <literal role=\"stmt\">CREATE LOGFILE\n GROUP</literal>. Not supported for <literal>InnoDB</literal>,\n where it fails with an error."
}
],
[
{
"para": "<literal>EXTENT_SIZE</literal>: This option is specific to\n NDB, and is not supported by InnoDB, where it fails with an\n error. <literal>EXTENT_SIZE</literal> 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 <emphasis role=\"firstterm\">extent</emphasis> 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 <literal>INITIAL_SIZE</literal> (described in the\n following item) is 256 MB and whose\n <literal>EXTENT_SIZE</literal> 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 <literal role=\"is\">INFORMATION_SCHEMA.FILES</literal> table,\n and so derive an estimate for how much space remains free in\n the file. For further discussion and examples, see\n <xref linkend=\"files-table\" />."
}
],
[
{
"para": "<literal>INITIAL_SIZE</literal>: This option is specific to\n <literal>NDB</literal>, and is not supported by\n <literal>InnoDB</literal>, where it fails with an error."
},
{
"para": "The <literal>INITIAL_SIZE</literal> parameter sets the total\n size in bytes of the data file that was specific using\n <literal>ADD DATATFILE</literal>. 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 <literal condition=\"alter-tablespace\" role=\"stmt\">ALTER\n TABLESPACE ... ADD DATAFILE</literal>."
},
{
"para": "<literal>INITIAL_SIZE</literal> is optional; its default value\n is 134217728 (128 MB)."
},
{
"para": "On 32-bit systems, the maximum supported value for\n <literal>INITIAL_SIZE</literal> is 4294967296 (4 GB)."
}
],
[
{
"para": "<literal>AUTOEXTEND_SIZE</literal>: 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": "<literal>MAX_SIZE</literal>: 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": "<literal>NODEGROUP</literal>: 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": "<literal>WAIT</literal>: 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": "<literal>COMMENT</literal>: 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 <literal>ENCRYPTION</literal> clause enables or disables\n page-level data encryption for an <literal>InnoDB</literal>\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 <literal>ENCRYPTION</literal>\n clause is not specified, the\n <literal role=\"sysvar\">default_table_encryption</literal>\n setting controls whether encryption is enabled. The\n <literal>ENCRYPTION</literal> clause overrides the\n <literal role=\"sysvar\">default_table_encryption</literal>\n setting. However, if the\n <literal role=\"sysvar\">table_encryption_privilege_check</literal>\n variable is enabled, the\n <literal role=\"priv\">TABLE_ENCRYPTION_ADMIN</literal>\n privilege is required to use an <literal>ENCRYPTION</literal>\n clause setting that differs from the\n <literal role=\"sysvar\">default_table_encryption</literal>\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 <xref linkend=\"innodb-data-encryption\" />"
}
],
[
{
"para": "<literal>ENGINE</literal>: Defines the storage engine which\n uses the tablespace, where\n <replaceable>engine_name</replaceable> is the name of the\n storage engine. Currently, only the <literal>InnoDB</literal>\n storage engine is supported by standard MySQL current-series\n releases. MySQL NDB Cluster supports both\n <literal>NDB</literal> and <literal>InnoDB</literal>\n tablespaces. The value of the\n <literal role=\"sysvar\">default_storage_engine</literal> system\n variable is used for <literal>ENGINE</literal> if the option\n is not specified."
}
]
]
},
{
"itemizedlist": [
[
{
"para": "For the rules covering the naming of MySQL tablespaces, see\n <xref linkend=\"identifiers\" />. In addition to these rules, the\n slash character (<quote>/</quote>) is not permitted, nor can\n you use names beginning with <literal>innodb_</literal>, 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 <literal>TABLESPACE</literal> option may be used with\n <literal role=\"stmt\">CREATE TABLE</literal> or\n <literal role=\"stmt\">ALTER TABLE</literal> to assign an\n <literal>InnoDB</literal> 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 <literal>InnoDB</literal> tablespaces is not supported. Shared\n tablespaces include the <literal>InnoDB</literal> system\n tablespace and general tablespaces."
}
],
[
{
"para": "General tablespaces support the addition of tables of any row\n format using\n <literal condition=\"create-table\" role=\"stmt\">CREATE TABLE ...\n TABLESPACE</literal>.\n <literal role=\"sysvar\">innodb_file_per_table</literal> does\n not need to be enabled."
}
],
[
{
"para": "<literal role=\"sysvar\">innodb_strict_mode</literal> is not\n applicable to general tablespaces. Tablespace management rules\n are strictly enforced independently of\n <literal role=\"sysvar\">innodb_strict_mode</literal>. If\n <literal>CREATE TABLESPACE</literal> parameters are incorrect\n or incompatible, the operation fails regardless of the\n <literal role=\"sysvar\">innodb_strict_mode</literal> setting.\n When a table is added to a general tablespace using\n <literal condition=\"create-table\" role=\"stmt\">CREATE TABLE ...\n TABLESPACE</literal> or\n <literal condition=\"alter-table\" role=\"stmt\">ALTER TABLE ...\n TABLESPACE</literal>,\n <literal role=\"sysvar\">innodb_strict_mode</literal> is ignored\n but the statement is evaluated as if\n <literal role=\"sysvar\">innodb_strict_mode</literal> is\n enabled."
}
],
[
{
"para": "Use <literal>DROP TABLESPACE</literal> to remove a tablespace.\n All tables must be dropped from a tablespace using\n <literal role=\"stmt\">DROP TABLE</literal> 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 <literal condition=\"alter-tablespace\" role=\"stmt\">ALTER\n TABLESPACE ... DROP DATATFILE</literal> statements. See\n <xref linkend=\"mysql-cluster-disk-data-objects\" />."
}
],
[
{
"para": "All parts of an <literal>InnoDB</literal> table added to an\n <literal>InnoDB</literal> general tablespace reside in the\n general tablespace, including indexes and\n <literal role=\"type\">BLOB</literal> pages."
},
{
"para": "For an <literal>NDB</literal> 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 <literal>NDB</literal> 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 <link linkend=\"glos_ibd_file\">.ibd data file</link> which can\n only be used for new <literal>InnoDB</literal> 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": "<literal condition=\"alter-table\" role=\"stmt\">ALTER TABLE ...\n DISCARD TABLESPACE</literal> and\n <literal condition=\"alter-table\" role=\"stmt\">ALTER TABLE\n ...IMPORT TABLESPACE</literal> 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 <quote>/</quote>\n character, which is present in file-per-table tablespace\n names, is not permitted in general tablespace names."
}
],
[
{
"para": "<command>mysqldump</command> and <command>mysqlpump</command>\n do not dump <literal>InnoDB</literal>\n <literal role=\"stmt\">CREATE TABLESPACE</literal> statements."
}
]
]
},
{
"para": "This example demonstrates creating a general tablespace and adding\n three uncompressed tables of different row formats."
},
{
"programlisting": ">\nmysql> <userinput>CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' ENGINE=INNODB;</userinput>\n\nmysql> <userinput>CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=REDUNDANT;</userinput>\n\nmysql> <userinput>CREATE TABLE t2 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=COMPACT;</userinput>\n\nmysql> <userinput>CREATE TABLE t3 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=DYNAMIC;</userinput>"
},
{
"para": "This example demonstrates creating a general tablespace and adding\n a compressed table. The example assumes a default\n <literal role=\"sysvar\">innodb_page_size</literal> value of 16K.\n The <literal>FILE_BLOCK_SIZE</literal> of 8192 requires that the\n compressed table have a <literal>KEY_BLOCK_SIZE</literal> of 8."
},
{
"programlisting": ">\nmysql> <userinput>CREATE TABLESPACE `ts2` ADD DATAFILE 'ts2.ibd' FILE_BLOCK_SIZE = 8192 Engine=InnoDB;</userinput>\n\nmysql> <userinput>CREATE TABLE t4 (c1 INT PRIMARY KEY) TABLESPACE ts2 ROW_FORMAT=COMPRESSED KEY_BLOCK_SIZE=8;</userinput>"
},
{
"para": "This example demonstrates creating a general tablespace without\n specifying the <literal>ADD DATAFILE</literal> clause, which is\n optional as of MySQL 8.0.14."
},
{
"programlisting": ">\nmysql> <userinput>CREATE TABLESPACE `ts3` ENGINE=INNODB;</userinput>"
},
{
"para": "This example demonstrates creating an undo tablespace."
},
{
"programlisting": ">\nmysql> <userinput>CREATE UNDO TABLESPACE <replaceable>undo_003</replaceable> ADD DATAFILE '<replaceable>undo_003</replaceable>.ibu';</userinput>"
},
{
"para": "Suppose that you wish to create an NDB Cluster Disk Data\n tablespace named <literal>myts</literal> using a datafile named\n <filename>mydata-1.dat</filename>. An <filename>NDB</filename>\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 <literal>mylg</literal> that contains one\n undo long file named <filename>myundo-1.dat</filename>, using the\n <literal role=\"stmt\">CREATE LOGFILE GROUP</literal> statement\n shown here:"
},
{
"programlisting": ">\nmysql> <userinput>CREATE LOGFILE GROUP myg1</userinput>\n -> <userinput>ADD UNDOFILE 'myundo-1.dat'</userinput>\n -> <userinput>ENGINE=NDB;</userinput>\nQuery OK, 0 rows affected (3.29 sec)"
},
{
"para": "Now you can create the tablespace previously described using the\n following statement:"
},
{
"programlisting": ">\nmysql> <userinput>CREATE TABLESPACE myts</userinput>\n -> <userinput>ADD DATAFILE 'mydata-1.dat'</userinput>\n -> <userinput>USE LOGFILE GROUP mylg</userinput>\n -> <userinput>ENGINE=NDB;</userinput>\nQuery OK, 0 rows affected (2.98 sec)"
},
{
"para": "You can now create a Disk Data table using a\n <literal role=\"stmt\">CREATE TABLE</literal> statement with the\n <literal>TABLESPACE</literal> and <literal>STORAGE DISK</literal>\n options, similar to what is shown here:"
},
{
"programlisting": ">\nmysql> <userinput>CREATE TABLE mytable (</userinput>\n -> <userinput>id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,</userinput>\n -> <userinput>lname VARCHAR(50) NOT NULL,</userinput>\n -> <userinput>fname VARCHAR(50) NOT NULL,</userinput>\n -> <userinput>dob DATE NOT NULL,</userinput>\n -> <userinput>joined DATE NOT NULL,</userinput>\n -> <userinput>INDEX(last_name, first_name)</userinput>\n -> <userinput>)</userinput>\n -> <userinput>TABLESPACE myts STORAGE DISK</userinput>\n -> <userinput>ENGINE=NDB;</userinput>\nQuery OK, 0 rows affected (1.41 sec)"
},
{
"para": "It is important to note that only the <literal>dob</literal> and\n <literal>joined</literal> columns from <literal>mytable</literal>\n are actually stored on disk, due to the fact that the\n <literal>id</literal>, <literal>lname</literal>, and\n <literal>fname</literal> columns are all indexed."
},
{
"para": "As mentioned previously, when <literal>CREATE TABLESPACE</literal>\n is used with <literal>ENGINE [=] NDB</literal>, 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 <literal role=\"is\">INFORMATION_SCHEMA.FILES</literal> table, as\n shown here:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT FILE_NAME, FILE_TYPE, LOGFILE_GROUP_NAME, STATUS, EXTRA</userinput>\n -> <userinput>FROM INFORMATION_SCHEMA.FILES</userinput>\n -> <userinput>WHERE TABLESPACE_NAME = 'myts';</userinput>\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 <xref linkend=\"mysql-cluster-disk-data-objects\" />."
}
],
"id": "CREATE TABLESPACE",
"syntax": [
{
"programlisting": ">\nCREATE [UNDO] TABLESPACE <replaceable>tablespace_name</replaceable>\n\n <emphasis>InnoDB and NDB:</emphasis>\n [ADD DATAFILE '<replaceable>file_name</replaceable>']\n\n <emphasis>InnoDB only:</emphasis>\n [FILE_BLOCK_SIZE = value]\n [ENCRYPTION [=] {'Y' | 'N'}]\n\n <emphasis>NDB only:</emphasis>\n USE LOGFILE GROUP <replaceable>logfile_group</replaceable>\n [EXTENT_SIZE [=] <replaceable>extent_size</replaceable>]\n [INITIAL_SIZE [=] <replaceable>initial_size</replaceable>]\n [AUTOEXTEND_SIZE [=] <replaceable>autoextend_size</replaceable>]\n [MAX_SIZE [=] <replaceable>max_size</replaceable>]\n [NODEGROUP [=] <replaceable>nodegroup_id</replaceable>]\n [WAIT]\n [COMMENT [=] '<replaceable>string</replaceable>']\n\n <emphasis>InnoDB and NDB:</emphasis>\n [ENGINE [=] <replaceable>engine_name</replaceable>]"
}
]
},
{
"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 <replaceable>tbl_name</replaceable>, which must refer to a\n permanent table. You cannot associate a trigger with a\n <literal>TEMPORARY</literal> 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 <literal role=\"stmt\">CREATE\n TRIGGER</literal> syntax. For additional discussion, see\n <xref linkend=\"trigger-syntax\" />."
},
{
"para": "<literal role=\"stmt\">CREATE TRIGGER</literal> requires the\n <literal role=\"priv\">TRIGGER</literal> privilege for the table\n associated with the trigger. If the <literal>DEFINER</literal>\n clause is present, the privileges required depend on the\n <replaceable>user</replaceable> value, as discussed in\n <xref linkend=\"stored-objects-security\" />. If binary logging is\n enabled, <literal role=\"stmt\">CREATE TRIGGER</literal> might\n require the <literal role=\"priv\">SUPER</literal> privilege, as\n discussed in <xref linkend=\"stored-programs-logging\" />."
},
{
"para": "The <literal>DEFINER</literal> 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": "<replaceable>trigger_time</replaceable> is the trigger action\n time. It can be <literal>BEFORE</literal> or\n <literal>AFTER</literal> 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 <literal>BEFORE</literal> triggers to convert\n values inappropriate for the column type to valid values."
},
{
"para": "<replaceable>trigger_event</replaceable> indicates the kind of\n operation that activates the trigger. These\n <replaceable>trigger_event</replaceable> values are permitted:"
},
{
"itemizedlist": [
[
{
"para": "<literal role=\"stmt\">INSERT</literal>: The trigger activates\n whenever a new row is inserted into the table (for example,\n through <literal role=\"stmt\">INSERT</literal>,\n <literal role=\"stmt\">LOAD DATA</literal>, and\n <literal role=\"stmt\">REPLACE</literal> statements)."
}
],
[
{
"para": "<literal role=\"stmt\">UPDATE</literal>: The trigger activates\n whenever a row is modified (for example, through\n <literal role=\"stmt\">UPDATE</literal> statements)."
}
],
[
{
"para": "<literal role=\"stmt\">DELETE</literal>: The trigger activates\n whenever a row is deleted from the table (for example, through\n <literal role=\"stmt\">DELETE</literal> and\n <literal role=\"stmt\">REPLACE</literal> statements).\n <literal role=\"stmt\">DROP TABLE</literal> and\n <literal role=\"stmt\">TRUNCATE TABLE</literal> statements on\n the table do <emphasis>not</emphasis> activate this trigger,\n because they do not use <literal role=\"stmt\">DELETE</literal>.\n Dropping a partition does not activate\n <literal role=\"stmt\">DELETE</literal> triggers, either."
}
]
]
}
],
"id": "CREATE TRIGGER",
"syntax": [
{
"programlisting": ">\nCREATE\n [DEFINER = <replaceable>user</replaceable>]\n TRIGGER <replaceable>trigger_name</replaceable>\n <replaceable>trigger_time</replaceable> <replaceable>trigger_event</replaceable>\n ON <replaceable>tbl_name</replaceable> FOR EACH ROW\n [<replaceable>trigger_order</replaceable>]\n <replaceable>trigger_body</replaceable>\n\n<replaceable>trigger_time</replaceable>: { BEFORE | AFTER }\n\n<replaceable>trigger_event</replaceable>: { INSERT | UPDATE | DELETE }\n\n<replaceable>trigger_order</replaceable>: { FOLLOWS | PRECEDES } <replaceable>other_trigger_name</replaceable>"
}
]
},
{
"keywords": [
"CREATE",
"VIEW"
],
"description": [
{
"para": "The <literal role=\"stmt\">CREATE VIEW</literal> statement creates a\n new view, or replaces an existing view if the <literal>OR\n REPLACE</literal> clause is given. If the view does not exist,\n <literal condition=\"create-view\" role=\"stmt\">CREATE OR REPLACE\n VIEW</literal> is the same as <literal role=\"stmt\">CREATE\n VIEW</literal>. If the view does exist,\n <literal condition=\"create-view\" role=\"stmt\">CREATE OR REPLACE\n VIEW</literal> replaces it."
},
{
"para": "For information about restrictions on view use, see\n <xref linkend=\"view-restrictions\" />."
},
{
"para": "The <replaceable>select_statement</replaceable> is a\n <literal role=\"stmt\">SELECT</literal> statement that provides the\n definition of the view. (Selecting from the view selects, in\n effect, using the <literal role=\"stmt\">SELECT</literal>\n statement.) The <replaceable>select_statement</replaceable> can\n select from base tables or other views."
},
{
"para": "The view definition is <quote>frozen</quote> 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 <literal>SELECT *</literal> 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 <literal>ALGORITHM</literal> clause affects how MySQL\n processes the view. The <literal>DEFINER</literal> and\n <literal>SQL SECURITY</literal> clauses specify the security\n context to be used when checking access privileges at view\n invocation time. The <literal>WITH CHECK OPTION</literal> 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 <literal role=\"stmt\">CREATE VIEW</literal> statement requires\n the <literal role=\"priv\">CREATE VIEW</literal> privilege for the\n view, and some privilege for each column selected by the\n <literal role=\"stmt\">SELECT</literal> statement. For columns used\n elsewhere in the <literal role=\"stmt\">SELECT</literal> statement,\n you must have the <literal role=\"priv\">SELECT</literal> privilege.\n If the <literal>OR REPLACE</literal> clause is present, you must\n also have the <literal role=\"priv\">DROP</literal> privilege for\n the view. If the <literal>DEFINER</literal> clause is present, the\n privileges required depend on the <replaceable>user</replaceable>\n value, as discussed in <xref linkend=\"stored-objects-security\" />."
},
{
"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 <replaceable>db_name.view_name</replaceable> 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 <literal role=\"stmt\">SELECT</literal> 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 <literal role=\"stmt\">SELECT</literal>\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 <literal role=\"stmt\">SELECT</literal> statement are used for\n the view column names. To define explicit names for the view\n columns, specify the optional\n <replaceable>column_list</replaceable> clause as a list of\n comma-separated identifiers. The number of names in\n <replaceable>column_list</replaceable> must be the same as the\n number of columns retrieved by the\n <literal role=\"stmt\">SELECT</literal> statement."
},
{
"para": "A view can be created from many kinds of\n <literal role=\"stmt\">SELECT</literal> statements. It can refer to\n base tables or other views. It can use joins,\n <literal role=\"stmt\">UNION</literal>, and subqueries. The\n <literal role=\"stmt\">SELECT</literal> 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> <userinput>CREATE TABLE t (qty INT, price INT);</userinput>\nmysql> <userinput>INSERT INTO t VALUES(3, 50);</userinput>\nmysql> <userinput>CREATE VIEW v AS SELECT qty, price, qty*price AS value FROM t;</userinput>\nmysql> <userinput>SELECT * FROM v;</userinput>\n+------+-------+-------+\n| qty | price | value |\n+------+-------+-------+\n| 3 | 50 | 150 |\n+------+-------+-------+"
},
{
"para": "A view definition is subject to the following restrictions:"
},
{
"itemizedlist": [
[
{
"para": "The <literal role=\"stmt\">SELECT</literal> statement cannot\n refer to system variables or user-defined variables."
}
],
[
{
"para": "Within a stored program, the\n <literal role=\"stmt\">SELECT</literal> statement cannot refer\n to program parameters or local variables."
}
],
[
{
"para": "The <literal role=\"stmt\">SELECT</literal> 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 <literal role=\"stmt\">CHECK TABLE</literal> statement."
}
],
[
{
"para": "The definition cannot refer to a <literal>TEMPORARY</literal>\n table, and you cannot create a <literal>TEMPORARY</literal>\n view."
}
],
[
{
"para": "You cannot associate a trigger with a view."
}
],
[
{
"para": "Aliases for column names in the\n <literal role=\"stmt\">SELECT</literal> statement are checked\n against the maximum column length of 64 characters (not the\n maximum alias length of 256 characters)."
}
]
]
},
{
"para": "<literal>ORDER BY</literal> 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 <literal>ORDER BY</literal>."
},
{
"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 <literal>LIMIT</literal> clause, and you select from\n the view using a statement that has its own\n <literal>LIMIT</literal> clause, it is undefined which limit\n applies. This same principle applies to options such as\n <literal>ALL</literal>, <literal>DISTINCT</literal>, or\n <literal>SQL_SMALL_RESULT</literal> that follow the\n <literal role=\"stmt\">SELECT</literal> keyword, and to clauses such\n as <literal>INTO</literal>, <literal>FOR UPDATE</literal>,\n <literal>FOR SHARE</literal>, <literal>LOCK IN SHARE\n MODE</literal>, and <literal>PROCEDURE</literal>."
},
{
"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> <userinput>CREATE VIEW v (mycol) AS SELECT 'abc';</userinput>\nQuery OK, 0 rows affected (0.01 sec)\n\nmysql> <userinput>SET sql_mode = '';</userinput>\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> <userinput>SELECT \"mycol\" FROM v;</userinput>\n+-------+\n| mycol |\n+-------+\n| mycol |\n+-------+\n1 row in set (0.01 sec)\n\nmysql> <userinput>SET sql_mode = 'ANSI_QUOTES';</userinput>\nQuery OK, 0 rows affected (0.00 sec)\n\nmysql> <userinput>SELECT \"mycol\" FROM v;</userinput>\n+-------+\n| mycol |\n+-------+\n| abc |\n+-------+\n1 row in set (0.00 sec)"
},
{
"para": "The <literal>DEFINER</literal> and <literal>SQL SECURITY</literal>\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 <literal>SQL SECURITY</literal>\n characteristic values are <literal>DEFINER</literal> (the default)\n and <literal>INVOKER</literal>. These indicate that the required\n privileges must be held by the user who defined or invoked the\n view, respectively."
},
{
"para": "If the <literal>DEFINER</literal> clause is present, the\n <replaceable>user</replaceable> value should be a MySQL account\n specified as\n <literal>'<replaceable>user_name</replaceable>'@'<replaceable>host_name</replaceable>'</literal>,\n <literal role=\"func\">CURRENT_USER</literal>, or\n <literal role=\"func\">CURRENT_USER()</literal>. The permitted\n <replaceable>user</replaceable> values depend on the privileges\n you hold, as discussed in\n <xref linkend=\"stored-objects-security\" />. Also see that section\n for additional information about view security."
},
{
"para": "If the <literal>DEFINER</literal> clause is omitted, the default\n definer is the user who executes the <literal role=\"stmt\">CREATE\n VIEW</literal> statement. This is the same as specifying\n <literal>DEFINER = CURRENT_USER</literal> explicitly."
},
{
"para": "Within a view definition, the\n <literal role=\"func\">CURRENT_USER</literal> function returns the\n view's <literal>DEFINER</literal> value by default. For views\n defined with the <literal>SQL SECURITY INVOKER</literal>\n characteristic, <literal role=\"func\">CURRENT_USER</literal>\n returns the account for the view's invoker. For information about\n user auditing within views, see\n <xref linkend=\"account-activity-auditing\" />."
},
{
"para": "Within a stored routine that is defined with the <literal>SQL\n SECURITY DEFINER</literal> characteristic,\n <literal role=\"func\">CURRENT_USER</literal> returns the routine's\n <literal>DEFINER</literal> value. This also affects a view defined\n within such a routine, if the view definition contains a\n <literal>DEFINER</literal> value of\n <literal role=\"func\">CURRENT_USER</literal>."
},
{
"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 <literal role=\"priv\">SELECT</literal> 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 (<literal role=\"priv\">SELECT</literal>\n to select from it, <literal role=\"priv\">INSERT</literal> 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 <literal>DEFINER</literal> account or invoker,\n depending on whether the <literal>SQL SECURITY</literal>\n characteristic is <literal>DEFINER</literal> or\n <literal>INVOKER</literal>, 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 <literal>SQL SECURITY</literal>\n characteristic is <literal>DEFINER</literal> or\n <literal>INVOKER</literal>. If the security characteristic is\n <literal>DEFINER</literal>, the function runs with the\n privileges of the <literal>DEFINER</literal> account. If the\n characteristic is <literal>INVOKER</literal>, the function\n runs with the privileges determined by the view's <literal>SQL\n SECURITY</literal> 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 <literal>f()</literal>:"
},
{
"programlisting": ">\nCREATE VIEW v AS SELECT * FROM t WHERE t.id = f(t.name);"
},
{
"para": "Suppose that <literal>f()</literal> 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 <literal>f()</literal> need to be checked when\n <literal>f()</literal> executes. This might mean that privileges\n are needed for <literal>p1()</literal> or <literal>p2()</literal>,\n depending on the execution path within <literal>f()</literal>.\n Those privileges must be checked at runtime, and the user who must\n possess the privileges is determined by the <literal>SQL\n SECURITY</literal> values of the view <literal>v</literal> and the\n function <literal>f()</literal>."
},
{
"para": "The <literal>DEFINER</literal> and <literal>SQL SECURITY</literal>\n clauses for views are extensions to standard SQL. In standard SQL,\n views are handled using the rules for <literal>SQL SECURITY\n DEFINER</literal>. 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 <literal role=\"priv\">SELECT</literal>) and may grant them. MySQL\n has no concept of a schema <quote>owner</quote>, so MySQL adds a\n clause to identify the definer. The <literal>DEFINER</literal>\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 <literal>DEFINER</literal> value is the\n account of the view creator."
},
{
"para": "The optional <literal>ALGORITHM</literal> clause is a MySQL\n extension to standard SQL. It affects how MySQL processes the\n view. <literal>ALGORITHM</literal> takes three values:\n <literal>MERGE</literal>, <literal>TEMPTABLE</literal>, or\n <literal>UNDEFINED</literal>. For more information, see\n <xref linkend=\"view-algorithms\" />, as well as\n <xref linkend=\"derived-table-optimization\" />."
},
{
"para": "Some views are updatable. That is, you can use them in statements\n such as <literal role=\"stmt\">UPDATE</literal>,\n <literal role=\"stmt\">DELETE</literal>, or\n <literal role=\"stmt\">INSERT</literal> 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 <literal>DEFAULT</literal>. For information about generated\n columns, see <xref linkend=\"create-table-generated-columns\" />."
},
{
"para": "The <literal>WITH CHECK OPTION</literal> clause can be given for\n an updatable view to prevent inserts or updates to rows except\n those for which the <literal>WHERE</literal> clause in the\n <replaceable>select_statement</replaceable> is true."
},
{
"para": "In a <literal>WITH CHECK OPTION</literal> clause for an updatable\n view, the <literal>LOCAL</literal> and <literal>CASCADED</literal>\n keywords determine the scope of check testing when the view is\n defined in terms of another view. The <literal>LOCAL</literal>\n keyword restricts the <literal>CHECK OPTION</literal> only to the\n view being defined. <literal>CASCADED</literal> causes the checks\n for underlying views to be evaluated as well. When neither keyword\n is given, the default is <literal>CASCADED</literal>."
},
{
"para": "For more information about updatable views and the <literal>WITH\n CHECK OPTION</literal> clause, see\n <xref linkend=\"view-updatability\" />, and\n <xref linkend=\"view-check-option\" />."
}
],
"id": "CREATE VIEW",
"syntax": [
{
"programlisting": ">\nCREATE\n [OR REPLACE]\n [ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}]\n [DEFINER = <replaceable>user</replaceable>]\n [SQL SECURITY { DEFINER | INVOKER }]\n VIEW <replaceable>view_name</replaceable> [(<replaceable>column_list</replaceable>)]\n AS <replaceable>select_statement</replaceable>\n [WITH [CASCADED | LOCAL] CHECK OPTION]"
}
]
},
{
"keywords": [
"DROP",
"DATABASE",
"SCHEMA",
"IF",
"EXISTS"
],
"description": [
{
"para": "<literal role=\"stmt\">DROP DATABASE</literal> drops all tables in\n the database and deletes the database. Be\n <emphasis>very</emphasis> careful with this statement! To use\n <literal role=\"stmt\">DROP DATABASE</literal>, you need the\n <literal role=\"priv\">DROP</literal> privilege on the database.\n <literal condition=\"drop-database\" role=\"stmt\">DROP\n SCHEMA</literal> is a synonym for <literal role=\"stmt\">DROP\n DATABASE</literal>."
},
{
"para": "<literal>IF EXISTS</literal> 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] <replaceable>db_name</replaceable>"
}
]
},
{
"keywords": [
"DROP",
"EVENT",
"IF",
"EXISTS"
],
"description": [
{
"para": "This statement drops the event named\n <replaceable>event_name</replaceable>. The event immediately\n ceases being active, and is deleted completely from the server."
},
{
"para": "If the event does not exist, the error <errortext>ERROR 1517\n (HY000): Unknown event\n '<replaceable>event_name</replaceable>'</errortext> results. You\n can override this and cause the statement to generate a warning\n for nonexistent events instead using <literal>IF EXISTS</literal>."
},
{
"para": "This statement requires the <literal role=\"priv\">EVENT</literal>\n privilege for the schema to which the event to be dropped belongs."
}
],
"id": "DROP EVENT",
"syntax": [
{
"programlisting": ">\nDROP EVENT [IF EXISTS] <replaceable>event_name</replaceable>"
}
]
},
{
"keywords": [
"DROP",
"INDEX"
],
"description": [
{
"para": "<literal role=\"stmt\">DROP INDEX</literal> drops the index named\n <replaceable>index_name</replaceable> from the table\n <replaceable>tbl_name</replaceable>. This statement is mapped to\n an <literal role=\"stmt\">ALTER TABLE</literal> statement to drop\n the index. See <xref linkend=\"alter-table\" />."
},
{
"para": "To drop a primary key, the index name is always\n <literal>PRIMARY</literal>, which must be specified as a quoted\n identifier because <literal>PRIMARY</literal> is a reserved word:"
},
{
"programlisting": ">\nDROP INDEX `PRIMARY` ON t;"
}
],
"id": "DROP INDEX",
"syntax": [
{
"programlisting": ">\nDROP INDEX <replaceable>index_name</replaceable> ON <replaceable>tbl_name</replaceable>\n [<replaceable>algorithm_option</replaceable> | <replaceable>lock_option</replaceable>] ...\n\n<replaceable>algorithm_option</replaceable>:\n ALGORITHM [=] {DEFAULT|INPLACE|COPY}\n\n<replaceable>lock_option</replaceable>:\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 <literal role=\"priv\">ALTER ROUTINE</literal>\n privilege for the routine. (If the\n <literal>automatic_sp_privileges</literal> system variable is\n enabled, that privilege and <literal role=\"priv\">EXECUTE</literal>\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 <xref linkend=\"stored-routines-privileges\" />.)"
},
{
"para": "The <literal>IF EXISTS</literal> 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 <literal role=\"stmt\">SHOW WARNINGS</literal>."
}
],
"id": "DROP PROCEDURE",
"syntax": [
{
"programlisting": ">\nDROP {PROCEDURE | FUNCTION} [IF EXISTS] <replaceable>sp_name</replaceable>"
}
]
},
{
"keywords": [
"DROP",
"SERVER",
"IF",
"EXISTS"
],
"description": [
{
"para": "Drops the server definition for the server named\n <literal><replaceable>server_name</replaceable></literal>. The\n corresponding row in the <literal>mysql.servers</literal> table is\n deleted. This statement requires the\n <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "Dropping a server for a table does not affect any\n <literal>FEDERATED</literal> tables that used this connection\n information when they were created. See\n <xref linkend=\"create-server\" />."
}
],
"id": "DROP SERVER",
"syntax": [
{
"programlisting": ">\nDROP SERVER [ IF EXISTS ] <replaceable>server_name</replaceable>"
}
]
},
{
"keywords": [
"DROP",
"SPATIAL",
"REFERENCE",
"SYSTEM",
"IF",
"EXISTS"
],
"description": [
{
"para": "This statement removes a\n <link linkend=\"spatial-reference-systems\">spatial reference\n system</link> (SRS) definition from the data dictionary. It\n requires the <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "Example:"
},
{
"programlisting": ">\nDROP SPATIAL REFERENCE SYSTEM 4120;"
},
{
"para": "If no SRS definition with the SRID value exists, an error occurs\n unless <literal>IF EXISTS</literal> 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> <userinput>DROP SPATIAL REFERENCE SYSTEM 4326;</userinput>\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 <literal role=\"stmt\">DROP SPATIAL REFERENCE SYSTEM</literal>."
}
],
[
{
"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 <ulink url=\"http://epsg.org\">European Petroleum\n Survey Group</ulink>."
}
],
[
{
"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 <replaceable>srid</replaceable>\n\n<replaceable>srid</replaceable>: <replaceable>32-bit unsigned integer</replaceable>"
}
]
},
{
"keywords": [
"DROP",
"TABLE",
"EXISTS",
"IF",
"TEMPORARY",
"RESTRICT",
"CASCADE"
],
"description": [
{
"para": "<literal role=\"stmt\">DROP TABLE</literal> removes one or more\n tables. You must have the <literal role=\"priv\">DROP</literal>\n privilege for each table."
},
{
"para": "<emphasis>Be careful</emphasis> 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": "<literal role=\"stmt\">DROP TABLE</literal> causes an implicit\n commit, except when used with the <literal>TEMPORARY</literal>\n keyword. See <xref linkend=\"implicit-commit\" />."
},
{
"para": "If any tables named in the argument list do not exist,\n <literal role=\"stmt\">DROP TABLE</literal> behavior depends on\n whether the <literal>IF EXISTS</literal> clause is given:"
},
{
"itemizedlist": [
[
{
"para": "Without <literal>IF EXISTS</literal>, the statement fails with\n an error indicating which nonexisting tables it was unable to\n drop, and no changes are made."
}
],
[
{
"para": "With <literal>IF EXISTS</literal>, no error occurs for\n nonexisting tables. The statement drops all named tables that\n do exist, and generates a <literal>NOTE</literal> diagnostic\n for each nonexistent table. These notes can be displayed with\n <literal role=\"stmt\">SHOW WARNINGS</literal>. See\n <xref linkend=\"show-warnings\" />."
}
]
]
},
{
"para": "<literal>IF EXISTS</literal> 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 <literal>TEMPORARY</literal> keyword has the following\n effects:"
},
{
"itemizedlist": [
[
{
"para": "The statement drops only <literal>TEMPORARY</literal> tables."
}
],
[
{
"para": "The statement does not cause an implicit commit."
}
],
[
{
"para": "No access rights are checked. A <literal>TEMPORARY</literal>\n table is visible only with the session that created it, so no\n check is necessary."
}
]
]
},
{
"para": "Including the <literal>TEMPORARY</literal> keyword is a good way\n to prevent accidentally dropping non-<literal>TEMPORARY</literal>\n tables."
},
{
"para": "The <literal>RESTRICT</literal> and <literal>CASCADE</literal>\n keywords do nothing. They are permitted to make porting easier\n from other database systems."
},
{
"para": "<literal role=\"stmt\">DROP TABLE</literal> is not supported with\n all <literal role=\"sysvar\">innodb_force_recovery</literal>\n settings. See <xref linkend=\"forcing-innodb-recovery\" />."
}
],
"id": "DROP TABLE",
"syntax": [
{
"programlisting": ">\nDROP [TEMPORARY] TABLE [IF EXISTS]\n <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ...\n [RESTRICT | CASCADE]"
}
]
},
{
"keywords": [
"DROP",
"UNDO",
"TABLESPACE",
"ENGINE"
],
"description": [
{
"para": "This statement drops a tablespace that was previously created\n using <literal role=\"stmt\">CREATE TABLESPACE</literal>. It is\n supported by the <literal>NDB</literal> and\n <literal>InnoDB</literal> storage engines."
},
{
"para": "The <literal>UNDO</literal> keyword, introduced in MySQL 8.0.14,\n must be specified to drop an undo tablespace. Only undo\n tablespaces created using\n <literal condition=\"create-tablespace\" role=\"stmt\">CREATE UNDO\n TABLESPACE</literal> syntax can be dropped. An undo tablespace\n must be in an <literal>empty</literal> state before it can be\n dropped. For more information, see\n <xref linkend=\"innodb-undo-tablespaces\" />."
},
{
"para": "<literal>ENGINE</literal> sets the storage engine that uses the\n tablespace, where <replaceable>engine_name</replaceable> is the\n name of the storage engine. Currently, the values\n <literal>InnoDB</literal> and <literal>NDB</literal> are\n supported. If not set, the value of\n <literal role=\"sysvar\">default_storage_engine</literal> is used.\n If it is not the same as the storage engine used to create the\n tablespace, the <literal>DROP TABLESPACE</literal> statement\n fails."
},
{
"para": "<literal><replaceable>tablespace_name</replaceable></literal> is a\n case-sensitive identifier in MySQL."
},
{
"para": "For an <literal>InnoDB</literal> general tablespace, all tables\n must be dropped from the tablespace prior to a <literal>DROP\n TABLESPACE</literal> operation. If the tablespace is not empty,\n <literal>DROP TABLESPACE</literal> returns an error."
},
{
"para": "An <literal>NDB</literal> tablespace to be dropped must not\n contain any data files; in other words, before you can drop an\n <literal>NDB</literal> tablespace, you must first drop each of its\n data files using\n <literal condition=\"alter-tablespace\" role=\"stmt\">ALTER TABLESPACE\n ... DROP DATAFILE</literal>."
},
{
"itemizedlist": [
[
{
"para": "A general <literal>InnoDB</literal> tablespace is not deleted\n automatically when the last table in the tablespace is\n dropped. The tablespace must be dropped explicitly using\n <literal>DROP TABLESPACE\n <replaceable>tablespace_name</replaceable></literal>."
}
],
[
{
"para": "A <literal role=\"stmt\">DROP DATABASE</literal> 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 <literal>DROP TABLESPACE\n <replaceable>tablespace_name</replaceable></literal>."
}
],
[
{
"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 <link linkend=\"glos_ibd_file\">.ibd data file</link> which can\n only be used for new <literal>InnoDB</literal> 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 <literal>InnoDB</literal>\n general tablespace. The general tablespace <literal>ts1</literal>\n is created with a single table. Before dropping the tablespace,\n the table must be dropped."
},
{
"programlisting": ">\nmysql> <userinput>CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' Engine=InnoDB;</userinput> \n\nmysql> <userinput>CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1 Engine=InnoDB;</userinput> \n\nmysql> <userinput>DROP TABLE t1;</userinput>\n\nmysql> <userinput>DROP TABLESPACE ts1;</userinput>"
},
{
"para": "This example demonstrates dropping an undo tablespace. An undo\n tablespace must be in an <literal>empty</literal> state before it\n can be dropped. For more information, see\n <xref linkend=\"innodb-undo-tablespaces\" />."
},
{
"programlisting": ">\nmysql> <userinput>DROP UNDO TABLESPACE <replaceable>undo_003</replaceable>;</userinput>"
},
{
"para": "This example shows how to drop an <literal>NDB</literal>\n tablespace <literal>myts</literal> having a data file named\n <filename>mydata-1.dat</filename> after first creating the\n tablespace, and assumes the existence of a log file group named\n <literal>mylg</literal> (see\n <xref linkend=\"create-logfile-group\" />)."
},
{
"programlisting": ">\nmysql> <userinput>CREATE TABLESPACE myts</userinput>\n -> <userinput>ADD DATAFILE 'mydata-1.dat'</userinput>\n -> <userinput>USE LOGFILE GROUP mylg</userinput>\n -> <userinput>ENGINE=NDB;</userinput>"
},
{
"para": "You must remove all data files from the tablespace using\n <literal role=\"stmt\">ALTER TABLESPACE</literal>, as shown here,\n before it can be dropped:"
},
{
"programlisting": ">\nmysql> <userinput>ALTER TABLESPACE myts</userinput>\n -> <userinput>DROP DATAFILE 'mydata-1.dat'</userinput>\n -> <userinput>ENGINE=NDB;</userinput>\n\nmysql> <userinput>DROP TABLESPACE myts;</userinput>"
}
],
"id": "DROP TABLESPACE",
"syntax": [
{
"programlisting": ">\nDROP [UNDO] TABLESPACE <replaceable>tablespace_name</replaceable>\n [ENGINE [=] <replaceable>engine_name</replaceable>]"
}
]
},
{
"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. <literal role=\"stmt\">DROP TRIGGER</literal>\n requires the <literal role=\"priv\">TRIGGER</literal> privilege for\n the table associated with the trigger."
},
{
"para": "Use <literal>IF EXISTS</literal> to prevent an error from\n occurring for a trigger that does not exist. A\n <literal>NOTE</literal> is generated for a nonexistent trigger\n when using <literal>IF EXISTS</literal>. See\n <xref linkend=\"show-warnings\" />."
},
{
"para": "Triggers for a table are also dropped if you drop the table."
}
],
"id": "DROP TRIGGER",
"syntax": [
{
"programlisting": ">\nDROP TRIGGER [IF EXISTS] [<replaceable>schema_name</replaceable>.]<replaceable>trigger_name</replaceable>"
}
]
},
{
"keywords": [
"DROP",
"VIEW",
"IF",
"EXISTS",
"RESTRICT",
"CASCADE"
],
"description": [
{
"para": "<literal role=\"stmt\">DROP VIEW</literal> removes one or more\n views. You must have the <literal role=\"priv\">DROP</literal>\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 <literal>IF EXISTS</literal> clause prevents an error from\n occurring for views that don't exist. When this clause is given, a\n <literal>NOTE</literal> is generated for each nonexistent view.\n See <xref linkend=\"show-warnings\" />."
},
{
"para": "<literal>RESTRICT</literal> and <literal>CASCADE</literal>, if\n given, are parsed and ignored."
}
],
"id": "DROP VIEW",
"syntax": [
{
"programlisting": ">\nDROP VIEW [IF EXISTS]\n <replaceable>view_name</replaceable> [, <replaceable>view_name</replaceable>] ...\n [RESTRICT | CASCADE]"
}
]
},
{
"keywords": [
"RENAME",
"TABLE"
],
"description": [
{
"para": "<literal role=\"stmt\">RENAME TABLE</literal> renames one or more\n tables. You must have <literal role=\"priv\">ALTER</literal> and\n <literal role=\"priv\">DROP</literal> privileges for the original\n table, and <literal role=\"priv\">CREATE</literal> and\n <literal role=\"priv\">INSERT</literal> privileges for the new\n table."
},
{
"para": "For example, to rename a table named <literal>old_table</literal>\n to <literal>new_table</literal>, use this statement:"
},
{
"programlisting": ">\nRENAME TABLE old_table TO new_table;"
},
{
"para": "That statement is equivalent to the following\n <literal role=\"stmt\">ALTER TABLE</literal> statement:"
},
{
"programlisting": ">\nALTER TABLE old_table RENAME new_table;"
},
{
"para": "<literal>RENAME TABLE</literal>, unlike <literal role=\"stmt\">ALTER\n TABLE</literal>, 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 <literal>tmp_table</literal> 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 <xref linkend=\"metadata-locking\" />."
},
{
"para": "As of MySQL 8.0.13, you can rename tables locked with a\n <literal role=\"stmt\">LOCK TABLES</literal> statement, provided\n that they are locked with a <literal>WRITE</literal> lock or are\n the product of renaming <literal>WRITE</literal>-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 <literal>RENAME TABLE</literal>,\n there must be no tables locked with <literal>LOCK\n TABLES</literal>."
},
{
"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 <literal>RENAME TABLE</literal>, the\n statement fails and no changes are made."
},
{
"para": "You can use <literal>RENAME TABLE</literal> to move a table from\n one database to another:"
},
{
"programlisting": ">\nRENAME TABLE <replaceable>current_db.tbl_name</replaceable> TO <replaceable>other_db.tbl_name;</replaceable>"
},
{
"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 <literal>RENAME TABLE</literal>, <literal>ALTER TABLE ...\n RENAME</literal> 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 <errortext>Trigger in wrong\n schema</errortext>\n (<literal role=\"error\">ER_TRG_IN_WRONG_SCHEMA</literal>) error."
},
{
"para": "An unencrypted table can be moved to an encryption-enabled\n database and vice versa. However, if the\n <literal role=\"sysvar\">table_encryption_privilege_check</literal>\n variable is enabled, the\n <literal role=\"priv\">TABLE_ENCRYPTION_ADMIN</literal> privilege is\n required if the table encryption setting differs from the default\n database encryption."
},
{
"para": "To rename <literal>TEMPORARY</literal> tables, <literal>RENAME\n TABLE</literal> does not work. Use <literal role=\"stmt\">ALTER\n TABLE</literal> instead."
},
{
"para": "<literal>RENAME TABLE</literal> 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": "<literal>RENAME TABLE <replaceable>tbl_name</replaceable> TO\n <replaceable>new_tbl_name</replaceable></literal> changes\n internally generated foreign key constraint names and user-defined\n foreign key constraint names that begin with the string\n <quote><replaceable>tbl_name</replaceable>_ibfk_</quote> to\n reflect the new table name. <literal>InnoDB</literal> interprets\n foreign key constraint names that begin with the string\n <quote><replaceable>tbl_name</replaceable>_ibfk_</quote> 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": "<literal>RENAME TABLE <replaceable>tbl_name</replaceable> TO\n <replaceable>new_tbl_name</replaceable></literal> changes\n internally generated and user-defined <literal>CHECK</literal>\n constraint names that begin with the string\n <quote><replaceable>tbl_name</replaceable>_chk_</quote> to reflect\n the new table name. MySQL interprets <literal>CHECK</literal>\n constraint names that begin with the string\n <quote><replaceable>tbl_name</replaceable>_chk_</quote> as\n internally generated names. Example:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW CREATE TABLE t1\\G</userinput>\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> <userinput>RENAME TABLE t1 TO t3;</userinput>\nQuery OK, 0 rows affected (0.03 sec)\n\nmysql> <userinput>SHOW CREATE TABLE t3\\G</userinput>\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 <replaceable>tbl_name</replaceable> TO <replaceable>new_tbl_name</replaceable>\n [, <replaceable>tbl_name2</replaceable> TO <replaceable>new_tbl_name2</replaceable>] ..."
}
]
},
{
"keywords": [
"TRUNCATE",
"TABLE"
],
"description": [
{
"para": "<literal role=\"stmt\">TRUNCATE TABLE</literal> empties a table\n completely. It requires the <literal role=\"priv\">DROP</literal>\n privilege. Logically, <literal role=\"stmt\">TRUNCATE\n TABLE</literal> is similar to a\n <literal role=\"stmt\">DELETE</literal> statement that deletes all\n rows, or a sequence of <literal role=\"stmt\">DROP TABLE</literal>\n and <literal role=\"stmt\">CREATE TABLE</literal> statements."
},
{
"para": "To achieve high performance, <literal role=\"stmt\">TRUNCATE\n TABLE</literal> bypasses the DML method of deleting data. Thus, it\n does not cause <literal>ON DELETE</literal> triggers to fire, it\n cannot be performed for <literal>InnoDB</literal> tables with\n parent-child foreign key relationships, and it cannot be rolled\n back like a DML operation. However, <literal>TRUNCATE\n TABLE</literal> 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 <xref linkend=\"atomic-ddl\" />."
},
{
"para": "Although <literal role=\"stmt\">TRUNCATE TABLE</literal> is similar\n to <literal role=\"stmt\">DELETE</literal>, it is classified as a\n DDL statement rather than a DML statement. It differs from\n <literal role=\"stmt\">DELETE</literal> 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 <xref linkend=\"implicit-commit\" />."
}
],
[
{
"para": "Truncation operations cannot be performed if the session holds\n an active table lock."
}
],
[
{
"para": "<literal role=\"stmt\">TRUNCATE TABLE</literal> fails for an\n <literal>InnoDB</literal> table or\n <literal role=\"se\">NDB</literal> table if there are any\n <literal>FOREIGN KEY</literal> 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 <quote>0 rows\n affected,</quote> which should be interpreted as <quote>no\n information.</quote>"
}
],
[
{
"para": "As long as the table definition is valid, the table can be\n re-created as an empty table with\n <literal role=\"stmt\">TRUNCATE TABLE</literal>, even if the\n data or index files have become corrupted."
}
],
[
{
"para": "Any <literal>AUTO_INCREMENT</literal> value is reset to its\n start value. This is true even for <literal>MyISAM</literal>\n and <literal>InnoDB</literal>, which normally do not reuse\n sequence values."
}
],
[
{
"para": "When used with partitioned tables,\n <literal role=\"stmt\">TRUNCATE TABLE</literal> 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 <literal role=\"stmt\">TRUNCATE TABLE</literal> statement\n does not invoke <literal>ON DELETE</literal> triggers."
}
],
[
{
"para": "Truncating a corrupted <literal>InnoDB</literal> table is\n supported."
}
]
]
}
],
"id": "TRUNCATE TABLE",
"syntax": [
{
"programlisting": ">\nTRUNCATE [TABLE] <replaceable>tbl_name</replaceable>"
}
]
},
{
"keywords": [
"CALL"
],
"description": [
{
"para": "The <literal role=\"stmt\">CALL</literal> statement invokes a stored\n procedure that was defined previously with\n <literal role=\"stmt\">CREATE PROCEDURE</literal>."
},
{
"para": "Stored procedures that take no arguments can be invoked without\n parentheses. That is, <literal>CALL p()</literal> and\n <literal>CALL p</literal> are equivalent."
},
{
"para": "<literal role=\"stmt\">CALL</literal> can pass back values to its\n caller using parameters that are declared as\n <literal>OUT</literal> or <literal>INOUT</literal> 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 <literal role=\"func\">ROW_COUNT()</literal> function; from the C\n API, call the\n <literal role=\"cfunc\">mysql_affected_rows()</literal> function."
},
{
"para": "For information about the effect of unhandled conditions on\n procedure parameters, see\n <xref linkend=\"conditions-and-parameters\" />."
}
],
"id": "CALL",
"syntax": [
{
"programlisting": ">\nCALL <replaceable>sp_name</replaceable>([<replaceable>parameter</replaceable>[,...]])\nCALL <replaceable>sp_name</replaceable>[()]"
}
]
},
{
"keywords": [
"DELETE",
"BY",
"ORDER",
"LIMIT",
"WHERE",
"FROM",
"USING",
"LOW_PRIORITY",
"QUICK",
"PARTITION"
],
"description": [
{
"para": "You need the <literal role=\"priv\">DELETE</literal> privilege on a\n table to delete rows from it. You need only the\n <literal role=\"priv\">SELECT</literal> privilege for any columns\n that are only read, such as those named in the\n <literal>WHERE</literal> clause."
},
{
"para": "When you do not need to know the number of deleted rows, the\n <literal role=\"stmt\">TRUNCATE TABLE</literal> statement is a\n faster way to empty a table than a\n <literal role=\"stmt\">DELETE</literal> statement with no\n <literal>WHERE</literal> clause. Unlike\n <literal role=\"stmt\">DELETE</literal>,\n <literal role=\"stmt\">TRUNCATE TABLE</literal> cannot be used\n within a transaction or if you have a lock on the table. See\n <xref linkend=\"truncate-table\" /> and\n <xref linkend=\"lock-tables\" />."
},
{
"para": "The speed of delete operations may also be affected by factors\n discussed in <xref linkend=\"delete-optimization\" />."
},
{
"para": "To ensure that a given <literal role=\"stmt\">DELETE</literal>\n statement does not take too much time, the MySQL-specific\n <literal>LIMIT <replaceable>row_count</replaceable></literal>\n clause for <literal role=\"stmt\">DELETE</literal> 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 <literal>DELETE</literal> statement until the number of affected\n rows is less than the <literal>LIMIT</literal> value."
},
{
"para": "You cannot delete from a table and select from the same table in a\n subquery."
},
{
"para": "<literal>DELETE</literal> supports explicit partition selection\n using the <literal>PARTITION</literal> 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 <literal>t</literal> with a partition named\n <literal>p0</literal>, executing the statement <literal>DELETE\n FROM t PARTITION (p0)</literal> has the same effect on the table\n as executing <literal condition=\"alter-table\" role=\"stmt\">ALTER\n TABLE t TRUNCATE PARTITION (p0)</literal>; in both cases, all rows\n in partition <literal>p0</literal> are dropped."
},
{
"para": "<literal>PARTITION</literal> can be used along with a\n <literal>WHERE</literal> condition, in which case the condition is\n tested only on rows in the listed partitions. For example,\n <literal>DELETE FROM t PARTITION (p0) WHERE c < 5</literal>\n deletes rows only from partition <literal>p0</literal> for which\n the condition <literal>c < 5</literal> is true; rows in any\n other partitions are not checked and thus not affected by the\n <literal>DELETE</literal>."
},
{
"para": "The <literal>PARTITION</literal> option can also be used in\n multiple-table <literal>DELETE</literal> statements. You can use\n up to one such option per table named in the\n <literal>FROM</literal> option."
},
{
"para": "For more information and examples, see\n <xref linkend=\"partitioning-selection\" />."
}
],
"id": "DELETE",
"syntax": [
{
"para": "<literal role=\"stmt\">DELETE</literal> is a DML statement that\n removes rows from a table."
},
{
"para": "A <literal role=\"stmt\">DELETE</literal> statement can start with a\n <literal role=\"stmt\">WITH</literal> clause to define common table\n expressions accessible within the\n <literal role=\"stmt\">DELETE</literal>. See <xref linkend=\"with\" />."
},
{
"programlisting": ">\nDELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROM <replaceable>tbl_name</replaceable> [[AS] <replaceable>tbl_alias</replaceable>]\n [PARTITION (<replaceable>partition_name</replaceable> [, <replaceable>partition_name</replaceable>] ...)]\n [WHERE <replaceable>where_condition</replaceable>]\n [ORDER BY ...]\n [LIMIT <replaceable>row_count</replaceable>]"
},
{
"para": "The <literal>DELETE</literal> statement deletes rows from\n <replaceable>tbl_name</replaceable> and returns the number of\n deleted rows. To check the number of deleted rows, call the\n <literal role=\"func\">ROW_COUNT()</literal> function described in\n <xref linkend=\"information-functions\" />."
},
{
"para": "The conditions in the optional <literal>WHERE</literal> clause\n identify which rows to delete. With no <literal>WHERE</literal>\n clause, all rows are deleted."
},
{
"para": "<replaceable>where_condition</replaceable> is an expression that\n evaluates to true for each row to be deleted. It is specified as\n described in <xref linkend=\"select\" />."
},
{
"para": "If the <literal>ORDER BY</literal> clause is specified, the rows\n are deleted in the order that is specified. The\n <literal>LIMIT</literal> 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 <replaceable>tbl_name</replaceable>[.*] [, <replaceable>tbl_name</replaceable>[.*]] ...\n FROM <replaceable>table_references</replaceable>\n [WHERE <replaceable>where_condition</replaceable>]\n\nDELETE [LOW_PRIORITY] [QUICK] [IGNORE]\n FROM <replaceable>tbl_name</replaceable>[.*] [, <replaceable>tbl_name</replaceable>[.*]] ...\n USING <replaceable>table_references</replaceable>\n [WHERE <replaceable>where_condition</replaceable>]"
}
]
},
{
"keywords": [
"DO"
],
"description": [
{
"para": "<literal role=\"stmt\">DO</literal> executes the expressions but\n does not return any results. In most respects,\n <literal role=\"stmt\">DO</literal> is shorthand for <literal>SELECT\n <replaceable>expr</replaceable>, ...</literal>, but has the\n advantage that it is slightly faster when you do not care about\n the result."
},
{
"para": "<literal role=\"stmt\">DO</literal> is useful primarily with\n functions that have side effects, such as\n <literal role=\"func\">RELEASE_LOCK()</literal>."
},
{
"para": "Example: This <literal role=\"stmt\">SELECT</literal> statement\n pauses, but also produces a result set:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT SLEEP(5);</userinput>\n+----------+\n| SLEEP(5) |\n+----------+\n| 0 |\n+----------+\n1 row in set (5.02 sec)"
},
{
"para": "<literal role=\"stmt\">DO</literal>, on the other hand, pauses\n without producing a result set.:"
},
{
"programlisting": ">\nmysql> <userinput>DO SLEEP(5);</userinput>\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": "<literal role=\"stmt\">DO</literal> only executes expressions. It\n cannot be used in all cases where <literal>SELECT</literal> can be\n used. For example, <literal>DO id FROM t1</literal> is invalid\n because it references a table."
}
],
"id": "DO",
"syntax": [
{
"programlisting": ">\nDO <replaceable>expr</replaceable> [, <replaceable>expr</replaceable>] ..."
}
]
},
{
"keywords": [
"HANDLER",
"OPEN",
"READ",
"LIMIT",
"FIRST",
"NEXT",
"PREV",
"LAST",
"WHERE",
"CLOSE"
],
"description": [
{
"para": "The <literal>HANDLER</literal> statement provides direct access to\n table storage engine interfaces. It is available for\n <literal>InnoDB</literal> and <literal>MyISAM</literal> tables."
}
],
"id": "HANDLER",
"syntax": [
{
"programlisting": ">\nHANDLER <replaceable>tbl_name</replaceable> OPEN [ [AS] <replaceable>alias</replaceable>]\n\nHANDLER <replaceable>tbl_name</replaceable> READ <replaceable>index_name</replaceable> { = | <= | >= | < | > } (<replaceable>value1</replaceable>,<replaceable>value2</replaceable>,...)\n [ WHERE <replaceable>where_condition</replaceable> ] [LIMIT ... ]\nHANDLER <replaceable>tbl_name</replaceable> READ <replaceable>index_name</replaceable> { FIRST | NEXT | PREV | LAST }\n [ WHERE <replaceable>where_condition</replaceable> ] [LIMIT ... ]\nHANDLER <replaceable>tbl_name</replaceable> READ { FIRST | NEXT }\n [ WHERE <replaceable>where_condition</replaceable> ] [LIMIT ... ]\n\nHANDLER <replaceable>tbl_name</replaceable> CLOSE"
}
]
},
{
"keywords": [
"IMPORT",
"TABLE",
"FROM"
],
"description": [
{
"para": "The <literal role=\"stmt\">IMPORT TABLE</literal> statement imports\n <literal>MyISAM</literal> tables based on information contained in\n <filename>.sdi</filename> (serialized dictionary information)\n metadata files. <literal role=\"stmt\">IMPORT TABLE</literal>\n requires the <literal role=\"priv\">FILE</literal> privilege to read\n the <filename>.sdi</filename> and table content files, and the\n <literal role=\"priv\">CREATE</literal> privilege for the table to\n be created."
},
{
"para": "Tables can be exported from one server using\n <command>mysqldump</command> to write a file of SQL statements and\n imported into another server using <command>mysql</command> to\n process the dump file. <literal role=\"stmt\">IMPORT TABLE</literal>\n provides a faster alternative using the <quote>raw</quote> 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 <filename>.sdi</filename> file must be located in a\n directory accessible to the server. For example, the\n <filename>.sdi</filename> file can be placed in the directory\n named by the <literal role=\"sysvar\">secure_file_priv</literal>\n system variable, or (if\n <literal role=\"sysvar\">secure_file_priv</literal> is empty) in a\n directory under the server data directory."
},
{
"para": "The following example describes how to export\n <literal>MyISAM</literal> tables named\n <literal>employees</literal> and <literal>managers</literal> from\n the <literal>hr</literal> schema of one server and import them\n into the <literal>hr</literal> 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 <replaceable>export_basedir</replaceable> represents its base\n directory, and its data directory is\n <filename><replaceable>export_basedir</replaceable>/data</filename>."
}
],
[
{
"para": "For the import server,\n <replaceable>import_basedir</replaceable> represents its base\n directory, and its data directory is\n <filename><replaceable>import_basedir</replaceable>/data</filename>."
}
],
[
{
"para": "Table files are exported from the export server into the\n <filename>/tmp/export</filename> directory and this directory\n is secure (not accessible to other users)."
}
],
[
{
"para": "The import server uses <filename>/tmp/mysql-files</filename>\n as the directory named by its\n <literal role=\"sysvar\">secure_file_priv</literal> 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 <filename>.sdi</filename> file need not be placed in the\n import server directory named by the\n <literal role=\"sysvar\">secure_file_priv</literal> 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 <filename>.sdi</filename> file is placed in that\n directory, however, it may be rewritten; the import operation\n creates a new <filename>.sdi</filename> file for the table, which\n will overwrite the old <filename>.sdi</filename> file if the\n operation uses the same file name for the new file."
},
{
"para": "Each <replaceable>sdi_file</replaceable> value must be a string\n literal that names the <filename>.sdi</filename> file for a table\n or is a pattern that matches <filename>.sdi</filename> files. If\n the string is a pattern, any leading directory path and the\n <filename>.sdi</filename> 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": "<literal>?</literal> matches any single character"
}
],
[
{
"para": "<literal>*</literal> matches any sequence of characters,\n including no characters"
}
]
]
},
{
"para": "Using a pattern, the previous <literal role=\"stmt\">IMPORT\n TABLE</literal> statement could have been written like this\n (assuming that the <filename>/tmp/mysql-files</filename> directory\n contains no other <filename>.sdi</filename> files matching the\n pattern):"
},
{
"programlisting": ">\nIMPORT TABLE FROM '/tmp/mysql-files/*.sdi';"
},
{
"para": "To interpret the location of <filename>.sdi</filename> file path\n names, the server uses the same rules for\n <literal role=\"stmt\">IMPORT TABLE</literal> as the server-side\n rules for <literal role=\"stmt\">LOAD DATA</literal> (that is, the\n non-<literal>LOCAL</literal> rules). See\n <xref linkend=\"load-data\" />, paying particular attention to the\n rules used to interpret relative path names."
},
{
"para": "<literal role=\"stmt\">IMPORT TABLE</literal> fails if the\n <literal>.sdi</literal> 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 <literal role=\"stmt\">REPAIR TABLE</literal>."
},
{
"para": "<literal role=\"stmt\">IMPORT TABLE</literal> is not written to the\n binary log."
}
],
"id": "IMPORT TABLE",
"syntax": [
{
"programlisting": ">\nIMPORT TABLE FROM <replaceable>sdi_file</replaceable> [, <replaceable>sdi_file</replaceable>] ..."
}
]
},
{
"keywords": [
"INSERT",
"SELECT"
],
"description": [
{
"para": "With <literal condition=\"insert-select\" role=\"stmt\">INSERT ...\n SELECT</literal>, you can quickly insert many rows into a table\n from the result of a <literal role=\"stmt\">SELECT</literal>\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] <replaceable>tbl_name</replaceable>\n [PARTITION (<replaceable>partition_name</replaceable> [, <replaceable>partition_name</replaceable>] ...)]\n [(<replaceable>col_name</replaceable> [, <replaceable>col_name</replaceable>] ...)]\n SELECT ...\n [ON DUPLICATE KEY UPDATE <replaceable>assignment_list</replaceable>]\n\n<replaceable>value</replaceable>:\n {<replaceable>expr</replaceable> | DEFAULT}\n\n<replaceable>assignment</replaceable>:\n <replaceable>col_name</replaceable> = <replaceable>value</replaceable>\n\n<replaceable>assignment_list</replaceable>:\n <replaceable>assignment</replaceable> [, <replaceable>assignment</replaceable>] ..."
}
]
},
{
"keywords": [
"INSERT",
"DELAYED"
],
"description": [
{
"para": "The <literal>DELAYED</literal> option for the\n <literal role=\"stmt\">INSERT</literal> 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 <literal>MyISAM</literal>), such that when a client uses\n <literal role=\"stmt\">INSERT DELAYED</literal>, 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": "<literal>DELAYED</literal> inserts and replaces were deprecated\n in MySQL 5.6. In MySQL current-series,\n <literal>DELAYED</literal> is not supported. The server\n recognizes but ignores the <literal>DELAYED</literal> keyword,\n handles the insert as a nondelayed insert, and generates an\n <literal>ER_WARN_LEGACY_SYNTAX_CONVERTED</literal> warning\n (<quote>INSERT DELAYED is no longer supported. The statement was\n converted to INSERT</quote>). The <literal>DELAYED</literal>\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": "<literal role=\"stmt\">INSERT</literal> inserts new rows into an\n existing table. The <literal condition=\"insert\" role=\"stmt\">INSERT\n ... VALUES</literal> and\n <literal condition=\"insert\" role=\"stmt\">INSERT ... SET</literal>\n forms of the statement insert rows based on explicitly specified\n values. The <literal condition=\"insert-select\" role=\"stmt\">INSERT\n ... SELECT</literal> form inserts rows selected from another table\n or tables. <literal role=\"stmt\">INSERT</literal> with an\n <literal>ON DUPLICATE KEY UPDATE</literal> clause enables existing\n rows to be updated if a row to be inserted would cause a duplicate\n value in a <literal>UNIQUE</literal> index or <literal>PRIMARY\n KEY</literal>."
},
{
"para": "For additional information about\n <literal condition=\"insert-select\" role=\"stmt\">INSERT ...\n SELECT</literal> and\n <literal condition=\"insert-on-duplicate\" role=\"stmt\">INSERT ... ON\n DUPLICATE KEY UPDATE</literal>, see\n <xref linkend=\"insert-select\" />, and\n <xref linkend=\"insert-on-duplicate\" />."
},
{
"para": "In MySQL current-series, the <literal>DELAYED</literal> keyword\n is accepted but ignored by the server. For the reasons for this,\n see <xref linkend=\"insert-delayed\" />,"
},
{
"para": "Inserting into a table requires the\n <literal role=\"priv\">INSERT</literal> privilege for the table. If\n the <literal>ON DUPLICATE KEY UPDATE</literal> clause is used and\n a duplicate key causes an <literal role=\"stmt\">UPDATE</literal> to\n be performed instead, the statement requires the\n <literal role=\"priv\">UPDATE</literal> privilege for the columns to\n be updated. For columns that are read but not modified you need\n only the <literal role=\"priv\">SELECT</literal> privilege (such as\n for a column referenced only on the right hand side of an\n <replaceable>col_name</replaceable>=<replaceable>expr</replaceable>\n assignment in an <literal>ON DUPLICATE KEY UPDATE</literal>\n clause)."
},
{
"para": "When inserting into a partitioned table, you can control which\n partitions and subpartitions accept new rows. The\n <literal>PARTITION</literal> 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 <literal role=\"stmt\">INSERT</literal> statement do not match\n one of the partitions listed, the\n <literal role=\"stmt\">INSERT</literal> statement fails with the\n error <errortext>Found a row not matching the given partition\n set</errortext>. For more information and examples, see\n <xref linkend=\"partitioning-selection\" />."
}
],
"id": "INSERT",
"syntax": [
{
"programlisting": ">\nINSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]\n [INTO] <replaceable>tbl_name</replaceable>\n [PARTITION (<replaceable>partition_name</replaceable> [, <replaceable>partition_name</replaceable>] ...)]\n [(<replaceable>col_name</replaceable> [, <replaceable>col_name</replaceable>] ...)]\n {VALUES | VALUE} (<replaceable>value_list</replaceable>) [, (<replaceable>value_list</replaceable>)] ...\n [ON DUPLICATE KEY UPDATE <replaceable>assignment_list</replaceable>]\n\nINSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]\n [INTO] <replaceable>tbl_name</replaceable>\n [PARTITION (<replaceable>partition_name</replaceable> [, <replaceable>partition_name</replaceable>] ...)]\n SET <replaceable>assignment_list</replaceable>\n [ON DUPLICATE KEY UPDATE <replaceable>assignment_list</replaceable>]\n\nINSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE]\n [INTO] <replaceable>tbl_name</replaceable>\n [PARTITION (<replaceable>partition_name</replaceable> [, <replaceable>partition_name</replaceable>] ...)]\n [(<replaceable>col_name</replaceable> [, <replaceable>col_name</replaceable>] ...)]\n SELECT ...\n [ON DUPLICATE KEY UPDATE <replaceable>assignment_list</replaceable>]\n\n<replaceable>value</replaceable>:\n {<replaceable>expr</replaceable> | DEFAULT}\n\n<replaceable>value_list</replaceable>:\n <replaceable>value</replaceable> [, <replaceable>value</replaceable>] ...\n\n<replaceable>assignment</replaceable>:\n <replaceable>col_name</replaceable> = <replaceable>value</replaceable>\n\n<replaceable>assignment_list</replaceable>:\n <replaceable>assignment</replaceable> [, <replaceable>assignment</replaceable>] ..."
}
]
},
{
"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 <literal role=\"stmt\">LOAD DATA</literal> statement reads rows\n from a text file into a table at a very high speed.\n <literal role=\"stmt\">LOAD DATA</literal> is the complement of\n <literal condition=\"select-into\" role=\"stmt\">SELECT ... INTO\n OUTFILE</literal>. (See <xref linkend=\"select-into\" />.) To write\n data from a table to a file, use\n <literal condition=\"select-into\" role=\"stmt\">SELECT ... INTO\n OUTFILE</literal>. To read the file back into a table, use\n <literal role=\"stmt\">LOAD DATA</literal>. The syntax of the\n <literal>FIELDS</literal> and <literal>LINES</literal> clauses is\n the same for both statements."
},
{
"para": "You can also load data files by using the\n <command>mysqlimport</command> utility; see\n <xref linkend=\"mysqlimport\" />. <command>mysqlimport</command>\n operates by sending a <literal role=\"stmt\">LOAD DATA</literal>\n statement to the server."
},
{
"para": "For more information about the efficiency of\n <literal role=\"stmt\">INSERT</literal> versus\n <literal role=\"stmt\">LOAD DATA</literal> and speeding up\n <literal role=\"stmt\">LOAD DATA</literal>, see\n <xref linkend=\"insert-optimization\" />."
}
],
"id": "LOAD DATA",
"syntax": [
{
"programlisting": ">\nLOAD DATA\n [LOW_PRIORITY | CONCURRENT] [LOCAL]\n INFILE '<replaceable>file_name</replaceable>'\n [REPLACE | IGNORE]\n INTO TABLE <replaceable>tbl_name</replaceable>\n [PARTITION (<replaceable>partition_name</replaceable> [, <replaceable>partition_name</replaceable>] ...)]\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [{FIELDS | COLUMNS}\n [TERMINATED BY '<replaceable>string</replaceable>']\n [[OPTIONALLY] ENCLOSED BY '<replaceable>char</replaceable>']\n [ESCAPED BY '<replaceable>char</replaceable>']\n ]\n [LINES\n [STARTING BY '<replaceable>string</replaceable>']\n [TERMINATED BY '<replaceable>string</replaceable>']\n ]\n [IGNORE <replaceable>number</replaceable> {LINES | ROWS}]\n [(<replaceable>col_name_or_user_var</replaceable>\n [, <replaceable>col_name_or_user_var</replaceable>] ...)]\n [SET <replaceable>col_name</replaceable>={<replaceable>expr</replaceable> | DEFAULT},\n [, <replaceable>col_name</replaceable>={<replaceable>expr</replaceable> | DEFAULT}] ...]"
}
]
},
{
"keywords": [
"LOW_PRIORITY",
"CONCURRENT",
"LOCAL",
"INFILE",
"REPLACE",
"IGNORE",
"CHARACTER",
"SET",
"ROWS",
"IDENTIFIED",
"BY",
"LINES"
],
"description": [
{
"para": "The <literal role=\"stmt\">LOAD XML</literal> statement reads data\n from an XML file into a table. The\n <replaceable>file_name</replaceable> must be given as a literal\n string. The <replaceable>tagname</replaceable> in the optional\n <literal>ROWS IDENTIFIED BY</literal> clause must also be given as\n a literal string, and must be surrounded by angle brackets\n (<literal><</literal> and <literal>></literal>)."
},
{
"para": "<literal role=\"stmt\">LOAD XML</literal> acts as the complement of\n running the <command>mysql</command> client in XML output mode\n (that is, starting the client with the\n <option role=\"mysql\">--xml</option> option). To write data from a\n table to an XML file, you can invoke the <command>mysql</command>\n client with the <option role=\"mysql\">--xml</option> and\n <option condition=\"execute\" role=\"mysql\">-e</option> options from\n the system shell, as shown here:"
},
{
"programlisting": ">\nshell> <userinput>mysql --xml -e 'SELECT * FROM mydb.mytable' > file.xml</userinput>"
},
{
"para": "To read the file back into a table, use <literal role=\"stmt\">LOAD\n XML</literal>. By default, the <literal><row></literal>\n element is considered to be the equivalent of a database table\n row; this can be changed using the <literal>ROWS IDENTIFIED\n BY</literal> clause."
},
{
"para": "This statement supports three different XML formats:"
},
{
"itemizedlist": [
[
{
"para": "Column names as attributes and column values as attribute\n values:"
},
{
"programlisting": ">\n<<replaceable>row</replaceable> <replaceable>column1</replaceable>=\"<replaceable>value1</replaceable>\" <replaceable>column2</replaceable>=\"<replaceable>value2</replaceable>\" .../>"
}
],
[
{
"para": "Column names as tags and column values as the content of these\n tags:"
},
{
"programlisting": ">\n<<replaceable>row</replaceable>>\n <<replaceable>column1</replaceable>><replaceable>value1</replaceable></<replaceable>column1</replaceable>>\n <<replaceable>column2</replaceable>><replaceable>value2</replaceable></<replaceable>column2</replaceable>>\n</<replaceable>row</replaceable>>"
}
],
[
{
"para": "Column names are the <literal>name</literal> attributes of\n <literal><field></literal> tags, and values are the\n contents of these tags:"
},
{
"programlisting": ">\n<row>\n <field name='<replaceable>column1</replaceable>'><replaceable>value1</replaceable></field>\n <field name='<replaceable>column2</replaceable>'><replaceable>value2</replaceable></field>\n</row>"
},
{
"para": "This is the format used by other MySQL tools, such as\n <command>mysqldump</command>."
}
]
]
},
{
"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 <literal role=\"stmt\">LOAD XML</literal> as they do for\n <literal role=\"stmt\">LOAD DATA</literal>:"
},
{
"itemizedlist": [
[
{
"para": "<literal>LOW_PRIORITY</literal> or\n <literal>CONCURRENT</literal>"
}
],
[
{
"para": "<literal>LOCAL</literal>"
}
],
[
{
"para": "<literal>REPLACE</literal> or <literal>IGNORE</literal>"
}
],
[
{
"para": "<literal>CHARACTER SET</literal>"
}
],
[
{
"para": "<literal>SET</literal>"
}
]
]
},
{
"para": "See <xref linkend=\"load-data\" />, for more information about these\n clauses."
},
{
"para": "<literal>(<replaceable>field_name_or_user_var</replaceable>,\n ...)</literal> 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 <literal>@</literal>. 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 <literal>IGNORE <replaceable>number</replaceable>\n LINES</literal> or <literal>IGNORE\n <replaceable>number</replaceable> ROWS</literal> clause causes the\n first <replaceable>number</replaceable> rows in the XML file to be\n skipped. It is analogous to the <literal role=\"stmt\">LOAD\n DATA</literal> statement's <literal>IGNORE ... LINES</literal>\n clause."
}
],
"id": "LOAD XML",
"syntax": [
{
"programlisting": ">\nLOAD XML\n [LOW_PRIORITY | CONCURRENT] [LOCAL]\n INFILE '<replaceable>file_name</replaceable>'\n [REPLACE | IGNORE]\n INTO TABLE [<replaceable>db_name</replaceable>.]<replaceable>tbl_name</replaceable>\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n [ROWS IDENTIFIED BY '<<replaceable>tagname</replaceable>>']\n [IGNORE <replaceable>number</replaceable> {LINES | ROWS}]\n [(<replaceable>field_name_or_user_var</replaceable>\n [, <replaceable>field_name_or_user_var</replaceable>] ...)]\n [SET <replaceable>col_name</replaceable>={<replaceable>expr</replaceable> | DEFAULT},\n [, <replaceable>col_name</replaceable>={<replaceable>expr</replaceable> | DEFAULT}] ...]"
}
]
},
{
"keywords": [
"REPLACE",
"DELAYED",
"LOW_PRIORITY",
"INTO",
"PARTITION",
"VALUES",
"VALUE",
"SELECT",
"SET",
"DEFAULT"
],
"description": [
{
"para": "<literal role=\"stmt\">REPLACE</literal> works exactly like\n <literal role=\"stmt\">INSERT</literal>, except that if an old row\n in the table has the same value as a new row for a\n <literal>PRIMARY KEY</literal> or a <literal>UNIQUE</literal>\n index, the old row is deleted before the new row is inserted. See\n <xref linkend=\"insert\" />."
},
{
"para": "<literal role=\"stmt\">REPLACE</literal> is a MySQL extension to the\n SQL standard. It either inserts, or <emphasis>deletes</emphasis>\n and inserts. For another MySQL extension to standard\n SQLmdashthat either inserts or\n <emphasis>updates</emphasis>mdashsee\n <xref linkend=\"insert-on-duplicate\" />."
},
{
"para": "<literal>DELAYED</literal> inserts and replaces were deprecated in\n MySQL 5.6. In MySQL current-series, <literal>DELAYED</literal>\n is not supported. The server recognizes but ignores the\n <literal>DELAYED</literal> keyword, handles the replace as a\n nondelayed replace, and generates an\n <literal>ER_WARN_LEGACY_SYNTAX_CONVERTED</literal> warning.\n (<quote>REPLACE DELAYED is no longer supported. The statement was\n converted to REPLACE.</quote>) The <literal>DELAYED</literal>\n keyword will be removed in a future release."
},
{
"para": "Values for all columns are taken from the values specified in the\n <literal role=\"stmt\">REPLACE</literal> statement. Any missing\n columns are set to their default values, just as happens for\n <literal role=\"stmt\">INSERT</literal>. 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 <literal>SET\n <replaceable>col_name</replaceable> =\n <replaceable>col_name</replaceable> + 1</literal>, the reference\n to the column name on the right hand side is treated as\n <literal role=\"func\">DEFAULT(<replaceable>col_name</replaceable>)</literal>,\n so the assignment is equivalent to <literal>SET\n <replaceable>col_name</replaceable> =\n DEFAULT(<replaceable>col_name</replaceable>) + 1</literal>."
},
{
"para": "To use <literal role=\"stmt\">REPLACE</literal>, you must have both\n the <literal role=\"priv\">INSERT</literal> and\n <literal role=\"priv\">DELETE</literal> privileges for the table."
},
{
"para": "If a generated column is replaced explicitly, the only permitted\n value is <literal>DEFAULT</literal>. For information about\n generated columns, see\n <xref linkend=\"create-table-generated-columns\" />."
},
{
"para": "<literal>REPLACE</literal> supports explicit partition selection\n using the <literal>PARTITION</literal> keyword with a list of\n comma-separated names of partitions, subpartitions, or both. As\n with <literal role=\"stmt\">INSERT</literal>, if it is not possible\n to insert the new row into any of these partitions or\n subpartitions, the <literal>REPLACE</literal> statement fails with\n the error <errortext>Found a row not matching the given partition\n set</errortext>. For more information and examples, see\n <xref linkend=\"partitioning-selection\" />."
}
],
"id": "REPLACE",
"syntax": [
{
"programlisting": ">\nREPLACE [LOW_PRIORITY | DELAYED]\n [INTO] <replaceable>tbl_name</replaceable>\n [PARTITION (<replaceable>partition_name</replaceable> [, <replaceable>partition_name</replaceable>] ...)]\n [(<replaceable>col_name</replaceable> [, <replaceable>col_name</replaceable>] ...)]\n {VALUES | VALUE} (<replaceable>value_list</replaceable>) [, (<replaceable>value_list</replaceable>)] ...\n\nREPLACE [LOW_PRIORITY | DELAYED]\n [INTO] <replaceable>tbl_name</replaceable>\n [PARTITION (<replaceable>partition_name</replaceable> [, <replaceable>partition_name</replaceable>] ...)]\n SET <replaceable>assignment_list</replaceable>\n\nREPLACE [LOW_PRIORITY | DELAYED]\n [INTO] <replaceable>tbl_name</replaceable>\n [PARTITION (<replaceable>partition_name</replaceable> [, <replaceable>partition_name</replaceable>] ...)]\n [(<replaceable>col_name</replaceable> [, <replaceable>col_name</replaceable>] ...)]\n SELECT ...\n\n<replaceable>value</replaceable>:\n {<replaceable>expr</replaceable> | DEFAULT}\n\n<replaceable>value_list</replaceable>:\n <replaceable>value</replaceable> [, <replaceable>value</replaceable>] ...\n\n<replaceable>assignment</replaceable>:\n <replaceable>col_name</replaceable> = <replaceable>value</replaceable>\n\n<replaceable>assignment_list</replaceable>:\n <replaceable>assignment</replaceable> [, <replaceable>assignment</replaceable>] ..."
}
]
},
{
"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": "<literal role=\"stmt\">SELECT</literal> is used to retrieve rows\n selected from one or more tables, and can include\n <literal role=\"stmt\">UNION</literal> statements and subqueries.\n See <xref linkend=\"union\" />, and <xref linkend=\"subqueries\" />. A\n <literal role=\"stmt\">SELECT</literal> statement can start with a\n <literal role=\"stmt\">WITH</literal> clause to define common table\n expressions accessible within the\n <literal role=\"stmt\">SELECT</literal>. See <xref linkend=\"with\" />."
},
{
"para": "The most commonly used clauses of\n <literal role=\"stmt\">SELECT</literal> statements are these:"
},
{
"itemizedlist": [
[
{
"para": "Each <replaceable>select_expr</replaceable> indicates a column\n that you want to retrieve. There must be at least one\n <replaceable>select_expr</replaceable>."
}
],
[
{
"para": "<replaceable>table_references</replaceable> indicates the\n table or tables from which to retrieve rows. Its syntax is\n described in <xref linkend=\"join\" />."
}
],
[
{
"para": "<literal>SELECT</literal> supports explicit partition\n selection using the <literal>PARTITION</literal> with a list\n of partitions or subpartitions (or both) following the name of\n the table in a <replaceable>table_reference</replaceable> (see\n <xref linkend=\"join\" />). 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 <xref linkend=\"partitioning-selection\" />."
},
{
"para": "<literal>SELECT ... PARTITION</literal> from tables using\n storage engines such as <literal role=\"se\">MyISAM</literal>\n that perform table-level locks (and thus partition locks) lock\n only the partitions or subpartitions named by the\n <literal>PARTITION</literal> option."
},
{
"para": "For more information, see\n <xref linkend=\"partitioning-limitations-locking\" />."
}
],
[
{
"para": "The <literal>WHERE</literal> clause, if given, indicates the\n condition or conditions that rows must satisfy to be selected.\n <replaceable>where_condition</replaceable> 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 <literal>WHERE</literal> clause."
},
{
"para": "In the <literal>WHERE</literal> expression, you can use any of\n the functions and operators that MySQL supports, except for\n aggregate (summary) functions. See\n <xref linkend=\"expressions\" />, and\n <xref linkend=\"functions\" />."
}
]
]
},
{
"para": "<literal role=\"stmt\">SELECT</literal> 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 <replaceable>select_expr</replaceable> [, <replaceable>select_expr</replaceable> ...]\n [FROM <replaceable>table_references</replaceable>\n [PARTITION <replaceable>partition_list</replaceable>]\n [WHERE <replaceable>where_condition</replaceable>]\n [GROUP BY {<replaceable>col_name</replaceable> | <replaceable>expr</replaceable> | <replaceable>position</replaceable>}, ... [WITH ROLLUP]]\n [HAVING <replaceable>where_condition</replaceable>]\n [WINDOW <replaceable>window_name</replaceable> AS (<replaceable>window_spec</replaceable>)\n [, <replaceable>window_name</replaceable> AS (<replaceable>window_spec</replaceable>)] ...]\n [ORDER BY {<replaceable>col_name</replaceable> | <replaceable>expr</replaceable> | <replaceable>position</replaceable>}\n [ASC | DESC], ... [WITH ROLLUP]]\n [LIMIT {[<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable> | <replaceable>row_count</replaceable> OFFSET <replaceable>offset</replaceable>}]\n [INTO OUTFILE '<replaceable>file_name</replaceable>'\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n <replaceable>export_options</replaceable>\n | INTO DUMPFILE '<replaceable>file_name</replaceable>'\n | INTO <replaceable>var_name</replaceable> [, <replaceable>var_name</replaceable>]]\n [FOR {UPDATE | SHARE} [OF <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ...] [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 <literal>JOIN</literal> syntax for\n the <replaceable>table_references</replaceable> part of\n <literal role=\"stmt\">SELECT</literal> statements and\n multiple-table <literal role=\"stmt\">DELETE</literal> and\n <literal role=\"stmt\">UPDATE</literal> statements:"
},
{
"programlisting": ">\n<replaceable>table_references:</replaceable>\n <replaceable>escaped_table_reference</replaceable> [, <replaceable>escaped_table_reference</replaceable>] ...\n\n<replaceable>escaped_table_reference</replaceable>:\n <replaceable>table_reference</replaceable>\n | { OJ <replaceable>table_reference</replaceable> }\n\n<replaceable>table_reference</replaceable>:\n <replaceable>table_factor</replaceable>\n | <replaceable>joined_table</replaceable>\n\n<replaceable>table_factor</replaceable>:\n <replaceable>tbl_name</replaceable> [PARTITION (<replaceable>partition_names</replaceable>)]\n [[AS] <replaceable>alias</replaceable>] [<replaceable>index_hint_list</replaceable>]\n | <replaceable>table_subquery</replaceable> [AS] <replaceable>alias</replaceable> [(<replaceable>col_list</replaceable>)]\n | ( <replaceable>table_references</replaceable> )\n\n<replaceable>joined_table</replaceable>:\n <replaceable>table_reference</replaceable> {[INNER | CROSS] JOIN | STRAIGHT_JOIN} <replaceable>table_factor</replaceable> [<replaceable>join_specification</replaceable>]\n | <replaceable>table_reference</replaceable> {LEFT|RIGHT} [OUTER] JOIN <replaceable>table_reference</replaceable> <replaceable>join_specification</replaceable>\n | <replaceable>table_reference</replaceable> NATURAL [INNER | {LEFT|RIGHT} [OUTER]] JOIN <replaceable>table_factor</replaceable>\n\n<replaceable>join_specification</replaceable>:\n ON <replaceable>search_condition</replaceable>\n | USING (<replaceable>join_column_list</replaceable>)\n\n<replaceable>join_column_list</replaceable>:\n <replaceable>column_name</replaceable> [, <replaceable>column_name</replaceable>] ...\n\n<replaceable>index_hint_list</replaceable>:\n <replaceable>index_hint</replaceable> [, <replaceable>index_hint</replaceable>] ...\n\n<replaceable>index_hint</replaceable>:\n USE {INDEX|KEY}\n [FOR {JOIN|ORDER BY|GROUP BY}] ([<replaceable>index_list</replaceable>])\n | {IGNORE|FORCE} {INDEX|KEY}\n [FOR {JOIN|ORDER BY|GROUP BY}] (<replaceable>index_list</replaceable>)\n\n<replaceable>index_list</replaceable>:\n <replaceable>index_name</replaceable> [, <replaceable>index_name</replaceable>] ..."
},
{
"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 <literal>PARTITION</literal> 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 <xref linkend=\"partitioning-selection\" />."
},
{
"para": "The syntax of <replaceable>table_factor</replaceable> is\n extended in MySQL in comparison with standard SQL. The standard\n accepts only <replaceable>table_reference</replaceable>, 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 <replaceable>table_reference</replaceable> 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, <literal>JOIN</literal>, <literal>CROSS\n JOIN</literal>, and <literal>INNER JOIN</literal> are syntactic\n equivalents (they can replace each other). In standard SQL, they\n are not equivalent. <literal>INNER JOIN</literal> is used with\n an <literal>ON</literal> clause, <literal>CROSS JOIN</literal>\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 <xref linkend=\"nested-join-optimization\" />."
},
{
"para": "Index hints can be specified to affect how the MySQL optimizer\n makes use of indexes. For more information, see\n <xref linkend=\"index-hints\" />. Optimizer hints and the\n <literal>optimizer_switch</literal> system variable are other\n ways to influence optimizer use of indexes. See\n <xref linkend=\"optimizer-hints\" />, and\n <xref linkend=\"switchable-optimizations\" />."
}
],
"id": "JOIN",
"syntax": []
},
{
"keywords": [
"UNION",
"ALL",
"DISTINCT"
],
"description": [
{
"para": "<literal role=\"stmt\">UNION</literal> is used to combine the\n result from multiple <literal role=\"stmt\">SELECT</literal>\n statements into a single result set."
},
{
"para": "The column names from the first\n <literal role=\"stmt\">SELECT</literal> statement are used as the\n column names for the results returned. Selected columns listed\n in corresponding positions of each\n <literal role=\"stmt\">SELECT</literal> 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": "<indexterm>\n <primary>DUAL</primary>\n </indexterm>\n\n You are permitted to specify <literal>DUAL</literal> as a dummy\n table name in situations where no tables are referenced:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT 1 + 1 FROM DUAL;</userinput>\n -> 2"
},
{
"para": "<literal>DUAL</literal> is purely for the convenience of people\n who require that all <literal role=\"stmt\">SELECT</literal>\n statements should have <literal>FROM</literal> and possibly other\n clauses. MySQL may ignore the clauses. MySQL does not require\n <literal>FROM DUAL</literal> 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 <replaceable>select_expr</replaceable> [, <replaceable>select_expr</replaceable> ...]\n [FROM <replaceable>table_references</replaceable>\n [PARTITION <replaceable>partition_list</replaceable>]\n [WHERE <replaceable>where_condition</replaceable>]\n [GROUP BY {<replaceable>col_name</replaceable> | <replaceable>expr</replaceable> | <replaceable>position</replaceable>}, ... [WITH ROLLUP]]\n [HAVING <replaceable>where_condition</replaceable>]\n [WINDOW <replaceable>window_name</replaceable> AS (<replaceable>window_spec</replaceable>)\n [, <replaceable>window_name</replaceable> AS (<replaceable>window_spec</replaceable>)] ...]\n [ORDER BY {<replaceable>col_name</replaceable> | <replaceable>expr</replaceable> | <replaceable>position</replaceable>}\n [ASC | DESC], ... [WITH ROLLUP]]\n [LIMIT {[<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable> | <replaceable>row_count</replaceable> OFFSET <replaceable>offset</replaceable>}]\n [INTO OUTFILE '<replaceable>file_name</replaceable>'\n [CHARACTER SET <replaceable>charset_name</replaceable>]\n <replaceable>export_options</replaceable>\n | INTO DUMPFILE '<replaceable>file_name</replaceable>'\n | INTO <replaceable>var_name</replaceable> [, <replaceable>var_name</replaceable>]]\n [FOR {UPDATE | SHARE} [OF <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ...] [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 <literal role=\"stmt\">UPDATE</literal> statement updates columns of\n existing rows in the named table with new values. The\n <literal>SET</literal> 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 <literal>DEFAULT</literal> to set a\n column explicitly to its default value. The\n <literal>WHERE</literal> clause, if given, specifies the\n conditions that identify which rows to update. With no\n <literal>WHERE</literal> clause, all rows are updated. If the\n <literal>ORDER BY</literal> clause is specified, the rows are\n updated in the order that is specified. The\n <literal>LIMIT</literal> clause places a limit on the number of\n rows that can be updated."
},
{
"para": "For the multiple-table syntax,\n <literal role=\"stmt\">UPDATE</literal> updates rows in each table\n named in <replaceable>table_references</replaceable> 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 <literal>ORDER BY</literal> and <literal>LIMIT</literal> 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 <literal>PARTITION</literal> 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 <replaceable>where_condition</replaceable> or not."
},
{
"para": "For more information and examples, see\n <xref linkend=\"partitioning-selection\" />."
},
{
"para": "<replaceable>where_condition</replaceable> is an expression that\n evaluates to true for each row to be updated. For expression\n syntax, see <xref linkend=\"expressions\" />."
},
{
"para": "<replaceable>table_references</replaceable> and\n <replaceable>where_condition</replaceable> are specified as\n described in <xref linkend=\"select\" />."
},
{
"para": "You need the <literal role=\"priv\">UPDATE</literal> privilege only\n for columns referenced in an <literal role=\"stmt\">UPDATE</literal>\n that are actually updated. You need only the\n <literal role=\"priv\">SELECT</literal> privilege for any columns\n that are read but not modified."
},
{
"para": "The <literal role=\"stmt\">UPDATE</literal> statement supports the\n following modifiers:"
},
{
"itemizedlist": [
[
{
"para": "With the <literal>LOW_PRIORITY</literal> modifier, execution\n of the <literal role=\"stmt\">UPDATE</literal> 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 <literal>MyISAM</literal>, <literal>MEMORY</literal>, and\n <literal>MERGE</literal>)."
},
{
"indexterm": "<primary>LOW_PRIORITY</primary>\n <secondary>UPDATE modifier</secondary>"
}
],
[
{
"para": "With the <literal>IGNORE</literal> 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 <xref linkend=\"ignore-strict-comparison\" />."
},
{
"indexterm": "<primary>IGNORE</primary>\n <secondary>UPDATE modifier</secondary>"
}
]
]
}
],
"id": "UPDATE",
"syntax": [
{
"para": "<literal role=\"stmt\">UPDATE</literal> is a DML statement that\n modifies rows in a table."
},
{
"para": "An <literal role=\"stmt\">UPDATE</literal> statement can start with\n a <literal role=\"stmt\">WITH</literal> clause to define common\n table expressions accessible within the\n <literal role=\"stmt\">UPDATE</literal>. See <xref linkend=\"with\" />."
},
{
"para": "Single-table syntax:"
},
{
"programlisting": ">\nUPDATE [LOW_PRIORITY] [IGNORE] <replaceable>table_reference</replaceable>\n SET <replaceable>assignment_list</replaceable>\n [WHERE <replaceable>where_condition</replaceable>]\n [ORDER BY ...]\n [LIMIT <replaceable>row_count</replaceable>]\n\n<replaceable>value</replaceable>:\n {<replaceable>expr</replaceable> | DEFAULT}\n\n<replaceable>assignment</replaceable>:\n <replaceable>col_name</replaceable> = <replaceable>value</replaceable>\n\n<replaceable>assignment_list</replaceable>:\n <replaceable>assignment</replaceable> [, <replaceable>assignment</replaceable>] ..."
},
{
"para": "Multiple-table syntax:"
},
{
"programlisting": ">\nUPDATE [LOW_PRIORITY] [IGNORE] <replaceable>table_references</replaceable>\n SET <replaceable>assignment_list</replaceable>\n [WHERE <replaceable>where_condition</replaceable>]"
}
]
},
{
"keywords": [
"PREPARE"
],
"description": [
{
"para": "The <literal role=\"stmt\">PREPARE</literal> statement prepares a\n SQL statement and assigns it a name,\n <replaceable>stmt_name</replaceable>, by which to refer to the\n statement later. The prepared statement is executed with\n <literal role=\"stmt\">EXECUTE</literal> and released with\n <literal role=\"stmt\">DEALLOCATE PREPARE</literal>. For examples,\n see <xref linkend=\"sql-prepared-statements\" />."
},
{
"para": "Statement names are not case-sensitive.\n <replaceable>preparable_stmt</replaceable> 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, <literal>?</literal>\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 <literal>?</literal> 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 <xref linkend=\"c-api-auto-reconnect\" />."
}
],
[
{
"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 <xref linkend=\"user-variables\" />."
}
]
]
}
],
"id": "PREPARE",
"syntax": [
{
"programlisting": ">\nPREPARE <replaceable>stmt_name</replaceable> FROM <replaceable>preparable_stmt</replaceable>"
}
]
},
{
"keywords": [
"EXECUTE",
"USING"
],
"description": [
{
"para": "After preparing a statement with\n <literal role=\"stmt\">PREPARE</literal>, you execute it with an\n <literal role=\"stmt\">EXECUTE</literal> statement that refers to\n the prepared statement name. If the prepared statement contains\n any parameter markers, you must supply a <literal>USING</literal>\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 <literal>USING</literal> 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 <replaceable>stmt_name</replaceable>\n [USING @<replaceable>var_name</replaceable> [, @<replaceable>var_name</replaceable>] ...]"
}
]
},
{
"keywords": [
"DEALLOCATE",
"PREPARE",
"DROP"
],
"description": [
{
"para": "To deallocate a prepared statement produced with\n <literal role=\"stmt\">PREPARE</literal>, use a\n <literal role=\"stmt\">DEALLOCATE PREPARE</literal> 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 <literal>DEALLOCATE PREPARE</literal> statement or the\n end of the session, you might encounter the upper limit enforced\n by the <literal role=\"sysvar\">max_prepared_stmt_count</literal>\n system variable."
}
],
"id": "DEALLOCATE PREPARE",
"syntax": [
{
"programlisting": ">\n{DEALLOCATE | DROP} PREPARE <replaceable>stmt_name</replaceable>"
}
]
},
{
"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 <xref linkend=\"binary-log\" />)."
},
{
"para": "The <literal role=\"stmt\">PURGE BINARY LOGS</literal> 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 <literal>BINARY</literal> and <literal>MASTER</literal> 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": "<literal role=\"stmt\">PURGE BINARY LOGS</literal> requires the\n <literal role=\"priv\">BINLOG_ADMIN</literal> privilege. This\n statement has no effect if the server was not started with the\n <option role=\"mysqld\">--log-bin</option> option to enable binary\n logging."
}
],
"id": "PURGE BINARY LOGS",
"syntax": [
{
"programlisting": ">\nPURGE { BINARY | MASTER } LOGS {\n TO '<replaceable>log_name</replaceable>'\n | BEFORE <replaceable>datetime_expr</replaceable>\n}"
}
]
},
{
"keywords": [
"RESET",
"MASTER"
],
"description": [
{
"para": "<literal role=\"stmt\">RESET MASTER</literal> requires the\n <literal role=\"priv\">RELOAD</literal> privilege."
},
{
"para": "For a server where binary logging is enabled\n (<literal role=\"sysvar\">log_bin</literal> is\n <literal>ON</literal>), <literal>RESET MASTER</literal> 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 (<literal role=\"sysvar\">gtid_mode</literal> is\n <literal>ON</literal>), issuing <literal>RESET MASTER</literal>\n resets the GTID execution history. The value of the\n <literal role=\"sysvar\">gtid_purged</literal> system variable is\n set to an empty string (<literal>''</literal>), the global value\n (but not the session value) of the\n <literal role=\"sysvar\">gtid_executed</literal> system variable\n is set to an empty string, and the\n <literal>mysql.gtid_executed</literal> table is cleared (see\n <xref linkend=\"replication-gtids-gtid-executed-table\" />). If the\n GTID-enabled server has binary logging enabled,\n <literal role=\"stmt\">RESET MASTER</literal> also resets the\n binary log as described above. Note that\n <literal role=\"stmt\">RESET MASTER</literal> 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 <literal role=\"stmt\">RESET SLAVE</literal> has no effect on the\n GTID execution history. For more information on resetting the\n GTID execution history, see\n <xref linkend=\"replication-gtids-execution-history\" />."
},
{
"para": "Issuing <literal>RESET MASTER</literal> without the optional\n <literal>TO</literal> 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 <literal>1</literal>. Use the optional <literal>TO</literal>\n clause to start the binary log file index from a number other\n than <literal>1</literal> after the reset."
},
{
"para": "Using <literal>RESET MASTER</literal> with the\n <literal>TO</literal> clause to specify a binary log file index\n number to start from simplifies failover by providing a single\n statement alternative to the <literal role=\"stmt\">FLUSH BINARY\n LOGS</literal> and\n <literal condition=\"purge-binary-logs\" role=\"stmt\">PURGE BINARY\n LOGS TO</literal> 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 <literal role=\"stmt\">RESET MASTER</literal> statement with or\n without the <literal>TO</literal> clause. If you do not correct\n a value that is out of range, the server cannot be restarted."
},
{
"para": "The following example demonstrates <literal>TO</literal> 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 <replaceable>binary_log_file_index_number</replaceable>]"
}
]
},
{
"keywords": [
"SET",
"SQL_LOG_BIN"
],
"description": [
{
"para": "The <literal role=\"sysvar\">sql_log_bin</literal> 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 <literal>ON</literal>. To disable\n or enable binary logging for the current session, set the\n session <literal role=\"sysvar\">sql_log_bin</literal> variable to\n <literal>OFF</literal> or <literal>ON</literal>."
},
{
"para": "Set this variable to <literal>OFF</literal> 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 <xref linkend=\"system-variable-privileges\" />."
},
{
"para": "It is not possible to set the session value of\n <literal role=\"sysvar\">sql_log_bin</literal> within a\n transaction or subquery."
},
{
"para": "<emphasis>Setting this variable to <literal>OFF</literal>\n prevents new GTIDs from being assigned to transactions in the\n binary log</emphasis>. 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": "<command>mysqldump</command> adds a <literal>SET\n @@SESSION.sql_log_bin=0</literal> 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": "<literal role=\"stmt\">CHANGE MASTER TO</literal> 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 <xref linkend=\"slave-logs\" />). <literal role=\"stmt\">CHANGE\n MASTER TO</literal> requires the\n <literal role=\"priv\">REPLICATION_SLAVE_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "You can issue <literal>CHANGE MASTER TO</literal> 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 <literal role=\"sysvar\">slave_parallel_workers</literal> is\n greater than 0), stopping the slave can cause\n <quote>gaps</quote> 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 <literal role=\"stmt\">CHANGE MASTER TO</literal>\n fails. The solution in this situation is to issue\n <literal condition=\"start-slave\" role=\"stmt\">START SLAVE UNTIL\n SQL_AFTER_MTS_GAPS</literal> which ensures that the gaps are\n closed."
},
{
"para": "The optional <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause enables you\n to name which replication channel the statement applies to.\n Providing a <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause applies the\n <literal>CHANGE MASTER TO</literal> 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 <literal>CHANGE\n MASTER TO</literal> statement does not name a channel using a\n <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause, an error\n occurs. See <xref linkend=\"replication-channels\" /> 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": "<literal>MASTER_HOST</literal>, <literal>MASTER_USER</literal>,\n <literal>MASTER_PASSWORD</literal>, and\n <literal>MASTER_PORT</literal> provide information to the slave\n about how to connect to its master:"
},
{
"itemizedlist": [
[
{
"para": "<literal>MASTER_HOST</literal> and\n <literal>MASTER_PORT</literal> are the host name (or IP\n address) of the master host and its TCP/IP port."
},
{
"note": "<para>\n Replication cannot use Unix socket files. You must be able\n to connect to the master MySQL server using TCP/IP.\n </para>"
},
{
"para": "If you specify the <literal>MASTER_HOST</literal> or\n <literal>MASTER_PORT</literal> 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 <literal>MASTER_LOG_FILE</literal> and\n <literal>MASTER_LOG_POS</literal> in the statement,\n <literal>MASTER_LOG_FILE=''</literal> and\n <literal>MASTER_LOG_POS=4</literal> are silently appended to\n it."
},
{
"para": "Setting <literal>MASTER_HOST=''</literal> (that is, setting\n its value explicitly to an empty string) is\n <emphasis>not</emphasis> the same as not setting\n <literal>MASTER_HOST</literal> at all. Trying to set\n <literal>MASTER_HOST</literal> to an empty string fails with\n an error."
},
{
"para": "Values used for <literal>MASTER_HOST</literal> and other\n <literal>CHANGE MASTER TO</literal> options are checked for\n linefeed (<literal>\\n</literal> or <literal>0x0A</literal>)\n characters; the presence of such characters in these values\n causes the statement to fail with\n <literal role=\"error\">ER_MASTER_INFO</literal>. (Bug\n #11758581, Bug #50801)"
}
],
[
{
"para": "<literal>MASTER_USER</literal> and\n <literal>MASTER_PASSWORD</literal> are the user name and\n password of the account to use for connecting to the master."
},
{
"para": "<literal>MASTER_USER</literal> cannot be made empty; setting\n <literal>MASTER_USER = ''</literal> or leaving it unset when\n setting a value for <literal>MASTER_PASSWORD</literal>\n causes an error (Bug #13427949)."
},
{
"para": "The password used for a MySQL Replication slave account in a\n <literal>CHANGE MASTER TO</literal> statement is limited to\n 32 characters in length; trying to use a password of more\n than 32 characters causes <literal>CHANGE MASTER\n TO</literal> to fail."
},
{
"para": "The text of a running <literal role=\"stmt\">CHANGE MASTER\n TO</literal> statement, including values for\n <literal>MASTER_USER</literal> and\n <literal>MASTER_PASSWORD</literal>, can be seen in the\n output of a concurrent <literal role=\"stmt\">SHOW\n PROCESSLIST</literal> statement. (The complete text of a\n <literal role=\"stmt\">START SLAVE</literal> statement is also\n visible to <literal role=\"stmt\">SHOW PROCESSLIST</literal>.)"
}
]
]
},
{
"para": "<literal>PRIVILEGE_CHECKS_USER</literal> (available as of MySQL\n 8.0.18) names a user account that supplies a security context\n for the specified channel. <literal>NULL</literal>, 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 <literal>channel_1</literal> 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 = '<replaceable>priv_repl</replaceable>'@'<replaceable>%.example.com</replaceable>' 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 <xref linkend=\"account-names\" />, and the\n user must not be an anonymous user (with a blank user name) or\n the <literal>CURRENT_USER</literal>. The account must have the\n <literal role=\"priv\">REPLICATION_APPLIER</literal> 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 <xref linkend=\"replication-privilege-checks\" />."
},
{
"para": "<literal>MASTER_COMPRESSION_ALGORITHMS</literal> and\n <literal>MASTER_ZSTD_COMPRESSION_LEVEL</literal> (available as\n of MySQL 8.0.18) enable control over the use of compression for\n connections to the master:"
},
{
"itemizedlist": [
[
{
"para": "<literal>MASTER_COMPRESSION_ALGORITHMS</literal> specifies\n the permitted compression algorithms. The available\n algorithms are the same as for the\n <literal role=\"sysvar\">protocol_compression_algorithms</literal>\n system variable. The default value is\n <literal>uncompressed</literal>."
},
{
"para": "The value of\n <literal>MASTER_COMPRESSION_ALGORITHMS</literal> applies\n only if the\n <literal role=\"sysvar\">slave_compressed_protocol</literal>\n system variable is disabled. If\n <literal role=\"sysvar\">slave_compressed_protocol</literal>\n is enabled, it takes precedence over\n <literal>MASTER_COMPRESSION_ALGORITHMS</literal> and\n connections to the master use <literal>zlib</literal>\n compression if both master and slave support that algorithm."
}
],
[
{
"para": "<literal>MASTER_ZSTD_COMPRESSION_LEVEL</literal> is the\n compression level to use for connections that use the\n <literal>zstd</literal> compression algorithm. The permitted\n levels are from 1 to 22, with larger values indicating\n increasing levels of compression. The default\n <literal>zstd</literal> compression level is 3. The\n compression level setting has no effect on connections that\n do not use <literal>zstd</literal> compression."
}
]
]
},
{
"para": "For more information, see\n <xref linkend=\"connection-compression-control\" />."
},
{
"para": "The <literal>MASTER_SSL_<replaceable>xxx</replaceable></literal>\n options and the <literal>MASTER_TLS_VERSION</literal> 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 <literal>MASTER_SSL_<replaceable>xxx</replaceable></literal> and\n <literal>MASTER_TLS_VERSION</literal> options perform the same\n functions as the\n <literal>--ssl-<replaceable>xxx</replaceable></literal> and\n <literal>--tls-version</literal> client options described in\n <xref linkend=\"encrypted-connection-options\" />. The\n correspondence between the two sets of options, and the use of\n the <literal>MASTER_SSL_<replaceable>xxx</replaceable></literal>\n and <literal>MASTER_TLS_VERSION</literal> options to set up a\n secure connection, is explained in\n <xref linkend=\"replication-solutions-encrypted-connections\" />."
},
{
"para": "To enable RSA key pair-based password exchange, specify either\n the <literal>MASTER_PUBLIC_KEY_PATH</literal> or the\n <literal>GET_MASTER_PUBLIC_KEY=1</literal> option. Either of\n these options provides the RSA public key to the slave:"
},
{
"itemizedlist": [
[
{
"para": "<literal>MASTER_PUBLIC_KEY_PATH</literal> 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 <literal>sha256_password</literal> or\n <literal>caching_sha2_password</literal> authentication\n plugin. (For <literal>sha256_password</literal>,\n <literal>MASTER_PUBLIC_KEY_PATH</literal> can be used only\n if MySQL was built using OpenSSL.)"
}
],
[
{
"para": "<literal>GET_MASTER_PUBLIC_KEY</literal> 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 <literal>caching_sha2_password</literal> 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 <literal>MASTER_PUBLIC_KEY_PATH</literal> is\n given and specifies a valid public key file, it takes\n precedence over <literal>GET_MASTER_PUBLIC_KEY</literal>."
}
]
]
},
{
"para": "The <literal>MASTER_HEARTBEAT_PERIOD</literal>,\n <literal>MASTER_CONNECT_RETRY</literal>, and\n <literal>MASTER_RETRY_COUNT</literal> 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 <literal role=\"sysvar\">slave_net_timeout</literal>\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 <literal>MASTER_HEARTBEAT_PERIOD</literal> 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 <replaceable>interval</replaceable>\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 <replaceable>interval</replaceable> to 0\n disables heartbeats altogether. The heartbeat interval\n defaults to half the value of the\n <literal role=\"sysvar\">slave_net_timeout</literal> system\n variable. It is recorded in the master info log and shown in\n the\n <literal role=\"ps\">replication_connection_configuration</literal>\n Performance Schema table. Issuing <literal role=\"stmt\">RESET\n SLAVE</literal> resets the heartbeat interval to the default\n value."
},
{
"para": "Note that a change to the value or default setting of\n <literal role=\"sysvar\">slave_net_timeout</literal> 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 <literal>@@GLOBAL.slave_net_timeout</literal> to a value\n less than that of the current heartbeat interval. If\n <literal role=\"sysvar\">slave_net_timeout</literal> is\n changed, you must also issue <literal role=\"stmt\">CHANGE\n MASTER TO</literal> 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 <literal>MASTER_CONNECT_RETRY</literal> specifies the\n interval between reconnection attempts, and\n <literal>MASTER_RETRY_COUNT</literal> limits the number of\n reconnection attempts. If both the default settings are\n used, the slave waits 60 seconds between reconnection\n attempts (<literal>MASTER_CONNECT_RETRY=60</literal>), and\n keeps attempting to reconnect at this rate for 60 days\n (<literal>MASTER_RETRY_COUNT=86400</literal>). These values\n are recorded in the master info log and shown in the\n <literal role=\"ps\">replication_connection_configuration</literal>\n Performance Schema table.\n <literal>MASTER_RETRY_COUNT</literal> supersedes the\n <option role=\"mysqld\">--master-retry-count</option> server\n startup option."
}
]
]
},
{
"para": "<literal>MASTER_DELAY</literal> 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 <replaceable>interval</replaceable> seconds later than its\n execution on the master. The default is 0. An error occurs if\n <replaceable>interval</replaceable> is not a nonnegative integer\n in the range from 0 to 2<superscript>31</superscript>minus1.\n For more information, see <xref linkend=\"replication-delayed\" />."
},
{
"para": "A <literal>CHANGE MASTER TO</literal> statement employing the\n <literal>MASTER_DELAY</literal> option can be executed on a\n running slave when the slave SQL thread is stopped."
},
{
"para": "<literal>MASTER_BIND</literal> 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 <literal>Master_Bind</literal> column of the output from\n <literal role=\"stmt\">SHOW SLAVE STATUS</literal>. In the master\n info repository table\n <literal>mysql.slave_master_info</literal>, the value can be\n seen as the <literal>Master_bind</literal> column."
},
{
"para": "The ability to bind a replication slave to a specific network\n interface is also supported by NDB Cluster."
},
{
"para": "<literal>MASTER_LOG_FILE</literal> and\n <literal>MASTER_LOG_POS</literal> are the coordinates at which\n the slave I/O thread should begin reading from the master the\n next time the thread starts. <literal>RELAY_LOG_FILE</literal>\n and <literal>RELAY_LOG_POS</literal> 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 <literal>MASTER_LOG_FILE</literal> or\n <literal>MASTER_LOG_POS</literal>, you cannot specify\n <literal>RELAY_LOG_FILE</literal> or\n <literal>RELAY_LOG_POS</literal>. If you specify either of\n <literal>MASTER_LOG_FILE</literal> or\n <literal>MASTER_LOG_POS</literal>, you also cannot specify\n <literal>MASTER_AUTO_POSITION = 1</literal> (described later in\n this section). If neither of <literal>MASTER_LOG_FILE</literal>\n or <literal>MASTER_LOG_POS</literal> is specified, the slave\n uses the last coordinates of the <emphasis>slave SQL\n thread</emphasis> before <literal role=\"stmt\">CHANGE MASTER\n TO</literal> 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": "<literal>RELAY_LOG_FILE</literal> can use either an absolute or\n relative path, and uses the same base name as\n <literal>MASTER_LOG_FILE</literal>. A <literal>CHANGE MASTER\n TO</literal> statement employing\n <literal>RELAY_LOG_FILE</literal>,\n <literal>RELAY_LOG_POS</literal>, 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 <literal>RELAY_LOG_FILE</literal> or\n <literal>RELAY_LOG_POS</literal> is specified. Note that the\n Group Replication applier channel\n (<literal>group_replication_applier</literal>) 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 <literal>MASTER_AUTO_POSITION = 1</literal> is used with\n <literal>CHANGE MASTER TO</literal>, the slave attempts to\n connect to the master using the GTID-based replication protocol.\n This option can be used with <literal>CHANGE MASTER TO</literal>\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 (<literal role=\"sysvar\">GTID_MODE=ON</literal>,\n <literal>ON_PERMISSIVE,</literal> or\n <literal>OFF_PERMISSIVE</literal> on the slave, and\n <literal role=\"sysvar\">GTID_MODE=ON</literal> on the master).\n Auto-positioning is used for the connection, so the coordinates\n represented by <literal>MASTER_LOG_FILE</literal> and\n <literal>MASTER_LOG_POS</literal> are not used, and the use of\n either or both of these options together with\n <literal>MASTER_AUTO_POSITION = 1</literal> causes an error. If\n multi-source replication is enabled on the slave, you need to\n set the <literal>MASTER_AUTO_POSITION = 1</literal> option for\n each applicable replication channel."
},
{
"para": "With <literal>MASTER_AUTO_POSITION = 1</literal> 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 <xref linkend=\"replication-gtids-auto-positioning\" />."
},
{
"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 <literal role=\"sysvar\">gtid_purged</literal>\n system variable by another method, the master sends the error\n <errorname>ER_MASTER_HAS_PURGED_REQUIRED_GTIDS</errorname> 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 <errorname>ER_FOUND_MISSING_GTIDS</errorname>. 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 <errorname>ER_SLAVE_HAS_MORE_GTIDS_THAN_MASTER</errorname> to\n the slave and replication does not start. For information on how\n to handle these situations, see\n <xref linkend=\"replication-gtids-auto-positioning\" />."
},
{
"para": "You can see whether replication is running with auto-positioning\n enabled by checking the Performance Schema\n <literal role=\"ps\">replication_connection_status</literal> table\n or the output of <literal role=\"stmt\">SHOW SLAVE\n STATUS</literal>. Disabling the\n <literal>MASTER_AUTO_POSITION</literal> 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 <literal>MASTER_LOG_FILE</literal> or\n <literal>MASTER_LOG_POS</literal> options."
},
{
"para": "<literal>IGNORE_SERVER_IDS</literal> 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 <literal>IGNORE_SERVER_IDS =\n (3)</literal> in the <literal role=\"stmt\">CHANGE MASTER\n TO</literal> 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 <literal>IGNORE_SERVER_IDS</literal> contains the\n server's own ID and the server was started with the\n <option role=\"mysqld\">--replicate-same-server-id</option> option\n enabled, an error results."
},
{
"para": "The master info repository and the output of\n <literal role=\"stmt\">SHOW SLAVE STATUS</literal> provide the\n list of servers that are currently ignored. For more\n information, see <xref linkend=\"slave-logs-status\" />, and\n <xref linkend=\"show-slave-status\" />."
},
{
"para": "If a <literal role=\"stmt\">CHANGE MASTER TO</literal> statement\n is issued without any <literal>IGNORE_SERVER_IDS</literal>\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": "<literal>RESET SLAVE ALL</literal> clears\n <literal>IGNORE_SERVER_IDS</literal>."
},
{
"para": "Invoking <literal role=\"stmt\">CHANGE MASTER TO</literal> causes\n the previous values for <literal>MASTER_HOST</literal>,\n <literal>MASTER_PORT</literal>,\n <literal>MASTER_LOG_FILE</literal>, and\n <literal>MASTER_LOG_POS</literal> to be written to the error\n log, along with other information about the slave's state\n prior to execution."
},
{
"para": "<literal>CHANGE MASTER TO</literal> causes an implicit commit of\n an ongoing transaction. See <xref linkend=\"implicit-commit\" />."
},
{
"para": "From MySQL 5.7, the strict requirement to execute\n <literal role=\"stmt\">STOP SLAVE</literal> prior to issuing any\n <literal role=\"stmt\">CHANGE MASTER TO</literal> statement (and\n <literal role=\"stmt\">START SLAVE</literal> afterward) is\n removed. Instead of depending on whether the slave is stopped,\n the behavior of <literal>CHANGE MASTER TO</literal> 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 <literal>CHANGE MASTER\n TO</literal> 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 <literal>CHANGE MASTER TO</literal> using any combination\n that is otherwise allowed of\n <literal>RELAY_LOG_FILE</literal>,\n <literal>RELAY_LOG_POS</literal>, and\n <literal>MASTER_DELAY</literal> 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 <literal>CHANGE MASTER TO</literal> using any of the options\n for this statement (in any allowed combination)\n <emphasis>except</emphasis>\n <literal>RELAY_LOG_FILE</literal>,\n <literal>RELAY_LOG_POS</literal>,\n <literal>MASTER_DELAY</literal>, or\n <literal>MASTER_AUTO_POSITION = 1</literal> 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 <literal>CHANGE MASTER TO</literal>\n statement that employs <literal>MASTER_AUTO_POSITION =\n 1</literal>."
}
]
]
},
{
"para": "You can check the current state of the slave SQL and I/O threads\n using <literal role=\"stmt\">SHOW SLAVE STATUS</literal>. Note\n that the Group Replication applier channel\n (<literal>group_replication_applier</literal>) has no I/O\n thread, only a SQL thread."
},
{
"para": "For more information, see\n <xref linkend=\"replication-solutions-switch\" />."
},
{
"para": "If you are using statement-based replication and temporary\n tables, it is possible for a <literal>CHANGE MASTER TO</literal>\n statement following a <literal>STOP SLAVE</literal> statement to\n leave behind temporary tables on the slave. A warning\n (<literal role=\"error\">ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO</literal>)\n is now issued whenever this occurs. You can avoid this in such\n cases by making sure that the value of the\n <literal role=\"statvar\">Slave_open_temp_tables</literal> system\n status variable is equal to 0 prior to executing such a\n <literal>CHANGE MASTER TO</literal> statement."
},
{
"para": "<literal role=\"stmt\">CHANGE MASTER TO</literal> 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 <literal>CHANGE MASTER TO\n MASTER_LOG_FILE='<replaceable>log_name</replaceable>',\n MASTER_LOG_POS=<replaceable>log_pos</replaceable></literal> 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='<replaceable>password</replaceable>',\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 <literal role=\"stmt\">CHANGE MASTER TO</literal> and start the\n SQL thread (<literal>START SLAVE SQL_THREAD</literal>):"
},
{
"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 <replaceable>option</replaceable> [, <replaceable>option</replaceable>] ... [ <replaceable>channel_option</replaceable> ]\n\n<replaceable>option</replaceable>:\n MASTER_BIND = '<replaceable>interface_name</replaceable>'\n | MASTER_HOST = '<replaceable>host_name</replaceable>'\n | MASTER_USER = '<replaceable>user_name</replaceable>'\n | MASTER_PASSWORD = '<replaceable>password</replaceable>'\n | MASTER_PORT = <replaceable>port_num</replaceable>\n | PRIVILEGE_CHECKS_USER = {'<replaceable>account</replaceable>' | NULL}\n | MASTER_CONNECT_RETRY = <replaceable>interval</replaceable>\n | MASTER_RETRY_COUNT = <replaceable>count</replaceable>\n | MASTER_DELAY = <replaceable>interval</replaceable>\n | MASTER_HEARTBEAT_PERIOD = <replaceable>interval</replaceable>\n | MASTER_LOG_FILE = '<replaceable>master_log_name</replaceable>'\n | MASTER_LOG_POS = <replaceable>master_log_pos</replaceable>\n | MASTER_AUTO_POSITION = {0|1}\n | RELAY_LOG_FILE = '<replaceable>relay_log_name</replaceable>'\n | RELAY_LOG_POS = <replaceable>relay_log_pos</replaceable>\n | MASTER_COMPRESSION_ALGORITHMS = '<replaceable>value</replaceable>'\n | MASTER_ZSTD_COMPRESSION_LEVEL = <replaceable>level</replaceable>\n | MASTER_SSL = {0|1}\n | MASTER_SSL_CA = '<replaceable>ca_file_name</replaceable>'\n | MASTER_SSL_CAPATH = '<replaceable>ca_directory_name</replaceable>'\n | MASTER_SSL_CERT = '<replaceable>cert_file_name</replaceable>'\n | MASTER_SSL_CRL = '<replaceable>crl_file_name</replaceable>'\n | MASTER_SSL_CRLPATH = '<replaceable>crl_directory_name</replaceable>'\n | MASTER_SSL_KEY = '<replaceable>key_file_name</replaceable>'\n | MASTER_SSL_CIPHER = '<replaceable>cipher_list</replaceable>'\n | MASTER_SSL_VERIFY_SERVER_CERT = {0|1}\n | MASTER_TLS_VERSION = '<replaceable>protocol_list</replaceable>'\n | MASTER_PUBLIC_KEY_PATH = '<replaceable>key_file_name</replaceable>'\n | GET_MASTER_PUBLIC_KEY = {0|1}\n | IGNORE_SERVER_IDS = (<replaceable>server_id_list</replaceable>)\n\n<replaceable>channel_option</replaceable>:\n FOR CHANNEL <replaceable>channel</replaceable>\n\n<replaceable>server_id_list</replaceable>:\n [<replaceable>server_id</replaceable> [, <replaceable>server_id</replaceable>] ... ]"
}
]
},
{
"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": "<literal>CHANGE REPLICATION FILTER</literal> sets one or more\n replication filtering rules on the slave in the same way as\n starting the slave <command>mysqld</command> with replication\n filtering options such as\n <option role=\"mysqld\">--replicate-do-db</option> or\n <option role=\"mysqld\">--replicate-wild-ignore-table</option>.\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 <literal condition=\"stop-slave\" role=\"stmt\">STOP SLAVE\n SQL_THREAD</literal> first (and restarted with\n <literal condition=\"start-slave\" role=\"stmt\">START SLAVE\n SQL_THREAD</literal> afterwards). <literal role=\"stmt\">CHANGE\n REPLICATION FILTER</literal> requires the\n <literal role=\"priv\">REPLICATION_SLAVE_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege. Use the\n <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> 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 <literal>FOR CHANNEL</literal> clause are\n considered global filters, meaning that they are applied to all\n replication channels."
},
{
"para": "<note>\n <para>\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 <literal>group_replication_applier</literal> or\n <literal>group_replication_recovery</literal> channels.\n </para>\n </note>"
},
{
"para": "The following list shows the <literal>CHANGE REPLICATION\n FILTER</literal> options and how they relate to\n <option>--replicate-*</option> server options:"
},
{
"itemizedlist": [
[
{
"para": "<literal>REPLICATE_DO_DB</literal>: Include updates based on\n database name. Equivalent to\n <option role=\"mysqld\">--replicate-do-db</option>."
}
],
[
{
"para": "<literal>REPLICATE_IGNORE_DB</literal>: Exclude updates\n based on database name. Equivalent to\n <option role=\"mysqld\">--replicate-ignore-db</option>."
}
],
[
{
"para": "<literal>REPLICATE_DO_TABLE</literal>: Include updates based\n on table name. Equivalent to\n <option role=\"mysqld\">--replicate-do-table</option>."
}
],
[
{
"para": "<literal>REPLICATE_IGNORE_TABLE</literal>: Exclude updates\n based on table name. Equivalent to\n <option role=\"mysqld\">--replicate-ignore-table</option>."
}
],
[
{
"para": "<literal>REPLICATE_WILD_DO_TABLE</literal>: Include updates\n based on wildcard pattern matching table name. Equivalent to\n <option role=\"mysqld\">--replicate-wild-do-table</option>."
}
],
[
{
"para": "<literal>REPLICATE_WILD_IGNORE_TABLE</literal>: Exclude\n updates based on wildcard pattern matching table name.\n Equivalent to\n <option role=\"mysqld\">--replicate-wild-ignore-table</option>."
}
],
[
{
"para": "<literal>REPLICATE_REWRITE_DB</literal>: Perform updates on\n slave after substituting new name on slave for specified\n database on master. Equivalent to\n <option role=\"mysqld\">--replicate-rewrite-db</option>."
}
]
]
},
{
"para": "The precise effects of <literal>REPLICATE_DO_DB</literal> and\n <literal>REPLICATE_IGNORE_DB</literal> filters are dependent on\n whether statement-based or row-based replication is in effect.\n See <xref linkend=\"replication-rules\" />, for more information."
},
{
"para": "Multiple replication filtering rules can be created in a single\n <literal>CHANGE REPLICATION FILTER</literal> 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 <command>mysqld</command> with the options\n <option role=\"mysqld\">--replicate-do-db=d1</option>\n <option role=\"mysqld\">--replicate-ignore-db=d2</option>."
},
{
"para": "On a multi-source replication slave, which uses multiple\n replication channels to process transaction from different\n sources, use the <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> 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 <literal>FOR\n CHANNEL</literal> 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 <errortext>ER_SLAVE_CONFIGURATION</errortext> error. If\n issued against Group Replication channels, the statement fails\n with an\n <errortext>ER_SLAVE_CHANNEL_OPERATION_NOT_ALLOWED</errortext>\n error."
},
{
"para": "On a replication slave with multiple replication channels\n configured, issuing <literal role=\"stmt\">CHANGE REPLICATION\n FILTER</literal> with no <literal>FOR CHANNEL</literal> 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 <xref linkend=\"replication-rules-channel-based-filters\" />."
},
{
"para": "If the same filtering rule is specified multiple times, only the\n <emphasis>last</emphasis> such rule is actually used. For\n example, the two statements shown here have exactly the same\n effect, because the first <literal>REPLICATE_DO_DB</literal>\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 <literal>REPLICATION_WILD_TABLE</literal> and\n <literal>REPLICATION_WILD_IGNORE_TABLE</literal> 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 <literal>REPLICATE_REWRITE_DB</literal>\n represent <emphasis>pairs</emphasis> of database names; each\n such value must be enclosed in parentheses. The following\n statement rewrites statements occurring on database\n <literal>db1</literal> on the master to database\n <literal>db2</literal> 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 <literal>rewrite-db</literal> rules, one rewriting database\n <literal>dbA</literal> to <literal>dbB</literal>, and one\n rewriting database <literal>dbC</literal> to\n <literal>dbD</literal>:"
},
{
"programlisting": ">\nCHANGE REPLICATION FILTER\n REPLICATE_REWRITE_DB = ((dbA, dbB), (dbC, dbD));"
},
{
"para": "The <literal role=\"stmt\">CHANGE REPLICATION FILTER</literal>\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 <literal>REPLICATE_DO_DB</literal> and\n <literal>REPLICATE_IGNORE_DB</literal> 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 <option>--replicate-*</option>\n options on the command line or in the configuration file."
},
{
"para": "The <literal condition=\"reset-slave\" role=\"stmt\">RESET SLAVE\n ALL</literal> 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 <xref linkend=\"replication-rules\" />."
}
],
"id": "CHANGE REPLICATION FILTER",
"syntax": [
{
"programlisting": ">\nCHANGE REPLICATION FILTER <replaceable>filter</replaceable>[, <replaceable>filter</replaceable>]\n\t[, ...] [FOR CHANNEL <replaceable>channel</replaceable>]\n\n<replaceable>filter</replaceable>:\n REPLICATE_DO_DB = (<replaceable>db_list</replaceable>)\n | REPLICATE_IGNORE_DB = (<replaceable>db_list</replaceable>)\n | REPLICATE_DO_TABLE = (<replaceable>tbl_list</replaceable>)\n | REPLICATE_IGNORE_TABLE = (<replaceable>tbl_list</replaceable>)\n | REPLICATE_WILD_DO_TABLE = (<replaceable>wild_tbl_list</replaceable>)\n | REPLICATE_WILD_IGNORE_TABLE = (<replaceable>wild_tbl_list</replaceable>)\n | REPLICATE_REWRITE_DB = (<replaceable>db_pair_list</replaceable>)\n\n<replaceable>db_list</replaceable>:\n <replaceable>db_name</replaceable>[, <replaceable>db_name</replaceable>][, ...]\n\n<replaceable>tbl_list</replaceable>:\n <replaceable>db_name.table_name</replaceable>[, <replaceable>db_name.table_name</replaceable>][, ...]\n<replaceable>wild_tbl_list</replaceable>:\n '<replaceable>db_pattern.table_pattern</replaceable>'[, '<replaceable>db_pattern.table_pattern</replaceable>'][, ...]\n\n<replaceable>db_pair_list</replaceable>:\n (<replaceable>db_pair</replaceable>)[, (<replaceable>db_pair</replaceable>)][, ...]\n\n<replaceable>db_pair</replaceable>:\n <replaceable>from_db</replaceable>, <replaceable>to_db</replaceable>"
}
]
},
{
"keywords": [
"RESET",
"SLAVE",
"ALL",
"FOR",
"CHANNEL"
],
"description": [
{
"para": "<literal role=\"stmt\">RESET SLAVE</literal> 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 <literal>MASTER_DELAY</literal> option to <literal>CHANGE MASTER\n TO</literal>."
},
{
"para": "For a server where GTIDs are in use\n (<literal role=\"sysvar\">gtid_mode</literal> is\n <literal>ON</literal>), issuing <literal role=\"stmt\">RESET\n SLAVE</literal> has no effect on the GTID execution history. The\n statement does not change the values of\n <literal>gtid_executed</literal> or\n <literal>gtid_purged</literal>, or the\n <literal>mysql.gtid_executed</literal> table. If you need to\n reset the GTID execution history, use <literal role=\"stmt\">RESET\n MASTER</literal>, even if the GTID-enabled server is a\n replication slave where binary logging is disabled."
},
{
"para": "<literal role=\"stmt\">RESET SLAVE</literal> requires the\n <literal role=\"priv\">RELOAD</literal> privilege."
},
{
"para": "To use <literal role=\"stmt\">RESET SLAVE</literal>, the slave\n replication threads must be stopped, so on a running slave use\n <literal role=\"stmt\">STOP SLAVE</literal> before issuing\n <literal role=\"stmt\">RESET SLAVE</literal>. To use\n <literal role=\"stmt\">RESET SLAVE</literal> on a Group\n Replication group member, the member status must be\n <literal>OFFLINE</literal>, 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 <literal role=\"stmt\">STOP\n GROUP REPLICATION</literal> statement."
},
{
"para": "The optional <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause enables you\n to name which replication channel the statement applies to.\n Providing a <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause applies the\n <literal>RESET SLAVE</literal> statement to a specific\n replication channel. Combining a <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause with the\n <literal>ALL</literal> 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 <literal condition=\"reset-slave\" role=\"stmt\">RESET SLAVE\n ALL</literal> statement without a <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause when\n multiple replication channels exist deletes\n <emphasis>all</emphasis> replication channels and recreates only\n the default channel. See <xref linkend=\"replication-channels\" />\n for more information."
},
{
"para": "<literal role=\"stmt\">RESET SLAVE</literal> does not change any\n replication connection parameters such as the master host,\n master port, master user, or master password.\n <literal role=\"stmt\">RESET SLAVE</literal> also does not affect\n the <literal>PRIVILEGE_CHECKS_USER</literal> account. If you\n want to reset the connection parameters intentionally, you need\n to use <literal condition=\"reset-slave\" role=\"stmt\">RESET SLAVE\n ALL</literal>, which clears the connection parameters, including\n the <literal>MASTER_USER</literal> and\n <literal>PRIVILEGE_CHECKS_USER</literal> accounts.\n <literal>RESET SLAVE ALL</literal> also clears the\n <literal>IGNORE_SERVER_IDS</literal> list set by\n <literal role=\"stmt\">CHANGE MASTER TO</literal>. When you have\n used <literal>RESET SLAVE ALL</literal>, you must issue a\n <literal role=\"stmt\">CHANGE MASTER TO</literal> 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 <literal role=\"stmt\">RESET SLAVE</literal> but before\n issuing <literal role=\"stmt\">START SLAVE</literal>, 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 <literal role=\"sysvar\">master_info_repository=TABLE</literal>\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 <literal>InnoDB</literal> table\n <literal>mysql.slave_master_info</literal> as part of the\n <literal role=\"stmt\">RESET SLAVE</literal> operation. They\n are also retained in memory. In the event of a server crash\n or deliberate restart after issuing\n <literal role=\"stmt\">RESET SLAVE</literal> but before\n issuing <literal role=\"stmt\">START SLAVE</literal>, the\n replication connection parameters are retrieved from the\n table and reused for the new connection."
}
],
[
{
"para": "When\n <literal role=\"sysvar\">master_info_repository=FILE</literal>\n is set on the server, replication connection parameters are\n only retained in memory. If the slave\n <command>mysqld</command> is restarted immediately after\n issuing <literal role=\"stmt\">RESET SLAVE</literal> due to a\n server crash or deliberate restart, the connection\n parameters are lost. In that case, you must issue a\n <literal role=\"stmt\">CHANGE MASTER TO</literal> statement\n after the server start to respecify the connection\n parameters before issuing <literal role=\"stmt\">START\n SLAVE</literal>."
}
]
]
},
{
"para": "<literal role=\"stmt\">RESET SLAVE</literal> does not change any\n replication filter settings (such as\n <option role=\"mysqld\">--replicate-ignore-table</option>) for\n channels affected by the statement. However, <literal>RESET\n SLAVE ALL</literal> 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 <xref linkend=\"replication-rules-channel-based-filters\" />."
},
{
"para": "<literal>RESET SLAVE</literal> causes an implicit commit of an\n ongoing transaction. See <xref linkend=\"implicit-commit\" />."
},
{
"para": "If the slave SQL thread was in the middle of replicating\n temporary tables when it was stopped, and\n <literal role=\"stmt\">RESET SLAVE</literal> is issued, these\n replicated temporary tables are deleted on the slave."
},
{
"para": "<literal>RESET SLAVE</literal> does not reset the heartbeat\n period\n (<literal role=\"statvar\">Slave_heartbeat_period</literal>) or\n <literal>SSL_VERIFY_SERVER_CERT</literal>."
}
],
"id": "RESET SLAVE",
"syntax": [
{
"programlisting": ">\nRESET SLAVE [ALL] [<replaceable>channel_option</replaceable>]\n\n<replaceable>channel_option</replaceable>:\n FOR CHANNEL <replaceable>channel</replaceable>"
}
]
},
{
"keywords": [
"SET",
"GLOBAL",
"sql_slave_skip_counter"
],
"description": [
{
"para": "This statement skips the next <replaceable>N</replaceable>\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 = <replaceable>N</replaceable>"
}
]
},
{
"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": "<literal role=\"stmt\">START SLAVE</literal> with no\n <replaceable>thread_type</replaceable> 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 <literal role=\"stmt\">START SLAVE</literal> requires the\n <literal role=\"priv\">REPLICATION_SLAVE_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "If <literal role=\"stmt\">START SLAVE</literal> 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). <literal role=\"stmt\">START SLAVE</literal> 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 <literal role=\"stmt\">SHOW\n SLAVE STATUS</literal>."
},
{
"para": "<literal>START SLAVE</literal> causes an implicit commit of an\n ongoing transaction. See <xref linkend=\"implicit-commit\" />."
},
{
"para": "<literal role=\"sysvar\">gtid_next</literal> must be set to\n <literal>AUTOMATIC</literal> before issuing this statement."
},
{
"para": "The optional <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause enables you\n to name which replication channel the statement applies to.\n Providing a <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause applies the\n <literal>START SLAVE</literal> 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 <literal>START SLAVE</literal> 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 <literal>group_replication_recovery</literal> channel.\n See <xref linkend=\"replication-channels\" /> for more information."
},
{
"para": "You can add <literal>IO_THREAD</literal> and\n <literal>SQL_THREAD</literal> options to the statement to name\n which of the threads to start. Note that the Group Replication\n applier channel (<literal>group_replication_applier</literal>)\n has no I/O thread, only a SQL thread. Specifying the\n <literal>IO_THREAD</literal> or <literal>SQL_THREAD</literal>\n options when you start this channel has no benefit."
},
{
"para": "MySQL supports pluggable user-password authentication with\n <literal>START SLAVE</literal> with the <literal>USER</literal>,\n <literal>PASSWORD</literal>, <literal>DEFAULT_AUTH</literal> and\n <literal>PLUGIN_DIR</literal> options, as described in the\n following list:"
},
{
"itemizedlist": [
[
{
"para": "<literal>USER</literal>: User name. Cannot be set to an\n empty or null string, or left unset if\n <literal>PASSWORD</literal> is used."
}
],
[
{
"para": "<literal>PASSWORD</literal>: Password."
}
],
[
{
"para": "<literal>DEFAULT_AUTH</literal>: Name of plugin; default is\n MySQL native authentication."
}
],
[
{
"para": "<literal>PLUGIN_DIR</literal>: Location of plugin."
}
]
]
},
{
"para": "You cannot use the <literal>SQL_THREAD</literal> option when\n specifying any of <literal>USER</literal>,\n <literal>PASSWORD</literal>, <literal>DEFAULT_AUTH</literal>, or\n <literal>PLUGIN_DIR</literal>, unless the\n <literal>IO_THREAD</literal> option is also provided."
},
{
"para": "See <xref linkend=\"pluggable-authentication\" />, for more\n information."
},
{
"para": "If an insecure connection is used with any these options, the\n server issues the warning <errortext>Sending passwords in plain\n text without SSL/TLS is extremely insecure</errortext>."
},
{
"para": "<literal>START SLAVE ... UNTIL</literal> supports two additional\n options for use with global transaction identifiers (GTIDs) (see\n <xref linkend=\"replication-gtids\" />). Each of these takes a set\n of one or more global transaction identifiers\n <replaceable>gtid_set</replaceable> as an argument (see\n <xref linkend=\"replication-gtids-concepts-gtid-sets\" />, for more\n information)."
},
{
"para": "When no <replaceable>thread_type</replaceable> is specified,\n <literal>START SLAVE UNTIL SQL_BEFORE_GTIDS</literal> causes the\n slave SQL thread to process transactions until it has reached\n the <emphasis>first</emphasis> transaction whose GTID is listed\n in the <replaceable>gtid_set</replaceable>. <literal>START SLAVE\n UNTIL SQL_AFTER_GTIDS</literal> causes the slave threads to\n process all transactions until the\n <replaceable>last</replaceable> transaction in the\n <replaceable>gtid_set</replaceable> has been processed by both\n threads. In other words, <literal>START SLAVE UNTIL\n SQL_BEFORE_GTIDS</literal> causes the slave SQL thread to\n process all transactions occurring before the first GTID in the\n <replaceable>gtid_set</replaceable> is reached, and\n <literal>START SLAVE UNTIL SQL_AFTER_GTIDS</literal> causes the\n slave threads to handle all transactions, including those whose\n GTIDs are found in <replaceable>gtid_set</replaceable>, until\n each has encountered a transaction whose GTID is not part of the\n set. <literal>SQL_BEFORE_GTIDS</literal> and\n <literal>SQL_AFTER_GTIDS</literal> each support the\n <literal>SQL_THREAD</literal> and <literal>IO_THREAD</literal>\n options, although using <literal>IO_THREAD</literal> with them\n currently has no effect."
},
{
"para": "For example, <literal>START SLAVE SQL_THREAD UNTIL\n SQL_BEFORE_GTIDS =\n 3E11FA47-71CA-11E1-9E33-C80AA9429562:11-56</literal> causes the\n slave SQL thread to process all transactions originating from\n the master whose <literal role=\"sysvar\">server_uuid</literal> is\n <literal>3E11FA47-71CA-11E1-9E33-C80AA9429562</literal> 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 <literal>START SLAVE\n SQL_THREAD UNTIL SQL_AFTER_GTIDS =\n 3E11FA47-71CA-11E1-9E33-C80AA9429562:11-56</literal>, 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 <literal>slave_preserve_commit_order=0</literal> 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": "<command>mysqld</command> shuts down unexpectedly"
}
]
]
},
{
"para": "Use the <literal condition=\"start-slave\" role=\"stmt\">START SLAVE\n UNTIL SQL_AFTER_MTS_GAPS</literal> 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 <literal>SQL_THREAD</literal> 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 <literal>IO_THREAD</literal> option)."
},
{
"para": "Issuing <literal role=\"stmt\">START SLAVE</literal> 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 <literal condition=\"start-slave\" role=\"stmt\">START SLAVE UNTIL\n SQL_AFTER_MTS_GAPS</literal>, then issue\n <literal role=\"stmt\">RESET SLAVE</literal> to remove any\n remaining relay logs. See\n <xref linkend=\"replication-features-transaction-inconsistencies\" />\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 [<replaceable>thread_types</replaceable>] [<replaceable>until_option</replaceable>] [<replaceable>connection_options</replaceable>] [<replaceable>channel_option</replaceable>]\n\n<replaceable>thread_types</replaceable>:\n [<replaceable>thread_type</replaceable> [, <replaceable>thread_type</replaceable>] ... ]\n\n<replaceable>thread_type</replaceable>:\n IO_THREAD | SQL_THREAD\n\n<replaceable>until_option</replaceable>:\n UNTIL { {SQL_BEFORE_GTIDS | SQL_AFTER_GTIDS} = <replaceable>gtid_set</replaceable>\n | MASTER_LOG_FILE = '<replaceable>log_name</replaceable>', MASTER_LOG_POS = <replaceable>log_pos</replaceable>\n | RELAY_LOG_FILE = '<replaceable>log_name</replaceable>', RELAY_LOG_POS = <replaceable>log_pos</replaceable>\n | SQL_AFTER_MTS_GAPS }\n\n<replaceable>connection_options</replaceable>:\n [USER='<replaceable>user_name</replaceable>'] [PASSWORD='<replaceable>user_pass</replaceable>'] [DEFAULT_AUTH='<replaceable>plugin_name</replaceable>'] [PLUGIN_DIR='<replaceable>plugin_dir</replaceable>']\n\n\n<replaceable>channel_option</replaceable>:\n FOR CHANNEL <replaceable>channel</replaceable>\n\n<replaceable>gtid_set</replaceable>:\n <replaceable>uuid_set</replaceable> [, <replaceable>uuid_set</replaceable>] ...\n | ''\n\n<replaceable>uuid_set</replaceable>:\n <replaceable>uuid</replaceable>:<replaceable>interval</replaceable>[:<replaceable>interval</replaceable>]...\n\n<replaceable>uuid</replaceable>:\n <replaceable>hhhhhhhh</replaceable>-<replaceable>hhhh</replaceable>-<replaceable>hhhh</replaceable>-<replaceable>hhhh</replaceable>-<replaceable>hhhhhhhhhhhh</replaceable>\n\n<replaceable>h</replaceable>:\n [0-9,A-F]\n\n<replaceable>interval</replaceable>:\n <replaceable>n</replaceable>[-<replaceable>n</replaceable>]\n\n (<replaceable>n</replaceable> >= 1)"
}
]
},
{
"keywords": [
"STOP",
"SLAVE",
"IO_THREAD",
"SQL_THREAD",
"FOR",
"CHANNEL"
],
"description": [
{
"para": "Stops the slave threads. <literal role=\"stmt\">STOP\n SLAVE</literal> requires the\n <literal role=\"priv\">REPLICATION_SLAVE_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege. Recommended best\n practice is to execute <literal>STOP SLAVE</literal> on the\n slave before stopping the slave server (see\n <xref linkend=\"server-shutdown\" />, for more information)."
},
{
"para": "<emphasis>When using the row-based logging format</emphasis>:\n You should execute <literal>STOP SLAVE</literal> or\n <literal>STOP SLAVE SQL_THREAD</literal> 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 <citetitle>Note</citetitle> later in this section)."
},
{
"para": "Like <literal role=\"stmt\">START SLAVE</literal>, this statement\n may be used with the <literal>IO_THREAD</literal> and\n <literal>SQL_THREAD</literal> options to name the thread or\n threads to be stopped. Note that the Group Replication applier\n channel (<literal>group_replication_applier</literal>) has no\n I/O thread, only a SQL thread. Using the\n <literal>SQL_THREAD</literal> option therefore stops this\n channel completely."
},
{
"para": "<literal>STOP SLAVE</literal> causes an implicit commit of an\n ongoing transaction. See <xref linkend=\"implicit-commit\" />."
},
{
"para": "<literal role=\"sysvar\">gtid_next</literal> must be set to\n <literal>AUTOMATIC</literal> before issuing this statement."
},
{
"para": "You can control how long <literal>STOP SLAVE</literal> waits\n before timing out by setting the\n <literal role=\"sysvar\">rpl_stop_slave_timeout</literal> system\n variable. This can be used to avoid deadlocks between\n <literal>STOP SLAVE</literal> 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 <literal>STOP SLAVE</literal>\n instruction remains in effect. Once the slave threads are no\n longer busy, the <literal>STOP SLAVE</literal> statement is\n executed and the slave stops."
},
{
"para": "Some <literal>CHANGE MASTER TO</literal> statements are allowed\n while the slave is running, depending on the states of the slave\n SQL and I/O threads. However, using <literal>STOP\n SLAVE</literal> prior to executing <literal>CHANGE MASTER\n TO</literal> in such cases is still supported. See\n <xref linkend=\"change-master-to\" />, and\n <xref linkend=\"replication-solutions-switch\" />, for more\n information."
},
{
"para": "The optional <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause enables you\n to name which replication channel the statement applies to.\n Providing a <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause applies the\n <literal>STOP SLAVE</literal> 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 <literal>STOP SLAVE</literal> 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 <literal>group_replication_recovery</literal>\n channel. See <xref linkend=\"replication-channels\" /> for more\n information."
},
{
"para": "<emphasis>When using statement-based replication</emphasis>:\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 <literal role=\"statvar\">Slave_open_temp_tables</literal>; when\n using statement-based replication, this value should be 0 before\n executing <literal>CHANGE MASTER TO</literal>. If there are any\n temporary tables open on the slave, issuing a <literal>CHANGE\n MASTER TO</literal> statement after issuing a <literal>STOP\n SLAVE</literal> causes an\n <literal role=\"error\">ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO</literal>\n warning."
},
{
"para": "When using a multithreaded slave\n (<literal role=\"sysvar\">slave_parallel_workers</literal> 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 <literal role=\"stmt\">KILL</literal>) while a\n <literal role=\"stmt\">STOP SLAVE</literal> statement is\n executing, the sequence of executed transactions from the relay\n log may become inconsistent. See\n <xref linkend=\"replication-features-transaction-inconsistencies\" />\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 <literal condition=\"kill\" role=\"stmt\">KILL QUERY</literal> or\n <literal condition=\"kill\" role=\"stmt\">KILL CONNECTION</literal>\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 [<replaceable>thread_types</replaceable>] [<replaceable>channel_option</replaceable>]\n\n<replaceable>thread_types</replaceable>:\n [<replaceable>thread_type</replaceable> [, <replaceable>thread_type</replaceable>] ... ]\n\n<replaceable>thread_type</replaceable>: IO_THREAD | SQL_THREAD\n\n<replaceable>channel_option</replaceable>:\n FOR CHANNEL <replaceable>channel</replaceable>"
}
]
},
{
"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 <literal role=\"stmt\">ALTER USER</literal> 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, <literal role=\"stmt\">ALTER USER</literal>\n requires the global <literal role=\"priv\">CREATE USER</literal>\n privilege, or the <literal role=\"priv\">UPDATE</literal>\n privilege for the <literal>mysql</literal> 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 <literal role=\"func\">CURRENT_USER()</literal> function:"
},
{
"programlisting": ">\nSELECT CURRENT_USER();"
}
],
[
{
"para": "For <literal>DEFAULT ROLE</literal> syntax,\n <literal role=\"stmt\">ALTER USER</literal> requires these\n privileges:"
},
{
"itemizedlist": [
[
{
"para": "Setting the default roles for another user requires the\n global <literal role=\"priv\">CREATE USER</literal>\n privilege, or the <literal role=\"priv\">UPDATE</literal>\n privilege for the <literal>mysql.default_roles</literal>\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 <literal role=\"priv\">APPLICATION_PASSWORD_ADMIN</literal>\n privilege is required to use the <literal>RETAIN CURRENT\n PASSWORD</literal> or <literal>DISCARD OLD\n PASSWORD</literal> clause for <literal role=\"stmt\">ALTER\n USER</literal> 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 <literal role=\"priv\">CREATE USER</literal> privilege\n rather than\n <literal role=\"priv\">APPLICATION_PASSWORD_ADMIN</literal>."
}
]
]
}
]
]
},
{
"para": "When the <literal role=\"sysvar\">read_only</literal> system\n variable is enabled, <literal role=\"stmt\">ALTER USER</literal>\n additionally requires the\n <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "By default, an error occurs if you try to modify a user that\n does not exist. If the <literal>IF EXISTS</literal> 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 <replaceable>user</replaceable> [<replaceable>auth_option</replaceable>] [, <replaceable>user</replaceable> [<replaceable>auth_option</replaceable>]] ...\n [REQUIRE {NONE | <replaceable>tls_option</replaceable> [[AND] <replaceable>tls_option</replaceable>] ...}]\n [WITH <replaceable>resource_option</replaceable> [<replaceable>resource_option</replaceable>] ...]\n [<replaceable>password_option</replaceable> | <replaceable>lock_option</replaceable>] ...\n\nALTER USER [IF EXISTS] USER() <replaceable>user_func_auth_option</replaceable>\n\nALTER USER [IF EXISTS]\n <replaceable>user</replaceable> DEFAULT ROLE\n {NONE | ALL | <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ...}\n\n<replaceable>user</replaceable>:\n (see <xref linkend=\"account-names\" />)\n\n<replaceable>auth_option</replaceable>: {\n IDENTIFIED BY '<replaceable>auth_string</replaceable>'\n [REPLACE '<replaceable>current_auth_string</replaceable>']\n [RETAIN CURRENT PASSWORD]\n | IDENTIFIED BY RANDOM PASSWORD\n [REPLACE '<replaceable>current_auth_string</replaceable>']\n [RETAIN CURRENT PASSWORD]\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable>\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> BY '<replaceable>auth_string</replaceable>'\n [REPLACE '<replaceable>current_auth_string</replaceable>']\n [RETAIN CURRENT PASSWORD]\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> BY RANDOM PASSWORD\n [REPLACE '<replaceable>current_auth_string</replaceable>']\n [RETAIN CURRENT PASSWORD]\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> AS '<replaceable>auth_string</replaceable>'\n | DISCARD OLD PASSWORD\n}\n\n<replaceable>user_func_auth_option</replaceable>: {\n IDENTIFIED BY '<replaceable>auth_string</replaceable>'\n [REPLACE '<replaceable>current_auth_string</replaceable>']\n [RETAIN CURRENT PASSWORD]\n | DISCARD OLD PASSWORD\n}\n\n<replaceable>tls_option</replaceable>: {\n SSL\n | X509\n | CIPHER '<replaceable>cipher</replaceable>'\n | ISSUER '<replaceable>issuer</replaceable>'\n | SUBJECT '<replaceable>subject</replaceable>'\n}\n\n<replaceable>resource_option</replaceable>: {\n MAX_QUERIES_PER_HOUR <replaceable>count</replaceable>\n | MAX_UPDATES_PER_HOUR <replaceable>count</replaceable>\n | MAX_CONNECTIONS_PER_HOUR <replaceable>count</replaceable>\n | MAX_USER_CONNECTIONS <replaceable>count</replaceable>\n}\n\n<replaceable>password_option</replaceable>: {\n PASSWORD EXPIRE [DEFAULT | NEVER | INTERVAL <replaceable>N</replaceable> DAY]\n | PASSWORD HISTORY {DEFAULT | <replaceable>N</replaceable>}\n | PASSWORD REUSE INTERVAL {DEFAULT | <replaceable>N</replaceable> DAY}\n | PASSWORD REQUIRE CURRENT [DEFAULT | OPTIONAL]\n | FAILED_LOGIN_ATTEMPTS <replaceable>N</replaceable>\n | PASSWORD_LOCK_TIME {<replaceable>N</replaceable> | UNBOUNDED}\n}\n\n<replaceable>lock_option</replaceable>: {\n ACCOUNT LOCK\n | ACCOUNT UNLOCK\n}"
}
]
},
{
"keywords": [
"CREATE",
"ROLE",
"IF",
"NOT",
"EXISTS"
],
"description": [
{
"para": "<literal role=\"stmt\">CREATE ROLE</literal> creates one or more\n roles, which are named collections of privileges. To use this\n statement, you must have the global <literal role=\"priv\">CREATE\n ROLE</literal> or <literal role=\"priv\">CREATE USER</literal>\n privilege. When the <literal role=\"sysvar\">read_only</literal>\n system variable is enabled, <literal role=\"stmt\">CREATE\n ROLE</literal> additionally requires the\n <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> 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 <literal role=\"stmt\">ALTER USER</literal>\n statement, by users who have the global\n <literal role=\"priv\">CREATE USER</literal> privilege.)"
},
{
"para": "<literal role=\"stmt\">CREATE ROLE</literal> 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 <literal>IF NOT EXISTS</literal>\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 <literal>IF NOT EXISTS</literal> 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 <xref linkend=\"role-names\" />. 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 <literal>'%'</literal>."
},
{
"para": "For role usage examples, see <xref linkend=\"roles\" />."
}
],
"id": "CREATE ROLE",
"syntax": [
{
"programlisting": ">\nCREATE ROLE [IF NOT EXISTS] <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ..."
}
]
},
{
"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 <literal role=\"stmt\">CREATE USER</literal> 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 <literal role=\"stmt\">CREATE USER</literal>, you must have\n the global <literal role=\"priv\">CREATE USER</literal> privilege,\n or the <literal role=\"priv\">INSERT</literal> privilege for the\n <literal>mysql</literal> system schema. When the\n <literal role=\"sysvar\">read_only</literal> system variable is\n enabled, <literal role=\"stmt\">CREATE USER</literal> additionally\n requires the <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "<literal role=\"stmt\">CREATE USER</literal> 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 <literal>IF NOT EXISTS</literal>\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 <replaceable>user</replaceable> [<replaceable>auth_option</replaceable>] [, <replaceable>user</replaceable> [<replaceable>auth_option</replaceable>]] ...\n DEFAULT ROLE <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ...\n [REQUIRE {NONE | <replaceable>tls_option</replaceable> [[AND] <replaceable>tls_option</replaceable>] ...}]\n [WITH <replaceable>resource_option</replaceable> [<replaceable>resource_option</replaceable>] ...]\n [<replaceable>password_option</replaceable> | <replaceable>lock_option</replaceable>] ...\n\n<replaceable>user</replaceable>:\n (see <xref linkend=\"account-names\" />)\n\n<replaceable>auth_option</replaceable>: {\n IDENTIFIED BY '<replaceable>auth_string</replaceable>'\n | IDENTIFIED BY RANDOM PASSWORD\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable>\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> BY '<replaceable>auth_string</replaceable>'\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> BY RANDOM PASSWORD\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> AS '<replaceable>auth_string</replaceable>'\n}\n\n<replaceable>tls_option</replaceable>: {\n SSL\n | X509\n | CIPHER '<replaceable>cipher</replaceable>'\n | ISSUER '<replaceable>issuer</replaceable>'\n | SUBJECT '<replaceable>subject</replaceable>'\n}\n\n<replaceable>resource_option</replaceable>: {\n MAX_QUERIES_PER_HOUR <replaceable>count</replaceable>\n | MAX_UPDATES_PER_HOUR <replaceable>count</replaceable>\n | MAX_CONNECTIONS_PER_HOUR <replaceable>count</replaceable>\n | MAX_USER_CONNECTIONS <replaceable>count</replaceable>\n}\n\n<replaceable>password_option</replaceable>: {\n PASSWORD EXPIRE [DEFAULT | NEVER | INTERVAL <replaceable>N</replaceable> DAY]\n | PASSWORD HISTORY {DEFAULT | <replaceable>N</replaceable>}\n | PASSWORD REUSE INTERVAL {DEFAULT | <replaceable>N</replaceable> DAY}\n | PASSWORD REQUIRE CURRENT [DEFAULT | OPTIONAL]\n | FAILED_LOGIN_ATTEMPTS <replaceable>N</replaceable>\n | PASSWORD_LOCK_TIME {<replaceable>N</replaceable> | UNBOUNDED}\n}\n\n<replaceable>lock_option</replaceable>: {\n ACCOUNT LOCK\n | ACCOUNT UNLOCK\n}"
}
]
},
{
"keywords": [
"DROP",
"ROLE",
"IF",
"EXISTS"
],
"description": [
{
"para": "<literal role=\"stmt\">DROP ROLE</literal> removes one or more\n roles (named collections of privileges). To use this statement,\n you must have the global <literal role=\"priv\">DROP\n ROLE</literal> or <literal role=\"priv\">CREATE USER</literal>\n privilege. When the <literal role=\"sysvar\">read_only</literal>\n system variable is enabled, <literal role=\"stmt\">DROP\n ROLE</literal> additionally requires the\n <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "As of MySQL 8.0.16, users who have the\n <literal role=\"priv\">CREATE USER</literal> privilege can use\n this statement to drop accounts that are locked or unlocked.\n Users who have the <literal role=\"priv\">DROP ROLE</literal>\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 <literal role=\"sysvar\">mandatory_roles</literal> system variable\n value cannot be dropped."
},
{
"para": "<literal role=\"stmt\">DROP ROLE</literal> 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 <literal>IF EXISTS</literal> 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 <literal>IF EXISTS</literal> 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 <xref linkend=\"role-names\" />. 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 <literal>'%'</literal>."
},
{
"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] <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ..."
}
]
},
{
"keywords": [
"DROP",
"USER",
"IF",
"EXISTS"
],
"description": [
{
"para": "The <literal role=\"stmt\">DROP USER</literal> 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 <literal role=\"sysvar\">mandatory_roles</literal> system variable\n value cannot be dropped."
},
{
"para": "To use <literal role=\"stmt\">DROP USER</literal>, you must have\n the global <literal role=\"priv\">CREATE USER</literal> privilege,\n or the <literal role=\"priv\">DELETE</literal> privilege for the\n <literal>mysql</literal> system schema. When the\n <literal role=\"sysvar\">read_only</literal> system variable is\n enabled, <literal role=\"stmt\">DROP USER</literal> additionally\n requires the <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "<literal role=\"stmt\">DROP USER</literal> 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 <literal>IF EXISTS</literal> 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 <literal>IF EXISTS</literal> 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 <xref linkend=\"account-names\" />. For example:"
},
{
"programlisting": ">\nDROP USER 'jeffrey'@'localhost';"
},
{
"para": "The host name part of the account name, if omitted, defaults to\n <literal>'%'</literal>."
}
],
"id": "DROP USER",
"syntax": [
{
"programlisting": ">\nDROP USER [IF EXISTS] <replaceable>user</replaceable> [, <replaceable>user</replaceable>] ..."
}
]
},
{
"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 <replaceable>priv_type</replaceable> [(<replaceable>column_list</replaceable>)]\n [, <replaceable>priv_type</replaceable> [(<replaceable>column_list</replaceable>)]] ...\n ON [<replaceable>object_type</replaceable>] <replaceable>priv_level</replaceable>\n TO <replaceable>user_or_role</replaceable> [, <replaceable>user_or_role</replaceable>] ...\n [WITH GRANT OPTION]\n [AS <replaceable>user</replaceable>\n [WITH ROLE\n DEFAULT\n | NONE\n | ALL\n | ALL EXCEPT <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ...\n | <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ...\n ]\n ]\n}\n\nGRANT PROXY ON <replaceable>user_or_role</replaceable>\n TO <replaceable>user_or_role</replaceable> [, <replaceable>user_or_role</replaceable>] ...\n [WITH GRANT OPTION]\n\nGRANT <replaceable>role</replaceable> [, <replaceable>role</replaceable>] ...\n TO <replaceable>user_or_role</replaceable> [, <replaceable>user_or_role</replaceable>] ...\n [WITH ADMIN OPTION]\n\n<replaceable>object_type</replaceable>: {\n TABLE\n | FUNCTION\n | PROCEDURE\n}\n\n<replaceable>priv_level</replaceable>: {\n *\n | *.*\n | <replaceable>db_name</replaceable>.*\n | <replaceable>db_name.tbl_name</replaceable>\n | <replaceable>tbl_name</replaceable>\n | <replaceable>db_name</replaceable>.<replaceable>routine_name</replaceable>\n}\n\n<replaceable>user_or_role</replaceable>: {\n <replaceable>user</replaceable> (see <xref linkend=\"account-names\" />)\n | <replaceable>role</replaceable> (see <xref linkend=\"role-names\" />)\n}"
},
{
"para": "The <literal role=\"stmt\">GRANT</literal> statement assigns\n privileges and roles to MySQL user accounts and roles. There are\n several aspects to the <literal role=\"stmt\">GRANT</literal>\n statement, described under the following topics:"
}
]
},
{
"keywords": [
"RENAME",
"USER"
],
"description": [
{
"para": "The <literal role=\"stmt\">RENAME USER</literal> 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 <literal role=\"stmt\">RENAME USER</literal>, you must have\n the global <literal role=\"priv\">CREATE USER</literal> privilege,\n or the <literal role=\"priv\">UPDATE</literal> privilege for the\n <literal>mysql</literal> system schema. When the\n <literal role=\"sysvar\">read_only</literal> system variable is\n enabled, <literal role=\"stmt\">RENAME USER</literal> additionally\n requires the <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege."
},
{
"para": "Each account name uses the format described in\n <xref linkend=\"account-names\" />. 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 <literal>'%'</literal>."
},
{
"para": "<literal role=\"stmt\">RENAME USER</literal> causes the privileges\n held by the old user to be those held by the new user. However,\n <literal role=\"stmt\">RENAME USER</literal> 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 <literal>DEFINER</literal> 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 <xref linkend=\"stored-objects-security\" />.)"
},
{
"para": "The privilege changes take effect as indicated in\n <xref linkend=\"privilege-changes\" />."
}
],
"id": "RENAME USER",
"syntax": [
{
"programlisting": ">\nRENAME USER <replaceable>old_user</replaceable> TO <replaceable>new_user</replaceable>\n [, <replaceable>old_user</replaceable> TO <replaceable>new_user</replaceable>] ..."
}
]
},
{
"keywords": [
"REVOKE",
"ALL",
"PRIVILEGES",
"GRANT",
"OPTION",
"PROXY"
],
"description": [
{
"para": "The <literal role=\"stmt\">REVOKE</literal> 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 <replaceable>priv_type</replaceable>,\n <replaceable>priv_level</replaceable>, and\n <replaceable>object_type</replaceable> values, and the syntax\n for specifying users and passwords, see <xref linkend=\"grant\" />."
},
{
"para": "For information about roles, see <xref linkend=\"roles\" />."
},
{
"para": "When the <literal role=\"sysvar\">read_only</literal> system\n variable is enabled, <literal role=\"stmt\">REVOKE</literal>\n requires the <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege in addition to\n any other required privileges described in the following\n discussion."
},
{
"para": "<literal role=\"stmt\">REVOKE</literal> 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 <xref linkend=\"account-names\" />. Each role name uses the format\n described in <xref linkend=\"role-names\" />. 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 <literal>'%'</literal>."
},
{
"para": "To use the first <literal role=\"stmt\">REVOKE</literal> syntax,\n you must have the <literal role=\"priv\">GRANT OPTION</literal>\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 <replaceable>user_or_role</replaceable> [, <replaceable>user_or_role</replaceable>] ..."
},
{
"para": "<literal>REVOKE ALL PRIVILEGES, GRANT OPTION</literal> does not\n revoke any roles."
},
{
"para": "To use this <literal role=\"stmt\">REVOKE</literal> syntax, you\n must have the global <literal role=\"priv\">CREATE USER</literal>\n privilege, or the <literal role=\"priv\">UPDATE</literal>\n privilege for the <literal>mysql</literal> system schema."
},
{
"para": "The syntax for which the <literal role=\"stmt\">REVOKE</literal>\n keyword is followed by one or more role names takes a\n <literal>FROM</literal> clause indicating one or more users or\n roles from which to revoke the roles."
},
{
"para": "Roles named in the\n <literal role=\"sysvar\">mandatory_roles</literal> 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 <literal role=\"priv\">SELECT</literal>, the\n account still can select after either role is revoked."
},
{
"para": "<literal>REVOKE ALL ON *.*</literal> (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 <replaceable>priv_type</replaceable> [(<replaceable>column_list</replaceable>)]\n [, <replaceable>priv_type</replaceable> [(<replaceable>column_list</replaceable>)]] ...\n ON [<replaceable>object_type</replaceable>] <replaceable>priv_level</replaceable>\n FROM <replaceable>user_or_role</replaceable> [, <replaceable>user_or_role</replaceable>] ...\n\nREVOKE ALL [PRIVILEGES], GRANT OPTION\n FROM <replaceable>user_or_role</replaceable> [, <replaceable>user_or_role</replaceable>] ...\n\nREVOKE PROXY ON <replaceable>user_or_role</replaceable>\n FROM <replaceable>user_or_role</replaceable> [, <replaceable>user_or_role</replaceable>] ...\n\nREVOKE <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ...\n FROM <replaceable>user_or_role</replaceable> [, <replaceable>user_or_role</replaceable> ] ...\n\n<replaceable>user_or_role</replaceable>: {\n <replaceable>user</replaceable> (see <xref linkend=\"account-names\" />)\n | <replaceable>role</replaceable> (see <xref linkend=\"role-names\" />.\n}"
}
]
},
{
"keywords": [
"SET",
"DEFAULT",
"ROLE",
"NONE",
"ALL"
],
"description": [
{
"para": "For each <replaceable>user</replaceable> named immediately after\n the <literal>TO</literal> 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 <literal condition=\"set-role\" role=\"stmt\">SET ROLE\n DEFAULT</literal> statement during a session."
},
{
"para": "<literal role=\"stmt\">SET DEFAULT ROLE</literal> is alternative\n syntax for <literal condition=\"alter-user\" role=\"stmt\">ALTER\n USER ... DEFAULT ROLE</literal> (see\n <xref linkend=\"alter-user\" />). However,\n <literal role=\"stmt\">ALTER USER</literal> can set the default\n for only a single user, whereas <literal role=\"stmt\">SET DEFAULT\n ROLE</literal> can set the default for multiple users. On the\n other hand, you can specify <literal>CURRENT_USER</literal> as\n the user name for the <literal role=\"stmt\">ALTER USER</literal>\n statement, whereas you cannot for <literal role=\"stmt\">SET\n DEFAULT ROLE</literal>."
},
{
"para": "<literal role=\"stmt\">SET DEFAULT ROLE</literal> requires these\n privileges:"
},
{
"itemizedlist": [
[
{
"para": "Setting the default roles for another user requires the\n global <literal role=\"priv\">CREATE USER</literal> privilege,\n or the <literal role=\"priv\">UPDATE</literal> privilege for\n the <literal>mysql.default_roles</literal> 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 <xref linkend=\"role-names\" />. 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 <literal>'%'</literal>."
},
{
"para": "The clause following the <literal>DEFAULT ROLE</literal>\n keywords permits these values:"
},
{
"itemizedlist": [
[
{
"para": "<literal>NONE</literal>: Set the default to\n <literal>NONE</literal> (no roles)."
}
],
[
{
"para": "<literal>ALL</literal>: Set the default to all roles granted\n to the account."
}
],
[
{
"para": "<literal><replaceable>role</replaceable> [,\n <replaceable>role</replaceable> ] ...</literal>: Set the\n default to the named roles, which must exist and be granted\n to the account at the time <literal role=\"stmt\">SET DEFAULT\n ROLE</literal> is executed."
}
]
]
}
],
"id": "SET DEFAULT ROLE",
"syntax": [
{
"programlisting": ">\nSET DEFAULT ROLE\n {NONE | ALL | <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ...}\n TO <replaceable>user</replaceable> [, <replaceable>user</replaceable> ] ..."
}
]
},
{
"keywords": [
"SET",
"PASSWORD",
"FOR",
"REPLACE",
"RETAIN",
"CURRENT",
"TO",
"RANDOM"
],
"description": [
{
"para": "The <literal role=\"stmt\">SET PASSWORD</literal> 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 <literal>'<replaceable>auth_string</replaceable>'</literal> and\n <literal>'<replaceable>current_auth_string</replaceable>'</literal>\n each represent a cleartext (unencrypted) password."
},
{
"para": "The <literal>REPLACE\n '<replaceable>current_auth_string</replaceable>'</literal>\n clause performs password verification and is available as of\n MySQL 8.0.13. If given:"
},
{
"itemizedlist": [
[
{
"para": "<literal>REPLACE</literal> 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": "<literal>REPLACE</literal> 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 <xref linkend=\"password-management\" />."
},
{
"para": "The <literal>RETAIN CURRENT PASSWORD</literal> clause implements\n dual-password capability and is available as of MySQL 8.0.14. If\n given:"
},
{
"itemizedlist": [
[
{
"para": "<literal>RETAIN CURRENT PASSWORD</literal> 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 <literal role=\"stmt\">SET PASSWORD</literal>\n statement is empty, the secondary password becomes empty as\n well, even if <literal>RETAIN CURRENT PASSWORD</literal> is\n given.)"
}
],
[
{
"para": "If you specify <literal>RETAIN CURRENT PASSWORD</literal>\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 <literal>RETAIN CURRENT\n PASSWORD</literal>, the secondary password remains\n unchanged."
}
]
]
},
{
"para": "For more information about use of dual passwords, see\n <xref linkend=\"password-management\" />."
},
{
"para": "<literal role=\"stmt\">SET PASSWORD</literal> permits these\n <replaceable>auth_option</replaceable> syntaxes:"
},
{
"itemizedlist": [
[
{
"para": "<literal>=\n '<replaceable>auth_string</replaceable>'</literal>"
},
{
"para": "Assigns the account the given literal password."
}
],
[
{
"para": "<literal>TO RANDOM</literal>"
},
{
"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 <xref linkend=\"random-password-generation\" />."
},
{
"para": "Random password generation is available as of MySQL 8.0.18."
}
]
]
},
{
"para": "<literal role=\"stmt\">SET PASSWORD</literal> can be used with or\n without a <literal>FOR</literal> clause that explicitly names a\n user account:"
},
{
"itemizedlist": [
[
{
"para": "With a <literal>FOR\n <replaceable>user</replaceable></literal> clause, the\n statement sets the password for the named account, which\n must exist:"
},
{
"programlisting": ">\nSET PASSWORD FOR 'jeffrey'@'localhost' = '<replaceable>auth_string</replaceable>';"
}
],
[
{
"para": "With no <literal>FOR\n <replaceable>user</replaceable></literal> clause, the\n statement sets the password for the current user:"
},
{
"programlisting": ">\nSET PASSWORD = '<replaceable>auth_string</replaceable>';"
},
{
"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 <literal role=\"func\">CURRENT_USER()</literal> function:"
},
{
"programlisting": ">\nSELECT CURRENT_USER();"
}
]
]
},
{
"para": "If a <literal>FOR <replaceable>user</replaceable></literal>\n clause is given, the account name uses the format described in\n <xref linkend=\"account-names\" />. For example:"
},
{
"programlisting": ">\nSET PASSWORD FOR 'bob'@'%.example.org' = '<replaceable>auth_string</replaceable>';"
},
{
"para": "The host name part of the account name, if omitted, defaults to\n <literal>'%'</literal>."
},
{
"para": "<literal role=\"stmt\">SET PASSWORD</literal> 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 <literal>mysql.user</literal> 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 <literal>FOR</literal> clause) requires the\n <literal role=\"stmt\">UPDATE</literal> privilege for the\n <literal>mysql</literal> system schema. Setting the password for\n yourself (for a nonanonymous account with no\n <literal>FOR</literal> clause) requires no special privileges."
},
{
"para": "Statements that modify secondary passwords require these\n privileges:"
},
{
"itemizedlist": [
[
{
"para": "The\n <literal role=\"priv\">APPLICATION_PASSWORD_ADMIN</literal>\n privilege is required to use the <literal>RETAIN CURRENT\n PASSWORD</literal> clause for <literal role=\"stmt\">SET\n PASSWORD</literal> 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 <literal role=\"priv\">CREATE USER</literal> privilege rather\n than\n <literal role=\"priv\">APPLICATION_PASSWORD_ADMIN</literal>."
}
]
]
},
{
"para": "When the <literal role=\"sysvar\">read_only</literal> system\n variable is enabled, <literal role=\"stmt\">SET PASSWORD</literal>\n requires the <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege in addition to\n any other required privileges."
}
],
"id": "SET PASSWORD",
"syntax": [
{
"programlisting": ">\nSET PASSWORD [FOR <replaceable>user</replaceable>] <replaceable>auth_option</replaceable>\n [REPLACE '<replaceable>current_auth_string</replaceable>']\n [RETAIN CURRENT PASSWORD]\n\n<replaceable>auth_option</replaceable>: {\n = '<replaceable>auth_string</replaceable>'\n | TO RANDOM\n}"
}
]
},
{
"keywords": [
"SET",
"ROLE",
"DEFAULT",
"NONE",
"ALL",
"EXCEPT"
],
"description": [
{
"para": "<literal role=\"stmt\">SET ROLE</literal> 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 <literal role=\"sysvar\">mandatory_roles</literal> 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 <xref linkend=\"role-names\" />. The host name part of the role\n name, if omitted, defaults to <literal>'%'</literal>."
},
{
"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": "<literal>DEFAULT</literal>: Activate the account default\n roles. Default roles are those specified with\n <literal role=\"stmt\">SET DEFAULT ROLE</literal>."
},
{
"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 <literal role=\"sysvar\">activate_all_roles_on_login</literal>\n system variable is enabled, the server activates all granted\n roles. Otherwise, the server executes\n <literal condition=\"set-role\" role=\"stmt\">SET ROLE\n DEFAULT</literal> 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 <literal condition=\"set-role\" role=\"stmt\">SET ROLE\n DEFAULT</literal> 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": "<literal>NONE</literal>: Set the active roles to\n <literal>NONE</literal> (no active roles)."
}
],
[
{
"para": "<literal>ALL</literal>: Activate all roles granted to the\n account."
}
],
[
{
"para": "<literal>ALL EXCEPT <replaceable>role</replaceable> [,\n <replaceable>role</replaceable> ] ...</literal>: 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": "<literal><replaceable>role</replaceable> [,\n <replaceable>role</replaceable> ] ...</literal>: 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 <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ...\n | <replaceable>role</replaceable> [, <replaceable>role</replaceable> ] ...\n}"
}
]
},
{
"keywords": [
"ALTER",
"RESOURCE",
"GROUP",
"VCPU",
"THREAD_PRIORITY",
"ENABLE",
"DISABLE",
"FORCE"
],
"description": [
{
"para": "<literal role=\"stmt\">ALTER RESOURCE GROUP</literal> is used for\n resource group management (see\n <xref linkend=\"resource-groups\" />). This statement alters\n modifiable attributes of an existing resource group. It requires\n the <literal role=\"priv\">RESOURCE_GROUP_ADMIN</literal>\n privilege."
},
{
"para": "<replaceable>group_name</replaceable> 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 <literal role=\"stmt\">ALTER\n RESOURCE GROUP</literal>. These attributes are specified the\n same way as described for <literal role=\"stmt\">CREATE RESOURCE\n GROUP</literal> (see <xref linkend=\"create-resource-group\" />).\n Only the attributes specified are altered. Unspecified\n attributes retain their current values."
},
{
"para": "The <literal>FORCE</literal> modifier is used with\n <literal>DISABLE</literal>. It determines statement behavior if\n the resource group has any threads assigned to it:"
},
{
"itemizedlist": [
[
{
"para": "If <literal>FORCE</literal> 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 <literal>FORCE</literal> is given, existing threads in\n the group are moved to their respective default group\n (system threads to <literal>SYS_default</literal>, user\n threads to <literal>USR_default</literal>)."
}
]
]
},
{
"para": "The name and type attributes are set at group creation time and\n cannot be modified thereafter with <literal role=\"stmt\">ALTER\n RESOURCE GROUP</literal>."
},
{
"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. <literal role=\"stmt\">ALTER RESOURCE GROUP</literal>\n statements are not written to the binary log and are not\n replicated."
}
],
"id": "ALTER RESOURCE GROUP",
"syntax": [
{
"programlisting": ">\nALTER RESOURCE GROUP <replaceable>group_name</replaceable>\n [VCPU [=] <replaceable>vcpu_spec</replaceable> [, <replaceable>vcpu_spec</replaceable>] ...]\n [THREAD_PRIORITY [=] <replaceable>N</replaceable>]\n [ENABLE|DISABLE [FORCE]]\n\n<replaceable>vcpu_spec</replaceable>: {<replaceable>N</replaceable> | <replaceable>M</replaceable> - <replaceable>N</replaceable>}"
}
]
},
{
"keywords": [
"CREATE",
"RESOURCE",
"GROUP",
"TYPE",
"SYSTEM",
"USER",
"VCPU",
"THREAD_PRIORITY",
"ENABLE",
"DISABLE"
],
"description": [
{
"para": "<literal role=\"stmt\">CREATE RESOURCE GROUP</literal> is used for\n resource group management (see\n <xref linkend=\"resource-groups\" />). This statement creates a new\n resource group and assigns its initial attribute values. It\n requires the <literal role=\"priv\">RESOURCE_GROUP_ADMIN</literal>\n privilege."
},
{
"para": "<replaceable>group_name</replaceable> identifies which resource\n group to create. If the group already exists, an error occurs."
},
{
"para": "The <literal>TYPE</literal> attribute is required. It should be\n <literal>SYSTEM</literal> for a system resource group,\n <literal>USER</literal> for a user resource group. The group\n type affects permitted <literal>THREAD_PRIORITY</literal>\n values, as described later."
},
{
"para": "The <literal>VCPU</literal> attribute indicates the CPU\n affinity; that is, the set of virtual CPUs the group can use:"
},
{
"itemizedlist": [
[
{
"para": "If <literal>VCPU</literal> is not given, the resource group\n has no CPU affinity and can use all available CPUs."
}
],
[
{
"para": "If <literal>VCPU</literal> 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 <replaceable>M</replaceable> minus\n <replaceable>N</replaceable>, where\n <replaceable>M</replaceable> is less than or equal to\n <replaceable>N</replaceable> 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 <literal>VCPU</literal> 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 <literal>THREAD_PRIORITY</literal> attribute indicates the\n priority for threads assigned to the group:"
},
{
"itemizedlist": [
[
{
"para": "If <literal>THREAD_PRIORITY</literal> is not given, the\n default priority is 0."
}
],
[
{
"para": "If <literal>THREAD_PRIORITY</literal> 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": "<literal>ENABLE</literal> and <literal>DISABLE</literal> 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. <literal role=\"stmt\">CREATE RESOURCE GROUP</literal>\n statements are not written to the binary log and are not\n replicated."
}
],
"id": "CREATE RESOURCE GROUP",
"syntax": [
{
"programlisting": ">\nCREATE RESOURCE GROUP <replaceable>group_name</replaceable>\n TYPE = {SYSTEM|USER}\n [VCPU [=] <replaceable>vcpu_spec</replaceable> [, <replaceable>vcpu_spec</replaceable>] ...]\n [THREAD_PRIORITY [=] <replaceable>N</replaceable>]\n [ENABLE|DISABLE]\n\n<replaceable>vcpu_spec</replaceable>: {<replaceable>N</replaceable> | <replaceable>M</replaceable> - <replaceable>N</replaceable>}"
}
]
},
{
"keywords": [
"DROP",
"RESOURCE",
"GROUP",
"FORCE"
],
"description": [
{
"para": "<literal role=\"stmt\">DROP RESOURCE GROUP</literal> is used for\n resource group management (see\n <xref linkend=\"resource-groups\" />). This statement drops a\n resource group. It requires the\n <literal role=\"priv\">RESOURCE_GROUP_ADMIN</literal> privilege."
},
{
"para": "<replaceable>group_name</replaceable> identifies which resource\n group to drop. If the group does not exist, an error occurs."
},
{
"para": "The <literal>FORCE</literal> modifier determines statement\n behavior if the resource group has any threads assigned to it:"
},
{
"itemizedlist": [
[
{
"para": "If <literal>FORCE</literal> is not given and any threads are\n assigned to the group, an error occurs."
}
],
[
{
"para": "If <literal>FORCE</literal> is given, existing threads in\n the group are moved to their respective default group\n (system threads to <literal>SYS_default</literal>, user\n threads to <literal>USR_default</literal>)."
}
]
]
},
{
"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. <literal role=\"stmt\">DROP RESOURCE GROUP</literal>\n statements are not written to the binary log and are not\n replicated."
}
],
"id": "DROP RESOURCE GROUP",
"syntax": [
{
"programlisting": ">\nDROP RESOURCE GROUP <replaceable>group_name</replaceable> [FORCE]"
}
]
},
{
"keywords": [
"SET",
"RESOURCE",
"GROUP",
"FOR"
],
"description": [
{
"para": "<literal role=\"stmt\">SET RESOURCE GROUP</literal> is used for\n resource group management (see\n <xref linkend=\"resource-groups\" />). This statement assigns\n threads to a resource group. It requires the\n <literal role=\"priv\">RESOURCE_GROUP_ADMIN</literal> or\n <literal role=\"priv\">RESOURCE_GROUP_USER</literal> privilege."
},
{
"para": "<replaceable>group_name</replaceable> identifies which resource\n group to be assigned. Any <replaceable>thread_id</replaceable>\n values indicate threads to assign to the group. Thread IDs can\n be determined from the Performance Schema\n <literal role=\"ps\">threads</literal> table. If the resource\n group or any named thread ID does not exist, an error occurs."
},
{
"para": "With no <literal>FOR</literal> clause, the statement assigns the\n current thread for the session to the resource group."
},
{
"para": "With a <literal>FOR</literal> 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. <literal role=\"stmt\">SET RESOURCE GROUP</literal>\n statements are not written to the binary log and are not\n replicated."
},
{
"para": "An alternative to <literal role=\"stmt\">SET RESOURCE\n GROUP</literal> is the\n <literal role=\"opthint\">RESOURCE_GROUP</literal> optimizer hint,\n which assigns individual statements to a resource group. See\n <xref linkend=\"optimizer-hints\" />."
}
],
"id": "SET RESOURCE GROUP",
"syntax": [
{
"programlisting": ">\nSET RESOURCE GROUP <replaceable>group_name</replaceable>\n [FOR <replaceable>thread_id</replaceable> [, <replaceable>thread_id</replaceable>] ...]"
}
]
},
{
"keywords": [
"ANALYZE",
"TABLE",
"NO_WRITE_TO_BINLOG",
"LOCAL"
],
"description": [
{
"para": "<literal role=\"stmt\">ANALYZE TABLE</literal> generates table\n statistics:"
},
{
"itemizedlist": [
[
{
"para": "<literal role=\"stmt\">ANALYZE TABLE</literal> without either\n <literal>HISTOGRAM</literal> clause performs a key\n distribution analysis and stores the distribution for the\n named table or tables. For <literal>MyISAM</literal> tables,\n <literal role=\"stmt\">ANALYZE TABLE</literal> for key\n distribution analysis is equivalent to using\n <command>myisamchk --analyze</command>."
}
],
[
{
"para": "<literal role=\"stmt\">ANALYZE TABLE</literal> with the\n <literal>UPDATE HISTOGRAM</literal> 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": "<literal role=\"stmt\">ANALYZE TABLE</literal> with the\n <literal>DROP HISTOGRAM</literal> 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 <literal role=\"priv\">SELECT</literal>\n and <literal role=\"priv\">INSERT</literal> privileges for the\n table."
},
{
"para": "<literal role=\"stmt\">ANALYZE TABLE</literal> works with\n <literal>InnoDB</literal>, <literal>NDB</literal>, and\n <literal>MyISAM</literal> tables. It does not work with views."
},
{
"para": "If the <literal role=\"sysvar\">innodb_read_only</literal> system\n variable is enabled, <literal role=\"stmt\">ANALYZE\n TABLE</literal> may fail because it cannot update statistics\n tables in the data dictionary, which use\n <literal>InnoDB</literal>. For <literal role=\"stmt\">ANALYZE\n TABLE</literal> 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 <literal>MyISAM</literal> table). To\n obtain the updated distribution statistics, set\n <literal role=\"sysvar\">information_schema_stats_expiry=0</literal>."
},
{
"para": "<literal role=\"stmt\">ANALYZE TABLE</literal> is supported for\n partitioned tables, and you can use <literal>ALTER TABLE ...\n ANALYZE PARTITION</literal> to analyze one or more partitions;\n for more information, see <xref linkend=\"alter-table\" />, and\n <xref linkend=\"partitioning-maintenance\" />."
},
{
"para": "During the analysis, the table is locked with a read lock for\n <literal>InnoDB</literal> and <literal>MyISAM</literal>."
},
{
"para": "<literal role=\"stmt\">ANALYZE TABLE</literal> 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 <literal role=\"stmt\">ANALYZE TABLE</literal> 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 <literal role=\"stmt\">ANALYZE\n TABLE</literal> statements to the binary log so that they\n replicate to replication slaves. To suppress logging, specify\n the optional <literal>NO_WRITE_TO_BINLOG</literal> keyword or\n its alias <literal>LOCAL</literal>."
}
],
"id": "ANALYZE TABLE",
"syntax": [
{
"programlisting": ">\nANALYZE [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ...\n\nANALYZE [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE <replaceable>tbl_name</replaceable>\n UPDATE HISTOGRAM ON <replaceable>col_name</replaceable> [, <replaceable>col_name</replaceable>] ...\n [WITH <replaceable>N</replaceable> BUCKETS]\n\nANALYZE [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE <replaceable>tbl_name</replaceable>\n DROP HISTOGRAM ON <replaceable>col_name</replaceable> [, <replaceable>col_name</replaceable>] ..."
}
]
},
{
"keywords": [
"CHECK",
"TABLE",
"QUICK",
"FAST",
"MEDIUM",
"UPGRADE"
],
"description": [
{
"para": "<literal role=\"stmt\">CHECK TABLE</literal> checks a table or\n tables for errors. <literal role=\"stmt\">CHECK TABLE</literal>\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": "<literal role=\"stmt\">CHECK TABLE</literal> works for\n <literal role=\"se\">InnoDB</literal>,\n <literal role=\"se\">MyISAM</literal>,\n <literal role=\"se\">ARCHIVE</literal>, and\n <literal role=\"se\">CSV</literal> tables."
},
{
"para": "Before running <literal role=\"stmt\">CHECK TABLE</literal> on\n <literal>InnoDB</literal> tables, see\n <xref linkend=\"check-table-innodb\" />."
},
{
"para": "<literal role=\"stmt\">CHECK TABLE</literal> is supported for\n partitioned tables, and you can use <literal>ALTER TABLE ...\n CHECK PARTITION</literal> to check one or more partitions; for\n more information, see <xref linkend=\"alter-table\" />, and\n <xref linkend=\"partitioning-maintenance\" />."
},
{
"para": "<literal role=\"stmt\">CHECK TABLE</literal> ignores virtual\n generated columns that are not indexed."
}
],
"id": "CHECK TABLE",
"syntax": [
{
"programlisting": ">\nCHECK TABLE <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ... [<replaceable>option</replaceable>] ...\n\n<replaceable>option</replaceable>: {\n FOR UPGRADE\n | QUICK\n | FAST\n | MEDIUM\n | EXTENDED\n | CHANGED\n}"
}
]
},
{
"keywords": [
"CHECKSUM",
"TABLE"
],
"description": [
{
"para": "<literal role=\"stmt\">CHECKSUM TABLE</literal> reports a\n <link linkend=\"glos_checksum\">checksum</link> 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 <literal role=\"priv\">SELECT</literal> privilege for the table."
},
{
"para": "This statement is not supported for views. If you run\n <literal role=\"stmt\">CHECKSUM TABLE</literal> against a view,\n the <literal>Checksum</literal> value is always\n <literal>NULL</literal>, and a warning is returned."
},
{
"para": "For a nonexistent table, <literal role=\"stmt\">CHECKSUM\n TABLE</literal> returns <literal>NULL</literal> and generates a\n warning."
},
{
"para": "During the checksum operation, the table is locked with a read\n lock for <literal>InnoDB</literal> and\n <literal>MyISAM</literal>."
}
],
"id": "CHECKSUM TABLE",
"syntax": [
{
"programlisting": ">\nCHECKSUM TABLE <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ... [QUICK | EXTENDED]"
}
]
},
{
"keywords": [
"OPTIMIZE",
"TABLE",
"NO_WRITE_TO_BINLOG",
"LOCAL"
],
"description": [
{
"para": "<literal role=\"stmt\">OPTIMIZE TABLE</literal> 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 <link linkend=\"glos_storage_engine\">storage engine</link> used\n by that table."
},
{
"para": "Use <literal role=\"stmt\">OPTIMIZE TABLE</literal> in these\n cases, depending on the type of table:"
},
{
"itemizedlist": [
[
{
"para": "After doing substantial insert, update, or delete operations\n on an <literal>InnoDB</literal> table that has its own\n <link linkend=\"glos_ibd_file\">.ibd file</link> because it\n was created with the\n <literal role=\"sysvar\">innodb_file_per_table</literal>\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 <literal>FULLTEXT</literal>\n index in an <literal>InnoDB</literal> table. Set the\n configuration option\n <literal role=\"sysvar\">innodb_optimize_fulltext_only=1</literal>\n first. To keep the index maintenance period to a reasonable\n time, set the\n <literal role=\"sysvar\">innodb_ft_num_word_optimize</literal>\n option to specify how many words to update in the search\n index, and run a sequence of <literal>OPTIMIZE\n TABLE</literal> statements until the search index is fully\n updated."
}
],
[
{
"para": "After deleting a large part of a <literal>MyISAM</literal>\n or <literal>ARCHIVE</literal> table, or making many changes\n to a <literal>MyISAM</literal> or <literal>ARCHIVE\n </literal>table with variable-length rows (tables that have\n <literal role=\"type\">VARCHAR</literal>,\n <literal role=\"type\">VARBINARY</literal>,\n <literal role=\"type\">BLOB</literal>, or\n <literal role=\"type\">TEXT</literal> columns). Deleted rows\n are maintained in a linked list and subsequent\n <literal role=\"stmt\">INSERT</literal> operations reuse old\n row positions. You can use <literal role=\"stmt\">OPTIMIZE\n TABLE</literal> 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 <literal role=\"priv\">SELECT</literal>\n and <literal role=\"priv\">INSERT</literal> privileges for the\n table."
},
{
"para": "<literal role=\"stmt\">OPTIMIZE TABLE</literal> works for\n <literal role=\"se\">InnoDB</literal>,\n <literal role=\"se\">MyISAM</literal>, and\n <literal role=\"se\">ARCHIVE</literal> tables.\n <literal role=\"stmt\">OPTIMIZE TABLE</literal> is also supported\n for dynamic columns of in-memory\n <literal role=\"se\">NDB</literal> 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 <literal>OPTIMIZE</literal>\n on NDB Cluster tables can be tuned using\n <option role=\"mysqld\">--ndb-optimization-delay</option>, which\n controls the length of time to wait between processing batches\n of rows by <literal role=\"stmt\">OPTIMIZE TABLE</literal>. For\n more information, see\n <xref linkend=\"mysql-cluster-limitations-resolved\" />."
},
{
"para": "For NDB Cluster tables, <literal role=\"stmt\">OPTIMIZE\n TABLE</literal> can be interrupted by (for example) killing the\n SQL thread performing the <literal>OPTIMIZE</literal> operation."
},
{
"para": "By default, <literal role=\"stmt\">OPTIMIZE TABLE</literal> does\n <emphasis>not</emphasis> work for tables created using any other\n storage engine and returns a result indicating this lack of\n support. You can make <literal role=\"stmt\">OPTIMIZE\n TABLE</literal> work for other storage engines by starting\n <command>mysqld</command> with the\n <option role=\"mysqld\">--skip-new</option> option. In this case,\n <literal role=\"stmt\">OPTIMIZE TABLE</literal> is just mapped to\n <literal role=\"stmt\">ALTER TABLE</literal>."
},
{
"para": "This statement does not work with views."
},
{
"para": "<literal role=\"stmt\">OPTIMIZE TABLE</literal> is supported for\n partitioned tables. For information about using this statement\n with partitioned tables and table partitions, see\n <xref linkend=\"partitioning-maintenance\" />."
},
{
"para": "By default, the server writes <literal role=\"stmt\">OPTIMIZE\n TABLE</literal> statements to the binary log so that they\n replicate to replication slaves. To suppress logging, specify\n the optional <literal>NO_WRITE_TO_BINLOG</literal> keyword or\n its alias <literal>LOCAL</literal>."
}
],
"id": "OPTIMIZE TABLE",
"syntax": [
{
"programlisting": ">\nOPTIMIZE [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ..."
}
]
},
{
"keywords": [
"REPAIR",
"TABLE",
"USE_FRM",
"QUICK",
"EXTENDED",
"NO_WRITE_TO_BINLOG",
"LOCAL"
],
"description": [
{
"para": "<literal role=\"stmt\">REPAIR TABLE</literal> repairs a possibly\n corrupted table, for certain storage engines only."
},
{
"para": "This statement requires <literal role=\"priv\">SELECT</literal>\n and <literal role=\"priv\">INSERT</literal> privileges for the\n table."
},
{
"para": "Although normally you should never have to run\n <literal role=\"stmt\">REPAIR TABLE</literal>, if disaster\n strikes, this statement is very likely to get back all your data\n from a <literal>MyISAM</literal> table. If your tables become\n corrupted often, try to find the reason for it, to eliminate the\n need to use <literal role=\"stmt\">REPAIR TABLE</literal>. See\n <xref linkend=\"crashing\" />, and\n <xref linkend=\"myisam-table-problems\" />."
},
{
"para": "<literal role=\"stmt\">REPAIR TABLE</literal> checks the table to\n see whether an upgrade is required. If so, it performs the\n upgrade, following the same rules as\n <literal condition=\"check-table\" role=\"stmt\">CHECK TABLE ... FOR\n UPGRADE</literal>. See <xref linkend=\"check-table\" />, for more\n information."
}
],
"id": "REPAIR TABLE",
"syntax": [
{
"programlisting": ">\nREPAIR [NO_WRITE_TO_BINLOG | LOCAL]\n TABLE <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ...\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 <literal role=\"func\">ABS()</literal> or\n <literal role=\"func\">CONCAT()</literal>."
},
{
"para": "<replaceable>function_name</replaceable> is the name that should\n be used in SQL statements to invoke the function. The\n <literal>RETURNS</literal> clause indicates the type of the\n function's return value. <literal role=\"type\">DECIMAL</literal>\n is a legal value after <literal>RETURNS</literal>, but currently\n <literal role=\"type\">DECIMAL</literal> functions return string\n values and should be written like <literal>STRING</literal>\n functions."
},
{
"para": "<replaceable>shared_library_name</replaceable> 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 <literal role=\"sysvar\">plugin_dir</literal> system variable. For\n more information, see <xref linkend=\"udf-loading\" />."
},
{
"para": "To create a function, you must have the\n <literal role=\"priv\">INSERT</literal> privilege for the\n <literal>mysql</literal> system schema. This is necessary\n because <literal role=\"stmt\">CREATE FUNCTION</literal> adds a\n row to the <literal>mysql.func</literal> system table that\n records the function's name, type, and shared library name."
},
{
"para": "UDFs registered using <literal role=\"stmt\">CREATE\n FUNCTION</literal> are listed in the Performance Schema\n <literal role=\"ps\">user_defined_functions</literal> table; see\n <xref linkend=\"user-defined-functions-table\" />."
}
],
"id": "CREATE FUNCTION UDF",
"syntax": [
{
"programlisting": ">\nCREATE [AGGREGATE] FUNCTION <replaceable>function_name</replaceable>\n RETURNS {STRING|INTEGER|REAL|DECIMAL}\n SONAME <replaceable>shared_library_name</replaceable>"
}
]
},
{
"keywords": [
"DROP",
"FUNCTION"
],
"description": [
{
"para": "This statement drops the user-defined function (UDF) named\n <replaceable>function_name</replaceable>."
},
{
"para": "To drop a function, you must have the\n <literal role=\"priv\">DELETE</literal> privilege for the\n <literal>mysql</literal> system schema. This is because\n <literal role=\"stmt\">DROP FUNCTION</literal> removes a row from\n the <literal>mysql.func</literal> system table that records the\n function's name, type, and shared library name."
}
],
"id": "DROP FUNCTION UDF",
"syntax": [
{
"programlisting": ">\nDROP FUNCTION <replaceable>function_name</replaceable>"
}
]
},
{
"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 <xref linkend=\"server-components\" />.\n <literal role=\"stmt\">INSTALL COMPONENT</literal> requires the\n <literal role=\"priv\">INSERT</literal> privilege for the\n <literal>mysql.component</literal> system table."
},
{
"para": "Example:"
},
{
"programlisting": ">\nINSTALL COMPONENT 'file://component1', 'file://component2';"
},
{
"para": "Component names are URNs that begin with\n <literal>file://</literal> and indicate the base name of the\n file that implements the component, located in the directory\n named by the <literal role=\"sysvar\">plugin_dir</literal> system\n variable. Component names do not include any platform-dependent\n file name suffix such as <filename>.so</filename> or\n <filename>.dll</filename>. (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 <literal>mysql.component</literal> system table that serves as a\n registry. For subsequent server restarts, any components listed\n in <literal>mysql.component</literal> are loaded by the loader\n service during the startup sequence. This occurs even if the\n server is started with the\n <option role=\"mysqld\">--skip-grant-tables</option> 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 <replaceable>component_name</replaceable> [, <replaceable>component_name</replaceable> ] ..."
}
]
},
{
"keywords": [
"INSTALL",
"PLUGIN"
],
"description": [
{
"para": "This statement installs a server plugin. It requires the\n <literal role=\"priv\">INSERT</literal> privilege for the\n <literal>mysql.plugin</literal> system table."
},
{
"para": "<replaceable>plugin_name</replaceable> is the name of the plugin\n as defined in the plugin descriptor structure contained in the\n library file (see <xref linkend=\"plugin-data-structures\" />).\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": "<replaceable>shared_library_name</replaceable> is the name of\n the shared library that contains the plugin code. The name\n includes the file name extension (for example,\n <filename>libmyplugin.so</filename>,\n <filename>libmyplugin.dll</filename>, or\n <filename>libmyplugin.dylib</filename>)."
},
{
"para": "The shared library must be located in the plugin directory (the\n directory named by the\n <literal role=\"sysvar\">plugin_dir</literal> system variable).\n The library must be in the plugin directory itself, not in a\n subdirectory. By default,\n <literal role=\"sysvar\">plugin_dir</literal> is the\n <filename>plugin</filename> directory under the directory named\n by the <literal>pkglibdir</literal> configuration variable, but\n it can be changed by setting the value of\n <literal role=\"sysvar\">plugin_dir</literal> at server startup.\n For example, set its value in a <filename>my.cnf</filename>\n file:"
},
{
"programlisting": ">\n[mysqld]\nplugin_dir=<replaceable>/path/to/plugin/directory</replaceable>"
},
{
"para": "If the value of <literal role=\"sysvar\">plugin_dir</literal> is a\n relative path name, it is taken to be relative to the MySQL base\n directory (the value of the\n <literal role=\"sysvar\">basedir</literal> system variable)."
},
{
"para": "<literal role=\"stmt\">INSTALL PLUGIN</literal> 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": "<literal role=\"stmt\">INSTALL PLUGIN</literal> also registers the\n plugin by adding a line that indicates the plugin name and\n library file name to the <literal>mysql.plugin</literal> system\n table. At server startup, the server loads and initializes any\n plugin that is listed in <literal>mysql.plugin</literal>. This\n means that a plugin is installed with\n <literal role=\"stmt\">INSTALL PLUGIN</literal> 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 role=\"mysqld\">--skip-grant-tables</option> option."
},
{
"para": "A plugin library can contain multiple plugins. For each of them\n to be installed, use a separate <literal role=\"stmt\">INSTALL\n PLUGIN</literal> statement. Each statement names a different\n plugin, but all of them specify the same library name."
}
],
"id": "INSTALL PLUGIN",
"syntax": [
{
"programlisting": ">\nINSTALL PLUGIN <replaceable>plugin_name</replaceable> SONAME '<replaceable>shared_library_name</replaceable>'"
}
]
},
{
"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 <xref linkend=\"server-components\" />.\n <literal role=\"stmt\">UNINSTALL COMPONENT</literal> is the\n complement of <literal role=\"stmt\">INSTALL COMPONENT</literal>.\n It requires the <literal role=\"priv\">DELETE</literal> privilege\n for the <literal>mysql.component</literal> system table."
},
{
"para": "Example:"
},
{
"programlisting": ">\nUNINSTALL COMPONENT 'file://component1', 'file://component2';"
},
{
"para": "For information about component naming, see\n <xref linkend=\"install-component\" />."
},
{
"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 <literal>mysql.component</literal> 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 <replaceable>component_name</replaceable> [, <replaceable>component_name</replaceable> ] ..."
}
]
},
{
"keywords": [
"UNINSTALL",
"PLUGIN"
],
"description": [
{
"para": "This statement removes an installed server plugin. It requires\n the <literal role=\"priv\">DELETE</literal> privilege for the\n <literal>mysql.plugin</literal> system table.\n <literal role=\"stmt\">UNINSTALL PLUGIN</literal> is the\n complement of <literal role=\"stmt\">INSTALL PLUGIN</literal>."
},
{
"para": "<replaceable>plugin_name</replaceable> must be the name of some\n plugin that is listed in the <literal>mysql.plugin</literal>\n table. The server executes the plugin's deinitialization\n function and removes the row for the plugin from the\n <literal>mysql.plugin</literal> system table, so that subsequent\n server restarts will not load and initialize the plugin.\n <literal role=\"stmt\">UNINSTALL PLUGIN</literal> does not remove\n the plugin's shared library file."
}
],
"id": "UNINSTALL PLUGIN",
"syntax": [
{
"programlisting": ">\nUNINSTALL PLUGIN <replaceable>plugin_name</replaceable>"
}
]
},
{
"keywords": [
"CLONE"
],
"description": [
{
"para": "The <literal role=\"stmt\">CLONE</literal> statement is used to\n clone data locally or from a remote MySQL server instance. To use\n <literal role=\"stmt\">CLONE</literal> syntax, the clone plugin must\n be installed. See <xref linkend=\"clone-plugin\" />."
},
{
"para": "<literal condition=\"clone\" role=\"stmt\">CLONE LOCAL DATA\n DIRECTORY</literal> 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 <literal>'clone_dir'</literal>\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 <xref linkend=\"clone-plugin-local\" />."
},
{
"para": "<literal condition=\"clone\" role=\"stmt\">CLONE INSTANCE</literal>\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": "<literal><replaceable>user</replaceable></literal> is the\n clone user on the donor MySQL server instance."
}
],
[
{
"para": "<literal><replaceable>host</replaceable></literal> is the\n <literal role=\"sysvar\">hostname</literal> 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": "<literal><replaceable>port</replaceable></literal> is the\n <literal role=\"sysvar\">port</literal> number of the donor\n MySQL server instance. (The mysqlxprotocol port specified by\n <literal role=\"sysvar\">mysqlx_port</literal> is not supported.\n Connecting to the donor MySQL server instance through router\n is also not supported.)"
}
],
[
{
"para": "<literal>IDENTIFIED BY\n '<replaceable>password</replaceable>'</literal> specifies the\n password of the clone user on the donor MySQL server instance."
}
],
[
{
"para": "<literal>DATA DIRECTORY [=]\n '<replaceable>clone_dir</replaceable>'</literal> 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 <literal>DATA DIRECTORY [=]\n '<replaceable>clone_dir</replaceable>'</literal> 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": "<literal>[REQUIRE [NO] SSL]</literal> 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 <xref linkend=\"clone-plugin-remote-ssl\" />."
}
]
]
},
{
"para": "For additional information about cloning data from a remote MySQL\n server instance, see <xref linkend=\"clone-plugin-remote\" />."
}
],
"id": "CLONE",
"syntax": [
{
"programlisting": ">\nCLONE <replaceable>clone_action</replaceable>\n\n<replaceable>clone_action</replaceable>: {\n LOCAL DATA DIRECTORY [=] '<replaceable>clone_dir</replaceable>';\n | INSTANCE FROM '<replaceable>user</replaceable>'@'<replaceable>host</replaceable>':<replaceable>port</replaceable>\n IDENTIFIED BY '<replaceable>password</replaceable>'\n [DATA DIRECTORY [=] '<replaceable>clone_dir</replaceable>']\n [REQUIRE [NO] SSL]\n}"
}
]
},
{
"keywords": [
"SET",
"GLOBAL",
"SESSION",
"VARIABLE",
"PERSIST",
"PERSIST_ONLY"
],
"description": [
{
"para": "<literal condition=\"set-variable\" role=\"stmt\">SET</literal>\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 <xref linkend=\"user-variables\" />."
}
],
[
{
"para": "Stored procedure and function parameters, and stored program\n local variables. See\n <xref linkend=\"stored-program-variables\" />."
}
],
[
{
"para": "System variables. See\n <xref linkend=\"server-system-variables\" />. System variables\n also can be set at server startup, as described in\n <xref linkend=\"using-system-variables\" />."
}
]
]
}
],
"id": "SET",
"syntax": [
{
"programlisting": ">\nSET <replaceable>variable</replaceable> = <replaceable>expr</replaceable> [, <replaceable>variable</replaceable> = <replaceable>expr</replaceable>] ...\n\n<replaceable>variable</replaceable>: {\n <replaceable>user_var_name</replaceable>\n | <replaceable>param_name</replaceable>\n | <replaceable>local_var_name</replaceable>\n | {GLOBAL | @@GLOBAL.} <replaceable>system_var_name</replaceable>\n | {PERSIST | @@PERSIST.} <replaceable>system_var_name</replaceable>\n | {PERSIST_ONLY | @@PERSIST_ONLY.} <replaceable>system_var_name</replaceable>\n | [SESSION | @@SESSION. | @@] <replaceable>system_var_name</replaceable>\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. <literal>SET CHARACTER\n SET</literal> sets three session system variables:\n <literal role=\"sysvar\">character_set_client</literal> and\n <literal role=\"sysvar\">character_set_results</literal> are set\n to the given character set, and\n <literal role=\"sysvar\">character_set_connection</literal> to the\n value of\n <literal role=\"sysvar\">character_set_database</literal>. See\n <xref linkend=\"charset-connection\" />."
},
{
"para": "<replaceable>charset_name</replaceable> may be quoted or\n unquoted."
},
{
"para": "The default character set mapping can be restored by using the\n value <literal>DEFAULT</literal>. 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 <literal role=\"stmt\">SET CHARACTER\n SET</literal> produces an error. See\n <xref linkend=\"charset-connection-impermissible-client-charset\" />."
}
],
"id": "SET CHARACTER SET",
"syntax": [
{
"programlisting": ">\nSET {CHARACTER SET | CHARSET}\n {'<replaceable>charset_name</replaceable>' | DEFAULT}"
}
]
},
{
"keywords": [
"SET",
"NAMES"
],
"description": [
{
"para": "This statement sets the three session system variables\n <literal role=\"sysvar\">character_set_client</literal>,\n <literal role=\"sysvar\">character_set_connection</literal>, and\n <literal role=\"sysvar\">character_set_results</literal> to the\n given character set. Setting\n <literal role=\"sysvar\">character_set_connection</literal> to\n <literal>charset_name</literal> also sets\n <literal role=\"sysvar\">collation_connection</literal> to the\n default collation for <literal>charset_name</literal>. See\n <xref linkend=\"charset-connection\" />."
},
{
"para": "The optional <literal>COLLATE</literal> clause may be used to\n specify a collation explicitly. If given, the collation must one\n of the permitted collations for\n <replaceable>charset_name</replaceable>."
},
{
"para": "<replaceable>charset_name</replaceable> and\n <replaceable>collation_name</replaceable> may be quoted or\n unquoted."
},
{
"para": "The default mapping can be restored by using a value of\n <literal>DEFAULT</literal>. 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 <literal role=\"stmt\">SET\n NAMES</literal> produces an error. See\n <xref linkend=\"charset-connection-impermissible-client-charset\" />."
}
],
"id": "SET NAMES",
"syntax": [
{
"programlisting": ">\nSET NAMES {'<replaceable>charset_name</replaceable>'\n [COLLATE '<replaceable>collation_name</replaceable>'] | 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 <xref linkend=\"purge-binary-logs\" />, that shows how to determine\n which logs can be purged. <literal role=\"stmt\">SHOW BINARY\n LOGS</literal> requires the <literal role=\"priv\">REPLICATION\n CLIENT</literal> or <literal role=\"priv\">SUPER</literal>\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 <literal role=\"stmt\">SHOW BINARY LOGS</literal>. The\n <literal>Encrypted</literal> column shows whether or not the\n binary log file is encrypted. Binary log encryption is active if\n <literal role=\"sysvar\">binlog_encryption=ON</literal> 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> <userinput>SHOW BINARY LOGS;</userinput>\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 <literal>'<replaceable>log_name</replaceable>'</literal>, the\n first binary log is displayed. <literal>SHOW BINLOG\n EVENTS</literal> requires the <literal role=\"priv\">REPLICATION\n SLAVE</literal> privilege."
}
],
"id": "SHOW BINLOG EVENTS",
"syntax": [
{
"programlisting": ">\nSHOW BINLOG EVENTS\n [IN '<replaceable>log_name</replaceable>']\n [FROM <replaceable>pos</replaceable>]\n [LIMIT [<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"CHARACTER",
"SET"
],
"description": [
{
"para": "The <literal role=\"stmt\">SHOW CHARACTER SET</literal> statement\n shows all available character sets. The\n <literal role=\"op\">LIKE</literal> clause, if present, indicates\n which character set names to match. The <literal>WHERE</literal>\n clause can be given to select rows using more general\n conditions, as discussed in <xref linkend=\"extended-show\" />. For\n example:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW CHARACTER SET LIKE 'latin%';</userinput>\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 '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"COLLATION"
],
"description": [
{
"para": "This statement lists collations supported by the server. By\n default, the output from <literal role=\"stmt\">SHOW\n COLLATION</literal> includes all available collations. The\n <literal role=\"op\">LIKE</literal> clause, if present, indicates\n which collation names to match. The <literal>WHERE</literal>\n clause can be given to select rows using more general\n conditions, as discussed in <xref linkend=\"extended-show\" />. For\n example:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW COLLATION WHERE Charset = 'latin1';</userinput>\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 '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"COLUMNS",
"FIELDS",
"EXTENDED",
"FULL",
"FROM",
"IN",
"LIKE",
"WHERE"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW COLUMNS</literal> displays information\n about the columns in a given table. It also works for views.\n <literal role=\"stmt\">SHOW COLUMNS</literal> displays information\n only for those columns for which you have some privilege."
},
{
"programlisting": ">\nmysql> <userinput>SHOW COLUMNS FROM City;</userinput>\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 <literal><replaceable>tbl_name</replaceable>\n FROM <replaceable>db_name</replaceable></literal> syntax is\n <replaceable>db_name.tbl_name</replaceable>. These two\n statements are equivalent:"
},
{
"programlisting": ">\nSHOW COLUMNS FROM mytable FROM mydb;\nSHOW COLUMNS FROM mydb.mytable;"
},
{
"para": "The optional <literal>EXTENDED</literal> 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 <literal>FULL</literal> 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 <literal role=\"op\">LIKE</literal> clause, if present,\n indicates which column names to match. The\n <literal>WHERE</literal> clause can be given to select rows\n using more general conditions, as discussed in\n <xref linkend=\"extended-show\" />."
},
{
"para": "The data types may differ from what you expect them to be based\n on a <literal role=\"stmt\">CREATE TABLE</literal> 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 <xref linkend=\"silent-column-changes\" />."
},
{
"para": "<literal role=\"stmt\">SHOW COLUMNS</literal> displays the\n following values for each table column:"
},
{
"itemizedlist": [
[
{
"para": "<literal>Field</literal>"
},
{
"para": "The name of the column."
}
],
[
{
"para": "<literal>Type</literal>"
},
{
"para": "The column data type."
}
],
[
{
"para": "<literal>Collation</literal>"
},
{
"para": "The collation for nonbinary string columns, or\n <literal>NULL</literal> for other columns. This value is\n displayed only if you use the <literal>FULL</literal>\n keyword."
}
],
[
{
"para": "<literal>Null</literal>"
},
{
"para": "The column nullability. The value is <literal>YES</literal>\n if <literal>NULL</literal> values can be stored in the\n column, <literal>NO</literal> if not."
}
],
[
{
"para": "<literal>Key</literal>"
},
{
"para": "Whether the column is indexed:"
},
{
"itemizedlist": [
[
{
"para": "If <literal>Key</literal> 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 <literal>Key</literal> is <literal>PRI</literal>, the\n column is a <literal>PRIMARY KEY</literal> or is one of\n the columns in a multiple-column <literal>PRIMARY\n KEY</literal>."
}
],
[
{
"para": "If <literal>Key</literal> is <literal>UNI</literal>, the\n column is the first column of a\n <literal>UNIQUE</literal> index. (A\n <literal>UNIQUE</literal> index permits multiple\n <literal>NULL</literal> values, but you can tell whether\n the column permits <literal>NULL</literal> by checking\n the <literal>Null</literal> field.)"
}
],
[
{
"para": "If <literal>Key</literal> is <literal>MUL</literal>, 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 <literal>Key</literal> values\n applies to a given column of a table, <literal>Key</literal>\n displays the one with the highest priority, in the order\n <literal>PRI</literal>, <literal>UNI</literal>,\n <literal>MUL</literal>."
},
{
"para": "A <literal>UNIQUE</literal> index may be displayed as\n <literal>PRI</literal> if it cannot contain\n <literal>NULL</literal> values and there is no\n <literal>PRIMARY KEY</literal> in the table. A\n <literal>UNIQUE</literal> index may display as\n <literal>MUL</literal> if several columns form a composite\n <literal>UNIQUE</literal> index; although the combination of\n the columns is unique, each column can still hold multiple\n occurrences of a given value."
}
],
[
{
"para": "<literal>Default</literal>"
},
{
"para": "The default value for the column. This is\n <literal>NULL</literal> if the column has an explicit\n default of <literal>NULL</literal>, or if the column\n definition includes no <literal>DEFAULT</literal> clause."
}
],
[
{
"para": "<literal>Extra</literal>"
},
{
"para": "Any additional information that is available about a given\n column. The value is nonempty in these cases:"
},
{
"indexterm": "<primary>generated columns</primary>\n <secondary>SHOW COLUMNS statement</secondary>"
},
{
"itemizedlist": [
[
{
"para": "<literal>auto_increment</literal> for columns that have\n the <literal>AUTO_INCREMENT</literal> attribute."
}
],
[
{
"para": "<literal>on update CURRENT_TIMESTAMP</literal> for\n <literal role=\"type\">TIMESTAMP</literal> or\n <literal role=\"type\">DATETIME</literal> columns that\n have the <literal>ON UPDATE CURRENT_TIMESTAMP</literal>\n attribute."
}
],
[
{
"para": "<literal>VIRTUAL GENERATED</literal> or <literal>VIRTUAL\n STORED</literal> for generated columns."
}
],
[
{
"para": "<literal>DEFAULT_GENERATED</literal> for columns that\n have an expression default value."
}
]
]
}
],
[
{
"para": "<literal>Privileges</literal>"
},
{
"para": "The privileges you have for the column. This value is\n displayed only if you use the <literal>FULL</literal>\n keyword."
}
],
[
{
"para": "<literal>Comment</literal>"
},
{
"para": "Any comment included in the column definition. This value is\n displayed only if you use the <literal>FULL</literal>\n keyword."
}
]
]
},
{
"para": "Table column information is also available from the\n <literal>INFORMATION_SCHEMA</literal>\n <literal role=\"is\">COLUMNS</literal> table. See\n <xref linkend=\"columns-table\" />. The extended information about\n hidden columns is available only using <literal>SHOW EXTENDED\n COLUMNS</literal>; it cannot be obtained from the\n <literal role=\"is\">COLUMNS</literal> table."
},
{
"para": "You can list a table's columns with the <command>mysqlshow\n <replaceable>db_name</replaceable>\n <replaceable>tbl_name</replaceable></command> command."
},
{
"para": "The <literal role=\"stmt\">DESCRIBE</literal> statement provides\n information similar to <literal role=\"stmt\">SHOW\n COLUMNS</literal>. See <xref linkend=\"describe\" />."
},
{
"para": "The <literal role=\"stmt\">SHOW CREATE TABLE</literal>,\n <literal role=\"stmt\">SHOW TABLE STATUS</literal>, and\n <literal role=\"stmt\">SHOW INDEX</literal> statements also\n provide information about tables. See <xref linkend=\"show\" />."
}
],
"id": "SHOW COLUMNS",
"syntax": [
{
"programlisting": ">\nSHOW [EXTENDED] [FULL] {COLUMNS | FIELDS}\n {FROM | IN} <replaceable>tbl_name</replaceable>\n [{FROM | IN} <replaceable>db_name</replaceable>]\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"DATABASE",
"SCHEMA"
],
"description": [
{
"para": "Shows the <literal role=\"stmt\">CREATE DATABASE</literal>\n statement that creates the named database. If the\n <literal>SHOW</literal> statement includes an <literal>IF NOT\n EXISTS</literal> clause, the output too includes such a clause.\n <literal condition=\"show-create-database\" role=\"stmt\">SHOW\n CREATE SCHEMA</literal> is a synonym for\n <literal role=\"stmt\">SHOW CREATE DATABASE</literal>."
}
],
"id": "SHOW CREATE DATABASE",
"syntax": [
{
"programlisting": ">\nSHOW CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] <replaceable>db_name</replaceable>"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"EVENT"
],
"description": [
{
"para": "This statement displays the <literal role=\"stmt\">CREATE\n EVENT</literal> statement needed to re-create a given event. It\n requires the <literal role=\"priv\">EVENT</literal> privilege for\n the database from which the event is to be shown. For example\n (using the same event <literal>e_daily</literal> defined and\n then altered in <xref linkend=\"show-events\" />):"
}
],
"id": "SHOW CREATE EVENT",
"syntax": [
{
"programlisting": ">\nSHOW CREATE EVENT <replaceable>event_name</replaceable>"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"FUNCTION"
],
"description": [
{
"para": "This statement is similar to <literal role=\"stmt\">SHOW CREATE\n PROCEDURE</literal> but for stored functions. See\n <xref linkend=\"show-create-procedure\" />."
}
],
"id": "SHOW CREATE FUNCTION",
"syntax": [
{
"programlisting": ">\nSHOW CREATE FUNCTION <replaceable>func_name</replaceable>"
}
]
},
{
"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, <literal role=\"stmt\">SHOW CREATE\n FUNCTION</literal>, displays information about stored functions\n (see <xref linkend=\"show-create-function\" />)."
},
{
"para": "To use either statement, you must have the global\n <literal role=\"stmt\">SELECT</literal> privilege."
}
],
"id": "SHOW CREATE PROCEDURE",
"syntax": [
{
"programlisting": ">\nSHOW CREATE PROCEDURE <replaceable>proc_name</replaceable>"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"TABLE"
],
"description": [
{
"para": "As of MySQL 8.0.16, MySQL implements <literal>CHECK</literal>\n constraints and <literal role=\"stmt\">SHOW CREATE TABLE</literal>\n displays them. All <literal>CHECK</literal> constraints are\n displayed as table constraints. That is, a\n <literal>CHECK</literal> 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> <userinput>CREATE TABLE t1 (</userinput>\n <userinput>i1 INT CHECK (i1 <> 0), -- column constraint</userinput>\n <userinput>i2 INT,</userinput>\n <userinput>CHECK (i2 > i1), -- table constraint</userinput>\n <userinput>CHECK (i2 <> 0) NOT ENFORCED -- table constraint, not enforced</userinput>\n <userinput>);</userinput>\n\nmysql> <userinput>SHOW CREATE TABLE t1\\G</userinput>\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": "<literal role=\"stmt\">SHOW CREATE TABLE</literal> quotes table\n and column names according to the value of the\n <literal role=\"sysvar\">sql_quote_show_create</literal> option.\n See <xref linkend=\"server-system-variables\" />."
},
{
"para": "For information about how <literal role=\"stmt\">CREATE\n TABLE</literal> statements are stored by MySQL, see\n <xref linkend=\"create-table-statement-retention\" />."
}
],
"id": "SHOW CREATE TABLE",
"syntax": [
{
"programlisting": ">\nSHOW CREATE TABLE <replaceable>tbl_name</replaceable>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This statement shows the <literal role=\"stmt\">CREATE\n TRIGGER</literal> statement that creates the named trigger. This\n statement requires the <literal role=\"priv\">TRIGGER</literal>\n privilege for the table associated with the trigger."
}
],
"id": "SHOW CREATE TRIGGER",
"syntax": [
{
"programlisting": ">\nSHOW CREATE TRIGGER <replaceable>trigger_name</replaceable>"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"USER"
],
"description": [
{
"para": "This statement shows the <literal role=\"stmt\">CREATE\n USER</literal> statement that creates the named user. An error\n occurs if the user does not exist. The statement requires the\n <literal role=\"priv\">SELECT</literal> privilege for the\n <literal>mysql</literal> system schema, except to see\n information for the current user. For the current user, the\n <literal role=\"priv\">SELECT</literal> privilege for the\n <literal>mysql.user</literal> system table is required for\n display of the password hash in the <literal>IDENTIFIED\n AS</literal> clause; otherwise, the hash displays as\n <literal><secret></literal>."
},
{
"para": "To name the account, use the format described in\n <xref linkend=\"account-names\" />. The host name part of the\n account name, if omitted, defaults to <literal>'%'</literal>. It\n is also possible to specify\n <literal role=\"func\">CURRENT_USER</literal> or\n <literal role=\"func\">CURRENT_USER()</literal> to refer to the\n account associated with the current session."
},
{
"para": "Password hash values displayed in the <literal>IDENTIFIED\n WITH</literal> clause of output from <literal role=\"stmt\">SHOW\n CREATE USER</literal> may contain unprintable characters that\n have adverse effects on terminal displays and in other\n environments. Enabling the\n <literal role=\"sysvar\">print_identified_with_as_hex</literal>\n system variable (available as of MySQL 8.0.17) causes\n <literal role=\"stmt\">SHOW CREATE USER</literal> 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 <replaceable>user</replaceable>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "This statement shows the <literal role=\"stmt\">CREATE\n VIEW</literal> statement that creates the named view."
}
],
"id": "SHOW CREATE VIEW",
"syntax": [
{
"programlisting": ">\nSHOW CREATE VIEW <replaceable>view_name</replaceable>"
}
]
},
{
"keywords": [
"SHOW",
"DATABASES",
"SCHEMAS"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW DATABASES</literal> lists the\n databases on the MySQL server host.\n <literal condition=\"show-databases\" role=\"stmt\">SHOW\n SCHEMAS</literal> is a synonym for <literal role=\"stmt\">SHOW\n DATABASES</literal>. The <literal role=\"op\">LIKE</literal>\n clause, if present, indicates which database names to match. The\n <literal>WHERE</literal> clause can be given to select rows\n using more general conditions, as discussed in\n <xref linkend=\"extended-show\" />."
},
{
"para": "You see only those databases for which you have some kind of\n privilege, unless you have the global <literal role=\"stmt\">SHOW\n DATABASES</literal> privilege. You can also get this list using\n the <command>mysqlshow</command> command."
},
{
"para": "If the server was started with the\n <option role=\"mysqld\">--skip-show-database</option> option, you\n cannot use this statement at all unless you have the\n <literal role=\"priv\">SHOW DATABASES</literal> 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 <literal>INFORMATION_SCHEMA</literal>\n <literal role=\"is\">SCHEMATA</literal> table. See\n <xref linkend=\"schemata-table\" />."
}
],
"id": "SHOW DATABASES",
"syntax": [
{
"programlisting": ">\nSHOW {DATABASES | SCHEMAS}\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"ENGINE",
"MUTEX",
"STATUS"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW ENGINE</literal> displays operational\n information about a storage engine. It requires the\n <literal role=\"priv\">PROCESS</literal> privilege. The statement\n has these variants:"
},
{
"programlisting": ">\nSHOW ENGINE INNODB STATUS\nSHOW ENGINE INNODB MUTEX\nSHOW ENGINE PERFORMANCE_SCHEMA STATUS"
},
{
"para": "<literal condition=\"show-engine\" role=\"stmt\">SHOW ENGINE INNODB\n STATUS</literal> displays extensive information from the\n standard <literal>InnoDB</literal> Monitor about the state of\n the <literal>InnoDB</literal> storage engine. For information\n about the standard monitor and other <literal>InnoDB</literal>\n Monitors that provide information about\n <literal>InnoDB</literal> processing, see\n <xref linkend=\"innodb-monitors\" />."
},
{
"para": "<literal condition=\"show-engine\" role=\"stmt\">SHOW ENGINE INNODB\n MUTEX</literal> displays <literal>InnoDB</literal>\n <link linkend=\"glos_mutex\">mutex</link> and\n <link linkend=\"glos_rw_lock\">rw-lock</link> 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 <literal condition=\"show-engine\" role=\"stmt\">SHOW ENGINE INNODB\n MUTEX</literal> can also be enabled by setting\n <literal role=\"sysvar\">innodb_monitor_enable='all'</literal>, or\n disabled by setting\n <literal role=\"sysvar\">innodb_monitor_disable='all'</literal>."
},
{
"para": "<literal condition=\"show-engine\" role=\"stmt\">SHOW ENGINE INNODB\n MUTEX</literal> output has these columns:"
},
{
"itemizedlist": [
[
{
"para": "<literal>Type</literal>"
},
{
"para": "Always <literal>InnoDB</literal>."
}
],
[
{
"para": "<literal>Name</literal>"
},
{
"para": "For mutexes, the <literal>Name</literal> field reports only\n the mutex name. For rwlocks, the <literal>Name</literal>\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": "<literal>Status</literal>"
},
{
"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 <literal>InnoDB</literal>, are not reported."
},
{
"itemizedlist": [
[
{
"para": "<literal>spins</literal> indicates the number of spins."
}
],
[
{
"para": "<literal>waits</literal> indicates the number of mutex\n waits."
}
],
[
{
"para": "<literal>calls</literal> indicates how many times the\n mutex was requested."
}
]
]
}
]
]
},
{
"para": "<literal>SHOW ENGINE INNODB MUTEX</literal> skips the\n <link linkend=\"glos_mutex\">mutexes</link> and\n <link linkend=\"glos_rw_lock\">rw-locks</link> of\n <link linkend=\"glos_buffer_pool\">buffer pool</link> 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 <literal>SHOW ENGINE INNODB MUTEX</literal> also does not list\n any mutexes or rw-locks that have never been waited on\n (<literal>os_waits=0</literal>). Thus, <literal>SHOW ENGINE\n INNODB MUTEX</literal> only displays information about mutexes\n and rw-locks outside of the buffer pool that have caused at\n least one OS-level <link linkend=\"glos_wait\">wait</link>."
},
{
"para": "Use <literal condition=\"show-engine\" role=\"stmt\">SHOW ENGINE\n PERFORMANCE_SCHEMA STATUS</literal> to inspect the internal\n operation of the Performance Schema code:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW ENGINE PERFORMANCE_SCHEMA STATUS\\G</userinput>\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": "<literal>Name</literal> 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 <literal>(pfs_cond_class).size</literal>,\n <literal>(pfs_mutex_class).memory</literal>."
}
],
[
{
"para": "An internal buffer that is exposed as a table in the\n <literal>performance_schema</literal> database is named\n after the table, without parentheses. Examples:\n <literal>events_waits_history.size</literal>,\n <literal>mutex_instances.count</literal>."
}
],
[
{
"para": "A value that applies to the Performance Schema as a whole\n begins with <literal>performance_schema</literal>. Example:\n <literal>performance_schema.memory</literal>."
}
]
]
},
{
"para": "Buffer attributes have these meanings:"
},
{
"itemizedlist": [
[
{
"para": "<literal>size</literal> is the size of the internal record\n used by the implementation, such as the size of a row in a\n table. <literal>size</literal> values cannot be changed."
}
],
[
{
"para": "<literal>count</literal> is the number of internal records,\n such as the number of rows in a table.\n <literal>count</literal> values can be changed using\n Performance Schema configuration options."
}
],
[
{
"para": "For a table,\n <literal><replaceable>tbl_name</replaceable>.memory</literal>\n is the product of <literal>size</literal> and\n <literal>count</literal>. For the Performance Schema as a\n whole, <literal>performance_schema.memory</literal> is the\n sum of all the memory used (the sum of all other\n <literal>memory</literal> values)."
}
]
]
},
{
"para": "In some cases, there is a direct relationship between a\n Performance Schema configuration parameter and a <literal>SHOW\n ENGINE</literal> value. For example,\n <literal>events_waits_history_long.count</literal> corresponds\n to\n <literal role=\"sysvar\">performance_schema_events_waits_history_long_size</literal>.\n In other cases, the relationship is more complex. For example,\n <literal>events_waits_history.count</literal> corresponds to\n <literal role=\"sysvar\">performance_schema_events_waits_history_size</literal>\n (the number of rows per thread) multiplied by\n <literal role=\"sysvar\">performance_schema_max_thread_instances</literal>\n ( the number of threads)."
},
{
"programlisting": ">\nmysql> <userinput>SHOW ENGINE NDB STATUS;</userinput>\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 <literal>Status</literal> 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 <literal>Status</literal> information is in\n the form of comma-delimited set of name/value pairs."
}
],
"id": "SHOW ENGINE",
"syntax": [
{
"programlisting": ">\nSHOW ENGINE <replaceable>engine_name</replaceable> {STATUS | MUTEX}"
}
]
},
{
"keywords": [
"SHOW",
"ENGINES",
"STORAGE"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW ENGINES</literal> 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 <xref linkend=\"innodb-storage-engine\" />, and\n <xref linkend=\"storage-engines\" />."
}
],
"id": "SHOW ENGINES",
"syntax": [
{
"programlisting": ">\nSHOW [STORAGE] ENGINES"
}
]
},
{
"keywords": [
"SHOW",
"ERRORS",
"COUNT"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW ERRORS</literal> is a diagnostic\n statement that is similar to <literal role=\"stmt\">SHOW\n WARNINGS</literal>, except that it displays information only for\n errors, rather than for errors, warnings, and notes."
},
{
"para": "The <literal>LIMIT</literal> clause has the same syntax as for\n the <literal role=\"stmt\">SELECT</literal> statement. See\n <xref linkend=\"select\" />."
},
{
"para": "The <literal condition=\"show-errors\" role=\"stmt\">SHOW COUNT(*)\n ERRORS</literal> statement displays the number of errors. You\n can also retrieve this number from the\n <literal role=\"sysvar\">error_count</literal> variable:"
},
{
"programlisting": ">\nSHOW COUNT(*) ERRORS;\nSELECT @@error_count;"
},
{
"para": "<literal role=\"stmt\">SHOW ERRORS</literal> and\n <literal role=\"sysvar\">error_count</literal> apply only to\n errors, not warnings or notes. In other respects, they are\n similar to <literal role=\"stmt\">SHOW WARNINGS</literal> and\n <literal role=\"sysvar\">warning_count</literal>. In particular,\n <literal role=\"stmt\">SHOW ERRORS</literal> cannot display\n information for more than\n <literal role=\"sysvar\">max_error_count</literal> messages, and\n <literal role=\"sysvar\">error_count</literal> can exceed the\n value of <literal role=\"sysvar\">max_error_count</literal> if the\n number of errors exceeds\n <literal role=\"sysvar\">max_error_count</literal>."
}
],
"id": "SHOW ERRORS",
"syntax": [
{
"programlisting": ">\nSHOW ERRORS [LIMIT [<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable>]\nSHOW COUNT(*) ERRORS"
}
]
},
{
"keywords": [
"SHOW",
"EVENTS"
],
"description": [
{
"para": "This statement displays information about Event Manager events,\n which are discussed in <xref linkend=\"event-scheduler\" />. It\n requires the <literal role=\"priv\">EVENT</literal> privilege for\n the database from which the events are to be shown."
},
{
"para": "In its simplest form, <literal role=\"stmt\">SHOW EVENTS</literal>\n lists all of the events in the current schema:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT CURRENT_USER(), SCHEMA();</userinput>\n+----------------+----------+\n| CURRENT_USER() | SCHEMA() |\n+----------------+----------+\n| jon@ghidora | myschema |\n+----------------+----------+\n1 row in set (0.00 sec)\n\nmysql> <userinput>SHOW EVENTS\\G</userinput>\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 <literal>FROM</literal> clause. For example, to see events for\n the <literal>test</literal> schema, use the following statement:"
},
{
"programlisting": ">\nSHOW EVENTS FROM test;"
},
{
"para": "The <literal role=\"op\">LIKE</literal> clause, if present,\n indicates which event names to match. The\n <literal>WHERE</literal> clause can be given to select rows\n using more general conditions, as discussed in\n <xref linkend=\"extended-show\" />."
}
],
"id": "SHOW EVENTS",
"syntax": [
{
"programlisting": ">\nSHOW EVENTS\n [{FROM | IN} <replaceable>schema_name</replaceable>]\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"FUNCTION",
"CODE"
],
"description": [
{
"para": "This statement is similar to <literal role=\"stmt\">SHOW PROCEDURE\n CODE</literal> but for stored functions. See\n <xref linkend=\"show-procedure-code\" />."
}
],
"id": "SHOW FUNCTION CODE",
"syntax": [
{
"programlisting": ">\nSHOW FUNCTION CODE <replaceable>func_name</replaceable>"
}
]
},
{
"keywords": [
"SHOW",
"FUNCTION",
"STATUS"
],
"description": [
{
"para": "This statement is similar to <literal role=\"stmt\">SHOW PROCEDURE\n STATUS</literal> but for stored functions. See\n <xref linkend=\"show-procedure-status\" />."
}
],
"id": "SHOW FUNCTION STATUS",
"syntax": [
{
"programlisting": ">\nSHOW FUNCTION STATUS\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"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 <literal role=\"stmt\">GRANT</literal> statements that must be\n executed to duplicate the privilege and role assignments."
},
{
"para": "<literal role=\"stmt\">SHOW GRANTS</literal> requires the\n <literal role=\"priv\">SELECT</literal> privilege for the\n <literal>mysql</literal> system schema, except to display\n privileges and roles for the current user."
},
{
"para": "To name the account or role for <literal role=\"stmt\">SHOW\n GRANTS</literal>, use the same format as for the\n <literal role=\"stmt\">GRANT</literal> statement (for example,\n <literal>'jeffrey'@'localhost'</literal>):"
},
{
"programlisting": ">\nmysql> <userinput>SHOW GRANTS FOR 'jeffrey'@'localhost';</userinput>\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 <literal>'%'</literal>.\n For additional information about specifying account and role\n names, see <xref linkend=\"account-names\" />, and\n <xref linkend=\"role-names\" />."
},
{
"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 <literal>SHOW GRANTS FOR CURRENT_USER</literal> (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 <literal role=\"stmt\">SHOW GRANTS</literal> no longer displays\n <literal condition=\"all\" role=\"priv\">ALL PRIVILEGES</literal> in\n its global-privileges output because the meaning of\n <literal condition=\"all\" role=\"priv\">ALL PRIVILEGES</literal> at\n the global level varies depending on which dynamic privileges\n are defined. Instead, <literal role=\"stmt\">SHOW GRANTS</literal>\n explictly lists each granted global privilege:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW GRANTS FOR 'root'@'localhost';</userinput>\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 <literal role=\"stmt\">SHOW\n GRANTS</literal> output should be adjusted accordingly."
},
{
"para": "At the global level, <literal role=\"priv\">GRANT OPTION</literal>\n applies to all granted static global privileges if granted for\n any of them, but applies individually to granted dynamic\n privileges. <literal role=\"stmt\">SHOW GRANTS</literal> displays\n global privileges this way:"
},
{
"itemizedlist": [
[
{
"para": "One line listing all granted static privileges, if there are\n any, including <literal>WITH GRANT OPTION</literal> if\n appropriate."
}
],
[
{
"para": "One line listing all granted dynamic privileges for which\n <literal role=\"priv\">GRANT OPTION</literal> is granted, if\n there are any, including <literal>WITH GRANT\n OPTION</literal>."
}
],
[
{
"para": "One line listing all granted dynamic privileges for which\n <literal role=\"priv\">GRANT OPTION</literal> is not granted,\n if there are any, without <literal>WITH GRANT\n OPTION</literal>."
}
]
]
},
{
"para": "With the optional <literal>USING</literal> clause,\n <literal role=\"stmt\">SHOW GRANTS</literal> enables you to\n examine the privileges associated with roles for the user. Each\n role named in the <literal>USING</literal> clause must be\n granted to the user."
},
{
"para": "Suppose that user <literal>u1</literal> is assigned roles\n <literal>r1</literal> and <literal>r2</literal>, 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": "<literal role=\"stmt\">SHOW GRANTS</literal> without\n <literal>USING</literal> shows the granted roles:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW GRANTS FOR 'u1'@'localhost';</userinput>\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 <literal>USING</literal> clause causes the statement to\n also display the privileges associated with each role named in\n the clause:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW GRANTS FOR 'u1'@'localhost' USING 'r1';</userinput>\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> <userinput>SHOW GRANTS FOR 'u1'@'localhost' USING 'r2';</userinput>\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> <userinput>SHOW GRANTS FOR 'u1'@'localhost' USING 'r1', 'r2';</userinput>\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 <xref linkend=\"partial-revokes\" />). To indicate which global\n schema privileges have been revoked for particular schemas,\n <literal>SHOW GRANTS</literal> output includes\n <literal>REVOKE</literal> statements:"
},
{
"programlisting": ">\nmysql> <userinput>SET PERSIST partial_revokes = ON;</userinput>\nmysql> <userinput>CREATE USER u1;</userinput>\nmysql> <userinput>GRANT SELECT, INSERT, DELETE ON *.* TO u1;</userinput>\nmysql> <userinput>REVOKE SELECT, INSERT ON mysql.* FROM u1;</userinput>\nmysql> <userinput>REVOKE DELETE ON world.* FROM u1;</userinput>\nmysql> <userinput>SHOW GRANTS FOR u1;</userinput>\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": "<literal role=\"stmt\">SHOW GRANTS</literal> 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 <literal role=\"stmt\">SHOW GRANTS</literal> does\n not display them."
}
],
"id": "SHOW GRANTS",
"syntax": [
{
"programlisting": ">\nSHOW GRANTS\n [FOR <replaceable>user_or_role</replaceable>\n [USING <replaceable>role</replaceable> [, <replaceable>role</replaceable>] ...]]\n\n<replaceable>user_or_role</replaceable>: {\n <replaceable>user</replaceable> (see <xref linkend=\"account-names\" />)\n | <replaceable>role</replaceable> (see <xref linkend=\"role-names\" />.\n}"
}
]
},
{
"keywords": [
"SHOW",
"INDEX",
"KEYS",
"EXTENDED",
"FROM",
"IN",
"WHERE"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW INDEX</literal> returns table index\n information. The format resembles that of the\n <literal>SQLStatistics</literal> call in ODBC. This statement\n requires some privilege for any column in the table."
},
{
"programlisting": ">\nmysql> <userinput>SHOW INDEX FROM City\\G</userinput>\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 <literal><replaceable>tbl_name</replaceable>\n FROM <replaceable>db_name</replaceable></literal> syntax is\n <replaceable>db_name</replaceable>.<replaceable>tbl_name</replaceable>.\n These two statements are equivalent:"
},
{
"programlisting": ">\nSHOW INDEX FROM mytable FROM mydb;\nSHOW INDEX FROM mydb.mytable;"
},
{
"para": "The optional <literal>EXTENDED</literal> keyword causes the\n output to include information about hidden indexes that MySQL\n uses internally and are not accessible by users."
},
{
"para": "The <literal>WHERE</literal> clause can be given to select rows\n using more general conditions, as discussed in\n <xref linkend=\"extended-show\" />."
},
{
"para": "<literal role=\"stmt\">SHOW INDEX</literal> returns the following\n fields:"
},
{
"itemizedlist": [
[
{
"para": "<literal>Table</literal>"
},
{
"para": "The name of the table."
}
],
[
{
"para": "<literal>Non_unique</literal>"
},
{
"para": "0 if the index cannot contain duplicates, 1 if it can."
}
],
[
{
"para": "<literal>Key_name</literal>"
},
{
"para": "The name of the index. If the index is the primary key, the\n name is always <literal>PRIMARY</literal>."
}
],
[
{
"para": "<literal>Seq_in_index</literal>"
},
{
"para": "The column sequence number in the index, starting with 1."
}
],
[
{
"para": "<literal>Column_name</literal>"
},
{
"para": "The column name. See also the description for the\n <literal>Expression</literal> column."
}
],
[
{
"para": "<literal>Collation</literal>"
},
{
"indexterm": "<primary>displaying</primary>\n <secondary>information</secondary>\n <tertiary>Collation</tertiary>"
},
{
"para": "How the column is sorted in the index. This can have values\n <literal>A</literal> (ascending), <literal>D</literal>\n (descending), or <literal>NULL</literal> (not sorted)."
}
],
[
{
"para": "<literal>Cardinality</literal>"
},
{
"indexterm": "<primary>displaying</primary>\n <secondary>information</secondary>\n <tertiary>Cardinality</tertiary>"
},
{
"indexterm": "<primary>calculating</primary>\n <secondary>cardinality</secondary>"
},
{
"para": "An estimate of the number of unique values in the index. To\n update this number, run <literal role=\"stmt\">ANALYZE\n TABLE</literal> or (for <literal>MyISAM</literal> tables)\n <command>myisamchk -a</command>."
},
{
"para": "<literal>Cardinality</literal> 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": "<literal>Sub_part</literal>"
},
{
"para": "The index prefix. That is, the number of indexed characters\n if the column is only partly indexed,\n <literal>NULL</literal> if the entire column is indexed."
},
{
"note": "<para>\n Prefix <emphasis>limits</emphasis> are measured in bytes.\n However, prefix <emphasis>lengths</emphasis> for index\n specifications in <literal role=\"stmt\">CREATE\n TABLE</literal>, <literal role=\"stmt\">ALTER\n TABLE</literal>, and <literal role=\"stmt\">CREATE\n INDEX</literal> statements are interpreted as number of\n characters for nonbinary string types\n (<literal role=\"type\">CHAR</literal>,\n <literal role=\"type\">VARCHAR</literal>,\n <literal role=\"type\">TEXT</literal>) and number of bytes\n for binary string types\n (<literal role=\"type\">BINARY</literal>,\n <literal role=\"type\">VARBINARY</literal>,\n <literal role=\"type\">BLOB</literal>). Take this into\n account when specifying a prefix length for a nonbinary\n string column that uses a multibyte character set.\n </para>"
},
{
"para": "For additional information about index prefixes, see\n <xref linkend=\"column-indexes\" />, and\n <xref linkend=\"create-index\" />."
}
],
[
{
"para": "<literal>Packed</literal>"
},
{
"para": "Indicates how the key is packed. <literal>NULL</literal> if\n it is not."
}
],
[
{
"para": "<literal>Null</literal>"
},
{
"para": "Contains <literal>YES</literal> if the column may contain\n <literal>NULL</literal> values and <literal>''</literal> if\n not."
}
],
[
{
"para": "<literal>Index_type</literal>"
},
{
"para": "The index method used (<literal>BTREE</literal>,\n <literal>FULLTEXT</literal>, <literal>HASH</literal>,\n <literal>RTREE</literal>)."
}
],
[
{
"para": "<literal>Comment</literal>"
},
{
"para": "Information about the index not described in its own column,\n such as <literal>disabled</literal> if the index is\n disabled."
}
],
[
{
"para": "<literal>Index_comment</literal>"
},
{
"para": "Any comment provided for the index with a\n <literal>COMMENT</literal> attribute when the index was\n created."
}
],
[
{
"para": "<literal>Visible</literal>"
},
{
"para": "Whether the index is visible to the optimizer. See\n <xref linkend=\"invisible-indexes\" />."
}
],
[
{
"para": "<literal>Expression</literal>"
},
{
"para": "MySQL 8.0.13 and higher supports functional key parts (see\n <xref linkend=\"create-index-functional-key-parts\" />), which\n affects both the <literal>Column_name</literal> and\n <literal>Expression</literal> columns:"
},
{
"itemizedlist": [
[
{
"para": "For a nonfunctional key part,\n <literal>Column_name</literal> indicates the column\n indexed by the key part and\n <literal>Expression</literal> is\n <literal>NULL</literal>."
}
],
[
{
"para": "For a functional key part,\n <literal>Column_name</literal> column is\n <literal>NULL</literal> and\n <literal>Expression</literal> indicates the expression\n for the key part."
}
]
]
}
]
]
},
{
"para": "Information about table indexes is also available from the\n <literal>INFORMATION_SCHEMA</literal>\n <literal role=\"is\">STATISTICS</literal> table. See\n <xref linkend=\"statistics-table\" />. The extended information\n about hidden indexes is available only using <literal>SHOW\n EXTENDED INDEX</literal>; it cannot be obtained from the\n <literal role=\"is\">STATISTICS</literal> table."
},
{
"para": "You can list a table's indexes with the <command>mysqlshow -k\n <replaceable>db_name</replaceable>\n <replaceable>tbl_name</replaceable></command> command."
}
],
"id": "SHOW INDEX",
"syntax": [
{
"programlisting": ">\nSHOW [EXTENDED] {INDEX | INDEXES | KEYS}\n {FROM | IN} <replaceable>tbl_name</replaceable>\n [{FROM | IN} <replaceable>db_name</replaceable>]\n [WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"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 <literal role=\"priv\">SUPER</literal> or\n <literal role=\"priv\">REPLICATION CLIENT</literal> privilege."
},
{
"para": "Example:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW MASTER STATUS\\G</userinput>\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": "<literal role=\"stmt\">SHOW OPEN TABLES</literal> lists the\n non-<literal>TEMPORARY</literal> tables that are currently open\n in the table cache. See <xref linkend=\"table-cache\" />. The\n <literal>FROM</literal> clause, if present, restricts the tables\n shown to those present in the <replaceable>db_name</replaceable>\n database. The <literal role=\"op\">LIKE</literal> clause, if\n present, indicates which table names to match. The\n <literal>WHERE</literal> clause can be given to select rows\n using more general conditions, as discussed in\n <xref linkend=\"extended-show\" />."
}
],
"id": "SHOW OPEN TABLES",
"syntax": [
{
"programlisting": ">\nSHOW OPEN TABLES\n [{FROM | IN} <replaceable>db_name</replaceable>]\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"PLUGINS"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW PLUGINS</literal> displays information\n about server plugins."
},
{
"para": "Example of <literal role=\"stmt\">SHOW PLUGINS</literal> output:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW PLUGINS\\G</userinput>\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": "<literal role=\"stmt\">SHOW PRIVILEGES</literal> 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, <literal role=\"stmt\">SHOW\n FUNCTION CODE</literal>, displays information about stored\n functions (see <xref linkend=\"show-function-code\" />)."
},
{
"para": "To use either statement, you must have the global\n <literal role=\"stmt\">SELECT</literal> 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 <quote>instruction</quote> in the routine. The first column is\n <literal>Pos</literal>, which is an ordinal number beginning\n with 0. The second column is <literal>Instruction</literal>,\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 <replaceable>proc_name</replaceable>"
}
]
},
{
"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, <literal role=\"stmt\">SHOW\n FUNCTION STATUS</literal>, displays information about stored\n functions (see <xref linkend=\"show-function-status\" />)."
},
{
"para": "The <literal role=\"op\">LIKE</literal> clause, if present,\n indicates which procedure or function names to match. The\n <literal>WHERE</literal> clause can be given to select rows\n using more general conditions, as discussed in\n <xref linkend=\"extended-show\" />."
}
],
"id": "SHOW PROCEDURE STATUS",
"syntax": [
{
"programlisting": ">\nSHOW PROCEDURE STATUS\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"PROCESSLIST",
"FULL"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW PROCESSLIST</literal> shows which\n threads are running. If you have the\n <literal role=\"priv\">PROCESS</literal> 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 <literal>FULL</literal> keyword,\n only the first 100 characters of each statement are shown in the\n <literal>Info</literal> field."
}
],
"id": "SHOW PROCESSLIST",
"syntax": [
{
"programlisting": ">\nSHOW [FULL] PROCESSLIST"
}
]
},
{
"keywords": [
"SHOW",
"PROFILE"
],
"description": [
{
"para": "The <literal role=\"stmt\">SHOW PROFILE</literal> and\n <literal role=\"stmt\">SHOW PROFILES</literal> 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 <literal role=\"sysvar\">profiling</literal> session variable,\n which has a default value of 0 (<literal>OFF</literal>). Enable\n profiling by setting <literal role=\"sysvar\">profiling</literal>\n to 1 or <literal>ON</literal>:"
},
{
"programlisting": ">\nmysql> <userinput>SET profiling = 1;</userinput>"
},
{
"para": "<literal role=\"stmt\">SHOW PROFILES</literal> displays a list of\n the most recent statements sent to the server. The size of the\n list is controlled by the\n <literal role=\"sysvar\">profiling_history_size</literal> 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 <literal role=\"stmt\">SHOW\n PROFILE</literal> and <literal role=\"stmt\">SHOW\n PROFILES</literal>, so you will find neither of those statements\n in the profile list. Malformed statements are profiled. For\n example, <literal>SHOW PROFILING</literal> 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": "<literal role=\"stmt\">SHOW PROFILE</literal> displays detailed\n information about a single statement. Without the <literal>FOR\n QUERY <replaceable>n</replaceable></literal> clause, the output\n pertains to the most recently executed statement. If\n <literal>FOR QUERY <replaceable>n</replaceable></literal> is\n included, <literal role=\"stmt\">SHOW PROFILE</literal> displays\n information for statement <replaceable>n</replaceable>. The\n values of <replaceable>n</replaceable> correspond to the\n <literal>Query_ID</literal> values displayed by\n <literal role=\"stmt\">SHOW PROFILES</literal>."
},
{
"para": "The <literal>LIMIT\n <replaceable>row_count</replaceable></literal> clause may be\n given to limit the output to\n <replaceable>row_count</replaceable> rows. If\n <literal>LIMIT</literal> is given, <literal>OFFSET\n <replaceable>offset</replaceable></literal> may be added to\n begin the output <replaceable>offset</replaceable> rows into the\n full set of rows."
},
{
"para": "By default, <literal role=\"stmt\">SHOW PROFILE</literal> displays\n <literal>Status</literal> and <literal>Duration</literal>\n columns. The <literal>Status</literal> values are like the\n <literal>State</literal> values displayed by\n <literal role=\"stmt\">SHOW PROCESSLIST</literal>, although there\n might be some minor differences in interpretion for the two\n statements for some status values (see\n <xref linkend=\"thread-information\" />)."
},
{
"para": "Optional <replaceable>type</replaceable> values may be specified\n to display specific additional types of information:"
},
{
"itemizedlist": [
[
{
"para": "<literal>ALL</literal> displays all information"
}
],
[
{
"para": "<literal>BLOCK IO</literal> displays counts for block input\n and output operations"
}
],
[
{
"para": "<literal>CONTEXT SWITCHES</literal> displays counts for\n voluntary and involuntary context switches"
}
],
[
{
"para": "<literal>CPU</literal> displays user and system CPU usage\n times"
}
],
[
{
"para": "<literal>IPC</literal> displays counts for messages sent and\n received"
}
],
[
{
"para": "<literal>MEMORY</literal> is not currently implemented"
}
],
[
{
"para": "<literal>PAGE FAULTS</literal> displays counts for major and\n minor page faults"
}
],
[
{
"para": "<literal>SOURCE</literal> 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": "<literal>SWAPS</literal> 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 [<replaceable>type</replaceable> [, <replaceable>type</replaceable>] ... ]\n [FOR QUERY <replaceable>n</replaceable>]\n [LIMIT <replaceable>row_count</replaceable> [OFFSET <replaceable>offset</replaceable>]]\n\n<replaceable>type</replaceable>: {\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 <literal role=\"stmt\">SHOW PROFILES</literal> statement,\n together with <literal role=\"stmt\">SHOW PROFILE</literal>,\n displays profiling information that indicates resource usage for\n statements executed during the course of the current session.\n For more information, see <xref linkend=\"show-profile\" />."
}
],
"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 <literal>'<replaceable>log_name</replaceable>'</literal>, the\n first relay log is displayed. This statement has no effect on\n the master. <literal>SHOW RELAYLOG EVENTS</literal> requires the\n <literal role=\"priv\">REPLICATION SLAVE</literal> privilege."
}
],
"id": "SHOW RELAYLOG EVENTS",
"syntax": [
{
"programlisting": ">\nSHOW RELAYLOG EVENTS\n [IN '<replaceable>log_name</replaceable>']\n [FROM <replaceable>pos</replaceable>]\n [LIMIT [<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable>]\n [<replaceable>channel_option</replaceable>]\n\n<replaceable>channel_option</replaceable>:\n FOR CHANNEL <replaceable>channel</replaceable>"
}
]
},
{
"keywords": [
"SHOW",
"SLAVE",
"HOSTS"
],
"description": [
{
"para": "Displays a list of replication slaves currently registered with\n the master. <literal>SHOW SLAVE HOSTS</literal> requires the\n <literal role=\"priv\">REPLICATION SLAVE</literal> privilege."
},
{
"para": "<literal>SHOW SLAVE HOSTS</literal> 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> <userinput>SHOW SLAVE HOSTS</userinput>;\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": "<literal>Server_id</literal>: 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 <option role=\"sysvar\">--server-id=<replaceable>value</replaceable></option>."
}
],
[
{
"para": "<literal>Host</literal>: The host name of the slave server\n as specified on the slave with the\n <option role=\"sysvar\">--report-host</option> option. This\n can differ from the machine name as configured in the\n operating system."
}
],
[
{
"para": "<literal>User</literal>: The slave server user name as,\n specified on the slave with the\n <option role=\"sysvar\">--report-user</option> option.\n Statement output includes this column only if the master\n server is started with the\n <option role=\"mysqld\">--show-slave-auth-info</option>\n option."
}
],
[
{
"para": "<literal>Password</literal>: The slave server password as,\n specified on the slave with the\n <option role=\"sysvar\">--report-password</option> option.\n Statement output includes this column only if the master\n server is started with the\n <option role=\"mysqld\">--show-slave-auth-info</option>\n option."
}
],
[
{
"para": "<literal>Port</literal>: The port on the master to which the\n slave server is listening, as specified on the slave with\n the <option role=\"sysvar\">--report-port</option> option."
},
{
"para": "A zero in this column means that the slave port\n (<option role=\"sysvar\">--report-port</option>) was not set."
}
],
[
{
"para": "<literal>Master_id</literal>: 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 <literal>SHOW\n SLAVE HOSTS</literal> is executed, so this same value is\n listed for each row in the result."
}
],
[
{
"para": "<indexterm>\n <primary>auto.cnf file</primary>\n <secondary>and SHOW SLAVE HOSTS statement</secondary>\n </indexterm>\n\n <literal>Slave_UUID</literal>: The globally unique ID of\n this slave, as generated on the slave and found in the\n slave's <filename>auto.cnf</filename> 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 <literal role=\"priv\">SUPER</literal> or\n <literal role=\"priv\">REPLICATION CLIENT</literal> privilege."
},
{
"para": "<literal>SHOW SLAVE STATUS</literal> is nonblocking. When run\n concurrently with <literal role=\"stmt\">STOP SLAVE</literal>,\n <literal>SHOW SLAVE STATUS</literal> returns without waiting for\n <literal>STOP SLAVE</literal> 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 <literal>SHOW SLAVE STATUS</literal> more\n important than ensuring that it returned the latest data."
},
{
"para": "If you issue this statement using the <command>mysql</command>\n client, you can use a <literal>\\G</literal> statement terminator\n rather than a semicolon to obtain a more readable vertical\n layout:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW SLAVE STATUS\\G</userinput>\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 <literal role=\"stmt\">SHOW SLAVE STATUS</literal> statement,\n but represented in table form. For details, see\n <xref linkend=\"performance-schema-replication-tables\" />."
}
],
"id": "SHOW SLAVE STATUS",
"syntax": [
{
"programlisting": ">\nSHOW SLAVE STATUS [FOR CHANNEL <replaceable>channel</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"STATUS",
"GLOBAL",
"SESSION"
],
"description": [
{
"para": "With a <literal role=\"op\">LIKE</literal> clause, the statement\n displays only rows for those variables with names that match the\n pattern:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW STATUS LIKE 'Key%';</userinput>\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 '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"TABLE",
"STATUS"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW TABLE STATUS</literal> works likes\n <literal role=\"stmt\">SHOW TABLES</literal>, but provides a lot\n of information about each non-<literal>TEMPORARY</literal>\n table. You can also get this list using the <command>mysqlshow\n --status <replaceable>db_name</replaceable></command> command.\n The <literal role=\"op\">LIKE</literal> clause, if present,\n indicates which table names to match. The\n <literal>WHERE</literal> clause can be given to select rows\n using more general conditions, as discussed in\n <xref linkend=\"extended-show\" />."
}
],
"id": "SHOW TABLE STATUS",
"syntax": [
{
"programlisting": ">\nSHOW TABLE STATUS\n [{FROM | IN} <replaceable>db_name</replaceable>]\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"TABLES",
"EXTENDED",
"FULL"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW TABLES</literal> lists the\n non-<literal>TEMPORARY</literal> tables in a given database. You\n can also get this list using the <command>mysqlshow\n <replaceable>db_name</replaceable></command> command. The\n <literal role=\"op\">LIKE</literal> clause, if present, indicates\n which table names to match. The <literal>WHERE</literal> clause\n can be given to select rows using more general conditions, as\n discussed in <xref linkend=\"extended-show\" />."
},
{
"para": "Matching performed by the <literal>LIKE</literal> clause is\n dependent on the setting of the\n <literal role=\"sysvar\">lower_case_table_names</literal> system\n variable."
},
{
"para": "The optional <literal>EXTENDED</literal> modifier causes\n <literal role=\"stmt\">SHOW TABLES</literal> to list hidden tables\n created by failed <literal role=\"stmt\">ALTER TABLE</literal>\n statements. These temporary tables have names beginning with\n <literal>#sql</literal> and can be dropped using\n <literal role=\"stmt\">DROP TABLE</literal>."
},
{
"para": "This statement also lists any views in the database. The\n optional <literal>FULL</literal> modifier causes\n <literal role=\"stmt\">SHOW TABLES</literal> to display a second\n output column with values of <literal>BASE TABLE</literal> for a\n table, <literal>VIEW</literal> for a view, or <literal>SYSTEM\n VIEW</literal> for an <literal>INFORMATION_SCHEMA</literal>\n table."
},
{
"para": "If you have no privileges for a base table or view, it does not\n show up in the output from <literal role=\"stmt\">SHOW\n TABLES</literal> or <command>mysqlshow db_name</command>."
}
],
"id": "SHOW TABLES",
"syntax": [
{
"programlisting": ">\nSHOW [EXTENDED] [FULL] TABLES\n [{FROM | IN} <replaceable>db_name</replaceable>]\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"TRIGGERS"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW TRIGGERS</literal> lists the triggers\n currently defined for tables in a database (the default database\n unless a <literal>FROM</literal> clause is given). This\n statement returns results only for databases and tables for\n which you have the <literal role=\"priv\">TRIGGER</literal>\n privilege. The <literal role=\"op\">LIKE</literal> 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 <literal>WHERE</literal> clause can be given to\n select rows using more general conditions, as discussed in\n <xref linkend=\"extended-show\" />."
},
{
"para": "For the <literal>ins_sum</literal> trigger defined in\n <xref linkend=\"triggers\" />, the output of\n <literal role=\"stmt\">SHOW TRIGGERS</literal> is as shown here:"
},
{
"programlisting": ">\nmysql> <userinput>SHOW TRIGGERS LIKE 'acc%'\\G</userinput>\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} <replaceable>db_name</replaceable>]\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"VARIABLES",
"GLOBAL",
"SESSION"
],
"description": [
{
"para": "With a <literal role=\"op\">LIKE</literal> 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 <literal role=\"op\">LIKE</literal> 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 <literal>%</literal> wildcard character in a\n <literal role=\"op\">LIKE</literal> 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 <literal>_</literal> is a wildcard that matches any single\n character, you should escape it as <literal>\\_</literal> to\n match it literally. In practice, this is rarely necessary."
}
],
"id": "SHOW VARIABLES",
"syntax": [
{
"programlisting": ">\nSHOW [GLOBAL | SESSION] VARIABLES\n [LIKE '<replaceable>pattern</replaceable>' | WHERE <replaceable>expr</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"WARNINGS",
"COUNT"
],
"description": [
{
"para": "<literal role=\"stmt\">SHOW WARNINGS</literal> 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 <literal role=\"stmt\">INSERT</literal>,\n <literal role=\"stmt\">UPDATE</literal>, and\n <literal role=\"stmt\">LOAD DATA</literal> as well as DDL\n statements such as <literal role=\"stmt\">CREATE TABLE</literal>\n and <literal role=\"stmt\">ALTER TABLE</literal>."
},
{
"para": "The <literal>LIMIT</literal> clause has the same syntax as for\n the <literal role=\"stmt\">SELECT</literal> statement. See\n <xref linkend=\"select\" />."
},
{
"para": "<literal role=\"stmt\">SHOW WARNINGS</literal> is also used\n following <literal role=\"stmt\">EXPLAIN</literal>, to display the\n extended information generated by\n <literal role=\"stmt\">EXPLAIN</literal>. See\n <xref linkend=\"explain-extended\" />."
},
{
"para": "<literal role=\"stmt\">SHOW WARNINGS</literal> 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 <literal role=\"stmt\">SHOW WARNINGS</literal> shows the resulting\n conditions, regardless of statement type (diagnostic or\n nondiagnostic)."
},
{
"para": "The <literal condition=\"show-warnings\" role=\"stmt\">SHOW COUNT(*)\n WARNINGS</literal> diagnostic statement displays the total\n number of errors, warnings, and notes. You can also retrieve\n this number from the\n <literal role=\"sysvar\">warning_count</literal> 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 <literal role=\"stmt\">SELECT</literal>\n statement is considered nondiagnostic and does clear the message\n list."
},
{
"para": "A related diagnostic statement, <literal role=\"stmt\">SHOW\n ERRORS</literal>, shows only error conditions (it excludes\n warnings and notes), and\n <literal condition=\"show-warnings\" role=\"stmt\">SHOW COUNT(*)\n ERRORS</literal> statement displays the total number of errors.\n See <xref linkend=\"show-errors\" />. <literal role=\"stmt\">GET\n DIAGNOSTICS</literal> can be used to examine information for\n individual conditions. See <xref linkend=\"get-diagnostics\" />."
}
],
"id": "SHOW WARNINGS",
"syntax": [
{
"programlisting": ">\nSHOW WARNINGS [LIMIT [<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable>]\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": "<literal role=\"stmt\">SHOW</literal> 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 '<replaceable>log_name</replaceable>'] [FROM <replaceable>pos</replaceable>] [LIMIT [<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable>]\nSHOW CHARACTER SET [<replaceable>like_or_where</replaceable>]\nSHOW COLLATION [<replaceable>like_or_where</replaceable>]\nSHOW [FULL] COLUMNS FROM <replaceable>tbl_name</replaceable> [FROM <replaceable>db_name</replaceable>] [<replaceable>like_or_where</replaceable>]\nSHOW CREATE DATABASE <replaceable>db_name</replaceable>\nSHOW CREATE EVENT <replaceable>event_name</replaceable>\nSHOW CREATE FUNCTION <replaceable>func_name</replaceable>\nSHOW CREATE PROCEDURE <replaceable>proc_name</replaceable>\nSHOW CREATE TABLE <replaceable>tbl_name</replaceable>\nSHOW CREATE TRIGGER <replaceable>trigger_name</replaceable>\nSHOW CREATE VIEW <replaceable>view_name</replaceable>\nSHOW DATABASES [<replaceable>like_or_where</replaceable>]\nSHOW ENGINE <replaceable>engine_name</replaceable> {STATUS | MUTEX}\nSHOW [STORAGE] ENGINES\nSHOW ERRORS [LIMIT [<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable>]\nSHOW EVENTS\nSHOW FUNCTION CODE <replaceable>func_name</replaceable>\nSHOW FUNCTION STATUS [<replaceable>like_or_where</replaceable>]\nSHOW GRANTS FOR <replaceable>user</replaceable>\nSHOW INDEX FROM <replaceable>tbl_name</replaceable> [FROM <replaceable>db_name</replaceable>]\nSHOW MASTER STATUS\nSHOW OPEN TABLES [FROM <replaceable>db_name</replaceable>] [<replaceable>like_or_where</replaceable>]\nSHOW PLUGINS\nSHOW PROCEDURE CODE <replaceable>proc_name</replaceable>\nSHOW PROCEDURE STATUS [<replaceable>like_or_where</replaceable>]\nSHOW PRIVILEGES\nSHOW [FULL] PROCESSLIST\nSHOW PROFILE [<replaceable>types</replaceable>] [FOR QUERY <replaceable>n</replaceable>] [OFFSET <replaceable>n</replaceable>] [LIMIT <replaceable>n</replaceable>]\nSHOW PROFILES\nSHOW RELAYLOG EVENTS [IN '<replaceable>log_name</replaceable>'] [FROM <replaceable>pos</replaceable>] [LIMIT [<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable>]\nSHOW SLAVE HOSTS\nSHOW SLAVE STATUS [FOR CHANNEL <replaceable>channel</replaceable>]\nSHOW [GLOBAL | SESSION] STATUS [<replaceable>like_or_where</replaceable>]\nSHOW TABLE STATUS [FROM <replaceable>db_name</replaceable>] [<replaceable>like_or_where</replaceable>]\nSHOW [FULL] TABLES [FROM <replaceable>db_name</replaceable>] [<replaceable>like_or_where</replaceable>]\nSHOW TRIGGERS [FROM <replaceable>db_name</replaceable>] [<replaceable>like_or_where</replaceable>]\nSHOW [GLOBAL | SESSION] VARIABLES [<replaceable>like_or_where</replaceable>]\nSHOW WARNINGS [LIMIT [<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable>]\n\n<replaceable>like_or_where</replaceable>:\n LIKE '<replaceable>pattern</replaceable>'\n | WHERE <replaceable>expr</replaceable>"
},
{
"para": "If the syntax for a given <literal role=\"stmt\">SHOW</literal>\n statement includes a <literal condition=\"like\" role=\"op\">LIKE\n '<replaceable>pattern</replaceable>'</literal> part,\n <literal>'<replaceable>pattern</replaceable>'</literal> is a\n string that can contain the SQL <literal>%</literal> and\n <literal>_</literal> wildcard characters. The pattern is useful\n for restricting statement output to matching values."
},
{
"para": "Several <literal role=\"stmt\">SHOW</literal> statements also accept\n a <literal>WHERE</literal> clause that provides more flexibility\n in specifying which rows to display. See\n <xref linkend=\"extended-show\" />."
}
],
"id": "SHOW",
"syntax": []
},
{
"keywords": [
"BINLOG"
],
"description": [
{
"para": "<literal role=\"stmt\">BINLOG</literal> is an internal-use\n statement. It is generated by the <command>mysqlbinlog</command>\n program as the printable representation of certain events in\n binary log files. (See <xref linkend=\"mysqlbinlog\" />.) The\n <literal>'<replaceable>str</replaceable>'</literal> 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 <literal role=\"stmt\">BINLOG</literal> statements when\n applying <command>mysqlbinlog</command> output, a user account\n requires the <literal role=\"priv\">BINLOG_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege, or the\n <literal role=\"priv\">REPLICATION_APPLIER</literal> privilege\n plus the appropriate privileges to execute each log event."
}
],
"id": "BINLOG",
"syntax": [
{
"programlisting": ">\nBINLOG '<replaceable>str</replaceable>'"
}
]
},
{
"keywords": [
"CACHE",
"INDEX",
"PARTITION",
"ALL"
],
"description": [
{
"para": "The <literal role=\"stmt\">CACHE INDEX</literal> statement assigns\n table indexes to a specific key cache. It applies only to\n <literal>MyISAM</literal> tables, including partitioned\n <literal>MyISAM</literal> tables. After the indexes have been\n assigned, they can be preloaded into the cache if desired with\n <literal condition=\"load-index\" role=\"stmt\">LOAD INDEX INTO\n CACHE</literal>."
},
{
"para": "The following statement assigns indexes from the tables\n <literal>t1</literal>, <literal>t2</literal>, and\n <literal>t3</literal> to the key cache named\n <literal>hot_cache</literal>:"
},
{
"programlisting": ">\nmysql> <userinput>CACHE INDEX t1, t2, t3 IN hot_cache;</userinput>\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 <replaceable>tbl_index_list</replaceable> [, <replaceable>tbl_index_list</replaceable>] ...\n | <replaceable>tbl_name</replaceable> PARTITION (<replaceable>partition_list</replaceable>)\n }\n IN <replaceable>key_cache_name</replaceable>\n\n<replaceable>tbl_index_list</replaceable>:\n <replaceable>tbl_name</replaceable> [{INDEX|KEY} (<replaceable>index_name</replaceable>[, <replaceable>index_name</replaceable>] ...)]\n\n<replaceable>partition_list</replaceable>: {\n <replaceable>partition_name</replaceable>[, <replaceable>partition_name</replaceable>] ...\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 <literal role=\"stmt\">FLUSH</literal> statement has several\n variant forms that clear or reload various internal caches,\n flush tables, or acquire locks. To execute\n <literal role=\"stmt\">FLUSH</literal>, you must have the\n <literal role=\"priv\">RELOAD</literal> privilege. Specific flush\n options might require additional privileges, as described later."
},
{
"para": "By default, the server writes\n <literal role=\"stmt\">FLUSH</literal> statements to the binary\n log so that they replicate to replication slaves. To suppress\n logging, specify the optional\n <literal>NO_WRITE_TO_BINLOG</literal> keyword or its alias\n <literal>LOCAL</literal>."
},
{
"para": "The <literal role=\"stmt\">FLUSH</literal> statement causes an\n implicit commit. See <xref linkend=\"implicit-commit\" />."
},
{
"para": "The <command>mysqladmin</command> utility provides a\n command-line interface to some flush operations, using commands\n such as <literal>flush-hosts</literal>,\n <literal>flush-logs</literal>,\n <literal>flush-privileges</literal>,\n <literal>flush-status</literal>, and\n <literal>flush-tables</literal>. See\n <xref linkend=\"mysqladmin\" />."
},
{
"para": "Sending a <literal>SIGHUP</literal> signal to the server causes\n several flush operations to occur that are similar to various\n forms of the <literal role=\"stmt\">FLUSH</literal> statement. See\n <xref linkend=\"server-signal-response\" />."
},
{
"para": "The <literal role=\"stmt\">RESET</literal> statement is similar to\n <literal role=\"stmt\">FLUSH</literal>. See\n <xref linkend=\"reset\" />, for information about using the\n <literal role=\"stmt\">RESET</literal> statement with replication."
}
],
"id": "FLUSH",
"syntax": [
{
"programlisting": ">\nFLUSH [NO_WRITE_TO_BINLOG | LOCAL] {\n <replaceable>flush_option</replaceable> [, <replaceable>flush_option</replaceable>] ...\n | <replaceable>tables_option</replaceable>\n}\n\n<replaceable>flush_option</replaceable>: {\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 <replaceable>channel</replaceable>]\n | SLOW LOGS\n | STATUS\n | USER_RESOURCES\n}\n\n<replaceable>tables_option</replaceable>: {\n TABLES\n | TABLES <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ...\n | TABLES WITH READ LOCK\n | TABLES <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ... WITH READ LOCK\n | TABLES <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ... FOR EXPORT\n}"
}
]
},
{
"keywords": [
"KILL",
"CONNECTION",
"QUERY"
],
"description": [
{
"para": "Each connection to <command>mysqld</command> runs in a separate\n thread. You can kill a thread with the <literal>KILL\n <replaceable>processlist_id</replaceable></literal> statement."
},
{
"para": "Thread processlist identifiers can be determined from the\n <literal>ID</literal> column of the\n <literal>INFORMATION_SCHEMA</literal>\n <literal role=\"is\">PROCESSLIST</literal> table, the\n <literal>Id</literal> column of <literal role=\"stmt\">SHOW\n PROCESSLIST</literal> output, and the\n <literal>PROCESSLIST_ID</literal> column of the Performance\n Schema <literal role=\"ps\">threads</literal> table. The value for\n the current thread is returned by the\n <literal role=\"func\">CONNECTION_ID()</literal> function."
},
{
"para": "<literal role=\"stmt\">KILL</literal> permits an optional\n <literal>CONNECTION</literal> or <literal>QUERY</literal>\n modifier:"
},
{
"itemizedlist": [
[
{
"para": "<literal condition=\"kill\" role=\"stmt\">KILL\n CONNECTION</literal> is the same as\n <literal role=\"stmt\">KILL</literal> with no modifier: It\n terminates the connection associated with the given\n <replaceable>processlist_id</replaceable>, after terminating\n any statement the connection is executing."
}
],
[
{
"para": "<literal condition=\"kill\" role=\"stmt\">KILL QUERY</literal>\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 <literal role=\"priv\">PROCESS</literal> privilege:"
},
{
"itemizedlist": [
[
{
"para": "Without <literal role=\"priv\">PROCESS</literal>, you can see\n only your own threads."
}
],
[
{
"para": "With <literal role=\"priv\">PROCESS</literal>, you can see all\n threads."
}
]
]
},
{
"para": "The ability to kill threads and statements depends on the\n <literal role=\"priv\">CONNECTION_ADMIN</literal> and\n <literal role=\"priv\">SUPER</literal> privileges:"
},
{
"itemizedlist": [
[
{
"para": "Without <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal>, you can kill only your\n own threads and statements."
}
],
[
{
"para": "With <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal>, you can kill all\n threads and statements, except that to affect a thread or\n statement that is executing with the\n <literal role=\"priv\">SYSTEM_USER</literal> privilege, your\n own session must additionally have the\n <literal role=\"priv\">SYSTEM_USER</literal> privilege."
}
]
]
},
{
"para": "You can also use the <command>mysqladmin processlist</command>\n and <command>mysqladmin kill</command> commands to examine and\n kill threads."
}
],
"id": "KILL",
"syntax": [
{
"programlisting": ">\nKILL [CONNECTION | QUERY] <replaceable>processlist_id</replaceable>"
}
]
},
{
"keywords": [
"LOAD",
"INDEX",
"INTO",
"CACHE",
"PARTITION",
"IGNORE",
"LEAVES",
"ALL"
],
"description": [
{
"para": "The <literal condition=\"load-index\" role=\"stmt\">LOAD INDEX INTO\n CACHE</literal> statement preloads a table index into the key\n cache to which it has been assigned by an explicit\n <literal role=\"stmt\">CACHE INDEX</literal> statement, or into\n the default key cache otherwise."
},
{
"para": "<literal condition=\"load-index\" role=\"stmt\">LOAD INDEX INTO\n CACHE</literal> applies only to <literal>MyISAM</literal>\n tables, including partitioned <literal>MyISAM</literal> tables.\n In addition, indexes on partitioned tables can be preloaded for\n one, several, or all partitions."
},
{
"para": "The <literal>IGNORE LEAVES</literal> modifier causes only blocks\n for the nonleaf nodes of the index to be preloaded."
},
{
"para": "<literal>IGNORE LEAVES</literal> is also supported for\n partitioned <literal>MyISAM</literal> tables."
}
],
"id": "LOAD INDEX",
"syntax": [
{
"programlisting": ">\nLOAD INDEX INTO CACHE\n <replaceable>tbl_index_list</replaceable> [, <replaceable>tbl_index_list</replaceable>] ...\n\n<replaceable>tbl_index_list</replaceable>:\n <replaceable>tbl_name</replaceable>\n [PARTITION (<replaceable>partition_list</replaceable>)]\n [{INDEX|KEY} (<replaceable>index_name</replaceable>[, <replaceable>index_name</replaceable>] ...)]\n [IGNORE LEAVES]\n\n<replaceable>partition_list</replaceable>: {\n <replaceable>partition_name</replaceable>[, <replaceable>partition_name</replaceable>] ...\n | ALL\n}"
}
]
},
{
"keywords": [
"RESET",
"MASTER",
"SLAVE"
],
"description": [
{
"para": "The <literal role=\"stmt\">RESET</literal> statement is used to\n clear the state of various server operations. You must have the\n <literal role=\"priv\">RELOAD</literal> privilege to execute\n <literal role=\"stmt\">RESET</literal>."
},
{
"para": "For information about the <literal role=\"stmt\">RESET\n PERSIST</literal> statement that removes persisted global system\n variables, see <xref linkend=\"reset-persist\" />."
},
{
"para": "<literal role=\"stmt\">RESET</literal> acts as a stronger version\n of the <literal role=\"stmt\">FLUSH</literal> statement. See\n <xref linkend=\"flush\" />."
},
{
"para": "The <literal role=\"stmt\">RESET</literal> statement causes an\n implicit commit. See <xref linkend=\"implicit-commit\" />."
},
{
"para": "The following list describes the permitted\n <literal role=\"stmt\">RESET</literal> statement\n <replaceable>reset_option</replaceable> values:"
},
{
"itemizedlist": [
[
{
"para": "<literal>RESET MASTER</literal>"
},
{
"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": "<literal>RESET SLAVE</literal>"
},
{
"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 <replaceable>reset_option</replaceable> [, <replaceable>reset_option</replaceable>] ...\n\n<replaceable>reset_option</replaceable>: {\n MASTER\n | SLAVE\n}"
}
]
},
{
"keywords": [
"RESET",
"PERSIST",
"IF",
"EXISTS"
],
"description": [
{
"para": "<literal role=\"stmt\">RESET PERSIST</literal> removes persisted\n global system variable settings from the\n <filename>mysqld-auto.cnf</filename> option file in the data\n directory. Removing a persisted system variable causes the\n variable no longer to be initialized from\n <filename>mysqld-auto.cnf</filename> at server startup. For more\n information about persisting system variables and the\n <filename>mysqld-auto.cnf</filename> file, see\n <xref linkend=\"persisted-system-variables\" />."
},
{
"para": "The privileges required for <literal role=\"stmt\">RESET\n PERSIST</literal> depend on the type of system variable to be\n removed:"
},
{
"itemizedlist": [
[
{
"para": "For dynamic system variables, this statement requires the\n <literal role=\"priv\">SYSTEM_VARIABLES_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> privilege."
}
],
[
{
"para": "For read-only system variables, this statement requires the\n <literal role=\"priv\">SYSTEM_VARIABLES_ADMIN</literal> and\n <literal role=\"priv\">PERSIST_RO_VARIABLES_ADMIN</literal>\n privileges."
}
]
]
},
{
"para": "See <xref linkend=\"system-variable-privileges\" />."
},
{
"para": "Depending on whether the variable name and <literal>IF\n EXISTS</literal> clauses are present, the\n <literal role=\"stmt\">RESET PERSIST</literal> statement has these\n forms:"
},
{
"itemizedlist": [
[
{
"para": "To remove all persisted variables from\n <filename>mysqld-auto.cnf</filename>, use\n <literal role=\"stmt\">RESET PERSIST</literal> 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 <filename>mysqld-auto.cnf</filename> contains both kinds of\n variables."
}
],
[
{
"para": "To remove a specific persisted variable from\n <filename>mysqld-auto.cnf</filename>, name it in the\n statement:"
},
{
"programlisting": ">\nRESET PERSIST <replaceable>system_var_name</replaceable>;"
},
{
"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 <filename>mysqld-auto.cnf</filename>, but produce a warning\n rather than an error if the variable is not present in the\n file, add an <literal>IF EXISTS</literal> clause to the\n previous syntax:"
},
{
"programlisting": ">\nRESET PERSIST IF EXISTS <replaceable>system_var_name</replaceable>;"
}
]
]
}
],
"id": "RESET PERSIST",
"syntax": [
{
"programlisting": ">\nRESET PERSIST [[IF EXISTS] <replaceable>system_var_name</replaceable>]"
}
]
},
{
"keywords": [
"RESTART"
],
"description": [
{
"para": "This statement stops and restarts the MySQL server. It requires\n the <literal role=\"priv\">SHUTDOWN</literal> privilege."
},
{
"para": "One use for <literal role=\"stmt\">RESTART</literal> 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 <literal condition=\"set-variable\" role=\"stmt\">SET\n PERSIST_ONLY</literal> 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 <literal role=\"stmt\">RESTART</literal> 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 <literal role=\"stmt\">RESTART</literal> operation\n requires <command>mysqld</command> 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 <literal role=\"stmt\">RESTART</literal> causes\n <command>mysqld</command> to terminate such that the\n monitoring process can determine that it should start a new\n <command>mysqld</command> instance."
}
],
[
{
"para": "If no monitoring process is present,\n <literal role=\"stmt\">RESTART</literal> fails with an error."
}
]
]
},
{
"para": "These platforms provide the necessary monitoring support for the\n <literal role=\"stmt\">RESTART</literal> statement:"
},
{
"itemizedlist": [
[
{
"para": "Windows, when <command>mysqld</command> is started as a\n Windows service or standalone. (<command>mysqld</command>\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 <command>mysqld_safe</command> to manage\n <command>mysqld</command>."
}
]
]
},
{
"para": "To configure a monitoring environment such that\n <command>mysqld</command> enables the\n <literal role=\"stmt\">RESTART</literal> statement:"
},
{
"para": "Here is a minimal example as implemented in the\n <command>bash</command> shell:"
},
{
"programlisting": ">\n#!/bin/bash\n\nexport MYSQLD_PARENT_PID=$$\n\nexport MYSQLD_RESTART_EXIT=16\n\nwhile true ; do\n bin/mysqld <replaceable>mysqld options here</replaceable>\n if [ $? -ne $MYSQLD_RESTART_EXIT ]; then\n break\n fi\ndone"
},
{
"para": "On Windows, the forking used to implement\n <literal role=\"stmt\">RESTART</literal> makes determining the\n server process to attach to for debugging more difficult. To\n alleviate this, starting the server with\n <option role=\"mysqld\">--gdb</option> suppresses forking, in\n addition to its other actions done to set up a debugging\n environment. In non-debug settings,\n <option role=\"mysqld\">--no-monitor</option> may be used for the\n sole purpose of suppressing forking the monitor process. For a\n server started with either <option role=\"mysqld\">--gdb</option>\n or <option role=\"mysqld\">--no-monitor</option>, executing\n <literal role=\"stmt\">RESTART</literal> 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 <literal role=\"priv\">SHUTDOWN</literal> privilege."
},
{
"para": "<literal role=\"stmt\">SHUTDOWN</literal> provides an SQL-level\n interface to the same functionality available using the\n <command>mysqladmin shutdown</command> command or the\n <literal role=\"cfunc\">mysql_shutdown()</literal> 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 <link linkend=\"glos_transaction\">transactions</link>:"
},
{
"itemizedlist": [
[
{
"para": "<literal>START TRANSACTION</literal> or\n <literal>BEGIN</literal> start a new transaction."
}
],
[
{
"para": "<literal>COMMIT</literal> commits the current transaction,\n making its changes permanent."
}
],
[
{
"para": "<literal>ROLLBACK</literal> rolls back the current\n transaction, canceling its changes."
}
],
[
{
"para": "<literal>SET autocommit</literal> disables or enables the\n default autocommit mode for the current session."
}
]
]
},
{
"para": "By default, MySQL runs with\n <link linkend=\"glos_autocommit\">autocommit</link> mode enabled.\n This means that, when not otherwise inside a transaction, each\n statement is atomic, as if it were surrounded by <literal>START\n TRANSACTION</literal> and <literal>COMMIT</literal>. You cannot\n use <literal>ROLLBACK</literal> 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 <literal>START TRANSACTION</literal>\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 <literal>START TRANSACTION</literal>, autocommit remains\n disabled until you end the transaction with\n <literal>COMMIT</literal> or <literal>ROLLBACK</literal>. The\n autocommit mode then reverts to its previous state."
},
{
"para": "<literal>START TRANSACTION</literal> permits several modifiers\n that control transaction characteristics. To specify multiple\n modifiers, separate them by commas."
},
{
"itemizedlist": [
[
{
"para": "The <literal>WITH CONSISTENT SNAPSHOT</literal> modifier\n starts a <link linkend=\"glos_consistent_read\">consistent\n read</link> for storage engines that are capable of it. This\n applies only to <literal>InnoDB</literal>. The effect is the\n same as issuing a <literal>START TRANSACTION</literal>\n followed by a <literal role=\"stmt\">SELECT</literal> from any\n <literal>InnoDB</literal> table. See\n <xref linkend=\"innodb-consistent-read\" />. The <literal>WITH\n CONSISTENT SNAPSHOT</literal> modifier does not change the\n current transaction\n <link linkend=\"glos_isolation_level\">isolation level</link>,\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 <literal role=\"isolevel\">REPEATABLE READ</literal>. For all\n other isolation levels, the <literal>WITH CONSISTENT\n SNAPSHOT</literal> clause is ignored. A warning is generated\n when the <literal>WITH CONSISTENT SNAPSHOT</literal> clause is\n ignored."
}
],
[
{
"para": "The <literal>READ WRITE</literal> and <literal>READ\n ONLY</literal> modifiers set the transaction access mode. They\n permit or prohibit changes to tables used in the transaction.\n The <literal>READ ONLY</literal> 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 <literal>InnoDB</literal> tables when the transaction is known\n to be read-only. Specifying <literal>READ ONLY</literal>\n ensures these optimizations are applied in cases where the\n read-only status cannot be determined automatically. See\n <xref linkend=\"innodb-performance-ro-txn\" /> 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 <literal>READ WRITE</literal>\n and <literal>READ ONLY</literal> in the same statement."
},
{
"para": "In read-only mode, it remains possible to change tables\n created with the <literal>TEMPORARY</literal> 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 <xref linkend=\"set-transaction\" />."
},
{
"para": "If the <literal role=\"sysvar\">read_only</literal> system\n variable is enabled, explicitly starting a transaction with\n <literal>START TRANSACTION READ WRITE</literal> requires the\n <literal role=\"priv\">CONNECTION_ADMIN</literal> or\n <literal role=\"priv\">SUPER</literal> 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 <literal role=\"sysvar\">autocommit</literal> variable to zero,\n changes to transaction-safe tables (such as those for\n <literal role=\"se\">InnoDB</literal> or\n <literal role=\"se\">NDB</literal>) are not made permanent\n immediately. You must use <literal role=\"stmt\">COMMIT</literal> to\n store your changes to disk or <literal>ROLLBACK</literal> to\n ignore the changes."
},
{
"para": "<literal role=\"sysvar\">autocommit</literal> 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 <literal role=\"sysvar\">autocommit</literal> system variable at\n <xref linkend=\"server-system-variables\" />."
},
{
"para": "<literal>BEGIN</literal> and <literal>BEGIN WORK</literal> are\n supported as aliases of <literal>START TRANSACTION</literal> for\n initiating a transaction. <literal>START TRANSACTION</literal> is\n standard SQL syntax, is the recommended way to start an ad-hoc\n transaction, and permits modifiers that <literal>BEGIN</literal>\n does not."
},
{
"para": "The <literal>BEGIN</literal> statement differs from the use of the\n <literal>BEGIN</literal> keyword that starts a\n <literal condition=\"begin-end\" role=\"stmt\">BEGIN ... END</literal>\n compound statement. The latter does not begin a transaction. See\n <xref linkend=\"begin-end\" />."
},
{
"para": "The optional <literal>WORK</literal> keyword is supported for\n <literal>COMMIT</literal> and <literal>ROLLBACK</literal>, as are\n the <literal>CHAIN</literal> and <literal>RELEASE</literal>\n clauses. <literal>CHAIN</literal> and <literal>RELEASE</literal>\n can be used for additional control over transaction completion.\n The value of the <literal role=\"sysvar\">completion_type</literal>\n system variable determines the default completion behavior. See\n <xref linkend=\"server-system-variables\" />."
},
{
"para": "The <literal>AND CHAIN</literal> 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 (<literal>READ\n WRITE</literal> or <literal>READ ONLY</literal>) as the\n just-terminated transaction. The <literal>RELEASE</literal> clause\n causes the server to disconnect the current client session after\n terminating the current transaction. Including the\n <literal>NO</literal> keyword suppresses <literal>CHAIN</literal>\n or <literal>RELEASE</literal> completion, which can be useful if\n the <literal role=\"sysvar\">completion_type</literal> system\n variable is set to cause chaining or release completion by\n default."
}
],
"id": "START TRANSACTION",
"syntax": [
{
"programlisting": ">\nSTART TRANSACTION\n [<replaceable>transaction_characteristic</replaceable> [, <replaceable>transaction_characteristic</replaceable>] ...]\n\n<replaceable>transaction_characteristic</replaceable>: {\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": "<literal>InnoDB</literal> supports the SQL statements\n <literal role=\"stmt\">SAVEPOINT</literal>,\n <literal condition=\"savepoint\" role=\"stmt\">ROLLBACK TO\n SAVEPOINT</literal>,\n <literal condition=\"savepoint\" role=\"stmt\">RELEASE\n SAVEPOINT</literal> and the optional <literal>WORK</literal>\n keyword for\n <literal condition=\"commit\" role=\"stmt\">ROLLBACK</literal>."
}
],
"id": "SAVEPOINT",
"syntax": [
{
"programlisting": ">\nSAVEPOINT <replaceable>identifier</replaceable>\nROLLBACK [WORK] TO [SAVEPOINT] <replaceable>identifier</replaceable>\nRELEASE SAVEPOINT <replaceable>identifier</replaceable>"
}
]
},
{
"keywords": [
"LOCK",
"UNLOCK",
"INSTANCE",
"BACKUP"
],
"description": [
{
"para": "<literal>LOCK INSTANCE FOR BACKUP</literal> acquires an\n instance-level <emphasis>backup lock</emphasis> that permits DML\n during an online backup while preventing operations that could\n result in an inconsistent snapshot."
},
{
"para": "Executing the <literal>LOCK INSTANCE FOR BACKUP</literal>\n statement requires the <literal role=\"priv\">BACKUP_ADMIN</literal>\n privilege. The <literal role=\"priv\">BACKUP_ADMIN</literal>\n privilege is automatically granted to users with the\n <literal role=\"priv\">RELOAD</literal> 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": "<literal>UNLOCK INSTANCE</literal> 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": "<literal>LOCK INSTANCE FOR BACKUP</literal> prevents files from\n being created, renamed, or removed. <literal role=\"stmt\">REPAIR\n TABLE</literal> <literal role=\"stmt\">TRUNCATE TABLE</literal>,\n <literal role=\"stmt\">OPTIMIZE TABLE</literal>, and account\n management statements are blocked. See\n <xref linkend=\"account-management-statements\" />. Operations that modify\n <literal>InnoDB</literal> files that are not recorded in the\n <literal>InnoDB</literal> redo log are also blocked."
},
{
"para": "<literal>LOCK INSTANCE FOR BACKUP</literal> 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 <literal>LOCK INSTANCE FOR\n BACKUP</literal> is independent of transactional locks and locks\n taken by\n <literal condition=\"flush-tables-with-read-lock-with-list\" role=\"stmt\">FLUSH\n TABLES <replaceable>tbl_name</replaceable> [,\n <replaceable>tbl_name</replaceable>] ... WITH READ LOCK</literal>,\n and the following sequences of statements are permitted:"
},
{
"programlisting": ">\nLOCK INSTANCE FOR BACKUP;\nFLUSH TABLES <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ... WITH READ LOCK;\nUNLOCK TABLES;\nUNLOCK INSTANCE;"
},
{
"programlisting": ">\nFLUSH TABLES <replaceable>tbl_name</replaceable> [, <replaceable>tbl_name</replaceable>] ... WITH READ LOCK;\nLOCK INSTANCE FOR BACKUP;\nUNLOCK INSTANCE;\nUNLOCK TABLES;"
},
{
"para": "The <literal role=\"sysvar\">lock_wait_timeout</literal> setting\n defines the amount of time that a <literal>LOCK INSTANCE FOR\n BACKUP</literal> 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 <xref linkend=\"lock-tables-restrictions\" />."
},
{
"para": "<literal role=\"stmt\">LOCK TABLES</literal> 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 <literal role=\"priv\">LOCK TABLES</literal> privilege, and the\n <literal role=\"priv\">SELECT</literal> privilege for each object to\n be locked."
},
{
"para": "For view locking, <literal role=\"stmt\">LOCK TABLES</literal> 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 <literal role=\"stmt\">LOCK TABLES</literal>, any tables used in\n triggers are also locked implicitly, as described in\n <xref linkend=\"lock-tables-and-triggers\" />."
},
{
"para": "If you lock a table explicitly with <literal role=\"stmt\">LOCK\n TABLES</literal>, any tables related by a foreign key constraint\n are opened and locked implicitly. For foreign key checks, a shared\n read-only lock (<literal condition=\"lock-tables\" role=\"stmt\">LOCK\n TABLES READ</literal>) is taken on related tables. For cascading\n updates, a shared-nothing write lock\n (<literal condition=\"lock-tables\" role=\"stmt\">LOCK TABLES\n WRITE</literal>) is taken on related tables that are involved in\n the operation."
},
{
"para": "<literal condition=\"lock-tables\" role=\"stmt\">UNLOCK\n TABLES</literal> explicitly releases any table locks held by the\n current session. <literal role=\"stmt\">LOCK TABLES</literal>\n implicitly releases any table locks held by the current session\n before acquiring new locks."
},
{
"para": "Another use for\n <literal condition=\"lock-tables\" role=\"stmt\">UNLOCK\n TABLES</literal> is to release the global read lock acquired with\n the <literal role=\"stmt\">FLUSH TABLES WITH READ LOCK</literal>\n statement, which enables you to lock all tables in all databases.\n See <xref linkend=\"flush\" />. (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 <replaceable>tbl_name</replaceable> [[AS] <replaceable>alias</replaceable>] <replaceable>lock_type</replaceable>\n [, <replaceable>tbl_name</replaceable> [[AS] <replaceable>alias</replaceable>] <replaceable>lock_type</replaceable>] ...\n\n<replaceable>lock_type</replaceable>: {\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 <link linkend=\"glos_transaction\">transaction</link>\n characteristics. It takes a list of one or more characteristic\n values separated by commas. Each characteristic value sets the\n transaction <link linkend=\"glos_isolation_level\">isolation\n level</link> or access mode. The isolation level is used for\n operations on <literal role=\"se\">InnoDB</literal> tables. The\n access mode specifies whether transactions operate in read/write\n or read-only mode."
},
{
"para": "In addition, <literal role=\"stmt\">SET TRANSACTION</literal> can\n include an optional <literal>GLOBAL</literal> or\n <literal>SESSION</literal> keyword to indicate the scope of the\n statement."
}
],
"id": "SET TRANSACTION",
"syntax": [
{
"programlisting": ">\nSET [GLOBAL | SESSION] TRANSACTION\n <replaceable>transaction_characteristic</replaceable> [, <replaceable>transaction_characteristic</replaceable>] ...\n\n<replaceable>transaction_characteristic</replaceable>: {\n ISOLATION LEVEL <replaceable>level</replaceable>\n | <replaceable>access_mode</replaceable>\n}\n\n<replaceable>level</replaceable>: {\n REPEATABLE READ\n | READ COMMITTED\n | READ UNCOMMITTED\n | SERIALIZABLE\n}\n\n<replaceable>access_mode</replaceable>: {\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 <literal condition=\"xa-statements\" role=\"stmt\">XA\n START</literal>, the <literal>JOIN</literal> and\n <literal>RESUME</literal> clauses are recognized but have no\n effect."
},
{
"para": "For <literal condition=\"xa-statements\" role=\"stmt\">XA\n END</literal> the <literal>SUSPEND [FOR MIGRATE]</literal>\n clause is recognized but has no effect."
},
{
"para": "Each XA statement begins with the <literal>XA</literal> keyword,\n and most of them require an <replaceable>xid</replaceable>\n value. An <replaceable>xid</replaceable> is an XA transaction\n identifier. It indicates which transaction the statement applies\n to. <replaceable>xid</replaceable> values are supplied by the\n client, or generated by the MySQL server. An\n <replaceable>xid</replaceable> value has from one to three\n parts:"
},
{
"programlisting": ">\n<replaceable>xid</replaceable>: <replaceable>gtrid</replaceable> [, <replaceable>bqual</replaceable> [, <replaceable>formatID</replaceable> ]]"
},
{
"para": "<replaceable>gtrid</replaceable> is a global transaction\n identifier, <replaceable>bqual</replaceable> is a branch\n qualifier, and <replaceable>formatID</replaceable> is a number\n that identifies the format used by the\n <replaceable>gtrid</replaceable> and\n <replaceable>bqual</replaceable> values. As indicated by the\n syntax, <replaceable>bqual</replaceable> and\n <replaceable>formatID</replaceable> are optional. The default\n <replaceable>bqual</replaceable> value is <literal>''</literal>\n if not given. The default <replaceable>formatID</replaceable>\n value is 1 if not given."
},
{
"para": "<replaceable>gtrid</replaceable> and\n <replaceable>bqual</replaceable> must be string literals, each\n up to 64 bytes (not characters) long.\n <replaceable>gtrid</replaceable> and\n <replaceable>bqual</replaceable> can be specified in several\n ways. You can use a quoted string (<literal>'ab'</literal>), hex\n string (<literal>X'6162'</literal>, <literal>0x6162</literal>),\n or bit value\n (<literal>b'<replaceable>nnnn</replaceable>'</literal>)."
},
{
"para": "<replaceable>formatID</replaceable> is an unsigned integer."
},
{
"para": "The <replaceable>gtrid</replaceable> and\n <replaceable>bqual</replaceable> 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 <replaceable>gtrid</replaceable> and\n <replaceable>bqual</replaceable> as hex strings."
},
{
"para": "<replaceable>xid</replaceable> 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 <replaceable>xid</replaceable> values\n in a list of values returned by the\n <literal condition=\"xa-statements\" role=\"stmt\">XA\n RECOVER</literal> statement."
},
{
"para": "<literal condition=\"xa-statements\" role=\"stmt\">XA START\n <replaceable>xid</replaceable></literal> starts an XA\n transaction with the given <replaceable>xid</replaceable> value.\n Each XA transaction must have a unique\n <replaceable>xid</replaceable> value, so the value must not\n currently be used by another XA transaction. Uniqueness is\n assessed using the <replaceable>gtrid</replaceable> and\n <replaceable>bqual</replaceable> values. All following XA\n statements for the XA transaction must be specified using the\n same <replaceable>xid</replaceable> value as that given in the\n <literal condition=\"xa-statements\" role=\"stmt\">XA\n START</literal> statement. If you use any of those statements\n but specify an <replaceable>xid</replaceable> 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 <replaceable>gtrid</replaceable>\n value in the <replaceable>xid</replaceable> value. For this\n reason, <replaceable>gtrid</replaceable> 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 <replaceable>bqual</replaceable> part of the\n <replaceable>xid</replaceable> value must be different for each\n XA transaction within a global transaction. (The requirement\n that <replaceable>bqual</replaceable> values be different is a\n limitation of the current MySQL XA implementation. It is not\n part of the XA specification.)"
},
{
"para": "The <literal condition=\"xa-statements\" role=\"stmt\">XA\n RECOVER</literal> statement returns information for those XA\n transactions on the MySQL server that are in the\n <literal>PREPARED</literal> state. (See\n <xref linkend=\"xa-states\" />.) The output includes a row for each\n such XA transaction on the server, regardless of which client\n started it."
},
{
"para": "<literal condition=\"xa-statements\" role=\"stmt\">XA\n RECOVER</literal> requires the\n <literal role=\"priv\">XA_RECOVER_ADMIN</literal> 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": "<literal condition=\"xa-statements\" role=\"stmt\">XA\n RECOVER</literal> output rows look like this (for an example\n <replaceable>xid</replaceable> value consisting of the parts\n <literal>'abc'</literal>, <literal>'def'</literal>, and\n <literal>7</literal>):"
},
{
"programlisting": ">\nmysql> <userinput>XA RECOVER;</userinput>\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": "<literal>formatID</literal> is the\n <replaceable>formatID</replaceable> part of the transaction\n <replaceable>xid</replaceable>"
}
],
[
{
"para": "<literal>gtrid_length</literal> is the length in bytes of\n the <replaceable>gtrid</replaceable> part of the\n <replaceable>xid</replaceable>"
}
],
[
{
"para": "<literal>bqual_length</literal> is the length in bytes of\n the <replaceable>bqual</replaceable> part of the\n <replaceable>xid</replaceable>"
}
],
[
{
"para": "<literal>data</literal> is the concatenation of the\n <replaceable>gtrid</replaceable> and\n <replaceable>bqual</replaceable> parts of the\n <replaceable>xid</replaceable>"
}
]
]
},
{
"para": "XID values may contain nonprintable characters.\n <literal condition=\"xa-statements\" role=\"stmt\">XA\n RECOVER</literal> permits an optional <literal>CONVERT\n XID</literal> clause so that clients can request XID values in\n hexadecimal."
}
],
"id": "XA",
"syntax": [
{
"programlisting": ">\nXA {START|BEGIN} <replaceable>xid</replaceable> [JOIN|RESUME]\n\nXA END <replaceable>xid</replaceable> [SUSPEND [FOR MIGRATE]]\n\nXA PREPARE <replaceable>xid</replaceable>\n\nXA COMMIT <replaceable>xid</replaceable> [ONE PHASE]\n\nXA ROLLBACK <replaceable>xid</replaceable>\n\nXA RECOVER [CONVERT XID]"
}
]
},
{
"keywords": [
"DESCRIBE",
"DESC",
"EXPLAIN",
"ANALYZE",
"SELECT",
"FORMAT",
"TRADITIONAL",
"TREE",
"JSON",
"FOR",
"CONNECTION"
],
"description": [
{
"para": "The <literal role=\"stmt\">DESCRIBE</literal> and\n <literal role=\"stmt\">EXPLAIN</literal> statements are synonyms. In\n practice, the <literal role=\"stmt\">DESCRIBE</literal> keyword is\n more often used to obtain information about table structure,\n whereas <literal role=\"stmt\">EXPLAIN</literal> 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 <replaceable>tbl_name</replaceable> [<replaceable>col_name</replaceable> | <replaceable>wild</replaceable>]\n\n{EXPLAIN | DESCRIBE | DESC}\n [<replaceable>explain_type</replaceable>]\n {<replaceable>explainable_stmt</replaceable> | FOR CONNECTION <replaceable>connection_id</replaceable>}\n\n{EXPLAIN | DESCRIBE | DESC} ANALYZE <replaceable>select_statement</replaceable> \n\n<replaceable>explain_type</replaceable>: {\n FORMAT = <replaceable>format_name</replaceable>\n}\n\n<replaceable>format_name</replaceable>: {\n TRADITIONAL\n | JSON\n | TREE\n}\n\n<replaceable>explainable_stmt</replaceable>: {\n SELECT statement\n | DELETE statement\n | INSERT statement\n | REPLACE statement\n | UPDATE statement\n}"
}
]
},
{
"keywords": [
"HELP"
],
"description": [
{
"para": "The <literal role=\"stmt\">HELP</literal> statement returns online\n information from the MySQL Reference Manual. Its proper operation\n requires that the help tables in the <literal>mysql</literal>\n database be initialized with help topic information (see\n <xref linkend=\"server-side-help-support\" />)."
},
{
"para": "The <literal role=\"stmt\">HELP</literal> 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 <literal>%</literal> and <literal>_</literal>. These have the same\n meaning as for pattern-matching operations performed with the\n <literal role=\"op\">LIKE</literal> operator. For example,\n <literal>HELP 'rep%'</literal> returns a list of topics that begin\n with <literal>rep</literal>."
}
],
"id": "HELP statement",
"syntax": [
{
"programlisting": ">\nHELP '<replaceable>search_string</replaceable>'"
}
]
},
{
"keywords": [
"USE"
],
"description": [
{
"para": "The <literal role=\"stmt\">USE</literal> 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 <literal role=\"stmt\">USE</literal> 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 <replaceable>db_name</replaceable>"
}
]
},
{
"keywords": [
"SERIAL",
"DEFAULT",
"VALUE"
],
"description": [
{
"para": "The <literal>AUTO_INCREMENT</literal> attribute can be used to\n generate a unique identity for new rows:"
}
],
"id": "AUTO_INCREMENT",
"syntax": []
}
]
}