File: C:/Program Files/MySQL/MySQL Workbench 8.0/modules/data/sqlide/help-5.7.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."
},
{
"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."
},
{
"para": "<literal>UNSIGNED</literal>, if specified, disallows\n negative values."
},
{
"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."
},
{
"para": "<literal>UNSIGNED</literal>, if specified, disallows\n negative values."
}
],
"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. (The practical limit is\n less than 3000.) A table can have no more than 255 unique\n element list definitions among its\n <literal role=\"type\">ENUM</literal> and\n <literal role=\"type\">SET</literal> columns considered as a\n group. For more information on these limits, see\n <xref linkend=\"limits-frm-file\" />."
}
],
"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. A table can have no more\n than 255 unique element list definitions among its\n <literal role=\"type\">ENUM</literal> and\n <literal role=\"type\">SET</literal> columns considered as a\n group. For more information on this limit, see\n <xref linkend=\"limits-frm-file\" />."
}
],
"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\" />."
}
],
"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, SPATIAL INDEX(g));"
}
],
[
{
"para": "With <literal role=\"stmt\">ALTER TABLE</literal>:"
},
{
"programlisting": ">\nCREATE TABLE geom (g GEOMETRY NOT NULL);\nALTER TABLE geom ADD SPATIAL INDEX(g);"
}
],
[
{
"para": "With <literal role=\"stmt\">CREATE INDEX</literal>:"
},
{
"programlisting": ">\nCREATE TABLE geom (g GEOMETRY NOT NULL);\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": "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 constants of\n the same type, and <replaceable>expr</replaceable> can be\n compared to each of them as a value of the same type\n (possibly after type conversion), an optimization takes\n place. The values the 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 numbers."
}
],
[
{
"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."
}
],
"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 all 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."
},
{
"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 <replaceable>substr</replaceable>\n or <replaceable>str</replaceable> is <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>latin1</literal> (cp1252 West European)."
},
{
"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 latin1));</userinput>\n+-------------+-----------------------------------+\n| LOWER(@str) | LOWER(CONVERT(@str USING latin1)) |\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>utf8_unicode_520_ci</literal>\n works according to UCA 5.2.0, 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>latin1</literal> (cp1252 West European)."
},
{
"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": "<literal>LEVEL</literal> clause: Optional; specify weight\n levels for the return value."
}
],
[
{
"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 = _latin1 'AB' COLLATE latin1_swedish_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 | 4142 |\n+------+---------+------------------------+"
},
{
"programlisting": ">\nmysql> <userinput>SET @s = _latin1 'ab' COLLATE latin1_swedish_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 | 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 | 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>)] [LEVEL\n <replaceable>levels</replaceable>]\n [<replaceable>flags</replaceable>])</literal>"
},
{
"para": "<literal><replaceable>levels</replaceable>:\n <replaceable>N</replaceable> [ASC|DESC|REVERSE] [,\n <replaceable>N</replaceable> [ASC|DESC|REVERSE]] ...</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 (as of\n MySQL 5.7.4) a warning <quote>Invalid argument for\n 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 (as of\n MySQL 5.7.4) a warning <quote>Invalid argument for\n 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 (as of\n MySQL 5.7.4) a warning <quote>Invalid argument for\n 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 (as of\n MySQL 5.7.4) a warning <quote>Invalid argument for\n 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": "As of MySQL 5.7.6, <literal>MySQL</literal> provides a\n built-in full-text ngram parser that supports Chinese,\n Japanese, and Korean (CJK), and an installable MeCab full-text\n parser plugin for Japanese. Parsing differences are outlined\n in <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": [
"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": "<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>)</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>JSON</literal> (added in MySQL 5.7.8)"
},
{
"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>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": null,
"description": [
{
"para": "Bitwise OR."
},
{
"para": "The result is an unsigned 64-bit integer."
}
],
"id": "|",
"syntax": [
{
"para": "<indexterm>\n <primary>| (bitwise OR)</primary>\n </indexterm>\n\n <indexterm>\n <primary>OR</primary>\n <secondary>bitwise</secondary>\n </indexterm>\n\n <literal condition=\"bitwise-or\" role=\"op\">|</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Bitwise AND."
},
{
"para": "The result is an unsigned 64-bit integer."
}
],
"id": "&",
"syntax": [
{
"para": "<indexterm>\n <primary>& (bitwise AND)</primary>\n </indexterm>\n\n <indexterm>\n <primary>AND</primary>\n <secondary>bitwise</secondary>\n </indexterm>\n\n <literal condition=\"bitwise-and\" role=\"op\">&</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Bitwise XOR."
},
{
"para": "The result is an unsigned 64-bit integer."
}
],
"id": "^",
"syntax": [
{
"para": "<indexterm>\n <primary>^ (bitwise XOR)</primary>\n </indexterm>\n\n <indexterm>\n <primary>XOR</primary>\n <secondary>bitwise</secondary>\n </indexterm>\n\n <literal condition=\"bitwise-xor\" role=\"op\">^</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Shifts a longlong (<literal role=\"type\">BIGINT</literal>)\n number to the left."
},
{
"para": "The result is an unsigned 64-bit integer. The value is\n truncated to 64 bits. In particular, if the shift count is\n greater or equal to the width of an unsigned 64-bit number,\n the result is zero."
}
],
"id": "<<",
"syntax": [
{
"para": "<indexterm>\n <primary><< (left shift)</primary>\n </indexterm>\n\n <literal condition=\"left-shift\" role=\"op\"><<</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Shifts a longlong (<literal role=\"type\">BIGINT</literal>)\n number to the right."
},
{
"para": "The result is an unsigned 64-bit integer. The value is\n truncated to 64 bits. In particular, if the shift count is\n greater or equal to the width of an unsigned 64-bit number,\n the result is zero."
}
],
"id": ">>",
"syntax": [
{
"para": "<indexterm>\n <primary>>> (right shift)</primary>\n </indexterm>\n\n <literal condition=\"right-shift\" role=\"op\">>></literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Invert all bits."
},
{
"para": "The result is an unsigned 64-bit integer."
}
],
"id": "~",
"syntax": [
{
"para": "<indexterm>\n <primary>~ (invert bits)</primary>\n </indexterm>\n\n <literal condition=\"bitwise-invert\" role=\"op\">~</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the number of bits that are set in the argument\n <replaceable>N</replaceable> as an unsigned 64-bit integer, or\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal>."
}
],
"id": "BIT_COUNT",
"syntax": [
{
"para": "<indexterm>\n <primary>BIT_COUNT()</primary>\n </indexterm>\n\n <literal role=\"func\">BIT_COUNT(<replaceable>N</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>, is available as of\n MySQL 5.7.4. As of that version, statements that use\n <literal role=\"func\">AES_DECRYPT()</literal> are unsafe for\n statement-based replication and cannot be stored in the query\n cache."
}
],
"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. As of MySQL 5.7.4, key lengths of 196 or\n 256 bits can be used, as described later. The key length is a\n trade off 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": "As of MySQL 5.7.4,\n <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": "<literal role=\"func\">DECODE()</literal> decrypts the encrypted\n string <replaceable>crypt_str</replaceable> using\n <replaceable>pass_str</replaceable> as the password.\n <replaceable>crypt_str</replaceable> should be a string\n returned from <literal role=\"func\">ENCODE()</literal>."
}
],
"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": "Decrypts a string encrypted with\n <literal role=\"func\">DES_ENCRYPT()</literal>. If an error\n occurs, this function returns <literal>NULL</literal>."
},
{
"para": "This function works only if MySQL has been configured with SSL\n support. See <xref linkend=\"encrypted-connections\" />."
},
{
"para": "If no <replaceable>key_str</replaceable> argument is given,\n <literal role=\"func\">DES_DECRYPT()</literal> examines the\n first byte of the encrypted string to determine the DES key\n number that was used to encrypt the original string, and then\n reads the key from the DES key file to decrypt the message.\n For this to work, the user must have the\n <literal role=\"priv\">SUPER</literal> privilege. The key file\n can be specified with the\n <option role=\"mysqld\">--des-key-file</option> server option."
},
{
"para": "If you pass this function a <replaceable>key_str</replaceable>\n argument, that string is used as the key for decrypting the\n message."
},
{
"para": "If the <replaceable>crypt_str</replaceable> argument does not\n appear to be an encrypted string, MySQL returns the given\n <replaceable>crypt_str</replaceable>."
}
],
"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": "Encrypts the string with the given key using the Triple-DES\n algorithm."
},
{
"para": "This function works only if MySQL has been configured with SSL\n support. See <xref linkend=\"encrypted-connections\" />."
},
{
"para": "The encryption key to use is chosen based on the second\n argument to <literal role=\"func\">DES_ENCRYPT()</literal>, if\n one was given. With no argument, the first key from the DES\n key file is used. With a <replaceable>key_num</replaceable>\n argument, the given key number (0 to 9) from the DES key file\n is used. With a <replaceable>key_str</replaceable> argument,\n the given key string is used to encrypt\n <replaceable>str</replaceable>."
},
{
"para": "The key file can be specified with the\n <option role=\"mysqld\">--des-key-file</option> server option."
},
{
"para": "The return string is a binary string where the first character\n is <literal role=\"func\">CHAR(128 |\n <replaceable>key_num</replaceable>)</literal>. If an error\n occurs, <literal role=\"func\">DES_ENCRYPT()</literal> returns\n <literal>NULL</literal>."
},
{
"para": "The 128 is added to make it easier to recognize an encrypted\n key. If you use a string key,\n <replaceable>key_num</replaceable> is 127."
},
{
"para": "The string length for the result is given by this formula:"
},
{
"programlisting": ">\n<replaceable>new_len</replaceable> = <replaceable>orig_len</replaceable> + (8 - (<replaceable>orig_len</replaceable> % 8)) + 1"
},
{
"para": "Each line in the DES key file has the following format:"
},
{
"programlisting": ">\n<replaceable>key_num</replaceable> <replaceable>des_key_str</replaceable>"
},
{
"para": "Each <replaceable>key_num</replaceable> value must be a number\n in the range from <literal>0</literal> to\n <literal>9</literal>. Lines in the file may be in any order.\n <replaceable>des_key_str</replaceable> is the string that is\n used to encrypt the message. There should be at least one\n space between the number and the key. The first key is the\n default key that is used if you do not specify any key\n argument to <literal role=\"func\">DES_ENCRYPT()</literal>."
},
{
"para": "You can tell MySQL to read new key values from the key file\n with the <literal role=\"stmt\">FLUSH DES_KEY_FILE</literal>\n statement. This requires the\n <literal role=\"priv\">RELOAD</literal> privilege."
},
{
"para": "One benefit of having a set of default keys is that it gives\n applications a way to check for the existence of encrypted\n column values, without giving the end user the right to\n decrypt those values."
}
],
"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": "<literal role=\"func\">ENCODE()</literal> encrypts\n <replaceable>str</replaceable> using\n <replaceable>pass_str</replaceable> as the password. The\n result is a binary string of the same length as\n <replaceable>str</replaceable>. To decrypt the result, use\n <literal role=\"func\">DECODE()</literal>."
},
{
"para": "If you still need to use\n <literal role=\"func\">ENCODE()</literal>, a salt value must be\n used with it to reduce risk. For example:"
},
{
"programlisting": ">\nENCODE('cleartext', CONCAT('my_random_salt','my_secret_password'))"
},
{
"para": "A new random salt value must be used whenever a password is\n updated."
}
],
"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": "Encrypts <replaceable>str</replaceable> using the Unix\n <function>crypt()</function> system call and returns a binary\n string. The <replaceable>salt</replaceable> argument must be a\n string with at least two characters or the result will be\n <literal>NULL</literal>. If no <replaceable>salt</replaceable>\n argument is given, a random value is used."
}
],
"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."
}
],
"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": "<literal role=\"func\">OLD_PASSWORD()</literal> was added when\n the implementation of\n <literal role=\"func\">PASSWORD()</literal> was changed in MySQL\n 4.1 to improve security.\n <literal role=\"func\">OLD_PASSWORD()</literal> returned the\n value of the pre-4.1 implementation of\n <literal role=\"func\">PASSWORD()</literal> as a string, and was\n intended to permit you to reset passwords for any pre-4.1\n clients that need to connect to your MySQL server without\n locking them out. See <xref linkend=\"password-hashing\" />."
},
{
"para": "Passwords that use the pre-4.1 hashing method are less secure\n than passwords that use the native password hashing method.\n Support for pre-4.1 passwords was removed in MySQL 5.7.5, as\n was <literal role=\"func\">OLD_PASSWORD()</literal>."
}
],
"id": "OLD_PASSWORD",
"syntax": [
{
"para": "<indexterm>\n <primary>OLD_PASSWORD()</primary>\n </indexterm>\n\n <literal role=\"func\">OLD_PASSWORD(<replaceable>str</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns a hashed password string calculated from the cleartext\n password <replaceable>str</replaceable>. The return value is a\n string in the connection character set, or\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal>. This function is the SQL interface to\n the algorithm used by the server to encrypt MySQL passwords\n for storage in the <literal>mysql.user</literal> grant table."
},
{
"para": "The <literal role=\"sysvar\">old_passwords</literal> system\n variable controls the password hashing method used by the\n <literal role=\"func\">PASSWORD()</literal> function. It also\n influences password hashing performed by\n <literal role=\"stmt\">CREATE USER</literal> and\n <literal role=\"stmt\">GRANT</literal> statements that specify a\n password using an <literal>IDENTIFIED BY</literal> clause."
}
],
"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 and cannot be stored in the query\n cache."
},
{
"para": "This function is available as of MySQL 5.7.4."
}
],
"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": 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": "In MySQL 5.7, <literal role=\"func\">GET_LOCK()</literal> was\n reimplemented using the metadata locking (MDL) subsystem and\n its capabilities were extended. Multiple simultaneous locks\n can be acquired and <literal role=\"func\">GET_LOCK()</literal>\n does not release any existing locks."
},
{
"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": "As a result of the MDL reimplementation, uniquely named locks\n acquired with <literal role=\"func\">GET_LOCK()</literal> appear\n in the Performance Schema\n <literal role=\"ps\">metadata_locks</literal> table. The\n <literal>OBJECT_TYPE</literal> column says <literal>USER LEVEL\n LOCK</literal> and the <literal>OBJECT_NAME</literal> column\n indicates the lock name. In the case that multiple locks are\n acquired for the <emphasis>same</emphasis> name, only the\n first lock for the 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": "Before MySQL 5.7, only a single simultaneous lock can be\n acquired and <literal role=\"func\">GET_LOCK()</literal>\n releases any existing lock. The difference in lock acquisition\n behavior as of MySQL 5.7 can be seen by the following example.\n Suppose that you execute these statements:"
},
{
"programlisting": ">\nSELECT GET_LOCK('lock1',10);\nSELECT GET_LOCK('lock2',10);\nSELECT RELEASE_LOCK('lock2');\nSELECT RELEASE_LOCK('lock1');"
},
{
"para": "In MySQL 5.7 or later, the second\n <literal role=\"func\">GET_LOCK()</literal> acquires a second\n lock and both <literal role=\"func\">RELEASE_LOCK()</literal>\n calls return 1 (success). Before MySQL 5.7, the second\n <literal role=\"func\">GET_LOCK()</literal> releases the first\n lock (<literal>'lock1')</literal> and the second\n <literal role=\"func\">RELEASE_LOCK()</literal> returns\n <literal>NULL</literal> (failure) because there is no\n <literal>'lock1'</literal> to release."
},
{
"para": "MySQL 5.7 and later enforces a maximum length on lock names of\n 64 characters. Previously, no limit was enforced."
},
{
"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": 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": 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": "Prior to MySQL 5.7.3, this function was not replicated\n correctly if replication filtering rules were in use. (Bug\n #17234370, Bug #69861)"
},
{
"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": 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 IDs\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 IDs\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 similar to <literal>WAIT_FOR_EXECUTED_GTID_SET()</literal> in\n that it waits until all of the transactions whose global\n transaction identifiers are contained in\n <replaceable>gtid_set</replaceable> have been applied, or\n until <replaceable>timeout</replaceable> seconds have elapsed,\n whichever occurs first. However,\n <literal>WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()</literal> applies\n to a specific replication channel, and stops only after the\n transactions have been applied on the specified channel, for\n which the applier must be running. In contrast,\n <literal>WAIT_FOR_EXECUTED_GTID_SET()</literal> stops after\n the transactions have been applied, regardless of where they\n were applied (on any replication channel or any user client),\n and whether or not any replication channels are running."
},
{
"para": "The <replaceable>channel</replaceable> option names which\n replication channel the function applies to. If no channel is\n named and no channels other than the default replication\n channel exist, the function applies to the default replication\n channel. If multiple replication channels exist, you must\n specify a channel as otherwise it is not known which\n replication channel the function applies to. See\n <xref linkend=\"replication-channels\" /> for more\n information on replication channels."
},
{
"para": "GTID sets used with\n <literal>WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()</literal> are\n represented as strings and must be quoted in the same way as\n for <literal>WAIT_FOR_EXECUTED_GTID_SET()</literal>. For\n <literal>WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()</literal>, the\n return value for the function is an arbitrary positive number.\n If GTID-based replication is not active (that is, if the value\n of the <literal role=\"sysvar\">gtid_mode</literal> variable is\n OFF), then this value is undefined and\n <literal>WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()</literal> returns\n NULL. If the slave is not running then the function also\n returns NULL."
},
{
"para": "<literal role=\"sysvar\">gtid_mode</literal> cannot be changed\n to OFF while any client is using this function to wait for\n GTIDs to be applied."
}
],
"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>."
}
],
"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>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the bitwise <literal>AND</literal> of all bits in\n <replaceable>expr</replaceable>. The calculation is\n performed with 64-bit\n (<literal role=\"type\">BIGINT</literal>) precision."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">BIT_AND()</literal> returns a neutral\n value (all bits set to 1)."
}
],
"id": "BIT_AND",
"syntax": [
{
"para": "<indexterm>\n <primary>BIT_AND()</primary>\n </indexterm>\n\n <literal role=\"func\">BIT_AND(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the bitwise <literal>OR</literal> of all bits in\n <replaceable>expr</replaceable>. The calculation is\n performed with 64-bit\n (<literal role=\"type\">BIGINT</literal>) precision."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">BIT_OR()</literal> returns a neutral\n value (all bits set to 0)."
}
],
"id": "BIT_OR",
"syntax": [
{
"para": "<indexterm>\n <primary>BIT_OR()</primary>\n </indexterm>\n\n <literal role=\"func\">BIT_OR(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"keywords": null,
"description": [
{
"para": "Returns the bitwise <literal role=\"op\">XOR</literal> of all\n bits in <replaceable>expr</replaceable>. The calculation is\n performed with 64-bit\n (<literal role=\"type\">BIGINT</literal>) precision."
},
{
"para": "If there are no matching rows,\n <literal role=\"func\">BIT_XOR()</literal> returns a neutral\n value (all bits set to 0)."
}
],
"id": "BIT_XOR",
"syntax": [
{
"para": "<indexterm>\n <primary>BIT_XOR()</primary>\n </indexterm>\n\n <literal role=\"func\">BIT_XOR(<replaceable>expr</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>."
}
],
"id": "COUNT",
"syntax": [
{
"para": "<indexterm>\n <primary>COUNT()</primary>\n </indexterm>\n\n <literal role=\"func\">COUNT(<replaceable>expr</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."
}
],
"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>)</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."
}
],
"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>)</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>."
}
],
"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>)</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>."
}
],
"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>)</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>."
}
],
"id": "STD",
"syntax": [
{
"para": "<indexterm>\n <primary>STD()</primary>\n </indexterm>\n\n <literal role=\"func\">STD(<replaceable>expr</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>."
}
],
"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>)</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>."
}
],
"id": "STDDEV_POP",
"syntax": [
{
"para": "<indexterm>\n <primary>STDDEV_POP()</primary>\n </indexterm>\n\n <literal role=\"func\">STDDEV_POP(<replaceable>expr</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>."
}
],
"id": "STDDEV_SAMP",
"syntax": [
{
"para": "<indexterm>\n <primary>STDDEV_SAMP()</primary>\n </indexterm>\n\n <literal role=\"func\">STDDEV_SAMP(<replaceable>expr</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>."
}
],
"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>)</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>."
}
],
"id": "VAR_POP",
"syntax": [
{
"para": "<indexterm>\n <primary>VAR_POP()</primary>\n </indexterm>\n\n <literal role=\"func\">VAR_POP(<replaceable>expr</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>."
}
],
"id": "VAR_SAMP",
"syntax": [
{
"para": "<indexterm>\n <primary>VAR_SAMP()</primary>\n </indexterm>\n\n <literal role=\"func\">VAR_SAMP(<replaceable>expr</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>."
}
],
"id": "VARIANCE",
"syntax": [
{
"para": "<indexterm>\n <primary>VARIANCE()</primary>\n </indexterm>\n\n <literal role=\"func\">VARIANCE(<replaceable>expr</replaceable>)</literal>"
}
]
},
{
"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": null,
"description": [
{
"para": "Returns the default value for a table column. An error results\n if the column has no 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": 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": 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": 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."
}
],
"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": "In MySQL 5.7.9 and later, 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 available\n in MySQL 5.7.13 and later. Whereas the\n <literal>-></literal> operator simply extracts a value, the\n <literal>->></literal> operator in addition unquotes the\n 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_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": [
"JSON_APPEND"
],
"description": [
{
"para": "Appends values to the end of the indicated arrays within a\n JSON document and returns the result. This function was\n renamed to <literal role=\"func\">JSON_ARRAY_APPEND()</literal>\n in MySQL 5.7.9; the alias <literal>JSON_APPEND()</literal> is\n now deprecated in MySQL 5.7, and is removed in MySQL 8.0."
}
],
"id": "JSON_APPEND",
"syntax": [
{
"para": "<indexterm>\n <primary>JSON_APPEND()</primary>\n </indexterm>\n\n <literal role=\"func\">JSON_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_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 5.7.22 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": "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": "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 <literal role=\"type\">BINARY</literal>,\n <literal role=\"type\">VARBINARY</literal>,\n <literal role=\"type\">BLOB</literal>"
}
],
[
{
"para": "<literal>BIT</literal>: MySQL\n <literal role=\"type\">BIT</literal> scalars"
}
]
]
}
],
[
{
"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_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_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. <replaceable>json_val</replaceable>\n must be a valid JSON document or a string which can be parsed\n as one. In the case where it is string, the function returns\n the amount of storage space in the JSON binary representation\n that is created by parsing the string as JSON and converting\n it to binary. It returns <literal>NULL</literal> if the\n argument is <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": [
"PROCEDURE",
"ANALYSE"
],
"description": [
{
"para": "<literal>ANALYSE()</literal> examines the result from a query\n and returns an analysis of the results that suggests optimal\n data types for each column that may help reduce table sizes.\n To obtain this analysis, append <literal>PROCEDURE\n ANALYSE</literal> to the end of a\n <literal role=\"stmt\">SELECT</literal> statement:"
},
{
"programlisting": ">\nSELECT ... FROM ... WHERE ... PROCEDURE ANALYSE([<replaceable>max_elements</replaceable>,[<replaceable>max_memory</replaceable>]])"
},
{
"para": "For example:"
},
{
"programlisting": ">\nSELECT col1, col2 FROM table1 PROCEDURE ANALYSE(10, 2000);"
},
{
"para": "The results show some statistics for the values returned by\n the query, and propose an optimal data type for the columns.\n This can be helpful for checking your existing tables, or\n after importing new data. You may need to try different\n settings for the arguments so that <literal>PROCEDURE\n ANALYSE()</literal> does not suggest the\n <literal role=\"type\">ENUM</literal> data type when it is not\n appropriate."
},
{
"para": "The arguments are optional and are used as follows:"
},
{
"itemizedlist": [
[
{
"para": "<replaceable>max_elements</replaceable> (default 256) is\n the maximum number of distinct values that\n <literal>ANALYSE()</literal> notices per column. This is\n used by <literal>ANALYSE()</literal> to check whether the\n optimal data type should be of type\n <literal role=\"type\">ENUM</literal>; if there are more\n than <replaceable>max_elements</replaceable> distinct\n values, then <literal role=\"type\">ENUM</literal> is not a\n suggested type."
}
],
[
{
"para": "<replaceable>max_memory</replaceable> (default 8192) is\n the maximum amount of memory that\n <literal>ANALYSE()</literal> should allocate per column\n while trying to find all distinct values."
}
]
]
},
{
"para": "A <literal>PROCEDURE</literal> clause is not permitted in a\n <literal role=\"stmt\">UNION</literal> statement."
}
],
"id": "PROCEDURE ANALYSE",
"syntax": [
{
"para": "<literal>ANALYSE([<replaceable>max_elements</replaceable>[,<replaceable>max_memory</replaceable>]])</literal>"
}
]
},
{
"keywords": [
"CACHE",
"QUERY",
"FLUSH",
"RESET"
],
"description": [
{
"para": "You can defragment the query cache to better utilize its\n memory with the <literal role=\"stmt\">FLUSH QUERY\n CACHE</literal> statement. The statement does not remove any\n queries from the cache."
},
{
"para": "The <literal>RESET QUERY CACHE</literal> statement removes all\n query results from the query cache. The\n <literal role=\"stmt\">FLUSH TABLES</literal> statement also\n does this."
}
],
"id": "FLUSH QUERY CACHE",
"syntax": []
},
{
"keywords": [
"GeomCollFromText",
"GeometryCollectionFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>GeomCollFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>GeometryCollectionFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">GeomCollFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"geomcollfromtext\" role=\"func\">GeometryCollectionFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_GeomCollFromText()</literal>,\n <literal condition=\"st-geomcollfromtext\" role=\"func\">ST_GeometryCollectionFromText()</literal>,\n <literal condition=\"st-geomcollfromtext\" role=\"func\">ST_GeomCollFromTxt()</literal>,\n <literal role=\"func\">GeomCollFromText()</literal>, and\n <literal condition=\"geomcollfromtext\" role=\"func\">GeometryCollectionFromText()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_GeomCollFromText()</literal>."
}
],
"id": "GeomCollFromText",
"syntax": []
},
{
"keywords": [
"GeomFromText",
"GeometryFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>GeomFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>GeometryFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">GeomFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"geomfromtext\" role=\"func\">GeometryFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_GeomFromText()</literal>,\n <literal condition=\"st-geomfromtext\" role=\"func\">ST_GeometryFromText()</literal>,\n <literal role=\"func\">GeomFromText()</literal>, and\n <literal condition=\"geomfromtext\" role=\"func\">GeometryFromText()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_GeomFromText()</literal>."
}
],
"id": "GeomFromText",
"syntax": []
},
{
"keywords": [
"LineFromText",
"LineStringFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>LineFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>LineStringFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">LineFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"linefromtext\" role=\"func\">LineStringFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_LineFromText()</literal>,\n <literal condition=\"st-linefromtext\" role=\"func\">ST_LineStringFromText()</literal>,\n <literal role=\"func\">LineFromText()</literal>, and\n <literal condition=\"linefromtext\" role=\"func\">LineStringFromText()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_LineFromText()</literal>."
}
],
"id": "LineFromText",
"syntax": []
},
{
"keywords": [
"MLineFromText",
"MultiLineStringFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>MLineFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>MultiLineStringFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">MLineFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"mlinefromtext\" role=\"func\">MultiLineStringFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_MLineFromText()</literal>,\n <literal condition=\"st-mlinefromtext\" role=\"func\">ST_MultiLineStringFromText()</literal>,\n <literal role=\"func\">MLineFromText()</literal>, and\n <literal condition=\"mlinefromtext\" role=\"func\">MultiLineStringFromText()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_MLineFromText()</literal>."
}
],
"id": "MLineFromText",
"syntax": []
},
{
"keywords": [
"MPointFromText",
"MultiPointFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>MPointFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>MultiPointFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">MPointFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"mpointfromtext\" role=\"func\">MultiPointFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_MPointFromText()</literal>,\n <literal condition=\"st-mpointfromtext\" role=\"func\">ST_MultiPointFromText()</literal>,\n <literal role=\"func\">MPointFromText()</literal>, and\n <literal condition=\"mpointfromtext\" role=\"func\">MultiPointFromText()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_MPointFromText()</literal>."
}
],
"id": "MPointFromText",
"syntax": []
},
{
"keywords": [
"MPolyFromText",
"MultiPolygonFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>MPolyFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>MultiPolygonFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">MPolyFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"mpolyfromtext\" role=\"func\">MultiPolygonFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_MPolyFromText()</literal>,\n <literal condition=\"st-mpolyfromtext\" role=\"func\">ST_MultiPolygonFromText()</literal>,\n <literal role=\"func\">MPolyFromText()</literal>, and\n <literal condition=\"mpolyfromtext\" role=\"func\">MultiPolygonFromText()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_MPolyFromText()</literal>."
}
],
"id": "MPolyFromText",
"syntax": []
},
{
"keywords": [
"PointFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>PointFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">PointFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_PointFromText()</literal> and\n <literal role=\"func\">PointFromText()</literal> are synonyms.\n For more information, see the description of\n <literal role=\"func\">ST_PointFromText()</literal>."
}
],
"id": "PointFromText",
"syntax": []
},
{
"keywords": [
"PolyFromText",
"PolygonFromText"
],
"description": [
{
"para": "<indexterm>\n <primary>PolyFromText()</primary>\n </indexterm>\n\n <indexterm>\n <primary>PolygonFromText()</primary>\n </indexterm>\n\n <literal role=\"func\">PolyFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"polyfromtext\" role=\"func\">PolygonFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_PolyFromText()</literal>,\n <literal condition=\"st-polyfromtext\" role=\"func\">ST_PolygonFromText()</literal>,\n <literal role=\"func\">PolyFromText()</literal>, and\n <literal condition=\"polyfromtext\" role=\"func\">PolygonFromText()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_PolyFromText()</literal>."
}
],
"id": "PolyFromText",
"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>])</literal>,\n <literal condition=\"st-geomcollfromtext\" role=\"func\">ST_GeometryCollectionFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"st-geomcollfromtext\" role=\"func\">ST_GeomCollFromTxt(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>GeometryCollection</literal> value using\n its WKT representation and SRID."
},
{
"para": "If the geometry argument is <literal>NULL</literal> or not a\n syntactically well-formed geometry, or if the SRID argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-geomfromtext\" role=\"func\">ST_GeometryFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a geometry value of any type using its WKT\n representation and SRID."
},
{
"para": "If the geometry argument is <literal>NULL</literal> or not a\n syntactically well-formed geometry, or if the SRID argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-linefromtext\" role=\"func\">ST_LineStringFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>LineString</literal> value using its WKT\n representation and SRID."
},
{
"para": "If the geometry argument is <literal>NULL</literal> or not a\n syntactically well-formed geometry, or if the SRID argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-mlinefromtext\" role=\"func\">ST_MultiLineStringFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>MultiLineString</literal> value using\n its WKT representation and SRID."
},
{
"para": "If the geometry argument is <literal>NULL</literal> or not a\n syntactically well-formed geometry, or if the SRID argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-mpointfromtext\" role=\"func\">ST_MultiPointFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>MultiPoint</literal> value using its WKT\n representation and SRID."
},
{
"para": "If the geometry argument is <literal>NULL</literal> or not a\n syntactically well-formed geometry, or if the SRID argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
},
{
"para": "As of MySQL 5.7.9, spatial functions such as\n <literal role=\"func\">ST_MPointFromText()</literal> and\n <literal role=\"func\">ST_GeomFromText()</literal> that accept\n WKT-format representations of <literal>MultiPoint</literal>\n values permit individual points within values to be surrounded\n by parentheses. For example, both of the following function\n calls are valid, whereas before MySQL 5.7.9 the second one\n produces an error:"
},
{
"programlisting": ">\nST_MPointFromText('MULTIPOINT (1 1, 2 2, 3 3)')\nST_MPointFromText('MULTIPOINT ((1 1), (2 2), (3 3))')"
}
],
"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>])</literal>,\n <literal condition=\"st-mpolyfromtext\" role=\"func\">ST_MultiPolygonFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>MultiPolygon</literal> value using its\n WKT representation and SRID."
},
{
"para": "If the geometry argument is <literal>NULL</literal> or not a\n syntactically well-formed geometry, or if the SRID argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"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>])</literal>"
},
{
"para": "Constructs a <literal>Point</literal> value using its WKT\n representation and SRID."
},
{
"para": "If the geometry argument is <literal>NULL</literal> or not a\n syntactically well-formed geometry, or if the SRID argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-polyfromtext\" role=\"func\">ST_PolygonFromText(<replaceable>wkt</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>Polygon</literal> value using its WKT\n representation and SRID."
},
{
"para": "If the geometry argument is <literal>NULL</literal> or not a\n syntactically well-formed geometry, or if the SRID argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"id": "ST_PolyFromText",
"syntax": []
},
{
"keywords": [
"GeomCollFromWKB",
"GeometryCollectionFromWKB"
],
"description": [
{
"para": "<indexterm>\n <primary>GeomCollFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>GeometryCollectionFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">GeomCollFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"geomcollfromwkb\" role=\"func\">GeometryCollectionFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_GeomCollFromWKB()</literal>,\n <literal condition=\"st-geomcollfromwkb\" role=\"func\">ST_GeometryCollectionFromWKB()</literal>,\n <literal role=\"func\">GeomCollFromWKB()</literal>, and\n <literal condition=\"geomcollfromwkb\" role=\"func\">GeometryCollectionFromWKB()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_GeomCollFromWKB()</literal>."
}
],
"id": "GeomCollFromWKB",
"syntax": []
},
{
"keywords": [
"GeomFromWKB",
"GeometryFromWKB"
],
"description": [
{
"para": "<indexterm>\n <primary>GeomFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>GeometryFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">GeomFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"geomfromwkb\" role=\"func\">GeometryFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_GeomFromWKB()</literal>,\n <literal condition=\"st-geomfromwkb\" role=\"func\">ST_GeometryFromWKB()</literal>,\n <literal role=\"func\">GeomFromWKB()</literal>, and\n <literal condition=\"geomfromwkb\" role=\"func\">GeometryFromWKB()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_GeomFromWKB()</literal>."
}
],
"id": "GeomFromWKB",
"syntax": []
},
{
"keywords": [
"LineFromWKB",
"LineStringFromWKB"
],
"description": [
{
"para": "<indexterm>\n <primary>LineFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>LineStringFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">LineFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"linefromwkb\" role=\"func\">LineStringFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_LineFromWKB()</literal>,\n <literal condition=\"st-linefromwkb\" role=\"func\">ST_LineStringFromWKB()</literal>,\n <literal role=\"func\">LineFromWKB()</literal>, and\n <literal condition=\"linefromwkb\" role=\"func\">LineStringFromWKB()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_LineFromWKB()</literal>."
}
],
"id": "LineFromWKB",
"syntax": []
},
{
"keywords": [
"MLineFromWKB",
"MultiLineStringFromWKB"
],
"description": [
{
"para": "<indexterm>\n <primary>MLineFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>MultiLineStringFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">MLineFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"mlinefromwkb\" role=\"func\">MultiLineStringFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_MLineFromWKB()</literal>,\n <literal condition=\"st-mlinefromwkb\" role=\"func\">ST_MultiLineStringFromWKB()</literal>,\n <literal role=\"func\">MLineFromWKB()</literal>, and\n <literal condition=\"mlinefromwkb\" role=\"func\">MultiLineStringFromWKB()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_MLineFromWKB()</literal>."
}
],
"id": "MLineFromWKB",
"syntax": []
},
{
"keywords": [
"MPointFromWKB",
"MultiPointFromWKB"
],
"description": [
{
"para": "<indexterm>\n <primary>MPointFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>MultiPointFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">MPointFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"mpointfromwkb\" role=\"func\">MultiPointFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_MPointFromWKB()</literal>,\n <literal condition=\"st-mpointfromwkb\" role=\"func\">ST_MultiPointFromWKB()</literal>,\n <literal role=\"func\">MPointFromWKB()</literal>, and\n <literal condition=\"mpointfromwkb\" role=\"func\">MultiPointFromWKB()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_MPointFromWKB()</literal>."
}
],
"id": "MPointFromWKB",
"syntax": []
},
{
"keywords": [
"MPolyFromWKB",
"MultiPolygonFromWKB"
],
"description": [
{
"para": "<indexterm>\n <primary>MPolyFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>MultiPolygonFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">MPolyFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"mpolyfromwkb\" role=\"func\">MultiPolygonFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_MPolyFromWKB()</literal>,\n <literal condition=\"st-mpolyfromwkb\" role=\"func\">ST_MultiPolygonFromWKB()</literal>,\n <literal role=\"func\">MPolyFromWKB()</literal>, and\n <literal condition=\"mpolyfromwkb\" role=\"func\">MultiPolygonFromWKB()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_MPolyFromWKB()</literal>."
}
],
"id": "MPolyFromWKB",
"syntax": []
},
{
"keywords": [
"PointFromWKB"
],
"description": [
{
"para": "<indexterm>\n <primary>PointFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">PointFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_PointFromWKB()</literal> and\n <literal role=\"func\">PointFromWKB()</literal> are synonyms.\n For more information, see the description of\n <literal role=\"func\">ST_PointFromWKB()</literal>."
}
],
"id": "PointFromWKB",
"syntax": []
},
{
"keywords": [
"PolyFromWKB",
"PolygonFromWKB"
],
"description": [
{
"para": "<indexterm>\n <primary>PolyFromWKB()</primary>\n </indexterm>\n\n <indexterm>\n <primary>PolygonFromWKB()</primary>\n </indexterm>\n\n <literal role=\"func\">PolyFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>,\n <literal condition=\"polyfromwkb\" role=\"func\">PolygonFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "<literal role=\"func\">ST_PolyFromWKB()</literal>,\n <literal condition=\"st-polyfromwkb\" role=\"func\">ST_PolygonFromWKB()</literal>,\n <literal role=\"func\">PolyFromWKB()</literal>, and\n <literal condition=\"polyfromwkb\" role=\"func\">PolygonFromWKB()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_PolyFromWKB()</literal>."
}
],
"id": "PolyFromWKB",
"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>])</literal>,\n <literal condition=\"st-geomcollfromwkb\" role=\"func\">ST_GeometryCollectionFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>GeometryCollection</literal> value using\n its WKB representation and SRID."
},
{
"para": "The result is <literal>NULL</literal> if the WKB or SRID\n argument is <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-geomfromwkb\" role=\"func\">ST_GeometryFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a geometry value of any type using its WKB\n representation and SRID."
},
{
"para": "The result is <literal>NULL</literal> if the WKB or SRID\n argument is <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-linefromwkb\" role=\"func\">ST_LineStringFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>LineString</literal> value using its WKB\n representation and SRID."
},
{
"para": "The result is <literal>NULL</literal> if the WKB or SRID\n argument is <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-mlinefromwkb\" role=\"func\">ST_MultiLineStringFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>MultiLineString</literal> value using\n its WKB representation and SRID."
},
{
"para": "The result is <literal>NULL</literal> if the WKB or SRID\n argument is <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-mpointfromwkb\" role=\"func\">ST_MultiPointFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>MultiPoint</literal> value using its WKB\n representation and SRID."
},
{
"para": "The result is <literal>NULL</literal> if the WKB or SRID\n argument is <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-mpolyfromwkb\" role=\"func\">ST_MultiPolygonFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>MultiPolygon</literal> value using its\n WKB representation and SRID."
},
{
"para": "The result is <literal>NULL</literal> if the WKB or SRID\n argument is <literal>NULL</literal>."
}
],
"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>])</literal>"
},
{
"para": "Constructs a <literal>Point</literal> value using its WKB\n representation and SRID."
},
{
"para": "The result is <literal>NULL</literal> if the WKB or SRID\n argument is <literal>NULL</literal>."
}
],
"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>])</literal>,\n <literal condition=\"st-polyfromwkb\" role=\"func\">ST_PolygonFromWKB(<replaceable>wkb</replaceable>[,\n <replaceable>srid</replaceable>])</literal>"
},
{
"para": "Constructs a <literal>Polygon</literal> value using its WKB\n representation and SRID."
},
{
"para": "The result is <literal>NULL</literal> if the WKB or SRID\n argument is <literal>NULL</literal>."
}
],
"id": "ST_PolyFromWKB",
"syntax": []
},
{
"keywords": [
"GeometryCollection"
],
"description": [
{
"para": "<literal role=\"func\">GeometryCollection(<replaceable>g</replaceable>\n [, <replaceable>g</replaceable>] ...)</literal>"
},
{
"para": "Constructs a <literal>GeometryCollection</literal> value from\n the 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."
}
],
"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": [
"AsBinary",
"AsWKB"
],
"description": [
{
"para": "<literal role=\"func\">AsBinary(<replaceable>g</replaceable>)</literal>,\n <literal condition=\"asbinary\" role=\"func\">AsWKB(<replaceable>g</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_AsBinary()</literal>,\n <literal condition=\"st-asbinary\" role=\"func\">ST_AsWKB()</literal>,\n <literal role=\"func\">AsBinary()</literal>, and\n <literal condition=\"asbinary\" role=\"func\">AsWKB()</literal>\n are synonyms. For more information, see the description of\n <literal role=\"func\">ST_AsBinary()</literal>."
}
],
"id": "AsBinary",
"syntax": []
},
{
"keywords": [
"AsText",
"AsWKT"
],
"description": [
{
"para": "<literal role=\"func\">AsText(<replaceable>g</replaceable>)</literal>,\n <literal condition=\"astext\" role=\"func\">AsWKT(<replaceable>g</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_AsText()</literal>,\n <literal condition=\"st-astext\" role=\"func\">ST_AsWKT()</literal>,\n <literal role=\"func\">AsText()</literal>, and\n <literal condition=\"astext\" role=\"func\">AsWKT()</literal> are\n synonyms. For more information, see the description of\n <literal role=\"func\">ST_AsText()</literal>."
}
],
"id": "AsText",
"syntax": []
},
{
"keywords": [
"ST_AsBinary",
"ST_AsWKB"
],
"description": [
{
"para": "<literal role=\"func\">ST_AsBinary(<replaceable>g</replaceable>)</literal>,\n <literal condition=\"st-asbinary\" role=\"func\">ST_AsWKB(<replaceable>g</replaceable>)</literal>"
},
{
"para": "Converts a value in internal geometry format to its WKB\n representation and returns the binary result."
},
{
"para": "If the argument is <literal>NULL</literal>, the return value\n is <literal>NULL</literal>. If the argument is not a\n syntactically well-formed geometry, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal> error\n occurs."
}
],
"id": "ST_AsBinary",
"syntax": []
},
{
"keywords": [
"ST_AsText",
"ST_AsWKT"
],
"description": [
{
"para": "<literal role=\"func\">ST_AsText(<replaceable>g</replaceable>)</literal>,\n <literal condition=\"st-astext\" role=\"func\">ST_AsWKT(<replaceable>g</replaceable>)</literal>"
},
{
"para": "Converts a value in internal geometry format to its WKT\n representation and returns the string result."
},
{
"para": "If the argument is <literal>NULL</literal>, the return value\n is <literal>NULL</literal>. If the argument is not a\n syntactically well-formed geometry, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal> error\n occurs."
}
],
"id": "ST_AsText",
"syntax": []
},
{
"keywords": [
"Dimension"
],
"description": [
{
"para": "<literal role=\"func\">Dimension(<replaceable>g</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_Dimension()</literal> and\n <literal role=\"func\">Dimension()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_Dimension()</literal>."
}
],
"id": "Dimension",
"syntax": []
},
{
"keywords": [
"Envelope"
],
"description": [
{
"para": "<literal role=\"func\">Envelope(<replaceable>g</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_Envelope()</literal> and\n <literal role=\"func\">Envelope()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_Envelope()</literal>."
}
],
"id": "Envelope",
"syntax": []
},
{
"keywords": [
"GeometryType"
],
"description": [
{
"para": "<literal role=\"func\">GeometryType(<replaceable>g</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_GeometryType()</literal> and\n <literal role=\"func\">GeometryType()</literal> are synonyms.\n For more information, see the description of\n <literal role=\"func\">ST_GeometryType()</literal>."
}
],
"id": "GeometryType",
"syntax": []
},
{
"keywords": [
"IsEmpty"
],
"description": [
{
"para": "<literal role=\"func\">IsEmpty(<replaceable>g</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_IsEmpty()</literal> and\n <literal role=\"func\">IsEmpty()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_IsEmpty()</literal>."
}
],
"id": "IsEmpty",
"syntax": []
},
{
"keywords": [
"IsSimple"
],
"description": [
{
"para": "<literal role=\"func\">IsSimple(<replaceable>g</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_IsSimple()</literal> and\n <literal role=\"func\">IsSimple()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_IsSimple()</literal>."
}
],
"id": "IsSimple",
"syntax": []
},
{
"keywords": [
"SRID"
],
"description": [
{
"para": "<literal role=\"func\">SRID(<replaceable>g</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_SRID()</literal> and\n <literal role=\"func\">SRID()</literal> are synonyms. For more\n information, see the description of\n <literal role=\"func\">ST_SRID()</literal>."
}
],
"id": "SRID",
"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>, or <literal>NULL</literal> if\n the argument is <literal>NULL</literal>. The dimension can\n be minus1, 0, 1, or 2. The meaning of these values is\n given in <xref linkend=\"gis-class-geometry\" />."
}
],
"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>, or\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal>. The result is returned as a\n <literal>Polygon</literal> value that is defined by the\n 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": "As of MySQL 5.7.6, if the argument is a point or a vertical\n or horizontal line segment,\n <literal role=\"func\">ST_Envelope()</literal> returns the\n point or the line segment as its MBR rather than returning\n 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+----------------------------------------------------------------+"
}
],
"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, or\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal>. The name corresponds to one of the\n instantiable <literal>Geometry</literal> subclasses."
}
],
"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 0 for any valid\n geometry value, 1 for any invalid geometry value, or\n <literal>NULL</literal> if the argument is\n <literal>NULL</literal>."
},
{
"para": "MySQL does not support GIS <literal>EMPTY</literal> values\n such as <literal>POINT EMPTY</literal>."
}
],
"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 has no anomalous geometric points, such as self-intersection\n or self-tangency.\n <literal role=\"func\">ST_IsSimple()</literal> returns 0 if\n the argument is not simple, and <literal>NULL</literal> if\n the argument is <literal>NULL</literal>."
},
{
"para": "The descriptions of the instantiable geometric classes given\n under <xref linkend=\"opengis-geometry-model\" /> includes the\n specific conditions that cause class instances to be\n classified as not simple."
}
],
"id": "ST_IsSimple",
"syntax": []
},
{
"keywords": [
"ST_SRID"
],
"description": [
{
"para": "<literal role=\"func\">ST_SRID(<replaceable>g</replaceable>)</literal>"
},
{
"para": "Returns an integer indicating the spatial reference system\n ID associated with the geometry value\n <replaceable>g</replaceable>, or <literal>NULL</literal> if\n the argument is <literal>NULL</literal>."
}
],
"id": "ST_SRID",
"syntax": []
},
{
"keywords": [
"ST_X"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_X()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_X(<replaceable>p</replaceable>)</literal>"
},
{
"para": "Returns the X-coordinate value for the\n <literal>Point</literal> object <replaceable>p</replaceable>\n as a double-precision number."
}
],
"id": "ST_X",
"syntax": []
},
{
"keywords": [
"ST_Y"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Y()</primary>\n </indexterm>\n\n <literal role=\"func\">ST_Y(<replaceable>p</replaceable>)</literal>"
},
{
"para": "Returns the Y-coordinate value for the\n <literal>Point</literal> object <replaceable>p</replaceable>\n as a double-precision number."
}
],
"id": "ST_Y",
"syntax": []
},
{
"keywords": [
"X"
],
"description": [
{
"para": "<indexterm>\n <primary>X()</primary>\n </indexterm>\n\n <literal role=\"func\">X(<replaceable>p</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_X()</literal> and\n <literal role=\"func\">X()</literal> are synonyms. For more\n information, see the description of\n <literal role=\"func\">ST_X()</literal>."
}
],
"id": "X",
"syntax": []
},
{
"keywords": [
"Y"
],
"description": [
{
"para": "<indexterm>\n <primary>Y()</primary>\n </indexterm>\n\n <literal role=\"func\">Y(<replaceable>p</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_Y()</literal> and\n <literal role=\"func\">Y()</literal> are synonyms. For more\n information, see the description of\n <literal role=\"func\">ST_Y()</literal>."
}
],
"id": "Y",
"syntax": []
},
{
"keywords": [
"EndPoint"
],
"description": [
{
"para": "<indexterm>\n <primary>EndPoint()</primary>\n </indexterm>\n\n <literal role=\"func\">EndPoint(<replaceable>ls</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_EndPoint()</literal> and\n <literal role=\"func\">EndPoint()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_EndPoint()</literal>."
}
],
"id": "EndPoint",
"syntax": []
},
{
"keywords": [
"GLength"
],
"description": [
{
"para": "<indexterm>\n <primary>GLength()</primary>\n </indexterm>\n\n <literal role=\"func\">GLength(<replaceable>ls</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">GLength()</literal> is a nonstandard\n name. It corresponds to the OpenGIS\n <literal role=\"func\">ST_Length()</literal> function. (There\n is an existing SQL function\n <literal role=\"func\">Length()</literal> that calculates the\n length of string values.)"
}
],
"id": "GLength",
"syntax": []
},
{
"keywords": [
"IsClosed"
],
"description": [
{
"para": "<indexterm>\n <primary>IsClosed()</primary>\n </indexterm>\n\n <literal role=\"func\">IsClosed(<replaceable>ls</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_IsClosed()</literal> and\n <literal role=\"func\">IsClosed()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_IsClosed()</literal>."
}
],
"id": "IsClosed",
"syntax": []
},
{
"keywords": [
"NumPoints"
],
"description": [
{
"para": "<indexterm>\n <primary>NumPoints()</primary>\n </indexterm>\n\n <literal role=\"func\">NumPoints(<replaceable>ls</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_NumPoints()</literal> and\n <literal role=\"func\">NumPoints()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_NumPoints()</literal>."
}
],
"id": "NumPoints",
"syntax": []
},
{
"keywords": [
"PointN"
],
"description": [
{
"para": "<indexterm>\n <primary>PointN()</primary>\n </indexterm>\n\n <literal role=\"func\">PointN(<replaceable>ls</replaceable>,\n <replaceable>N</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_PointN()</literal> and\n <literal role=\"func\">PointN()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_PointN()</literal>."
}
],
"id": "PointN",
"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>. If the argument is\n <literal>NULL</literal> or an empty geometry, the return\n value is <literal>NULL</literal>."
}
],
"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). If the argument is <literal>NULL</literal> or an\n empty geometry, the return value is <literal>NULL</literal>."
},
{
"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."
}
],
"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>)</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. If the argument is\n <literal>NULL</literal> or an empty geometry, the return\n value is <literal>NULL</literal>."
}
],
"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>. If the argument is\n <literal>NULL</literal> or an empty geometry, the return\n value is <literal>NULL</literal>."
}
],
"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. If any argument is <literal>NULL</literal> or the\n geometry argument is an empty geometry, the return value is\n <literal>NULL</literal>."
}
],
"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>. If the argument is\n <literal>NULL</literal> or an empty geometry, the return\n value is <literal>NULL</literal>."
}
],
"id": "ST_StartPoint",
"syntax": []
},
{
"keywords": [
"StartPoint"
],
"description": [
{
"para": "<indexterm>\n <primary>StartPoint()</primary>\n </indexterm>\n\n <literal role=\"func\">StartPoint(<replaceable>ls</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_StartPoint()</literal> and\n <literal role=\"func\">StartPoint()</literal> are synonyms.\n For more information, see the description of\n <literal role=\"func\">ST_StartPoint()</literal>."
}
],
"id": "StartPoint",
"syntax": []
},
{
"keywords": [
"Area"
],
"description": [
{
"para": "<indexterm>\n <primary>Area()</primary>\n </indexterm>\n\n <literal role=\"func\">Area({<replaceable>poly</replaceable>|<replaceable>mpoly</replaceable>})</literal>"
},
{
"para": "<literal role=\"func\">ST_Area()</literal> and\n <literal role=\"func\">Area()</literal> are synonyms. For more\n information, see the description of\n <literal role=\"func\">ST_Area()</literal>."
}
],
"id": "Area",
"syntax": []
},
{
"keywords": [
"Centroid"
],
"description": [
{
"para": "<indexterm>\n <primary>Centroid()</primary>\n </indexterm>\n\n <literal role=\"func\">Centroid({<replaceable>poly</replaceable>|<replaceable>mpoly</replaceable>})</literal>"
},
{
"para": "<literal role=\"func\">ST_Centroid()</literal> and\n <literal role=\"func\">Centroid()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_Centroid()</literal>."
}
],
"id": "Centroid",
"syntax": []
},
{
"keywords": [
"ExteriorRing"
],
"description": [
{
"para": "<indexterm>\n <primary>ExteriorRing()</primary>\n </indexterm>\n\n <literal role=\"func\">ExteriorRing(<replaceable>poly</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_ExteriorRing()</literal> and\n <literal role=\"func\">ExteriorRing()</literal> are synonyms.\n For more information, see the description of\n <literal role=\"func\">ST_ExteriorRing()</literal>."
}
],
"id": "ExteriorRing",
"syntax": []
},
{
"keywords": [
"InteriorRingN"
],
"description": [
{
"para": "<indexterm>\n <primary>InteriorRingN()</primary>\n </indexterm>\n\n <literal role=\"func\">InteriorRingN(<replaceable>poly</replaceable>,\n <replaceable>N</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_InteriorRingN()</literal> and\n <literal role=\"func\">InteriorRingN()</literal> are synonyms.\n For more information, see the description of\n <literal role=\"func\">ST_InteriorRingN()</literal>."
}
],
"id": "InteriorRingN",
"syntax": []
},
{
"keywords": [
"NumInteriorRings"
],
"description": [
{
"para": "<indexterm>\n <primary>NumInteriorRings()</primary>\n </indexterm>\n\n <literal role=\"func\">NumInteriorRings(<replaceable>poly</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_NumInteriorRings()</literal> and\n <literal role=\"func\">NumInteriorRings()</literal> are\n synonyms. For more information, see the description of\n <literal role=\"func\">ST_NumInteriorRings()</literal>."
}
],
"id": "NumInteriorRings",
"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. For arguments of dimension 0 or 1,\n the result is 0. If the argument is an empty geometry the\n return value is 0. If the argument is\n <literal>NULL</literal> the return value is\n <literal>NULL</literal>."
},
{
"para": "The result is the sum of the area values of all components\n for a geometry collection. If a geometry collection is\n empty, its area is returned as 0."
}
],
"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>. If the argument is\n <literal>NULL</literal> or an empty geometry, the return\n value is <literal>NULL</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. If\n the argument is an empty geometry collection, the return\n value is <literal>NULL</literal>."
}
],
"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>. If the argument is\n <literal>NULL</literal> or an empty geometry, the return\n value is <literal>NULL</literal>."
}
],
"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. If the argument is <literal>NULL</literal> or an\n empty geometry, the return value is <literal>NULL</literal>."
}
],
"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>. If the argument is\n <literal>NULL</literal> or an empty geometry, the return\n value is <literal>NULL</literal>."
}
],
"id": "ST_NumInteriorRings",
"syntax": []
},
{
"keywords": [
"GeometryN"
],
"description": [
{
"para": "<indexterm>\n <primary>GeometryN()</primary>\n </indexterm>\n\n <literal role=\"func\">GeometryN(<replaceable>gc</replaceable>,\n <replaceable>N</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_GeometryN()</literal> and\n <literal role=\"func\">GeometryN()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_GeometryN()</literal>."
}
],
"id": "GeometryN",
"syntax": []
},
{
"keywords": [
"NumGeometries"
],
"description": [
{
"para": "<indexterm>\n <primary>NumGeometries()</primary>\n </indexterm>\n\n <literal role=\"func\">NumGeometries(<replaceable>gc</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_NumGeometries()</literal> and\n <literal role=\"func\">NumGeometries()</literal> are synonyms.\n For more information, see the description of\n <literal role=\"func\">ST_NumGeometries()</literal>."
}
],
"id": "NumGeometries",
"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. If any argument is <literal>NULL</literal>\n or the geometry argument is an empty geometry, the return\n value is <literal>NULL</literal>."
}
],
"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>. If the argument is\n <literal>NULL</literal> or an empty geometry, the return\n value is <literal>NULL</literal>."
}
],
"id": "ST_NumGeometries",
"syntax": []
},
{
"keywords": [
"Buffer"
],
"description": [
{
"para": "<indexterm>\n <primary>Buffer()</primary>\n </indexterm>\n\n <literal role=\"func\">Buffer(<replaceable>g</replaceable>,\n <replaceable>d</replaceable>[,\n <replaceable>strategy1</replaceable>[,\n <replaceable>strategy2</replaceable>[,\n <replaceable>strategy3</replaceable>]]])</literal>"
},
{
"para": "<literal role=\"func\">ST_Buffer()</literal> and\n <literal role=\"func\">Buffer()</literal> are synonyms. For more\n information, see the description of\n <literal role=\"func\">ST_Buffer()</literal>."
}
],
"id": "Buffer",
"syntax": []
},
{
"keywords": [
"CONVEXHULL"
],
"description": [
{
"para": "<indexterm>\n <primary>ConvexHull()</primary>\n </indexterm>\n\n <literal role=\"func\">ConvexHull(<replaceable>g</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_ConvexHull()</literal> and\n <literal role=\"func\">ConvexHull()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_ConvexHull()</literal>."
}
],
"id": "ConvexHull",
"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>,\n or <literal>NULL</literal> if any argument is\n <literal>NULL</literal>. The SRID of the geometry argument\n must be 0 because <literal role=\"func\">ST_Buffer()</literal>\n supports only the Cartesian coordinate system. If any geometry\n argument is not a syntactically well-formed geometry, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal> error\n occurs."
},
{
"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. An\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs for <literal role=\"func\">ST_Buffer()</literal> with a\n negative distance for <literal>Point</literal>,\n <literal>MultiPoint</literal>, <literal>LineString</literal>,\n and <literal>MultiLineString</literal> values, and for\n geometry collections not containing any\n <literal>Polygon</literal> or <literal>MultiPolygon</literal>\n values."
},
{
"para": "As of MySQL 5.7.7, <literal role=\"func\">ST_Buffer()</literal>\n permits up to three optional strategy arguments following the\n distance argument. Strategies influence buffer computation.\n These arguments are 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. If multiple strategies of a given type\n 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. If any argument is <literal>NULL</literal>, the\n return value is <literal>NULL</literal>. If any argument is\n invalid, an <literal role=\"error\">ER_WRONG_ARGUMENTS</literal>\n error occurs."
},
{
"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 as of MySQL 5.7.8, 65,536 before that. If the first\n argument is <literal>'point_square'</literal> or\n <literal>'end_flat'</literal>, the\n <replaceable>points_per_circle</replaceable> argument must not\n be given or an\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs."
},
{
"para": "For examples, see the description of\n <literal role=\"func\">ST_Buffer()</literal>."
}
],
"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>. If the argument\n is <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
},
{
"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. If the argument is an empty geometry\n collection, the return value is <literal>NULL</literal>."
}
],
"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>. If any argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"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>. If any argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"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": "If any argument is <literal>NULL</literal>, the return value\n is <literal>NULL</literal>."
}
],
"id": "ST_SymDifference",
"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>. If any argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
}
],
"id": "ST_Union",
"syntax": []
},
{
"keywords": [
"Crosses"
],
"description": [
{
"para": "<indexterm>\n <primary>Crosses()</primary>\n </indexterm>\n\n <literal role=\"func\">Crosses(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_Crosses()</literal> and\n <literal role=\"func\">Crosses()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_Crosses()</literal>."
}
],
"id": "Crosses",
"syntax": []
},
{
"keywords": [
"DISTANCE"
],
"description": [
{
"para": "<indexterm>\n <primary>Distance()</primary>\n </indexterm>\n\n <literal role=\"func\">Distance(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_Distance()</literal> and\n <literal role=\"func\">Distance()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_Distance()</literal>."
}
],
"id": "Distance",
"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>."
}
],
"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": "The term <emphasis>spatially crosses</emphasis> denotes a\n spatial relation between two given geometries that has the\n following properties:"
},
{
"itemizedlist": [
[
{
"para": "The two geometries intersect."
}
],
[
{
"para": "Their intersection results in a geometry that has a\n dimension that is one less than the maximum dimension of\n the two given geometries."
}
],
[
{
"para": "Their intersection is not equal to either of the two\n given geometries."
}
]
]
},
{
"para": "This function returns 1 or 0 to indicate whether\n <replaceable>g1</replaceable> spatially crosses\n <replaceable>g2</replaceable>. If <literal>g1</literal> is a\n <literal>Polygon</literal> or a\n <literal>MultiPolygon</literal>, or if\n <replaceable>g2</replaceable> is a <literal>Point</literal>\n or a <literal>MultiPoint</literal>, the return value is\n <literal>NULL</literal>."
},
{
"para": "This function returns 0 if called with an inapplicable\n geometry argument type combination. For example, it returns\n 0 if the first argument is a <literal>Polygon</literal> or\n <literal>MultiPolygon</literal> and/or the second argument\n is a <literal>Point</literal> or\n <literal>MultiPoint</literal>."
},
{
"para": "Returns 1 if <replaceable>g1</replaceable> spatially crosses\n <replaceable>g2</replaceable>. Returns\n <literal>NULL</literal> if <literal>g1</literal> is a\n <literal>Polygon</literal> or a\n <literal>MultiPolygon</literal>, or if\n <replaceable>g2</replaceable> is a <literal>Point</literal>\n or a <literal>MultiPoint</literal>. Otherwise, returns 0."
},
{
"para": "This function returns 0 if called with an inapplicable\n geometry argument type combination. For example, it returns\n 0 if the first argument is a <literal>Polygon</literal> or\n <literal>MultiPolygon</literal> and/or the second argument\n is a <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>."
}
],
"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>)</literal>"
},
{
"para": "Returns the distance between <replaceable>g1</replaceable>\n and <replaceable>g2</replaceable>. If either argument is\n <literal>NULL</literal> or an empty geometry, the return\n value is <literal>NULL</literal>."
},
{
"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": "If an intermediate or final result produces NaN or a\n negative number, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal> error\n occurs."
}
],
"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>."
}
],
"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>."
}
],
"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": "This function returns 0 if called with an inapplicable\n geometry argument type combination. For example, it returns\n 0 if called with geometries of different dimensions or any\n argument is a <literal>Point</literal>."
}
],
"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": "This function returns 0 if called with an inapplicable\n geometry argument type combination. For example, it returns\n 0 if either of the arguments is a <literal>Point</literal>\n or <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>."
}
],
"id": "ST_Within",
"syntax": []
},
{
"keywords": [
"Touches"
],
"description": [
{
"para": "<indexterm>\n <primary>Touches()</primary>\n </indexterm>\n\n <literal role=\"func\">Touches(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">ST_Touches()</literal> and\n <literal role=\"func\">Touches()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">ST_Touches()</literal>."
}
],
"id": "Touches",
"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>."
}
],
"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 follows:"
},
{
"itemizedlist": [
[
{
"para": "If either argument is <literal>NULL</literal> or an\n empty geometry, the return value is\n <literal>NULL</literal>."
}
],
[
{
"para": "If either argument is not a syntactically well-formed\n geometry byte string, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal>\n error occurs."
}
],
[
{
"para": "Otherwise, the return value is\n non-<literal>NULL</literal>."
}
]
]
}
],
"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 follows:"
},
{
"itemizedlist": [
[
{
"para": "If either argument is <literal>NULL</literal> or an\n empty geometry, the return value is\n <literal>NULL</literal>."
}
],
[
{
"para": "If either argument is not a syntactically well-formed\n geometry byte string, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal>\n error occurs."
}
],
[
{
"para": "Otherwise, the return value is\n non-<literal>NULL</literal>."
}
]
]
}
],
"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)."
}
],
"id": "MBRDisjoint",
"syntax": []
},
{
"keywords": [
"MBREqual"
],
"description": [
{
"para": "<indexterm>\n <primary>MBREqual()</primary>\n </indexterm>\n\n <literal role=\"func\">MBREqual(<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."
}
],
"id": "MBREqual",
"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."
}
],
"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."
}
],
"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."
}
],
"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."
}
],
"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>."
}
],
"id": "MBRWithin",
"syntax": []
},
{
"keywords": [
"Contains"
],
"description": [
{
"para": "<indexterm>\n <primary>Contains()</primary>\n </indexterm>\n\n <literal role=\"func\">Contains(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">MBRContains()</literal> and\n <literal role=\"func\">Contains()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">MBRContains()</literal>."
}
],
"id": "Contains",
"syntax": []
},
{
"keywords": [
"Disjoint"
],
"description": [
{
"para": "<indexterm>\n <primary>Disjoint()</primary>\n </indexterm>\n\n <literal role=\"func\">Disjoint(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">MBRDisjoint()</literal> and\n <literal role=\"func\">Disjoint()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">MBRDisjoint()</literal>."
}
],
"id": "Disjoint",
"syntax": []
},
{
"keywords": [
"Equals"
],
"description": [
{
"para": "<indexterm>\n <primary>Equals()</primary>\n </indexterm>\n\n <literal role=\"func\">Equals(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">MBREquals()</literal> and\n <literal role=\"func\">Equals()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">MBREquals()</literal>."
}
],
"id": "Equals",
"syntax": []
},
{
"keywords": [
"Intersects"
],
"description": [
{
"para": "<indexterm>\n <primary>Intersects()</primary>\n </indexterm>\n\n <literal role=\"func\">Intersects(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">MBRIntersects()</literal> and\n <literal role=\"func\">Intersects()</literal> are synonyms.\n For more information, see the description of\n <literal role=\"func\">MBRIntersects()</literal>."
}
],
"id": "Intersects",
"syntax": []
},
{
"keywords": [
"Overlaps"
],
"description": [
{
"para": "<indexterm>\n <primary>Overlaps()</primary>\n </indexterm>\n\n <literal role=\"func\">Overlaps(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">MBROverlaps()</literal> and\n <literal role=\"func\">Overlaps()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">MBROverlaps()</literal>."
}
],
"id": "Overlaps",
"syntax": []
},
{
"keywords": [
"Within"
],
"description": [
{
"para": "<indexterm>\n <primary>Within()</primary>\n </indexterm>\n\n <literal role=\"func\">Within(<replaceable>g1</replaceable>,\n <replaceable>g2</replaceable>)</literal>"
},
{
"para": "<literal role=\"func\">MBRWithin()</literal> and\n <literal role=\"func\">Within()</literal> are synonyms. For\n more information, see the description of\n <literal role=\"func\">MBRWithin()</literal>."
}
],
"id": "Within",
"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": "If any argument is <literal>NULL</literal>, the return value\n is <literal>NULL</literal>. If any argument is invalid, an\n error occurs."
},
{
"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."
}
],
"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 <literal role=\"type\">DOUBLE</literal> value in the range\n [minus90, 90]."
},
{
"para": "If the argument is <literal>NULL</literal>, the return value\n is <literal>NULL</literal>. If the argument is invalid, an\n error occurs."
},
{
"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."
}
],
"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 <literal role=\"type\">DOUBLE</literal> value in the range\n [minus180, 180]."
},
{
"para": "If the argument is <literal>NULL</literal>, the return value\n is <literal>NULL</literal>. If the argument is invalid, an\n error occurs."
},
{
"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>."
}
],
"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": "If any argument is <literal>NULL</literal>, the return value\n is <literal>NULL</literal>. If any argument is invalid, an\n error occurs."
},
{
"para": "The <replaceable>srid</replaceable> argument is an unsigned\n 32-bit 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>."
}
],
"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 two points\n and/or multipoints on a sphere, in meters, or\n <literal>NULL</literal> if any geometry argument is\n <literal>NULL</literal> or empty."
},
{
"para": "Calculations use a spherical earth and a configurable radius.\n The optional <replaceable>radius</replaceable> argument should\n be given in meters. If omitted, the default radius is\n 6,370,986 meters. An\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs if the <replaceable>radius</replaceable> argument is\n present but not positive."
},
{
"para": "The geometry arguments should consist of points that specify\n (longitude, latitude) coordinate values:"
},
{
"itemizedlist": [
[
{
"para": "Longitude and latitude are the first and second\n coordinates of the point, respectively."
}
],
[
{
"para": "Both coordinates are in degrees."
}
],
[
{
"para": "Longitude values must be in the range (-180, 180].\n Positive values are east of the prime meridian."
}
],
[
{
"para": "Latitude values must be in the range [-90, 90]. Positive\n values are north of the equator."
}
]
]
},
{
"para": "Supported argument combinations are (<literal>Point</literal>,\n <literal>Point</literal>), (<literal>Point</literal>,\n <literal>MultiPoint</literal>), and\n (<literal>MultiPoint</literal>, <literal>Point</literal>). An\n <literal role=\"error\">ER_GIS_UNSUPPORTED_ARGUMENT</literal>\n error occurs for other combinations."
},
{
"para": "If any geometry argument is not a syntactically well-formed\n geometry byte string, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal> error\n 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 syntactically well-formed and is\n geometrically valid, 0 if the argument is not syntactically\n well-formed or is not geometrically valid. If the argument is\n <literal>NULL</literal>, the return value is\n <literal>NULL</literal>. Geometry validity is defined by the\n 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."
},
{
"para": "<literal role=\"func\">ST_IsValid()</literal> works only for the\n Cartesian coordinate system and requires a geometry argument\n with an SRID of 0. An\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs otherwise."
}
],
"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>.\n If any argument is <literal>NULL</literal>, the return value\n is <literal>NULL</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> requires\n <literal>Point</literal> geometry arguments with an SRID of 0.\n An <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs otherwise."
},
{
"para": "If any argument is not a syntactically well-formed geometry\n byte string, or if any coordinate value of the two points is\n infinite or <literal>NaN</literal>, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal> error\n 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. If any argument\n is <literal>NULL</literal>, the return value is\n <literal>NULL</literal>."
},
{
"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. If the\n <replaceable>max_distance</replaceable> argument is not\n positive, or is <literal>NaN</literal>, an\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs."
},
{
"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": "If the geometry argument is not a syntactically well-formed\n geometry byte string, an\n <literal role=\"error\">ER_GIS_INVALID_DATA</literal> error\n occurs."
}
],
"id": "ST_Simplify",
"syntax": []
},
{
"keywords": [
"ST_VALIDATE"
],
"description": [
{
"para": "<indexterm>\n <primary>ST_Validate()</primary>\n </indexterm>\n\n <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": "<literal role=\"func\">ST_Validate()</literal> works only for\n the Cartesian coordinate system and requires a geometry\n argument with an SRID of 0. An\n <literal role=\"error\">ER_WRONG_ARGUMENTS</literal> error\n occurs otherwise."
}
],
"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",
"UPGRADE",
"DATA",
"DIRECTORY",
"NAME"
],
"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 <filename>db.opt</filename> file\n in the database directory. To use <literal role=\"stmt\">ALTER\n 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 syntax that includes the <literal>UPGRADE DATA DIRECTORY\n NAME</literal> clause updates the name of the directory associated\n with the database to use the encoding implemented in MySQL 5.1 for\n mapping database names to database directory names (see\n <xref linkend=\"identifier-mapping\" />). This clause is for use\n under these conditions:"
},
{
"itemizedlist": [
[
{
"para": "It is intended when upgrading MySQL to 5.1 or later from older\n versions."
}
],
[
{
"para": "It is intended to update a database directory name to the\n current encoding format if the name contains special\n characters that need encoding."
}
],
[
{
"para": "The statement is used by <command>mysqlcheck</command> (as\n invoked by <command>mysql_upgrade</command>)."
}
]
]
},
{
"para": "For example, if a database in MySQL 5.0 has the name\n <literal>a-b-c</literal>, the name contains instances of the\n <literal>-</literal> (dash) character. In MySQL 5.0, the database\n directory is also named <literal>a-b-c</literal>, which is not\n necessarily safe for all file systems. In MySQL 5.1 and later, the\n same database name is encoded as <literal>a@002db@002dc</literal>\n to produce a file system-neutral directory name."
},
{
"para": "When a MySQL installation is upgraded to MySQL 5.1 or later from\n an older version,the server displays a name such as\n <literal>a-b-c</literal> (which is in the old format) as\n <literal>#mysql50#a-b-c</literal>, and you must refer to the name\n using the <literal>#mysql50#</literal> prefix. Use\n <literal>UPGRADE DATA DIRECTORY NAME</literal> in this case to\n explicitly tell the server to re-encode the database directory\n name to the current encoding format:"
},
{
"programlisting": ">\nALTER DATABASE `#mysql50#a-b-c` UPGRADE DATA DIRECTORY NAME;"
},
{
"para": "After executing this statement, you can refer to the database as\n <literal>a-b-c</literal> without the special\n <literal>#mysql50#</literal> prefix."
}
],
"id": "ALTER DATABASE",
"syntax": [
{
"programlisting": ">\nALTER {DATABASE | SCHEMA} [<replaceable>db_name</replaceable>]\n <replaceable>alter_specification</replaceable> ...\nALTER {DATABASE | SCHEMA} <replaceable>db_name</replaceable>\n UPGRADE DATA DIRECTORY NAME\n\n<replaceable>alter_specification</replaceable>:\n [DEFAULT] CHARACTER SET [=] <replaceable>charset_name</replaceable>\n | [DEFAULT] COLLATE [=] <replaceable>collation_name</replaceable>"
}
]
},
{
"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>, introduced in MySQL 5.7.11,\n defines actions applicable to a MySQL server instance."
},
{
"para": "The <literal>ALTER INSTANCE ROTATE INNODB MASTER KEY</literal>\n statement is used to rotate the master encryption key used for\n <literal>InnoDB</literal> tablespace encryption. A keyring plugin\n must be installed and configured to use this statement. For\n information about keyring plugins, see <xref linkend=\"keyring\" />.\n Key rotation requires the <literal role=\"priv\">SUPER</literal>\n privilege."
},
{
"para": "<literal>ALTER INSTANCE ROTATE INNODB MASTER KEY</literal>\n supports concurrent DML. However, it cannot be run concurrently\n with <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 prevent\n conflicts that could arise from concurrent execution of these\n statements. If one of the conflicting statements is running, it\n must complete before another can proceed."
},
{
"para": "<literal>ALTER INSTANCE</literal> actions are written to the\n binary log so that they can be 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\" />. For information about\n keyring plugins, see <xref linkend=\"keyring\" />."
}
],
"id": "ALTER INSTANCE",
"syntax": [
{
"programlisting": ">ALTER INSTANCE ROTATE INNODB MASTER KEY"
}
]
},
{
"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",
"AUTO_INCREMENT",
"CHARACTER",
"CHECKSUM",
"COLLATE",
"COMMENT",
"COMPRESSION",
"CONNECTION",
"DATA",
"DIRECTORY",
"DELAY_KEY_WRITE",
"ENCRYPTION",
"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."
}
],
[
{
"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": "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 CHECK (<replaceable>expr</replaceable>)\n | ALGORITHM [=] {DEFAULT|INPLACE|COPY}\n | ALTER [COLUMN] <replaceable>col_name</replaceable> {SET DEFAULT <replaceable>literal</replaceable> | DROP DEFAULT}\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 {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 | UPGRADE PARTITIONING\n\n<replaceable>key_part</replaceable>:\n <replaceable>col_name</replaceable> [(<replaceable>length</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\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",
"TABLESPACE",
"ADD",
"DROP",
"DATAFILE",
"INITIAL_SIZE",
"WAIT",
"ENGINE"
],
"description": [
{
"para": "This statement is used either to add a new data file, or to drop a\n data file from a tablespace."
},
{
"para": "The <literal>ADD DATAFILE</literal> variant enables you to specify\n an initial size using an <literal>INITIAL_SIZE</literal> clause,\n where <replaceable>size</replaceable> is measured in bytes; the\n default 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 the tablespace using\n additional <literal>ALTER TABLESPACE ... ADD DATAFILE</literal>\n statements."
},
{
"para": "Using <literal>DROP DATAFILE</literal> with\n <literal role=\"stmt\">ALTER TABLESPACE</literal> drops the data\n file '<replaceable>file_name</replaceable>' from the tablespace.\n You cannot drop a data file from a tablespace which is in use by\n any table; in other words, the data file must be empty (no extents\n used). See <xref linkend=\"mysql-cluster-disk-data-objects\" />. In\n addition, any data file to be dropped must previously have been\n added to the tablespace with <literal role=\"stmt\">CREATE\n TABLESPACE</literal> or <literal role=\"stmt\">ALTER\n TABLESPACE</literal>."
},
{
"para": "Both <literal>ALTER TABLESPACE ... ADD DATAFILE</literal> and\n <literal>ALTER TABLESPACE ... DROP DATAFILE</literal> require an\n <literal>ENGINE</literal> clause which specifies the storage\n engine used by the tablespace. Currently, the only accepted values\n for <replaceable>engine_name</replaceable> are\n <literal role=\"se\">NDB</literal> and\n <literal role=\"se\">NDBCLUSTER</literal>."
},
{
"para": "<literal>WAIT</literal> is parsed but otherwise ignored, and so\n has no effect in MySQL current-series. It is intended for future\n expansion."
},
{
"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. You can verify that the data files were\n created and obtain information about them by querying the\n <literal role=\"is\">INFORMATION_SCHEMA.FILES</literal> table. For\n example, the following query shows all data files belonging to the\n tablespace named <literal>newts</literal>:"
},
{
"programlisting": ">\nmysql> <userinput>SELECT LOGFILE_GROUP_NAME, FILE_NAME, EXTRA</userinput>\n -> <userinput>FROM INFORMATION_SCHEMA.FILES</userinput>\n -> <userinput>WHERE TABLESPACE_NAME = 'newts' AND FILE_TYPE = 'DATAFILE';</userinput>\n+--------------------+--------------+----------------+\n| LOGFILE_GROUP_NAME | FILE_NAME | EXTRA |\n+--------------------+--------------+----------------+\n| lg_3 | newdata.dat | CLUSTER_NODE=3 |\n| lg_3 | newdata.dat | CLUSTER_NODE=4 |\n| lg_3 | newdata2.dat | CLUSTER_NODE=3 |\n| lg_3 | newdata2.dat | CLUSTER_NODE=4 |\n+--------------------+--------------+----------------+\n2 rows in set (0.03 sec)"
},
{
"para": "See <xref linkend=\"files-table\" />."
},
{
"para": "<literal role=\"stmt\">ALTER TABLESPACE</literal> is useful only\n with Disk Data storage for NDB Cluster. See\n <xref linkend=\"mysql-cluster-disk-data\" />."
}
],
"id": "ALTER TABLESPACE",
"syntax": [
{
"programlisting": ">\nALTER TABLESPACE <replaceable>tablespace_name</replaceable>\n {ADD|DROP} DATAFILE '<replaceable>file_name</replaceable>'\n [INITIAL_SIZE [=] <replaceable>size</replaceable>]\n [WAIT]\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 <literal role=\"priv\">SUPER</literal>\n 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"
],
"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>"
}
]
},
{
"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"
],
"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>:\n <replaceable>col_name</replaceable> [(<replaceable>length</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\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": [
"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",
"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 | CHECK (<replaceable>expr</replaceable>)\n\n<replaceable>column_definition</replaceable>:\n <replaceable>data_type</replaceable> [NOT NULL | NULL] [DEFAULT <replaceable>default_value</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>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\n<replaceable>data_type</replaceable>:\n (see <xref linkend=\"data-types\" />)\n\n<replaceable>key_part</replaceable>:\n <replaceable>col_name</replaceable> [(<replaceable>length</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\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",
"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 5.7 releases, this is always an\n <literal role=\"se\">InnoDB</literal> tablespace. MySQL NDB Cluster\n 7.5 also supports tablespaces using the\n <literal role=\"se\">NDB</literal> storage engine in addition to\n those using <literal>InnoDB</literal>."
},
{
"para": "<literal role=\"stmt\">CREATE TABLESPACE</literal> syntax is used to\n create general tablespaces. A general tablespace is a shared\n tablespace. It can hold multiple tables, and supports all table\n row formats. General tablespaces can be created in a location\n relative to or independent of the data directory."
},
{
"para": "After creating an <literal>InnoDB</literal> general tablespace,\n you can use <literal condition=\"create-table\" role=\"stmt\">CREATE\n TABLE <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": "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; this option is always required. An\n <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."
},
{
"note": "<para>\n <literal>ALTER TABLESPACE</literal> is not supported by\n <literal>InnoDB</literal>.\n </para>"
},
{
"para": "To place the data file in a location outside of the data\n directory (<literal role=\"sysvar\">datadir</literal>), include\n an absolute directory path or a path relative to the data\n directory. If you do not specify a path, the tablespace is\n created in the data directory. An\n <link linkend=\"glos_isl_file\">isl</link> file is created in\n the data directory when an <literal>InnoDB</literal>\n tablespace is created outside of the data directory."
},
{
"para": "To avoid conflicts with implicitly created file-per-table\n tablespaces, creating a general tablespace in a subdirectory\n under the data directory is not supported. When creating a\n general tablespace outside of the data directory, the\n directory must exist prior to creating the tablespace."
},
{
"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": "<literal>FILE_BLOCK_SIZE</literal>: This optionmdashwhich is\n specific to <literal>InnoDB</literal>, and is ignored by\n <literal>NDB</literal>mdashdefines the block size for the\n tablespace data file. Values can be specified in bytes or\n kilobytes. For example, an 8 kilobyte file block size can be\n specified as 8192 or 8K. If you do not specify this option,\n <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."
},
{
"remark": ">\n [js] Maybe move the rest of this explanation elsewhere?"
},
{
"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 5.7 or MySQL NDB Cluster 7.5, 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 5.7 or MySQL NDB Cluster 7.5, 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 5.7 or MySQL NDB Cluster 7.5, 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 5.7 or MySQL NDB Cluster 7.5, 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 5.7 or MySQL NDB Cluster 7.5, regardless of the\n storage engine used."
}
],
[
{
"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 7.5 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": "Tablespaces do not support temporary tables."
}
],
[
{
"para": "<literal role=\"sysvar\">innodb_file_per_table</literal>,\n <literal role=\"sysvar\">innodb_file_format</literal>, and\n <literal role=\"sysvar\">innodb_file_format_max</literal>\n settings have no influence on <literal>CREATE\n TABLESPACE</literal> operations.\n <literal role=\"sysvar\">innodb_file_per_table</literal> does\n not need to be enabled. General tablespaces support all table\n row formats regardless of file format settings. Likewise,\n 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>, regardless of file format settings."
}
],
[
{
"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": "Tables stored in a general tablespace can only be opened in\n MySQL 5.7.6 or later due to the addition of new table flags."
}
],
[
{
"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": "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 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\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>LOCK IN SHARE MODE</literal>, and\n <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",
"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 drops all\n named tables that do exist, and returns an error indicating\n which nonexisting tables it was unable to drop."
}
],
[
{
"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\n <filename>.frm</filename> file but no table managed by the storage\n engine. (For example, if an abnormal server exit occurs after\n removal of the table from the storage engine but before\n <filename>.frm</filename> file removal.)"
},
{
"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",
"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 with all MySQL NDB Cluster 7.5 releases, and with\n <literal>InnoDB</literal> in the standard MySQL Server as well."
},
{
"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": "For an <literal>InnoDB</literal> tablespace, all tables must be\n 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": "As with the <literal>InnoDB</literal> system tablespace,\n truncating or dropping <literal>InnoDB</literal> tables stored in\n a general tablespace creates free space in the 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 not\n released back to the operating system by such operations as it is\n for file-per-table tablespaces."
},
{
"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": "Tablespaces are not deleted automatically. A tablespace must\n be dropped explicitly using <literal>DROP\n TABLESPACE</literal>. <literal role=\"stmt\">DROP\n DATABASE</literal> has no effect in this regard, even if the\n operation drops all tables belonging to the tablespace."
}
],
[
{
"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 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 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 returns an error indicating by name which nonexisting\n views it was unable to drop, but also drops all views in the list\n that do exist."
},
{
"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": "To execute <literal>RENAME TABLE</literal>, there must be no\n active transactions or tables locked with <literal>LOCK\n TABLES</literal>. With the transaction table locking conditions\n satisfied, the rename operation is done atomically; no other\n session can access any of the tables while the rename is in\n 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": "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."
}
],
"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."
},
{
"para": "Logically, <literal role=\"stmt\">TRUNCATE TABLE</literal> is\n similar to a <literal role=\"stmt\">DELETE</literal> statement that\n deletes all rows, or a sequence of <literal role=\"stmt\">DROP\n TABLE</literal> and <literal role=\"stmt\">CREATE TABLE</literal>\n statements. To achieve high performance, it bypasses the DML\n method of deleting data. Thus, it cannot be rolled back, it does\n not cause <literal>ON DELETE</literal> triggers to fire, and it\n cannot be performed for <literal>InnoDB</literal> tables with\n parent-child foreign key relationships."
},
{
"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 format file\n <filename><replaceable>tbl_name</replaceable>.frm</filename>\n is valid, the table can be 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\n (<filename>.par</filename>) file is unaffected."
}
],
[
{
"para": "The <literal role=\"stmt\">TRUNCATE TABLE</literal> statement\n does not invoke <literal>ON DELETE</literal> triggers."
}
]
]
}
],
"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."
},
{
"programlisting": ">\nDELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROM <replaceable>tbl_name</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": [
"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>."
},
{
"indexterm": "<primary>DELAYED</primary>\n <secondary>INSERT modifier</secondary>"
}
]
]
},
{
"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_CACHE",
"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",
"PROCEDURE",
"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\" />."
},
{
"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\" />."
},
{
"indexterm": "<primary>HIGH_PRIORITY</primary>\n <secondary>INSERT modifier</secondary>"
},
{
"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."
},
{
"indexterm": "<primary>IGNORE</primary>\n <secondary>INSERT modifier</secondary>"
},
{
"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\" />."
},
{
"indexterm": "<primary>ON DUPLICATE KEY</primary>\n <secondary>INSERT modifier</secondary>"
}
]
]
},
{
"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_CACHE | 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>}\n [ASC | DESC], ... [WITH ROLLUP]]\n [HAVING <replaceable>where_condition</replaceable>]\n [ORDER BY {<replaceable>col_name</replaceable> | <replaceable>expr</replaceable> | <replaceable>position</replaceable>}\n [ASC | DESC], ...]\n [LIMIT {[<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable> | <replaceable>row_count</replaceable> OFFSET <replaceable>offset</replaceable>}]\n [PROCEDURE <replaceable>procedure_name</replaceable>(<replaceable>argument_list</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 | 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>\n | ( <replaceable>table_references</replaceable> )\n\n<replaceable>joined_table</replaceable>:\n <replaceable>table_reference</replaceable> [INNER | CROSS] JOIN <replaceable>table_factor</replaceable> [<replaceable>join_specification</replaceable>]\n | <replaceable>table_reference</replaceable> STRAIGHT_JOIN <replaceable>table_factor</replaceable>\n | <replaceable>table_reference</replaceable> STRAIGHT_JOIN <replaceable>table_factor</replaceable> ON <replaceable>search_condition</replaceable>\n | <replaceable>table_reference</replaceable> {LEFT|RIGHT} [OUTER] JOIN <replaceable>table_reference</replaceable> <replaceable>join_specification</replaceable>\n | <replaceable>table_reference</replaceable> NATURAL [{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_CACHE | 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>}\n [ASC | DESC], ... [WITH ROLLUP]]\n [HAVING <replaceable>where_condition</replaceable>]\n [ORDER BY {<replaceable>col_name</replaceable> | <replaceable>expr</replaceable> | <replaceable>position</replaceable>}\n [ASC | DESC], ...]\n [LIMIT {[<replaceable>offset</replaceable>,] <replaceable>row_count</replaceable> | <replaceable>row_count</replaceable> OFFSET <replaceable>offset</replaceable>}]\n [PROCEDURE <replaceable>procedure_name</replaceable>(<replaceable>argument_list</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 | 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": "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\" />."
}
],
"id": "RESET MASTER",
"syntax": [
{
"programlisting": ">\nRESET MASTER"
}
]
},
{
"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 GTIDs from being assigned to transactions in the binary\n log</emphasis>. If you are using GTIDs for replication, this\n means that even when binary logging is later enabled again, the\n GTIDs written into the log from this point do not account for\n any transactions that occurred in the meantime, so in effect\n those transactions are lost."
},
{
"para": "The global <literal role=\"sysvar\">sql_log_bin</literal> variable\n is read only and cannot be modified. The global scope is\n deprecated and will be removed in a future MySQL release."
}
],
"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"
],
"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\">SUPER</literal> privilege."
},
{
"para": "Prior to MySQL 5.7.4, the slave replication threads must be\n stopped, using <literal role=\"stmt\">STOP SLAVE</literal> if\n necessary, before issuing this statement. In MySQL 5.7.4 and\n later, you can issue <literal>CHANGE MASTER TO</literal>\n statements on a running slave without doing this, depending on\n the states of the slave SQL thread and slave I/O thread. The\n rules 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. For example, if the\n password to connect to your MySQL master has changed, issue this\n statement to tell the slave about the new password:"
},
{
"programlisting": ">\nCHANGE MASTER TO MASTER_PASSWORD='new3cret';"
},
{
"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. Beginning with MySQL\n 5.5, trying to set <literal>MASTER_HOST</literal> to an\n empty string fails with an error. Previously, setting\n <literal>MASTER_HOST</literal> to an empty string caused\n <literal role=\"stmt\">START SLAVE</literal> subsequently to\n fail. (Bug #28796)"
},
{
"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; prior to MySQL 5.7.5, if the\n password was longer, the statement succeeded, but any excess\n characters were silently truncated. In MySQL 5.7.5 and\n later, trying to use a password of more than 32 characters\n causes <literal>CHANGE MASTER TO</literal> to fail. (Bug\n #11752299, Bug #43439)"
},
{
"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": "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": "As of MySQL 5.7.3, setting <literal>MASTER_SSL=1</literal> means\n that the slave connection to the master must use SSL, or the\n connection attempt fails. Before 5.7.3, the use of an SSL\n connection by the slave was not enforced with\n <literal>MASTER_SSL=1</literal>. This is analogous to the\n client-side meaning of the <option role=\"general\">--ssl</option>\n command-line option; see\n <xref linkend=\"encrypted-connection-options\" />."
},
{
"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). Prior to MySQL 5.7.7, the\n default was 3600 seconds (one hour)."
}
],
[
{
"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": "Prior to MySQL 5.7.4, not including\n <literal>MASTER_HEARTBEAT_PERIOD</literal> caused\n <literal>CHANGE MASTER TO</literal> to reset the heartbeat\n interval to the default (half the value of the\n <literal role=\"sysvar\">slave_net_timeout</literal> system\n variable), and\n <literal role=\"statvar\">Slave_received_heartbeats</literal>\n to 0. The heartbeat interval is now not reset except by\n <literal role=\"stmt\">RESET SLAVE</literal>. (Bug #18185490)"
}
],
[
{
"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": "From MySQL 5.7, a <literal>CHANGE MASTER TO</literal> statement\n employing the <literal>MASTER_DELAY</literal> option can be\n executed on a running slave when the slave SQL thread is\n 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>. If you are\n using slave status log tables (server started with\n <literal role=\"sysvar\">master_info_repository=TABLE</literal>),\n the value can also be seen as the <literal>Master_bind</literal>\n column of the <literal>mysql.slave_master_info</literal> table."
},
{
"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": "From MySQL 5.7, a <literal>CHANGE MASTER TO</literal> statement\n employing <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. Prior to MySQL 5.7.4, <literal>CHANGE MASTER\n TO</literal> deletes all relay log files and starts a new one,\n unless you specify <literal>RELAY_LOG_FILE</literal> or\n <literal>RELAY_LOG_POS</literal>. In that case, relay log files\n are kept; the\n <literal role=\"sysvar\">relay_log_purge</literal>\n global variable is set silently to 0. In MySQL 5.7.4 and later,\n relay logs are preserved if at least one of the slave SQL thread\n and the slave I/O thread is running. If both threads are\n stopped, all relay log files are deleted unless at least one of\n <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": "<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>. (Bug #12190)"
},
{
"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 From MySQL 5.7, this option can be employed by <literal>CHANGE\n MASTER TO</literal> only if both the slave SQL and slave I/O\n threads are stopped. Both the slave and the master must have\n GTIDs enabled (<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. Also, if during the\n exchange of transactions it is found that the slave has recorded\n or committed transactions with the master's UUID in the GTID,\n but the master itself has not committed them, the master sends\n 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 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": "Prior to MySQL 5.7.5,\n <literal condition=\"reset-slave\" role=\"stmt\">RESET SLAVE\n ALL</literal> has no effect on the server ID list. In MySQL\n 5.7.5 and later, <literal>RESET SLAVE ALL</literal> clears\n <literal>IGNORE_SERVER_IDS</literal>. (Bug #18816897)"
},
{
"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": "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": "In MySQL 5.7.4 and later, 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 (in\n MySQL 5.7.4 and later) on the states of the slave SQL thread and\n slave I/O threads; which of these threads is stopped or running\n now determines the options that can or cannot be used with a\n <literal>CHANGE MASTER TO</literal> statement at a given point\n in time. The rules for making this determination are listed\n 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. From MySQL 5.7, a\n warning\n (<literal role=\"error\">ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO</literal>)\n is issued whenever this occurs. You can avoid this in such cases\n 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 | 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_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 | 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\">SUPER</literal> privilege."
},
{
"para": "<note>\n <para>\n Replication filters cannot be set on a MySQL server instance\n that is configured for Group Replication, because filtering\n transactions on some servers would make the group unable to\n reach agreement on a consistent state.\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": "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 perhap 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": "This statement leaves any existing replication filtering rules\n unchanged; to unset all filters of a given type, set the\n filter's value to an explicitly empty list, as shown in\n this example, which removes all existing\n <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": "Values employed with <literal>REPLICATE_WILD_DO_TABLE</literal>\n and <literal>REPLICATE_WILD_IGNORE_TABLE</literal> must be in\n the format\n <literal><replaceable>db_name</replaceable>.<replaceable>tbl_name</replaceable></literal>.\n Prior to MySQL 5.7.5, this was not strictly enforced, although\n using nonconforming values with these options could lead to\n erroneous results (Bug #18095449)."
},
{
"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\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_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 master host, master\n port, master user, or master password."
},
{
"itemizedlist": [
[
{
"para": "From MySQL 5.7.24, when\n <literal role=\"sysvar\">master_info_repository=TABLE</literal>\n is set on the server, replication connection parameters are\n preserved in the 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 (which is the default in MySQL 5.7),\n replication connection parameters are only retained in\n memory. If the slave <command>mysqld</command> is restarted\n immediately after issuing <literal role=\"stmt\">RESET\n SLAVE</literal> due to a server crash or deliberate restart,\n the connection parameters are lost. In that case, you must\n issue a <literal role=\"stmt\">CHANGE MASTER TO</literal>\n statement after the server start to respecify the connection\n parameters before issuing <literal role=\"stmt\">START\n SLAVE</literal>."
}
]
]
},
{
"para": "If you want to reset the connection parameters intentionally,\n you need to use\n <literal condition=\"reset-slave\" role=\"stmt\">RESET SLAVE\n ALL</literal>, which clears the connection parameters. In that\n case, you must issue a <literal role=\"stmt\">CHANGE MASTER\n TO</literal> statement after the server start to specify the new\n connection parameters."
},
{
"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": "Prior to MySQL 5.7.5, <literal>RESET SLAVE</literal> also had\n the effect of resetting both the heartbeat period\n (<literal role=\"statvar\">Slave_heartbeat_period</literal>) and\n <literal>SSL_VERIFY_SERVER_CERT</literal>. This issue is fixed\n in MySQL 5.7.5 and later. (Bug #18777899, Bug #18778485)"
},
{
"para": "Prior to MySQL 5.7.5, <literal>RESET SLAVE ALL</literal> did not\n clear the <literal>IGNORE_SERVER_IDS</literal> list set by\n <literal role=\"stmt\">CHANGE MASTER TO</literal>. In MySQL 5.7.5\n and later, the statement clears the list. (Bug #18816897)"
}
],
"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": "In MySQL current-series, <literal>START SLAVE</literal> causes\n an implicit commit of an ongoing transaction. See\n <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": "Prior to MySQL 5.7.3, <literal>SQL_AFTER_GTIDS</literal> did not\n stop the slave once the indicated transaction was completed, but\n waited until another GTID event was received (Bug #14767986)."
},
{
"para": "When using a multithreaded slave, there is a chance of gaps in\n the sequence of transactions that have been executed from the\n relay log in the following cases:"
},
{
"itemizedlist": [
[
{
"para": "killing the coordinator thread"
}
],
[
{
"para": "after an error occurs in the worker 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": "From MySQL 5.7, <literal role=\"sysvar\">gtid_next</literal> must\n be set to <literal>AUTOMATIC</literal> before issuing this\n statement (Bug #16062608)."
},
{
"para": "From MySQL 5.7, you can control how long <literal>STOP\n SLAVE</literal> waits 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. (Bug #16856735)"
},
{
"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"
],
"description": [
{
"para": "The <literal role=\"stmt\">ALTER USER</literal> statement modifies\n MySQL accounts. It enables authentication, 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": "To use <literal role=\"stmt\">ALTER 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 database. When the\n <literal role=\"sysvar\">read_only</literal> system variable is\n enabled, <literal role=\"stmt\">ALTER USER</literal> additionally\n requires the <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]\n USER() IDENTIFIED BY '<replaceable>auth_string</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 WITH <replaceable>auth_plugin</replaceable>\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> BY '<replaceable>auth_string</replaceable>'\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\n | PASSWORD EXPIRE DEFAULT\n | PASSWORD EXPIRE NEVER\n | PASSWORD EXPIRE INTERVAL <replaceable>N</replaceable> DAY\n}\n\n<replaceable>lock_option</replaceable>: {\n ACCOUNT LOCK\n | ACCOUNT UNLOCK\n}"
}
]
},
{
"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"
],
"description": [
{
"para": "The <literal role=\"stmt\">CREATE USER</literal> statement creates\n new MySQL accounts. It enables authentication, SSL/TLS,\n resource-limit, and password-management properties to be\n established for new accounts, and controls whether accounts are\n 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 database. 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\">SUPER</literal> privilege."
},
{
"para": "An error occurs if you try to create an account that already\n exists. If the <literal>IF NOT EXISTS</literal> clause is given,\n the statement produces a warning for each named account that\n 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 [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 WITH <replaceable>auth_plugin</replaceable>\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> BY '<replaceable>auth_string</replaceable>'\n | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> AS '<replaceable>auth_string</replaceable>'\n | IDENTIFIED BY PASSWORD '<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\n | PASSWORD EXPIRE DEFAULT\n | PASSWORD EXPIRE NEVER\n | PASSWORD EXPIRE INTERVAL <replaceable>N</replaceable> DAY\n}\n\n<replaceable>lock_option</replaceable>: {\n ACCOUNT LOCK\n | ACCOUNT UNLOCK\n}"
}
]
},
{
"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": "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 database. 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\">SUPER</literal> privilege."
},
{
"para": "An error occurs if you try to drop an account that does not\n exist. If the <literal>IF EXISTS</literal> clause is given, the\n statement produces a warning for each named user that does not\n exist, rather than an error."
},
{
"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",
"BY",
"ALTER",
"IDENTIFIED",
"REQUIRE",
"PASSWORD",
"GRANT",
"ISSUER",
"CIPHER",
"WITH",
"SUBJECT",
"OPTION",
"MAX_QUERIES_PER_HOUR",
"MAX_UPDATES_PER_HOUR",
"MAX_CONNECTIONS_PER_HOUR",
"MAX_USER_CONNECTIONS",
"CLIENT",
"EXECUTE",
"FILE",
"SSL",
"X509",
"SECURITY",
"USAGE",
"SUPER",
"NONE",
"PROCESS",
"PRIVILEGES",
"REFERENCES",
"RELOAD",
"REPLICATION",
"SHUTDOWN"
],
"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</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 {GRANT OPTION | <replaceable>resource_option</replaceable>} ...]\n\nGRANT PROXY ON <replaceable>user</replaceable>\n TO <replaceable>user</replaceable> [, <replaceable>user</replaceable>] ...\n [WITH GRANT 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</replaceable>:\n (see <xref linkend=\"account-names\" />)\n\n<replaceable>auth_option</replaceable>: {\n IDENTIFIED BY '<replaceable>auth_string</replaceable>'\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> AS '<replaceable>auth_string</replaceable>'\n | IDENTIFIED BY PASSWORD '<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}"
},
{
"para": "The <literal role=\"stmt\">GRANT</literal> statement grants\n privileges to MySQL user accounts. There are several aspects to\n the <literal role=\"stmt\">GRANT</literal> statement, described\n 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 database. 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\">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 from MySQL accounts."
},
{
"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": "When the <literal role=\"sysvar\">read_only</literal> system\n variable is enabled, <literal role=\"stmt\">REVOKE</literal>\n requires the <literal role=\"priv\">SUPER</literal> privilege in\n addition to any other required privileges described in the\n following discussion."
},
{
"para": "Each account name uses the format described in\n <xref linkend=\"account-names\" />. For example:"
},
{
"programlisting": ">\nREVOKE INSERT ON *.* FROM 'jeffrey'@'localhost';"
},
{
"para": "The host name part of the account name, if omitted, defaults to\n <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 user or users:"
},
{
"programlisting": ">\nREVOKE ALL PRIVILEGES, GRANT OPTION FROM <replaceable>user</replaceable> [, <replaceable>user</replaceable>] ..."
},
{
"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 database."
},
{
"para": "User accounts from which privileges are to be revoked must\n exist, but the privileges to be revoked need not be currently\n granted to 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</replaceable> [, <replaceable>user</replaceable>] ...\n\nREVOKE ALL [PRIVILEGES], GRANT OPTION\n FROM <replaceable>user</replaceable> [, <replaceable>user</replaceable>] ...\n\nREVOKE PROXY ON <replaceable>user</replaceable>\n FROM <replaceable>user</replaceable> [, <replaceable>user</replaceable>] ..."
}
]
},
{
"keywords": [
"SET",
"PASSWORD",
"FOR"
],
"description": [
{
"para": "The <literal role=\"stmt\">SET PASSWORD</literal> statement\n assigns a password to a MySQL user account.\n <literal>'<replaceable>auth_string</replaceable>'</literal>\n represents a cleartext (unencrypted) password."
},
{
"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": "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 database. Setting the password\n for yourself (for a nonanonymous account with no\n <literal>FOR</literal> clause) requires no special privileges.\n 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\">SUPER</literal> privilege in\n addition to any other required privileges."
},
{
"para": "The password can be specified in these ways:"
},
{
"itemizedlist": [
[
{
"para": "Use a string without\n <literal role=\"func\">PASSWORD()</literal>"
},
{
"programlisting": ">\nSET PASSWORD FOR 'jeffrey'@'localhost' = '<replaceable>password</replaceable>';"
},
{
"para": "<literal role=\"stmt\">SET PASSWORD</literal> interprets the\n string as a cleartext string, passes it to the\n authentication plugin associated with the account, and\n stores the result returned by the plugin in the account row\n in the <literal>mysql.user</literal> system table. (The\n plugin is given the opportunity to hash the value into the\n encryption format it expects. The plugin may use the value\n as specified, in which case no hashing occurs.)"
}
],
[
{
"para": "Use the <literal role=\"func\">PASSWORD()</literal> function\n (deprecated as of MySQL 5.7.6)"
},
{
"programlisting": ">\nSET PASSWORD FOR 'jeffrey'@'localhost' = PASSWORD('<replaceable>password</replaceable>');"
},
{
"para": "The <literal role=\"func\">PASSWORD()</literal> argument is\n the cleartext (unencrypted) password.\n <literal role=\"func\">PASSWORD()</literal> hashes the\n password and returns the encrypted password string for\n storage in the account row in the\n <literal>mysql.user</literal> system table."
},
{
"para": "The <literal role=\"func\">PASSWORD()</literal> function\n hashes the password using the hashing method determined by\n the value of the\n <literal role=\"sysvar\">old_passwords</literal> system\n variable value. Be sure that\n <literal role=\"sysvar\">old_passwords</literal> has the value\n corresponding to the hashing method expected by the\n authentication plugin associated with the account. For\n example, if the account uses the\n <literal>mysql_native_password</literal> plugin, the\n <literal role=\"sysvar\">old_passwords</literal> value must be\n 0:"
},
{
"programlisting": ">\nSET old_passwords = 0;\nSET PASSWORD FOR 'jeffrey'@'localhost' = PASSWORD('<replaceable>password</replaceable>');"
},
{
"para": "If the <literal role=\"sysvar\">old_passwords</literal> value\n differs from that required by the authentication plugin, the\n hashed password value returned by\n <literal role=\"func\">PASSWORD()</literal> will not by usable\n by the plugin and correct authentication of client\n connections will not occur."
}
]
]
}
],
"id": "SET PASSWORD",
"syntax": [
{
"programlisting": ">\nSET PASSWORD [FOR <replaceable>user</replaceable>] = <replaceable>password_option</replaceable>\n\n<replaceable>password_option</replaceable>: {\n '<replaceable>auth_string</replaceable>'\n | PASSWORD('<replaceable>auth_string</replaceable>')\n}"
}
]
},
{
"keywords": [
"ANALYZE",
"TABLE",
"NO_WRITE_TO_BINLOG",
"LOCAL"
],
"description": [
{
"para": "<literal role=\"stmt\">ANALYZE TABLE</literal> performs a key\n distribution analysis and stores the distribution for the named\n table or tables. For <literal>MyISAM</literal> tables, this\n statement is equivalent to using <command>myisamchk\n --analyze</command>."
},
{
"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": "<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>] ..."
}
]
},
{
"keywords": [
"CHECK",
"TABLE",
"QUICK",
"FAST",
"MEDIUM",
"UPGRADE"
],
"description": [
{
"para": "<literal role=\"stmt\">CHECK TABLE</literal> checks a table or\n tables for errors. For <literal>MyISAM</literal> tables, the key\n statistics are updated as well. <literal role=\"stmt\">CHECK\n TABLE</literal> can also check views for problems, such as\n tables that are referenced in the view definition that no longer\n 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 database. 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."
}
],
"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 database. 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",
"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",
"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": [
"SET",
"GLOBAL",
"SESSION",
"VARIABLE"
],
"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 | [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. A user with the\n <literal role=\"priv\">SUPER</literal> or\n <literal role=\"priv\">REPLICATION CLIENT</literal> privilege may\n execute this statement."
},
{
"programlisting": ">\nmysql> <userinput>SHOW BINARY LOGS;</userinput>\n+---------------+-----------+\n| Log_name | File_size |\n+---------------+-----------+\n| binlog.000015 | 724935 |\n| binlog.000016 | 733481 |\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 role=\"stmt\">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",
"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>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 column name."
}
],
[
{
"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>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\" />."
},
{
"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 [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 be the user named in the\n routine <literal>DEFINER</literal> clause or have\n <literal role=\"stmt\">SELECT</literal> access to the\n <literal>mysql.proc</literal> table. If you do not have\n privileges for the routine itself, the value displayed for the\n <literal>Create Procedure</literal> or <literal>Create\n Function</literal> field will be <literal>NULL</literal>."
}
],
"id": "SHOW CREATE PROCEDURE",
"syntax": [
{
"programlisting": ">\nSHOW CREATE PROCEDURE <replaceable>proc_name</replaceable>"
}
]
},
{
"keywords": [
"SHOW",
"CREATE",
"TABLE"
],
"description": [
{
"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 database, except to display\n information for the current user."
},
{
"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."
}
],
"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": "<literal condition=\"show-engine\" role=\"stmt\">SHOW ENGINE INNODB\n MUTEX</literal> output was removed in MySQL 5.7.2. It was\n revised and reintroduced in MySQL 5.7.8."
},
{
"para": "In MySQL 5.7.8, mutex statistics collection is configured\n dynamically using the 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": "Prior to MySQL 5.7.8, the <literal>Name</literal> field\n reports the source file where the mutex is implemented, and\n the line number in the file where the mutex is created. The\n line number is specific to your version of MySQL. As of\n MySQL 5.7.8, only the mutex name is reported. File name and\n line number are still reported for rwlocks."
}
],
[
{
"para": "<literal>Status</literal>"
},
{
"para": "The mutex status."
},
{
"para": "Prior to MySQL 5.7.8, the <literal>Status</literal> field\n displays several values if\n <option role=\"cmake\">WITH_DEBUG</option> was defined at\n MySQL compilation time. If\n <option role=\"cmake\">WITH_DEBUG</option> was not defined,\n the statement displays only the <literal>os_waits</literal>\n value. In the latter case (without\n <option role=\"cmake\">WITH_DEBUG</option>), the information\n on which the output is based is insufficient to distinguish\n regular mutexes and mutexes that protect rwlocks (which\n permit multiple readers or a single writer). Consequently,\n the output may appear to contain multiple rows for the same\n mutex. Pre-MySQL 5.7.8 <literal>Status</literal> field\n values include:"
},
{
"itemizedlist": [
[
{
"para": "<literal>count</literal> indicates how many times the\n mutex was requested."
}
],
[
{
"para": "<literal>spin_waits</literal> indicates how many times\n the spinlock had to run."
}
],
[
{
"para": "<literal>spin_rounds</literal> indicates the number of\n spinlock rounds. (<literal>spin_rounds</literal> divided\n by <literal>spin_waits</literal> provides the average\n round count.)"
}
],
[
{
"para": "<literal>os_waits</literal> indicates the number of\n operating system waits. This occurs when the spinlock\n did not work (the mutex was not locked during the\n spinlock and it was necessary to yield to the operating\n system and wait)."
}
],
[
{
"para": "<literal>os_yields</literal> indicates the number of\n times a thread trying to lock a mutex gave up its\n timeslice and yielded to the operating system (on the\n presumption that permitting other threads to run will\n free the mutex so that it can be locked)."
}
],
[
{
"para": "<literal>os_wait_times</literal> indicates the amount of\n time (in ms) spent in operating system waits. In MySQL\n current-series timing is disabled and this value is\n always 0."
}
]
]
},
{
"para": "As of MySQL 5.7.8, the <literal>Status</literal> field\n reports the number of spins, waits, and calls. Statistics\n for low-level operating system mutexes, which are\n implemented outside of <literal>InnoDB</literal>, are not\n 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: utf8\ncollation_connection: utf8_general_ci\n Database Collation: latin1_swedish_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"
],
"description": [
{
"para": "This statement displays the privileges that are assigned to a\n MySQL user account, in the form of\n <literal role=\"stmt\">GRANT</literal> statements that must be\n executed to duplicate the privilege assignments."
},
{
"para": "<literal role=\"stmt\">SHOW GRANTS</literal> requires the\n <literal role=\"priv\">SELECT</literal> privilege for the\n <literal>mysql</literal> system database, except to display\n privileges for the current user."
},
{
"para": "To name the account 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 names, see\n <xref linkend=\"account-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": "<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."
},
{
"para": "<literal>SHOW GRANTS</literal> output does not include\n <literal>IDENTIFIED BY PASSWORD</literal> clauses. Use the\n <literal role=\"stmt\">SHOW CREATE USER</literal> statement\n instead. See <xref linkend=\"show-create-user\" />."
}
],
"id": "SHOW GRANTS",
"syntax": [
{
"programlisting": ">\nSHOW GRANTS [FOR <replaceable>user</replaceable>]"
}
]
},
{
"keywords": [
"SHOW",
"INDEX",
"KEYS",
"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*************************** 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:"
},
{
"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 <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 name of the 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) or <literal>NULL</literal>\n (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": "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\" />."
},
{
"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 {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 exact list\n of privileges depends on the version of your server."
}
],
"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 be the owner of the routine or\n have <literal role=\"stmt\">SELECT</literal> access to the\n <literal>mysql.proc</literal> table."
},
{
"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 role=\"stmt\">SHOW RELAYLOG EVENTS</literal>\n requires the <literal role=\"priv\">REPLICATION SLAVE</literal>\n 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."
},
{
"para": "<literal>SHOW SLAVE HOSTS</literal> should be executed on a\n server that acts as a replication master. <literal>SHOW SLAVE\n HOSTS</literal> requires the <literal role=\"priv\">REPLICATION\n SLAVE</literal> privilege. The statement displays information\n about servers that are or have been connected as replication\n slaves, with each row of the result corresponding to one slave\n 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": "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: /var/mysqld.2/data/master.info\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"
},
{
"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",
"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": "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 [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_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION\n Definer: me@localhost\ncharacter_set_client: utf8\ncollation_connection: utf8_general_ci\n Database Collation: latin1_swedish_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. This statement\n requires the <literal role=\"priv\">SUPER</literal> privilege."
}
],
"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",
"DES_KEY_FILE",
"ENGINE",
"ERROR",
"GENERAL",
"HOSTS",
"LOGS",
"PRIVILEGES",
"OPTIMIZER_COSTS",
"QUERY",
"CACHE",
"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 | DES_KEY_FILE\n | ENGINE LOGS\n | ERROR LOGS\n | GENERAL LOGS\n | HOSTS\n | LOGS\n | PRIVILEGES\n | OPTIMIZER_COSTS\n | QUERY CACHE\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\">SUPER</literal> privilege:"
},
{
"itemizedlist": [
[
{
"para": "Without <literal role=\"priv\">SUPER</literal>, you can kill\n only your own threads and statements."
}
],
[
{
"para": "With <literal role=\"priv\">SUPER</literal>, you can kill all\n threads and statements."
}
]
]
},
{
"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",
"QUERY",
"CACHE"
],
"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": "<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 QUERY CACHE</literal>"
},
{
"para": "Removes all query results from the query cache."
},
{
"note": "<para>\n The query cache is deprecated as of MySQL 5.7.20, and is\n removed in MySQL next-series. Deprecation includes\n <literal condition=\"reset\" role=\"stmt\">RESET QUERY\n CACHE</literal>.\n </para>"
}
],
[
{
"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 | QUERY CACHE\n | SLAVE\n}"
}
]
},
{
"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": [
"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": "This statement has no effect if the server was not started with\n the <option role=\"mysqld\">--log-bin</option> option to enable\n binary logging."
}
],
"id": "PURGE BINARY LOGS",
"syntax": [
{
"programlisting": ">\nPURGE { BINARY | MASTER } LOGS\n { TO '<replaceable>log_name</replaceable>' | BEFORE <replaceable>datetime_expr</replaceable> }"
}
]
},
{
"keywords": [
"RESET",
"MASTER"
],
"description": [
{
"para": "Deletes all binary log files listed in the index file, resets\n the binary log index file to be empty, and creates a new binary\n log file."
},
{
"para": "<literal>RESET MASTER</literal> also clears the values of the\n <literal role=\"sysvar\">gtid_purged</literal> system variable as\n well as the global value of the\n <literal role=\"sysvar\">gtid_executed</literal> system variable\n (but not its session value); that is, executing this statement\n sets each of these values to an empty string\n (<literal>''</literal>). In MySQL 5.7.5 and later, this\n statement also clears the\n <xref linkend=\"replication-gtids-gtid-executed-table\" />."
},
{
"para": "This statement is intended to be used only when the master is\n started for the first time."
}
],
"id": "RESET MASTER",
"syntax": [
{
"programlisting": ">\nRESET MASTER"
}
]
},
{
"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 done. The default\n value is 1 (do logging). To change logging for the current\n session, change the session value of this variable. The session\n user must have the <literal role=\"priv\">SUPER</literal>\n privilege to set this variable. Set this variable to 0 for a\n session to temporarily disable binary logging while making\n changes to the master which you do not want to replicate to the\n slave."
},
{
"para": "As of MySQL 5.5, <literal role=\"sysvar\">sql_log_bin</literal>\n can be set as a global or session variable. Setting\n <literal role=\"sysvar\">sql_log_bin</literal> globally is only\n detected when a new session is started. Any sessions previously\n running are not impacted when setting\n <literal role=\"sysvar\">sql_log_bin</literal> globally."
},
{
"para": "In MySQL 5.7, it is not possible to set\n <literal>@@SESSION.sql_log_bin</literal> within a transaction or\n subquery. (Bug #53437)"
}
],
"id": "SET sql_log_bin",
"syntax": [
{
"programlisting": ">\nSET sql_log_bin = {0|1}"
}
]
},
{
"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"
],
"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\" />)."
},
{
"para": "If a slave is already running, in MySQL 5.7.4 and later, you can\n issue <literal>CHANGE MASTER TO</literal> statements without\n stopping the slave, depending on the states of the slave SQL\n thread and slave I/O thread. The rules governing such use are\n provided later in this section. Prior to MySQL 5.7.4, the slave\n replication threads must be stopped, using\n <literal role=\"stmt\">STOP SLAVE</literal> if necessary, before\n issuing this statement."
},
{
"para": "The simplest way to use this statement to configure a\n replication slave to use a specific master is:"
},
{
"programlisting": ">CHANGE MASTER TO MASTER_HOST='<replaceable>master_host</replaceable>', MASTER_PORT=<replaceable>master_port</replaceable>"
},
{
"para": "where <replaceable>master_host</replaceable> is the\n master's IP or hostname and\n <replaceable>master_port</replaceable> is the port which is open\n on the master."
},
{
"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. For example, if the\n password to connect to your MySQL master has changed, issue this\n statement to tell the slave about the new password:"
},
{
"programlisting": ">\nCHANGE MASTER TO MASTER_PASSWORD='new3cret';"
},
{
"para": "The optional <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause added in\n MySQL 5.7.6 enables you to choose which replication channel the\n statement applies to. If no clause is set and no extra channels\n exist, the statement applies to the default channel and behaves\n the same as versions of MySQL prior to 5.7.6. Providing a\n <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": "When using multiple replication channels, if a <literal>CHANGE\n MASTER TO</literal> statement does not have a channel defined\n using a <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause an error is\n generated. See <xref linkend=\"replication-channels\" /> for more\n information."
},
{
"para": "<literal>MASTER_CONNECT_RETRY</literal> specifies how many\n seconds to wait between connect retries. The default is 60."
},
{
"para": "<literal>MASTER_RETRY_COUNT</literal> limits the\n <emphasis>number</emphasis> of reconnection attempts and updates\n the value of the <literal>Master_Retry_Count</literal> column in\n the output of <literal role=\"stmt\">SHOW SLAVE STATUS</literal>.\n The default value is 24 * 3600 = 86400.\n <literal>MASTER_RETRY_COUNT</literal> is intended to replace the\n older <option role=\"mysqld\">--master-retry-count</option> server\n option, and is now the preferred method for setting this limit.\n You are encouraged not to rely on\n <option role=\"mysqld\">--master-retry-count</option> in new\n applications and, when upgrading to MySQL current-series, to\n update any existing applications that rely on it, so that they\n use <literal>CHANGE MASTER TO ... MASTER_RETRY_COUNT</literal>\n instead."
},
{
"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": "In MySQL 5.7.4 and later, a <literal>CHANGE MASTER TO</literal>\n statement employing the <literal>MASTER_DELAY</literal> option\n can be executed on a running slave when the slave SQL thread is\n 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>. If you are\n using slave status log tables (server started with\n <literal role=\"sysvar\">master_info_repository=TABLE</literal>),\n the value can also be seen as the <literal>Master_bind</literal>\n column of the <literal>mysql.slave_master_info</literal> table."
},
{
"para": "The ability to bind a replication slave to a specific network\n interface is also supported by NDB Cluster."
},
{
"para": "<literal>MASTER_HEARTBEAT_PERIOD</literal> sets the interval in\n seconds between replication heartbeats. Whenever the master's\n binary log is updated with an event, the waiting period for the\n next heartbeat is reset. <replaceable>interval</replaceable> is\n a decimal value having the range 0 to 4294967 seconds and a\n resolution in milliseconds; the smallest nonzero value is 0.001.\n Heartbeats are sent by the master only if there are no unsent\n events in the binary log file for a period longer than\n <replaceable>interval</replaceable>."
},
{
"para": "Prior to MySQL 5.7.4, not including\n <literal>MASTER_HEARTBEAT_PERIOD</literal> caused\n <literal>CHANGE MASTER TO</literal> to reset the heartbeat\n period\n (<literal role=\"statvar\">Slave_heartbeat_period</literal>) to\n the default, and\n <literal role=\"statvar\">Slave_received_heartbeats</literal> to\n 0. (Bug #18185490)"
},
{
"para": "If you are logging master connection information to tables,\n <literal>MASTER_HEARTBEAT_PERIOD</literal> can be seen as the\n value of the <literal>Heartbeat</literal> column of the\n <literal>mysql.slave_master_info</literal> table."
},
{
"para": "Setting <replaceable>interval</replaceable> to 0 disables\n heartbeats altogether. The default value for\n <replaceable>interval</replaceable> is equal to the value of\n <literal role=\"sysvar\">slave_net_timeout</literal> divided by 2."
},
{
"para": "Setting <literal>@@GLOBAL.slave_net_timeout</literal> to a value\n less than that of the current heartbeat interval results in a\n warning being issued. The effect of issuing\n <literal role=\"stmt\">RESET SLAVE</literal> on the heartbeat\n interval is to reset it to the default value."
},
{
"para": "Prior to MySQL 5.7.4, <literal>CHANGE MASTER TO</literal>\n deletes all relay log files and starts a new one, unless you\n specify <literal>RELAY_LOG_FILE</literal> or\n <literal>RELAY_LOG_POS</literal>. In that case, relay log files\n are kept; the <literal role=\"sysvar\">relay_log_purge</literal>\n global variable is set silently to 0. In MySQL 5.7.4 and later,\n relay logs are preserved if at least one of the slave SQL thread\n and the slave I/O thread is running; if both threads are\n stopped, all relay log files are deleted unless at least one of\n <literal>RELAY_LOG_FILE</literal> or\n <literal>RELAY_LOG_POS</literal> is specified."
},
{
"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>. (Bug #12190)"
},
{
"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 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": "Prior to MySQL 5.7.5,\n <literal condition=\"reset-slave\" role=\"stmt\">RESET SLAVE\n ALL</literal> has no effect on the server ID list. In MySQL\n 5.7.5 and later, <literal>RESET SLAVE ALL</literal> clears\n <literal>IGNORE_SERVER_IDS</literal>. (Bug #18816897)"
},
{
"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": "In MySQL current-series, the master info repository and the\n output of <literal role=\"stmt\">SHOW SLAVE STATUS</literal>\n provide the 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": "In MySQL current-series, invoking <literal role=\"stmt\">CHANGE\n MASTER TO</literal> causes the previous values for\n <literal>MASTER_HOST</literal>, <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": "In MySQL current-series, <literal>CHANGE MASTER TO</literal>\n causes an implicit commit of an ongoing transaction. See\n <xref linkend=\"implicit-commit\" />."
},
{
"para": "In MySQL 5.7.4 and later, 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 (in\n MySQL 5.7.4 and later) on the states of the slave SQL thread and\n slave I/O threads; which of these threads is stopped or running\n now determines the options that can or cannot be used with a\n <literal>CHANGE MASTER TO</literal> statement at a given point\n in time. The rules for making this determination are listed\n 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>, or\n <literal>MASTER_DELAY</literal>, even when the SQL thread is\n running. These three options may not be used when the I/O\n 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>."
},
{
"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. In MySQL 5.7.4 and\n later, a warning\n (<errorname>ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO</errorname>)\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='bigs3cret',\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 | 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_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 | 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": "In MySQL 5.7.3 and later, <literal>CHANGE REPLICATION\n FILTER</literal> sets one or more replication filtering rules on\n the slave in the same way as starting the slave\n <command>mysqld</command> with replication filtering options\n such as <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)."
},
{
"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": "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>dbA</literal> on the master to database\n <literal>dbB</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 perhap 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": "This statement leaves any existing replication filtering rules\n unchanged; to unset all filters of a given type, set the\n filter's value to an explicitly empty list, as shown in\n this example, which removes all existing\n <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": "Values employed with <literal>REPLICATE_WILD_DO_TABLE</literal>\n and <literal>REPLICATE_WILD_IGNORE_TABLE</literal> must be in\n the format\n <literal><replaceable>db_name</replaceable>.<replaceable>tbl_name</replaceable></literal>.\n Prior to MySQL 5.7.5, this was not strictly enforced, although\n using nonconforming values with these options could lead to\n erroneous results (Bug #18095449)."
},
{
"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\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_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"
],
"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>. To use <literal role=\"stmt\">RESET SLAVE</literal>,\n the slave replication threads must be stopped (use\n <literal role=\"stmt\">STOP SLAVE</literal> if necessary)."
},
{
"para": "The optional <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause added in\n MySQL 5.7.6 enables you to choose which replication channel the\n statement applies to. If no clause is set and no extra channels\n exist, the statement applies to the default channel and behaves\n the same as versions of MySQL prior to 5.7.6. Providing a\n <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.\n Issuing a <literal condition=\"reset-slave\" role=\"stmt\">RESET\n SLAVE 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 master host, master\n port, master user, or master password, which are retained in\n memory. This means that <literal role=\"stmt\">START\n SLAVE</literal> can be issued without requiring a\n <literal role=\"stmt\">CHANGE MASTER TO</literal> statement\n following <literal role=\"stmt\">RESET SLAVE</literal>."
},
{
"para": "Connection parameters are reset by <literal>RESET SLAVE\n ALL</literal>. (<literal>RESET SLAVE</literal> followed by a\n restart of the slave <command>mysqld</command> also does this.)"
},
{
"para": "In MySQL current-series <literal>RESET SLAVE</literal> causes\n an implicit commit of an ongoing transaction. See\n <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": "Prior to MySQL 5.7.5, <literal>RESET SLAVE</literal> also had\n the effect of resetting both the heartbeat period\n (<literal role=\"statvar\">Slave_heartbeat_period</literal>) and\n <literal>SSL_VERIFY_SERVER_CERT</literal>. This issue is fixed\n in MySQL 5.7.5 and later. (Bug #18777899, Bug #18778485)"
},
{
"para": "Prior to MySQL 5.7.5, <literal>RESET SLAVE ALL</literal> did not\n clear the <literal>IGNORE_SERVER_IDS</literal> list set by\n <literal role=\"stmt\">CHANGE MASTER TO</literal>. In MySQL 5.7.5\n and later, the statement clears the list. (Bug #18816897)"
}
],
"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"
],
"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\">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": "In MySQL current-series, <literal>START SLAVE</literal> causes\n an implicit commit of an ongoing transaction. See\n <xref linkend=\"implicit-commit\" />."
},
{
"para": "Beginning with MySQL 5.7.1,\n <literal role=\"sysvar\">gtid_next</literal> must be set to\n <literal>AUTOMATIC</literal> before issuing this statement (Bug\n #16062608)."
},
{
"para": "The optional <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause added in\n MySQL 5.7.6 enables you to choose which replication channel the\n statement applies to. If no clause is set and no extra channels\n exist, the statement applies to the default channel and behaves\n the same as versions of MySQL prior to 5.7.6. Providing a\n <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause applies the\n <literal>START SLAVE</literal> statement to a specific\n replication channel. If a <literal>START SLAVE</literal>\n statement does not have a channel defined when using multiple\n channels, this statement starts the specified threads for all\n channels. Beginning with MySQL 5.7.9, this statement is\n disallowed for the <literal>group_replication_recovery</literal>\n channel. See <xref linkend=\"replication-channels\" /> for more\n information."
},
{
"para": "MySQL current-series supports pluggable user-password\n authentication with <literal>START SLAVE</literal> with the\n <literal>USER</literal>, <literal>PASSWORD</literal>,\n <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": "Prior to MySQL 5.7.3, <literal>SQL_AFTER_GTIDS</literal> did not\n stop the slave once the indicated transaction was completed, but\n waited until another GTID event was received (Bug #14767986)."
},
{
"para": "When using a multithreaded slave, there is a chance of gaps in\n the sequence of transactions that have been executed from the\n relay log in the following cases:"
},
{
"itemizedlist": [
[
{
"para": "killing the coordinator thread"
}
],
[
{
"para": "after an error occurs in the worker 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"
],
"description": [
{
"para": "Stops the slave threads. <literal role=\"stmt\">STOP\n SLAVE</literal> requires the\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."
},
{
"para": "In MySQL current-series, <literal>STOP SLAVE</literal> causes\n an implicit commit of an ongoing transaction. See\n <xref linkend=\"implicit-commit\" />."
},
{
"para": "Beginning with MySQL 5.7.1,\n <literal role=\"sysvar\">gtid_next</literal> must be set to\n <literal>AUTOMATIC</literal> before issuing this statement (Bug\n #16062608)."
},
{
"para": "In MySQL 5.7.2 and later, you can control how long <literal>STOP\n SLAVE</literal> waits 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. (Bug #16856735)"
},
{
"para": "Prior to MySQL 5.7.4, it was necessary to issue this statement\n on a running slave prior to executing\n <literal role=\"stmt\">CHANGE MASTER TO</literal>. In MySQL 5.7.4\n and later, this is no longer always the case; some\n <literal>CHANGE MASTER TO</literal> statements are now 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 added in\n MySQL 5.7.6 enables you to choose which replication channel the\n statement applies to. If no clause is set and no extra channels\n exist, the statement applies to the default channel and behaves\n the same as versions of MySQL prior to 5.7.6. Providing a\n <literal>FOR CHANNEL\n <replaceable>channel</replaceable></literal> clause applies the\n <literal>STOP SLAVE</literal> statement to a specific\n replication channel. If a <literal>STOP SLAVE</literal>\n statement does not have a channel defined when using multiple\n channels, this statement stops the specified threads for all\n channels. Beginning with MySQL 5.7.9, 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>. In MySQL 5.7.4\n and later, if there are any temporary tables open on the slave,\n issuing a <literal>CHANGE MASTER TO</literal> statement after\n issuing a <literal>STOP SLAVE</literal> causes an\n <errorname>ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO</errorname>\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>]\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": [
"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. As of MySQL 5.7.2, a\n warning is generated when the <literal>WITH CONSISTENT\n SNAPSHOT</literal> clause is 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\">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",
"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": "<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> 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. As of MySQL\n 5.7.5, <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",
"SELECT",
"EXTENDED",
"PARTITIONS",
"FORMAT",
"TRADITIONAL",
"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<replaceable>explain_type</replaceable>: {\n EXTENDED\n | PARTITIONS\n | FORMAT = <replaceable>format_name</replaceable>\n}\n\n<replaceable>format_name</replaceable>: {\n TRADITIONAL\n | JSON\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": []
}
]
}