MySQL8 中文参考（八十四）

原文：docs.oracle.com/javase/tutorial/reallybigindex.html

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-documents-find.html

22.4.3.3 查找文档

您可以使用find()方法查询并返回模式中集合中的文档。MySQL Shell 提供额外的方法与find()方法一起使用，以过滤和排序返回的文档。

MySQL 提供以下运算符来指定搜索条件：OR（||），AND（&&），XOR，IS，NOT，BETWEEN，IN，LIKE，!=，<>，>，>=，<，<=，&，|，<<，>>，+，-，*，/，~和%。

查找集合中的所有文档

要返回集合中的所有文档，请使用未指定搜索条件的find()方法。例如，以下操作返回countryinfo集合中的所有文档。

mysql-py> db.countryinfo.find()
[
     {
          "GNP": 828,
          "Code:": "ABW",
          "Name": "Aruba",
          "IndepYear": null,
          "geography": {
              "Continent": "North America",
              "Region": "Caribbean",
              "SurfaceArea": 193
          },
          "government": {
              "GovernmentForm": "Nonmetropolitan Territory of The Netherlands",
              "HeadOfState": "Beatrix"
          }
          "demographics": {
              "LifeExpectancy": 78.4000015258789,
              "Population": 103000
          },
          ...
      }
 ]
240 documents in set (0.00 sec)

该方法生成包含操作信息以及集合中所有文档的结果。

空集（没有匹配的文档）返回以下信息：

Empty set (0.00 sec)

过滤搜索

您可以在find()方法中包含搜索条件。形成搜索条件的表达式语法与传统 MySQL 第十四章，函数和运算符相同。您必须将所有表达式括在引号中。为简洁起见，一些示例未显示输出。

一个简单的搜索条件可能包括Name字段和我们知道在文档中的值。以下示例返回一个文档：

mysql-py> db.countryinfo.find("Name = 'Australia'")
[
    {
        "GNP": 351182,
        "Code:": "AUS",
        "Name": "Australia",
        "IndepYear": 1901,
        "geography": {
            "Continent": "Oceania",
            "Region": "Australia and New Zealand",
            "SurfaceArea": 7741220
        },
        "government": {
            "GovernmentForm": "Constitutional Monarchy, Federation",
            "HeadOfState": "Elisabeth II"
        }
        "demographics": {
            "LifeExpectancy": 79.80000305175781,
            "Population": 18886000
        },
    }
]

以下示例搜索所有 GNP 高于 5000 亿美元的国家。countryinfo集合以百万为单位衡量 GNP。

mysql-py> db.countryinfo.find("GNP > 500000")
...[*output removed*]
10 documents in set (0.00 sec)

以下查询中的人口字段嵌入在人口统计对象中。要访问嵌入字段，请在人口统计和人口之间使用句点以确定关系。文档和字段名称区分大小写。

mysql-py> db.countryinfo.find("GNP > 500000 and demographics.Population < 100000000")
...[*output removed*]
6 documents in set (0.00 sec)

以下表达式中的算术运算符用于查询 GNP 人均超过 30000 美元的国家。搜索条件可以包括算术运算符和大多数 MySQL 函数。

注意

countryinfo集合中有七个人口值为零的文档。因此，在输出末尾会出现警告消息。

mysql-py> db.countryinfo.find("GNP*1000000/demographics.Population > 30000")
...[*output removed*]
9 documents in set, 7 warnings (0.00 sec)
Warning (Code 1365): Division by 0
Warning (Code 1365): Division by 0
Warning (Code 1365): Division by 0
Warning (Code 1365): Division by 0
Warning (Code 1365): Division by 0
Warning (Code 1365): Division by 0
Warning (Code 1365): Division by 0

您可以使用bind()方法将值与搜索条件分离。例如，不要将硬编码的国家名称作为条件，而是用由冒号和以字母开头的名称组成的命名占位符替换。然后使用bind(*占位符*, *值*)方法如下：

mysql-py> db.countryinfo.find("Name = :country").bind("country", "Italy")
{
    "GNP": 1161755,
    "_id": "00005de917d8000000000000006a",
    "Code": "ITA",
    "Name": "Italy",
    "Airports": [],
    "IndepYear": 1861,
    "geography": {
        "Region": "Southern Europe",
        "Continent": "Europe",
        "SurfaceArea": 301316
    },
    "government": {
        "HeadOfState": "Carlo Azeglio Ciampi",
        "GovernmentForm": "Republic"
    },
    "demographics": {
        "Population": 57680000,
        "LifeExpectancy": 79
    }
}
1 document in set (0.01 sec)

提示

在程序中，绑定使您能够在表达式中指定占位符，在执行之前用值填充，并且可以从适当的自动转义中受益。

始终使用绑定来清理输入。避免使用字符串连接在查询中引入值，这可能会产生无效输入，并且在某些情况下可能会导致安全问题。

您可以使用占位符和bind()方法创建保存的搜索，然后可以使用不同的值调用它们。例如，为一个国家创建一个保存的搜索：

mysql-py> myFind = db.countryinfo.find("Name = :country")
mysql-py> myFind.bind('country', 'France')
{
    "GNP": 1424285,
    "_id": "00005de917d80000000000000048",
    "Code": "FRA",
    "Name": "France",
    "IndepYear": 843,
    "geography": {
        "Region": "Western Europe",
        "Continent": "Europe",
        "SurfaceArea": 551500
    },
    "government": {
        "HeadOfState": "Jacques Chirac",
        "GovernmentForm": "Republic"
    },
    "demographics": {
        "Population": 59225700,
        "LifeExpectancy": 78.80000305175781
    }
}
1 document in set (0.0028 sec)

mysql-py> myFind.bind('country', 'Germany')
{
    "GNP": 2133367,
    "_id": "00005de917d80000000000000038",
    "Code": "DEU",
    "Name": "Germany",
    "IndepYear": 1955,
    "geography": {
        "Region": "Western Europe",
        "Continent": "Europe",
        "SurfaceArea": 357022
    },
    "government": {
        "HeadOfState": "Johannes Rau",
        "GovernmentForm": "Federal Republic"
    },
    "demographics": {
        "Population": 82164700,
        "LifeExpectancy": 77.4000015258789
    }
}

1 document in set (0.0026 sec)

项目结果

您可以返回文档的特定字段，而不是返回所有字段。以下示例返回countryinfo集合中所有文档的 GNP 和 Name 字段，符合搜索条件。

使用fields()方法传递要返回的字段列表。

mysql-py> db.countryinfo.find("GNP > 5000000").fields(["GNP", "Name"])
[
    {
        "GNP": 8510700,
        "Name": "United States"
    }
]
1 document in set (0.00 sec)

此外，您可以修改返回的文档——添加、重命名、嵌套甚至计算新的字段值，使用描述要返回的文档的表达式。例如，使用以下表达式修改字段名称以仅返回两个文档。

mysql-py> db.countryinfo.find().fields(
mysqlx.expr('{"Name": upper(Name), "GNPPerCapita": GNP*1000000/demographics.Population}')).limit(2)
{
    "Name": "ARUBA",
    "GNPPerCapita": 8038.834951456311
}
{
    "Name": "AFGHANISTAN",
    "GNPPerCapita": 263.0281690140845
}

限制、排序和跳过结果

您可以应用limit()、sort()和skip()方法来管理find()方法返回的文档数量和顺序。

要指定结果集中包含的文档数量，请将limit()方法附加到find()方法的值。以下查询返回countryinfo集合中的前五个文档。

mysql-py> db.countryinfo.find().limit(5)
... [*output removed*]
5 documents in set (0.00 sec)

要为结果指定顺序，请将sort()方法附加到find()方法。将一个或多个要排序的字段列表传递给sort()方法，并根据需要选择降序(desc)或升序(asc)属性。升序是默认的排序类型。

例如，以下查询按照 IndepYear 字段对所有文档进行排序，然后以降序返回前八个文档。

mysql-py> db.countryinfo.find().sort(["IndepYear desc"]).limit(8)
... [*output removed*]
8 documents in set (0.00 sec)

默认情况下，limit()方法从集合中的第一个文档开始。您可以使用skip()方法来更改起始文档。例如，要忽略第一个文档并返回符合条件的接下来的八个文档，请将值 1 传递给skip()方法。

mysql-py> db.countryinfo.find().sort(["IndepYear desc"]).limit(8).skip(1)
... [*output removed*]
8 documents in set (0.00 sec)

相关信息

• MySQL 参考手册提供了有关函数和运算符的详细文档。
• 请查看 CollectionFindFunction 以获取完整的语法定义。

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-documents-modify.html

22.4.3.4 修改文档

您可以使用modify()方法来更新集合中的一个或多个文档。X DevAPI 提供了与modify()方法一起使用的附加方法，以：

• 设置和取消文档中的字段。
• 追加、插入和删除数组
• 绑定、限制和排序要修改的文档。

设置和取消文档字段

modify()方法通过过滤集合以仅包括要修改的文档，然后对这些文档应用您指定的操作来工作。

在以下示例中，modify()方法使用搜索条件标识要更改的文档，然后set()方法替换嵌套的 demographics 对象中的两个值。

mysql-py> db.countryinfo.modify("Code = 'SEA'").set(
"demographics", {"LifeExpectancy": 78, "Population": 28})

修改文档后，请使用find()方法验证更改。

要从文档中删除内容，请使用modify()和unset()方法。例如，以下查询从符合搜索条件的文档中删除 GNP。

mysql-py> db.countryinfo.modify("Name = 'Sealand'").unset("GNP")

使用find()方法验证更改。

mysql-py> db.countryinfo.find("Name = 'Sealand'")
{
    "_id": "00005e2ff4af00000000000000f4",
    "Name": "Sealand",
    "Code:": "SEA",
    "IndepYear": 1967,
    "geography": {
        "Region": "British Islands",
        "Continent": "Europe",
        "SurfaceArea": 193
    },
    "government": {
        "HeadOfState": "Michael Bates",
        "GovernmentForm": "Monarchy"
    },
    "demographics": {
        "Population": 27,
        "LifeExpectancy": 79
    }
}

追加、插入和删除数组

要向数组字段追加元素，或者插入、删除数组中的元素，请使用array_append()、array_insert()或array_delete()方法。以下示例修改countryinfo集合以启用对国际机场的跟踪。

第一个示例使用modify()和set()方法在所有文档中创建一个新的 Airports 字段。

注意

在修改文档时没有指定搜索条件时要小心；这样会修改集合中的所有文档。

mysql-py> db.countryinfo.modify("true").set("Airports", [])

添加了 Airports 字段后，下一个示例使用array_append()方法向其中一个文档添加一个新机场。在以下示例中，$.Airports代表当前文档的 Airports 字段。

mysql-py> db.countryinfo.modify("Name = 'France'").array_append("$.Airports", "ORY")

使用find()查看更改。

mysql-py> db.countryinfo.find("Name = 'France'")
{
    "GNP": 1424285,
    "_id": "00005de917d80000000000000048",
    "Code": "FRA",
    "Name": "France",
    "Airports": [
        "ORY"
    ],
    "IndepYear": 843,
    "geography": {
        "Region": "Western Europe",
        "Continent": "Europe",
        "SurfaceArea": 551500
    },
    "government": {
        "HeadOfState": "Jacques Chirac",
        "GovernmentForm": "Republic"
    },
    "demographics": {
        "Population": 59225700,
        "LifeExpectancy": 78.80000305175781
    }
}

要在数组中的不同位置插入元素，请使用array_insert()方法来指定要在路径表达式中插入的索引。在这种情况下，索引为 0，或者数组中的第一个元素。

mysql-py> db.countryinfo.modify("Name = 'France'").array_insert("$.Airports[0]", "CDG")

要从数组中删除元素，必须将要删除的元素的索引传递给array_delete()方法。

mysql-py> db.countryinfo.modify("Name = 'France'").array_delete("$.Airports[1]")

相关信息

• MySQL 参考手册提供了帮助您搜索和修改 JSON 值的说明。
• 请参阅 CollectionModifyFunction 获取完整的语法定义。

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-documents-remove.html

22.4.3.5 删除文档

您可以使用remove()方法从模式中的集合中删除一些或所有文档。X DevAPI 提供了额外的方法与remove()方法一起使用，以过滤和排序要删除的文档。

使用条件删除文档

以下示例向remove()方法传递了搜索条件。与条件匹配的所有文档都将从countryinfo集合中删除。在此示例中，有一个文档符合条件。

mysql-py> db.countryinfo.remove("Code = 'SEA'")

删除第一个文档

要删除countryinfo集合中的第一个文档，请使用值为 1 的limit()方法。

mysql-py> db.countryinfo.remove("true").limit(1)

删除订单中的最后一个文档

以下示例通过国家名称删除countryinfo集合中的最后一个文档。

mysql-py> db.countryinfo.remove("true").sort(["Name desc"]).limit(1)

删除集合中的所有文档

您可以删除集合中的所有文档。要这样做，请使用不指定搜索条件的remove("true")方法。

注意

在不指定搜索条件的情况下删除文档时要小心。此操作会从集合中删除所有文档。

或者，使用db.drop_collection('countryinfo')操作删除countryinfo集合。

相关信息

• 请参阅 CollectionRemoveFunction 获取完整的语法定义。
• 请参阅 Section 22.4.2，“下载和导入 world_x 数据库”，了解重新创建world_x模式的说明。

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-documents-index.html

22.4.3.6 创建和删除索引

索引用于快速查找具有特定字段值的文档。没有索引，MySQL 必须从第一个文档开始，然后逐个读取整个集合以查找相关字段。集合越大，成本就越高。如果集合很大且对特定字段的查询很常见，则考虑在文档内的特定字段上创建索引。

例如，以下查询在 Population 字段上使用索引性能更好：

mysql-py> db.countryinfo.find("demographics.Population < 100")
...[*output removed*]
8 documents in set (0.00 sec)

create_index()方法创建一个索引，您可以使用指定要使用的字段的 JSON 文档进行定义。本节是索引的高级概述。有关更多信息，请参阅索引集合。

添加一个非唯一索引

要创建非唯一索引，请将索引名称和索引信息传递给create_index()方法。禁止重复索引名称。

以下示例指定了一个名为popul的索引，针对demographics对象中的Population字段进行定义，作为Integer数值进行索引。最后一个参数指示字段是否应该需要NOT NULL约束。如果值为false，则该字段可以包含NULL值。索引信息是一个包含一个或多个字段详细信息的 JSON 文档，用于包含在索引中。每个字段定义必须包括字段的完整文档路径，并指定字段的类型。

mysql-py> db.countryinfo.createIndex("popul", {fields:
[{field: '$.demographics.Population', type: 'INTEGER'}]})

在这里，索引使用整数数值创建。还有其他选项可用，包括用于 GeoJSON 数据的选项。您还可以指定索引类型，这里省略了，因为默认类型“index”是合适的。

添加一个唯一索引

要创建唯一索引，请将索引名称、索引定义和索引类型“unique”传递给create_index()方法。此示例显示了在国家名称（"Name"）上创建的唯一索引，这是countryinfo集合中另一个常见字段进行索引。在索引字段描述中，"TEXT(40)"表示要索引的字符数，"required": True指定该字段必须存在于文档中。

mysql-py> db.countryinfo.create_index("name",
{"fields": [{"field": "$.Name", "type": "TEXT(40)", "required": True}], "unique": True})

删除索引

要删除索引，请将要删除的索引名称传递给drop_index()方法。例如，您可以按如下方式删除“popul”索引：

mysql-py> db.countryinfo.drop_index("popul")

相关信息

• 有关更多信息，请参阅索引集合。
• 有关定义索引的更多信息，请参阅定义索引中定义索引的 JSON 文档。
• 请参阅集合索引管理函数以获取完整的语法定义。

22.4.4 关系表

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-relational-tables.html

22.4.4.1 向表中插入记录

22.4.4.2 选择表

22.4.4.3 更新表

22.4.4.4 删除表

您也可以使用 X DevAPI 来处理关系表。在 MySQL 中，每个关系表都与特定的存储引擎相关联。本节中的示例使用InnoDB表在world_x模式中。

确认模式

要显示分配给db全局变量的模式，请发出db。

mysql-py> db
<Schema:world_x>

如果返回的值不是Schema:world_x，请将db变量设置如下：

mysql-py> \use world_x
Schema `world_x` accessible through db.

显示所有表

要显示world_x模式中的所有关系表，请在db对象上使用get_tables()方法。

mysql-py> db.get_tables()
[
    <Table:city>,
    <Table:country>,
    <Table:countrylanguage>
]

基本表操作

由表限定的基本操作包括：

相关信息

• 有关更多信息，请参阅处理关系表。
• CRUD EBNF 定义 提供了操作的完整列表。
• 请参阅第 22.4.2 节，“下载和导入 world_x 数据库”，了解设置world_x模式示例的说明。

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-table-insert.html

22.4.4.1 向表中插入记录

您可以使用insert()方法与values()方法将记录插入到现有的关系表中。insert()方法接受单个列或表中的所有列。使用一个或多个values()方法来指定要插入的值。

插入完整记录

要插入完整记录，将表中的所有列传递给insert()方法。然后，对于每个列，将一个值传递给values()方法。例如，要向world_x数据库中的 city 表添加新记录，请插入以下记录并按两次Enter。

mysql-py> db.city.insert("ID", "Name", "CountryCode", "District", "Info").values(
None, "Olympia", "USA", "Washington", '{"Population": 5000}')

city 表有五列：ID、Name、CountryCode、District 和 Info。每个值必须与其代表的列的数据类型匹配。

插入部分记录

以下示例将值插入到 city 表的 ID、Name 和 CountryCode 列中。

mysql-py> db.city.insert("ID", "Name", "CountryCode").values(
None, "Little Falls", "USA").values(None, "Happy Valley", "USA")

当您使用insert()方法指定列时，值的数量必须与列的数量匹配。在前面的示例中，您必须提供三个值以匹配指定的三列。

相关信息

• 请参阅 TableInsertFunction 以获取完整的语法定义。

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-table-select.html

22.4.4.2 选择表

您可以使用select()方法从数据库中的表中查询并返回记录。X DevAPI 提供了与select()方法一起使用的附加方法，以过滤和排序返回的记录。

MySQL 提供以下运算符来指定搜索条件：OR（||）、AND（&&）、XOR、IS、NOT、BETWEEN、IN、LIKE、!=、<>、>、>=、<、<=、&、|、<<、>>、+、-、*、/、~和%。

选择所有记录

要发出返回现有表中的所有记录的查询，请使用未指定搜索条件的select()方法。以下示例从world_x数据库中的 city 表中选择所有记录。

注意

限制空的select()方法的使用仅限于交互式语句。始终在应用程序代码中使用显式列名选择。

mysql-py> db.city.select()
+------+------------+-------------+------------+-------------------------+
| ID   | Name       | CountryCode | District   | Info                    |
+------+------------+-------------+------------+-------------------------+
|    1 | Kabul      | AFG         | Kabol      |{"Population": 1780000}  |
|    2 | Qandahar   | AFG         | Qandahar   |{"Population": 237500}   |
|    3 | Herat      | AFG         | Herat      |{"Population": 186800}   |
...    ...          ...           ...          ...
| 4079 | Rafah      | PSE         | Rafah      |{"Population": 92020}    |
+------+------- ----+-------------+------------+-------------------------+
4082 rows in set (0.01 sec)

空集（没有匹配记录）返回以下信息：

Empty set (0.00 sec)

过滤搜索

要发出返回一组表列的查询，请使用select()方法，并在方括号之间指定要返回的列。此查询从 city 表返回 Name 和 CountryCode 列。

mysql-py> db.city.select(["Name", "CountryCode"])
+-------------------+-------------+
| Name              | CountryCode |
+-------------------+-------------+
| Kabul             | AFG         |
| Qandahar          | AFG         |
| Herat             | AFG         |
| Mazar-e-Sharif    | AFG         |
| Amsterdam         | NLD         |
...                 ...
| Rafah             | PSE         |
| Olympia           | USA         |
| Little Falls      | USA         |
| Happy Valley      | USA         |
+-------------------+-------------+
4082 rows in set (0.00 sec)

要发出返回符合特定搜索条件的行的查询，请使用where()方法包含这些条件。例如，以下示例返回以字母 Z 开头的城市的名称和国家代码。

mysql-py> db.city.select(["Name", "CountryCode"]).where("Name like 'Z%'")
+-------------------+-------------+
| Name              | CountryCode |
+-------------------+-------------+
| Zaanstad          | NLD         |
| Zoetermeer        | NLD         |
| Zwolle            | NLD         |
| Zenica            | BIH         |
| Zagazig           | EGY         |
| Zaragoza          | ESP         |
| Zamboanga         | PHL         |
| Zahedan           | IRN         |
| Zanjan            | IRN         |
| Zabol             | IRN         |
| Zama              | JPN         |
| Zhezqazghan       | KAZ         |
| Zhengzhou         | CHN         |
...                 ...
| Zeleznogorsk      | RUS         |
+-------------------+-------------+
59 rows in set (0.00 sec)

您可以使用bind()方法将值与搜索条件分开。例如，不要使用"Name = ‘Z%’ "作为条件，而是替换为以字母开头的名称为前缀的命名占位符，例如name。然后将占位符和值包含在bind()方法中，如下所示：

mysql-py> db.city.select(["Name", "CountryCode"]).where(
"Name like :name").bind("name", "Z%")

提示

在程序内部，绑定使您可以在表达式中指定占位符，在执行之前用值填充，并可以根据需要受益于自动转义。

始终使用绑定来清理输入。避免使用字符串连接引入查询中的值，这可能会产生无效输入，并且在某些情况下可能会导致安全问题。

项目结果

要使用AND运算符发出查询，请在where()方法中的搜索条件之间添加运算符。

mysql-py> db.city.select(["Name", "CountryCode"]).where(
"Name like 'Z%' and CountryCode = 'CHN'")
+----------------+-------------+
| Name           | CountryCode |
+----------------+-------------+
| Zhengzhou      | CHN         |
| Zibo           | CHN         |
| Zhangjiakou    | CHN         |
| Zhuzhou        | CHN         |
| Zhangjiang     | CHN         |
| Zigong         | CHN         |
| Zaozhuang      | CHN         |
...              ...
| Zhangjiagang   | CHN         |
+----------------+-------------+
22 rows in set (0.01 sec)

要指定多个条件运算符，可以将搜索条件括在括号中以更改运算符优先级。以下示例演示了AND和OR运算符的放置位置。

mysql-py> db.city.select(["Name", "CountryCode"]).where(
"Name like 'Z%' and (CountryCode = 'CHN' or CountryCode = 'RUS')")
+-------------------+-------------+
| Name              | CountryCode |
+-------------------+-------------+
| Zhengzhou         | CHN         |
| Zibo              | CHN         |
| Zhangjiakou       | CHN         |
| Zhuzhou           | CHN         |
...                 ...
| Zeleznogorsk      | RUS         |
+-------------------+-------------+
29 rows in set (0.01 sec)

限制、排序和偏移结果

您可以应用limit()、order_by()和offset()方法来管理select()方法返回的记录数量和顺序。

要指定结果集中包含的记录数，请将一个值附加到select()方法的limit()方法。例如，以下查询返回 country 表中的前五条记录。

mysql-py> db.country.select(["Code", "Name"]).limit(5)
+------+-------------+
| Code | Name        |
+------+-------------+
| ABW  | Aruba       |
| AFG  | Afghanistan |
| AGO  | Angola      |
| AIA  | Anguilla    |
| ALB  | Albania     |
+------+-------------+
5 rows in set (0.00 sec)

要指定结果的顺序，请将order_by()方法附加到select()方法。将一个或多个要排序的列的列表传递给order_by()方法，并根据需要选择降序（desc）或升序（asc）属性。升序是默认的排序类型。

例如，以下查询按 Name 列对所有记录进行排序，然后以降序返回前三条记录。

mysql-py> db.country.select(["Code", "Name"]).order_by(["Name desc"]).limit(3)
+------+------------+
| Code | Name       |
+------+------------+
| ZWE  | Zimbabwe   |
| ZMB  | Zambia     |
| YUG  | Yugoslavia |
+------+------------+
3 rows in set (0.00 sec)

默认情况下，limit()方法从表中的第一条记录开始。您可以使用offset()方法来更改起始记录。例如，要忽略第一条记录并返回符合条件的接下来三条记录，请将一个值传递给offset()方法。

mysql-py> db.country.select(["Code", "Name"]).order_by(["Name desc"]).limit(3).offset(1)
+------+------------+
| Code | Name       |
+------+------------+
| ZMB  | Zambia     |
| YUG  | Yugoslavia |
| YEM  | Yemen      |
+------+------------+
3 rows in set (0.00 sec)

相关信息

• MySQL 参考手册提供了有关函数和运算符的详细文档。
• 请参阅 TableSelectFunction 以获取完整的语法定义。

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-table-update.html

22.4.4.3 更新表格

您可以使用update()方法修改表中的一个或多个记录。update()方法通过过滤查询以仅包括要更新的记录，然后对这些记录应用您指定的操作来工作。

要在城市表中替换城市名称，请将新城市名称传递给set()方法。然后，将要定位和替换的城市名称传递给where()方法。以下示例将城市 Peking 替换为 Beijing。

mysql-py> db.city.update().set("Name", "Beijing").where("Name = 'Peking'")

使用select()方法验证更改。

mysql-py> db.city.select(["ID", "Name", "CountryCode", "District", "Info"]).where("Name = 'Beijing'")
+------+-----------+-------------+----------+-----------------------------+
| ID   | Name      | CountryCode | District | Info                        |
+------+-----------+-------------+----------+-----------------------------+
| 1891 | Beijing   | CHN         | Peking   | {"Population": 7472000}     |
+------+-----------+-------------+----------+-----------------------------+
1 row in set (0.00 sec)

相关信息

• 查看 TableUpdateFunction 以获取完整的语法定义。

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-table-delete.html

22.4.4.4 删除表

你可以使用delete()方法从数据库中的表中删除一些或所有记录。X DevAPI 提供了额外的方法与delete()方法一起使用，以过滤和排序要删除的记录。

使用条件删除记录

以下示例将搜索条件传递给delete()方法。所有匹配条件的记录都将从city表中删除。在这个示例中，有一条记录符合条件。

mysql-py> db.city.delete().where("Name = 'Olympia'")

删除第一条记录

要删除城市表中的第一条记录，使用值为 1 的limit()方法。

mysql-py> db.city.delete().limit(1)

删除表中的所有记录

你可以删除表中的所有记录。要这样做，使用delete()方法而不指定搜索条件。

注意

当你删除记录而不指定搜索条件时要小心；这样会删除表中的所有记录。

删除表

drop_collection()方法也可用于在 MySQL Shell 中从数据库中删除关系表。例如，要从world_x数据库中删除citytest表，执行：

mysql-py> db.drop_collection("citytest")

相关信息

• 查看 TableDeleteFunction 获取完整的语法定义。
• 查看第 22.4.2 节，“下载和导入 world_x 数据库”以获取重新创建world_x数据库的说明。

22.4.5 表中的文档

原文：dev.mysql.com/doc/refman/8.0/en/mysql-shell-tutorial-python-documents-in-tables.html

在 MySQL 中，表可以包含传统关系数据、JSON 值或两者兼有。您可以通过将文档存储在具有本机JSON数据类型的列中，将传统数据与 JSON 文档结合起来。

本节示例使用world_x模式中的城市表。

城市表描述

城市表有五列（或字段）。

+---------------+------------+-------+-------+---------+------------------+
| Field         | Type       | Null  | Key   | Default | Extra            |
+---------------+------------+-------+-------+---------+------------------+
| ID            | int(11)    | NO    | PRI   | null    | auto_increment   |
| Name          | char(35)   | NO    |       |         |                  |
| CountryCode   | char(3)    | NO    |       |         |                  |
| District      | char(20)   | NO    |       |         |                  |
| Info          | json       | YES   |       | null    |                  |
+---------------+------------+-------+-------+---------+------------------+

插入一条记录

要将文档插入表的列中，请按正确顺序将格式良好的 JSON 文档传递给values()方法。在下面的示例中，一个文档作为最终值传递，将插入到 Info 列中。

mysql-py> db.city.insert().values(
None, "San Francisco", "USA", "California", '{"Population":830000}')

选择一条记录

您可以发出带有评估表达式中文档值的搜索条件的查询。

mysql-py> db.city.select(["ID", "Name", "CountryCode", "District", "Info"]).where(
"CountryCode = :country and Info->'$.Population' > 1000000").bind(
'country', 'USA')
+------+----------------+-------------+----------------+-----------------------------+
| ID   | Name           | CountryCode | District       | Info                        |
+------+----------------+-------------+----------------+-----------------------------+
| 3793 | New York       | USA         | New York       | {"Population": 8008278}     |
| 3794 | Los Angeles    | USA         | California     | {"Population": 3694820}     |
| 3795 | Chicago        | USA         | Illinois       | {"Population": 2896016}     |
| 3796 | Houston        | USA         | Texas          | {"Population": 1953631}     |
| 3797 | Philadelphia   | USA         | Pennsylvania   | {"Population": 1517550}     |
| 3798 | Phoenix        | USA         | Arizona        | {"Population": 1321045}     |
| 3799 | San Diego      | USA         | California     | {"Population": 1223400}     |
| 3800 | Dallas         | USA         | Texas          | {"Population": 1188580}     |
| 3801 | San Antonio    | USA         | Texas          | {"Population": 1144646}     |
+------+----------------+-------------+----------------+-----------------------------+
9 rows in set (0.01 sec)

相关信息

• 有关更多信息，请参阅与关系表和文档一起工作。
• 详细描述数据类型，请参阅第 13.5 节，“JSON 数据类型”。

22.5 X 插件

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin.html

22.5.1 检查 X 插件安装

22.5.2 禁用 X 插件

22.5.3 使用 X 插件进行加密连接

22.5.4 使用 X 插件与缓存 SHA-2 认证插件

22.5.5 使用 X 插件进行连接压缩

22.5.6 X 插件选项和变量

22.5.7 监控 X 插件

本节介绍如何使用、配置和监控 X 插件。

22.5.1 检查 X 插件安装情况

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-checking-installation.html

MySQL 8 默认启用了 X 插件，因此安装或升级到 MySQL 8 将使插件可用。您可以使用 SHOW plugins 语句查看插件列表来验证 X 插件是否已安装在 MySQL 服务器的实例上。

使用 MySQL Shell 来验证 X 插件是否已安装，请执行：

$> mysqlsh -u *user* --sqlc -P 3306 -e "SHOW plugins"

使用 MySQL Client 来验证 X 插件是否已安装，请执行：

$> mysql -u *user* -p -e "SHOW plugins"

如果 X 插件已安装，则示例结果如下所示：

+----------------------------+----------+--------------------+---------+---------+
| Name                       | Status   | Type               | Library | License |
+----------------------------+----------+--------------------+---------+---------+

...

| mysqlx                     | ACTIVE   | DAEMON             | NULL    | GPL     |

...

+----------------------------+----------+--------------------+---------+---------+

22.5.2 禁用 X 插件

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-disabling.html

X 插件可以在启动时通过在 MySQL 配置文件中设置mysqlx=0，或者在启动 MySQL 服务器时传入--mysqlx=0或--skip-mysqlx来禁用。

或者，可以使用-DWITH_MYSQLX=OFF CMake 选项来编译不包含 X 插件的 MySQL 服务器。

22.5.3 使用 X 插件进行加密连接

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-encrypted-connections.html

本节解释了如何配置 X 插件以使用加密连接。有关更多背景信息，请参阅 Section 8.3, “Using Encrypted Connections”。

要启用对加密连接的支持进行配置，X 插件具有mysqlx_ssl_*xxx*系统变量，这些变量的值可以与用于 MySQL 服务器的ssl_*xxx*系统变量不同。例如，X 插件可以具有与 MySQL 服务器不同的 SSL 密钥、证书和证书颁发机构文件。这些变量在 Section 22.5.6.2, “X Plugin Options and System Variables”中有描述。同样，X 插件具有其自己的Mysqlx_ssl_*xxx*状态变量，对应于 MySQL 服务器加密连接的Ssl_*xxx*状态变量。请参阅 Section 22.5.6.3, “X Plugin Status Variables”。

在初始化时，X 插件确定其用于加密连接的 TLS 上下文如下：

• 如果所有mysqlx_ssl_*xxx*系统变量都具有其默认值，则 X 插件使用与 MySQL 服务器主连接接口相同的 TLS 上下文，该接口由ssl_*xxx*系统变量的值确定。
• 如果任何mysqlx_ssl_*xxx*变量具有非默认值，则 X 插件使用由其自身系统变量的值定义的 TLS 上下文。（如果任何mysqlx_ssl_*xxx*系统变量设置为与其默认值不同的值，则是这种情况。）

这意味着，在启用 X 插件的服务器上，您可以选择通过仅设置ssl_*xxx*变量来共享 MySQL 协议和 X 协议连接的相同加密配置，或者通过分别配置ssl_*xxx*和mysqlx_ssl_*xxx*变量来为 MySQL 协议和 X 协议连接设置不同的加密配置。

要使 MySQL 协议和 X 协议连接使用相同的加密配置，请在my.cnf中仅设置ssl_*xxx*系统变量：

[mysqld]
ssl_ca=ca.pem
ssl_cert=server-cert.pem
ssl_key=server-key.pem

要为 MySQL 协议和 X 协议连接分别配置加密，请在my.cnf中设置ssl_*xxx*和mysqlx_ssl_*xxx*系统变量：

[mysqld]
ssl_ca=ca1.pem
ssl_cert=server-cert1.pem
ssl_key=server-key1.pem

mysqlx_ssl_ca=ca2.pem
mysqlx_ssl_cert=server-cert2.pem
mysqlx_ssl_key=server-key2.pem

有关配置连接加密支持的一般信息，请参阅 Section 8.3.1, “Configuring MySQL to Use Encrypted Connections”。该讨论是针对 MySQL 服务器编写的，但参数名称对于 X 插件是类似的。（X 插件的mysqlx_ssl_*xxx*系统变量名称对应于 MySQL 服务器的ssl_*xxx*系统变量名称。）

tls_version 系统变量确定了 MySQL 协议连接所允许的 TLS 版本，也适用于 X 协议连接。因此，这两种连接类型所允许的 TLS 版本是相同的。

每个连接的加密是可选的，但可以通过在创建用户的 CREATE USER 语句中包含适当的 REQUIRE 子句来要求特定用户在 X 协议和 MySQL 协议连接中使用加密。有关详细信息，请参见 Section 15.7.1.3, “CREATE USER Statement”。或者，要求所有用户在 X 协议和 MySQL 协议连接中使用加密，可以启用 require_secure_transport 系统变量。有关更多信息，请参见 将加密连接配置为强制性。

22.5.4 使用 X 插件与缓存 SHA-2 认证插件

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-sha2-cache-plugin.html

X 插件支持使用caching_sha2_password认证插件创建的 MySQL 用户账户。有关此插件的更多信息，请参阅 8.4.1.2 节，“缓存 SHA-2 可插拔认证”。您可以使用 X 插件对这些账户进行身份验证，使用非 SSL 连接进行SHA256_MEMORY认证和使用 SSL 连接进行PLAIN认证。

虽然caching_sha2_password认证插件拥有一个认证缓存，但这个缓存不与 X 插件共享，因此 X 插件使用自己的认证缓存进行SHA256_MEMORY认证。X 插件认证缓存存储用户账户密码的哈希值，并且无法通过 SQL 访问。如果用户账户被修改或移除，相关条目将从缓存中移除。X 插件认证缓存由默认启用的mysqlx_cache_cleaner插件维护，没有相关的系统变量或状态变量。

在您可以使用非 SSL X 协议连接对使用caching_sha2_password认证插件的账户进行身份验证之前，该账户必须至少通过 SSL 进行一次 X 协议连接的认证，以向 X 插件认证缓存提供密码。一旦这个初始的 SSL 认证成功，就可以使用非 SSL X 协议连接。

可以通过使用选项--mysqlx_cache_cleaner=0启动 MySQL 服务器来禁用mysqlx_cache_cleaner插件。如果这样做，X 插件认证缓存将被禁用，因此在使用SHA256_MEMORY认证进行身份验证时，必须始终使用 SSL 进行 X 协议连接。

22.5.5 X 插件的连接压缩

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-connection-compression.html

从 MySQL 8.0.19 开始，X 插件支持在 X 协议连接上发送消息时进行压缩。如果服务器和客户端就一个相互支持的压缩算法达成一致，连接可以进行压缩。启用压缩会减少通过网络发送的字节数，但会增加服务器和客户端进行压缩和解压缩操作的额外 CPU 成本。因此，压缩的好处主要在网络带宽较低、网络传输时间主导压缩和解压缩操作成本、结果集较大时才会发生。

注意

不同的 MySQL 客户端以不同方式实现对连接压缩的支持；请查阅您的客户端文档以获取详细信息。例如，对于经典 MySQL 协议连接，请参阅 6.2.8 节，“连接压缩控制”。

• 配置 X 插件的连接压缩
• X 插件的压缩连接特性
• 监控 X 插件连接压缩

配置 X 插件的连接压缩

默认情况下，X 插件支持 zstd、LZ4 和 Deflate 压缩算法。使用 Deflate 算法进行压缩时，使用 zlib 软件库，因此 X 协议连接的 deflate_stream 压缩算法设置等效于经典 MySQL 协议连接的 zlib 设置。

在服务器端，您可以通过将 mysqlx_compression_algorithms 系统变量设置为仅包含允许的压缩算法来禁止任何压缩算法。算法名称 zstd_stream、lz4_message 和 deflate_stream 可以以任何组合指定，顺序和大小写不重要。如果系统变量值为空字符串，则不允许任何压缩算法，连接将不被压缩。

以下表格比较了不同压缩算法的特性，并显示了它们的分配优先级。默认情况下，服务器选择服务器和客户端共同允许的最高优先级算法；客户端可以按后文所述更改优先级。在指定时，客户端可以使用算法的简短别名。

表 22.1 X 协议压缩算法特性

X 协议允许的压缩算法集（无论是用户指定的还是默认的）与 MySQL 服务器允许经典 MySQL 协议连接的压缩算法集是独立的，后者由protocol_compression_algorithms服务器系统变量指定。如果您没有指定mysqlx_compression_algorithms系统变量，X 插件不会回退到使用经典 MySQL 协议连接的压缩设置。相反，默认情况下，它允许表 22.1，“X 协议压缩算法特性”中显示的所有算法。这与 TLS 上下文的情况不同，如果未设置 X 插件系统变量，则使用 MySQL 服务器设置，如第 22.5.3 节，“使用 X 插件进行加密连接”中所述。有关经典 MySQL 协议连接的压缩信息，请参阅第 6.2.8 节，“连接压缩控制”。

在客户端端，X 协议连接请求可以为压缩控制指定几个参数：

• 压缩模式。
• 压缩级别（从 MySQL 8.0.20 开始）。
• 按优先顺序列出的允许的压缩算法列表（从 MySQL 8.0.22 开始）。

注意

一些客户端或连接器可能不支持特定的压缩控制功能。例如，仅 MySQL Shell 支持为 X 协议连接指定压缩级别，而其他 MySQL 客户端或连接器不支持。有关支持的功能及如何使用它们的详细信息，请参阅特定产品的文档。

连接模式具有以下允许的值：

• disabled：连接未经压缩。
• preferred：服务器和客户端协商以找到双方都允许的压缩算法。如果没有可用的公共算法，则连接未经压缩。如果未明确指定，则这是默认模式。
• required：压缩算法协商与preferred模式相同，但如果没有可用的公共算法，则连接请求将以错误终止。

除了为每个连接协商压缩算法外，服务器和客户端还可以就适用于约定算法的数字范围内的压缩级别达成一致。随着算法的压缩级别的增加，数据压缩比例增加，从而减少了发送消息到客户端所需的网络带宽和传输时间。然而，数据压缩所需的工作量也增加，占用了服务器上的时间、CPU 和内存资源。压缩工作量的增加与压缩比例的增加之间没有线性关系。

在 MySQL 8.0.19 中，X Plugin 始终使用每种算法的库默认压缩级别（zstd 为 3，LZ4 为 0，Deflate 为 6），客户端无法协商此设置。从 MySQL 8.0.20 开始，客户端可以在与服务器进行 X 协议连接的能力协商期间请求特定的压缩级别。

MySQL 8.0.20 中 X Plugin 使用的默认压缩级别是通过性能测试选择的，是在压缩时间和网络传输时间之间的良好折衷。这些默认值不一定与每种算法的库默认值相同。如果客户端没有为算法请求压缩级别，则会应用这些默认压缩级别。默认压缩级别最初设置为 zstd 的 3，LZ4 的 2，以及 Deflate 的 3。您可以使用mysqlx_zstd_default_compression_level，mysqlx_lz4_default_compression_level，和mysqlx_deflate_default_compression_level系统变量来调整这些设置。

为防止服务器上的资源消耗过多，X Plugin 为每种算法设置了服务器允许的最大压缩级别。如果客户端请求的压缩级别超过此设置，服务器将使用其允许的最大压缩级别（客户端请求的压缩级别仅由 MySQL Shell 支持）。最大压缩级别最初设置为 zstd 的 11，LZ4 的 8，以及 Deflate 的 5。您可以使用mysqlx_zstd_max_client_compression_level，mysqlx_lz4_max_client_compression_level，和mysqlx_deflate_max_client_compression_level系统变量来调整这些设置。

如果服务器和客户端共同允许多个算法，则在协商期间选择算法的默认优先顺序如表 22.1，“X 协议压缩算法特性”中所示。从 MySQL 8.0.22 开始，对于支持指定压缩算法的客户端，连接请求可以包含客户端允许的算法列表，使用算法名称或其别名指定。列表中这些算法的顺序被服务器视为优先顺序。在这种情况下使用的算法是客户端列表中第一个在服务器端也允许的算法。然而，压缩算法选项取决于压缩模式：

• 如果压缩模式为disabled，则忽略压缩算法选项。
• 如果压缩模式为preferred，但客户端端和服务器端上没有允许的算法，则连接未经压缩。
• 如果压缩模式为required，但客户端端和服务器端上没有允许的算法，则会发生错误。

要监视消息压缩的效果，请使用 X Plugin 监视连接压缩中描述的 X Plugin 状态变量。您可以使用这些状态变量来计算使用当前设置的消息压缩的好处，并使用该信息来调整您的设置。

X Plugin 的压缩连接特性

X 协议连接压缩具有以下行为和边界：

• 算法名称中的_stream和_message后缀指的是两种不同的操作模式：在流模式中，单个连接中的所有 X 协议消息被压缩成连续的流，并且必须以相同的方式解压缩——按照它们被压缩的顺序进行，而且不能跳过任何消息。在消息模式中，每个消息都被单独和独立地压缩，不需要按照它们被压缩的顺序进行解压缩。此外，消息模式不要求所有压缩的消息都必须被解压缩。
• 不适用于在身份验证成功之前发送的任何消息的压缩。
• 压缩不适用于诸如Mysqlx.Ok、Mysqlx.Error和Mysqlx.Sql.StmtExecuteOk等控制流消息。
• 如果服务器和客户端在能力协商期间就共同允许的压缩算法达成一致，那么所有其他 X 协议消息都可以进行压缩。如果客户端在该阶段不请求压缩，则客户端和服务器都不会对消息应用压缩。
• 当通过 X 协议连接发送的消息被压缩时，mysqlx_max_allowed_packet系统变量指定的限制仍然适用。消息负载解压缩后的网络数据包必须小于此限制。如果超过限制，X 插件将返回解压缩错误并关闭连接。
• 客户端的压缩级别请求仅由 MySQL Shell 支持，以下是相关要点：
  • 客户端必须将压缩级别指定为整数。如果提供了其他类型的值，则连接将以错误关闭。
  • 如果客户端指定算法但未指定压缩级别，则服务器将使用该算法的默认压缩级别。
  • 如果客户端请求的算法压缩级别超过服务器允许的最大级别，则服务器使用最大允许级别。
  • 如果客户端请求的算法压缩级别低于服务器允许的最小级别，则服务器使用最小允许级别。

监控 X 插件的连接压缩效果

您可以使用 X 插件状态变量监视消息压缩的效果。当使用消息压缩时，会话Mysqlx_compression_algorithm状态变量显示当前 X 协议连接中使用的压缩算法，Mysqlx_compression_level显示所选的压缩级别。这些会话状态变量从 MySQL 8.0.20 开始可用。

从 MySQL 8.0.19 开始，X 插件状态变量可用于计算所选的压缩算法的效率（数据压缩比），以及使用消息压缩的整体效果。在以下计算中使用状态变量的会话值，以查看已知压缩算法的特定会话的消息压缩带来的好处。或者使用状态变量的全局值，检查使用 X 协议连接的服务器的整体消息压缩效益，包括为这些会话使用的所有压缩算法，以及未使用消息压缩的所有会话。然后，可以通过调整允许的压缩算法、最大压缩级别和默认压缩级别来调整消息压缩，如为 X 插件配置连接压缩中所述。

当消息压缩被使用时，Mysqlx_bytes_sent 状态变量显示从服务器发送的总字节数，包括压缩后测量的压缩消息有效载荷、未压缩的压缩消息中未压缩的项目（如 X 协议头）以及任何未压缩的消息。Mysqlx_bytes_sent_compressed_payload 状态变量显示作为压缩消息有效载荷发送的总字节数，压缩后测量，而 Mysqlx_bytes_sent_uncompressed_frame 状态变量显示相同消息有效载荷的总字节数，但在压缩之前测量。因此，压缩算法的效率可以通过以下表达式计算：

mysqlx_bytes_sent_uncompressed_frame / mysqlx_bytes_sent_compressed_payload

服务器发送的 X 协议消息的压缩效果可以通过以下表达式计算：

(mysqlx_bytes_sent - mysqlx_bytes_sent_compressed_payload + mysqlx_bytes_sent_uncompressed_frame) / mysqlx_bytes_sent

对于服务器从客户端接收的消息，Mysqlx_bytes_received_compressed_payload 状态变量显示作为压缩消息有效载荷接收的总字节数，解压缩前测量，而 Mysqlx_bytes_received_uncompressed_frame 状态变量显示相同消息有效载荷的总字节数，但在解压缩后测量。Mysqlx_bytes_received 状态变量包括解压缩前测量的压缩消息有效载荷、压缩消息中的任何未压缩项目以及任何未压缩消息。

22.5.6 X 插件选项和变量

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-options-variables.html

22.5.6.1 X 插件选项和变量参考

22.5.6.2 X 插件选项和系统变量

22.5.6.3 X 插件状态变量

本节描述了配置 X 插件的命令选项和系统变量，以及用于监控目的的状态变量。如果在启动时指定的配置值不正确，X 插件可能无法正确初始化，服务器也无法加载它。在这种情况下，服务器还可能因为无法识别其他 X 插件设置而产生错误消息。

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-option-variable-reference.html

22.5.6.1 X 插件选项和变量参考

该表提供了 X 插件提供的命令选项、系统变量和状态变量的概述。

表 22.2 X 插件选项和变量参考

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-options-system-variables.html

22.5.6.2 X Plugin 选项和系统变量

使用此选项来控制 X Plugin 的激活：

• --mysqlx[=value] 命令行格式--mysqlx[=value]类型枚举默认值ON有效值ON``OFF``FORCE``FORCE_PLUS_PERMANENT此选项控制服务器在启动时如何加载 X Plugin。在 MySQL 8.0 中，默认情况下启用 X Plugin，但此选项可用于控制其激活状态。 选项值应该是插件加载选项中可用的一个，如第 7.6.1 节，“安装和卸载插件”中所述。

如果启用了 X Plugin，它会公开几个系统变量，允许控制其操作：

mysqlx_bind_address

X Plugin 监听 TCP/IP 连接的网络地址。此变量不是动态的，只能在启动时配置。这是bind_address系统变量的 X Plugin 等效变量；有关更多信息，请参阅该变量描述。

默认情况下，X Plugin 接受所有服务器主机 IPv4 接口上的 TCP/IP 连接，并且如果服务器主机支持 IPv6，则接受所有 IPv6 接口上的连接。如果指定了mysqlx_bind_address，其值必须满足这些要求：

• 在 MySQL 8.0.21 之前，mysqlx_bind_address接受单个地址值，该值可以指定单个非通配符 IP 地址（IPv4 或 IPv6）、主机名或允许监听多个网络接口的通配符地址格式之一（*、0.0.0.0或::）。
• 在 MySQL 8.0.21 中，mysqlx_bind_address接受单个值或逗号分隔值列表。当变量命名多个值列表时，每个值必须指定单个非通配符 IP 地址（IPv4 或 IPv6）或主机名。通配符地址格式（*、0.0.0.0或::）不允许在值列表中使用。
• 截至 MySQL 8.0.22，该值可能包括网络命名空间说明符。

IP 地址可以指定为 IPv4 或 IPv6 地址。对于任何作为主机名的值，X Plugin 将名称解析为 IP 地址并绑定到该地址。如果主机名解析为多个 IP 地址，则 X Plugin 将使用第一个 IPv4 地址（如果有）或否则使用第一个 IPv6 地址。

X Plugin 对不同类型的地址处理如下：

• 如果地址是*，X Plugin 将在所有服务器主机 IPv4 接口上接受 TCP/IP 连接，并且，如果服务器主机支持 IPv6，则在所有 IPv6 接口上接受连接。使用此地址允许 X Plugin 进行 IPv4 和 IPv6 连接。这是默认值。如果变量指定了多个值的列表，则不允许此值。
• 如果地址是0.0.0.0，X Plugin 将在所有服务器主机 IPv4 接口上接受 TCP/IP 连接。如果变量指定了多个值的列表，则不允许此值。
• 如果地址是::，X Plugin 将在所有服务器主机 IPv4 和 IPv6 接口上接受 TCP/IP 连接。如果变量指定了多个值的列表，则不允许此值。
• 如果地址是 IPv4 映射地址，则 X Plugin 接受该地址的 TCP/IP 连接，无论是 IPv4 还是 IPv6 格式。例如，如果 X Plugin 绑定到::ffff:127.0.0.1，则诸如 MySQL Shell 之类的客户端可以使用--host=127.0.0.1或--host=::ffff:127.0.0.1进行连接。
• 如果地址是“常规”IPv4 或 IPv6 地址（例如127.0.0.1或::1），X Plugin 仅接受针对该 IPv4 或 IPv6 地址的 TCP/IP 连接。

这些规则适用于为地址指定网络命名空间：

• 可以为 IP 地址或主机名指定网络命名空间。
• 无法为通配符 IP 地址指定网络命名空间。
• 对于给定的地址，网络命名空间是可选的。如果给定，必须将其指定为地址后紧跟着的/*ns*后缀。
• 没有/*ns*后缀的地址使���主机系统全局命名空间。因此，全局命名空间是默认值。
• 带有/*ns*后缀的地址使用命名为*ns*的命名空间。
• 主机系统必须支持网络命名空间，并且每个命名空间必须事先设置好。命名不存在的命名空间会产生错误。
• 如果变量值指定了多个地址，它可以包括全局命名空间中的地址，命名空间中的地址，或者混合使用。

有关网络命名空间的更多信息，请参见第 7.1.14 节，“网络命名空间支持”。

重要

由于 X 插件不是强制性插件，因此如果指定地址或地址列表中存在错误（就像 MySQL 服务器对bind_address错误所做的那样），它不会阻止服务器启动。对于 X 插件，如果无法解析列表中的某个地址或 X 插件无法绑定到它，该地址将被跳过，将记录错误消息，并且 X 插件尝试绑定到剩余的每个地址。X 插件的Mysqlx_address状态变量仅显示成功绑定的列表中的地址。如果列表中没有任何地址导致成功绑定，或者如果单个指定的地址失败，X 插件将记录错误消息ER_XPLUGIN_FAILED_TO_PREPARE_IO_INTERFACES，指出无法使用 X 协议。mysqlx_bind_address不是动态的，因此要解决任何问题，您必须停止服务器，更正系统变量值，然后重新启动服务器。

mysqlx_compression_algorithms

允许在 X 协议连接上使用的压缩算法。默认情况下，允许使用 Deflate、LZ4 和 zstd 算法。要禁止任何算法，请将mysqlx_compression_algorithms设置为仅包含您允许的算法。算法名称deflate_stream、lz4_message和zstd_stream可以以任何组合指定，顺序和大小写不重要。如果将系统变量设置为空字符串，则不允许任何压缩算法，并且仅使用未压缩的连接。使用特定于算法的系统变量来调整每个允许算法的默认和最大压缩级别。有关更多详细信息，以及有关 X 协议连接压缩与 MySQL 服务器等效设置的关系的信息，请参见第 22.5.5 节，“X 插件连接压缩”。

mysqlx_connect_timeout

X 插件等待新连接客户端接收第一个数据包的秒数。这是 X 插件对应的connect_timeout；有关更多信息，请参阅该变量描述。

mysqlx_deflate_default_compression_level

服务器在 X 协议连接上使用的默认 Deflate 算法压缩级别。将级别指定为整数，从 1（最低压缩力度）到 9（最高力度）。如果客户端在能力协商期间未请求压缩级别，则使用此级别。如果您未指定此系统变量，服务器将使用级别 3 作为默认值。有关更多信息，请参阅第 22.5.5 节，“X 插件连接压缩”。

mysqlx_deflate_max_client_compression_level

服务器允许在 X 协议连接上使用 Deflate 算法的最大压缩级别。该范围与此算法的默认压缩级别相同。如果客户端请求比此更高的压缩级别，服务器将使用您在此处设置的级别。如果您未指定此系统变量，服务器将设置最大压缩级别为 5。

mysqlx_document_id_unique_prefix

设置服务器在将文档添加到集合时生成的文档 ID 的前 4 个字节。通过为每个实例设置此变量的唯一值，您可以确保文档 ID 在实例之间是唯一的。参见理解文档 ID。

mysqlx_enable_hello_notice

控制发送给尝试通过 X 协议连接的经典 MySQL 协议客户端的消息。启用时，不支持 X 协议的客户端尝试连接到服务器 X 协议端口的客户端会收到一个错误，解释他们正在使用错误的协议。

mysqlx_idle_worker_thread_timeout

空闲工作线程终止的秒数。

mysqlx_interactive_timeout

交互客户端的mysqlx_wait_timeout会话变量的默认值。（等待交互客户端超时的秒数。）

mysqlx_lz4_default_compression_level

服务器在 X 协议连接上使用的 LZ4 算法的默认压缩级别。将级别指定为从 0（最低压缩力度）到 16（最高力度）的整数。如果客户端在能力协商期间未请求压缩级别，则使用此级别。如果您没有指定此系统变量，服务器将使用级别 2 作为默认值。有关更多信息，请参见 第 22.5.5 节，“X 插件连接压缩”。

mysqlx_lz4_max_client_compression_level

服务器在 X 协议连接上允许的 LZ4 算法的最大压缩级别。该范围与此算法的默认压缩级别相同。如果客户端请求比此更高的压缩级别，服务器将使用您在此处设置的级别。如果您没有指定此系统变量，服务器将设置最大压缩级别为 8。

mysqlx_max_allowed_packet

X 插件可以接收的网络数据包的最大大小。当连接使用压缩时，此限制也适用，因此在消息被解压缩后，网络数据包必须小于此大小。这是 X 插件等同于max_allowed_packet的变量；有关更多信息，请参阅该变量描述。

mysqlx_max_connections

X 插件可以接受的最大并发客户端连接数。这是 X 插件等同于max_connections的变量；有关更多信息，请参阅该变量描述。

对于此变量的修改，如果新值小于当前连接数，则新限制仅对新连接生效。

mysqlx_min_worker_threads

X 插件用于处理客户端请求的工作线程的最小数量。

mysqlx_port

X 插件用于监听 TCP/IP 连接的网络端口。这是 X 插件等同于port的变量；有关更多信息，请参阅该变量描述。

mysqlx_port_open_timeout

X 插件等待 TCP/IP 端口空闲的秒数。

mysqlx_read_timeout

X 插件等待阻塞读操作完成的秒数。超过此时间后，如果读操作不成功，X 插件将关闭连接并向客户端应用程序返回带有错误代码 ER_IO_READ_ERROR 的警告通知。

mysqlx_socket

X 插件用于连接的 Unix 套接字文件的路径。此设置仅在运行在 Unix 操作系统上的 MySQL 服务器时使用。客户端可以使用此套接字通过 X 插件连接到 MySQL 服务器。

默认的mysqlx_socket路径和文件名基于 MySQL 服务器主套接字文件的默认路径和文件名，文件名后附加了一个 x。主套接字文件的默认路径和文件名为 /tmp/mysql.sock，因此 X 插件套接字文件的默认路径和文件名为 /tmp/mysqlx.sock。

如果您在服务器启动时使用socket系统变量指定了主套接字文件的替代路径和文件名，则这不会影响 X 插件套接字文件的默认值。在这种情况下，如果您希望将两个套接字存储在单个路径上，您还必须设置mysqlx_socket系统变量。例如，在配置文件中：

socket=/home/sockets/mysqld/mysql.sock
mysqlx_socket=/home/sockets/xplugin/xplugin.sock

如果您在编译时使用MYSQL_UNIX_ADDR编译选项更改主套接字文件的默认路径和文件名，则会影响 X 插件套接字文件的默认值，该值是通过在MYSQL_UNIX_ADDR文件名后附加一个x形成的。如果您想在编译时为 X 插件套接字文件设置不同的默认值，请使用MYSQLX_UNIX_ADDR编译选项。

MYSQLX_UNIX_PORT环境变量也可用于在服务器启动时设置 X 插件套接字文件的默认值（请参阅第 6.9 节，“环境变量”）。如果设置了此环境变量，则会覆盖编译的MYSQLX_UNIX_ADDR值，但会被mysqlx_socket值覆盖。

mysqlx_ssl_ca

mysqlx_ssl_ca系统变量类似于ssl_ca，不同之处在于它适用于 X 插件而不是 MySQL 服务器的主连接接口。有关为 X 插件配置加密支持的信息，请参见第 22.5.3 节，“使用 X 插件进行加密连接”。

mysqlx_ssl_capath

mysqlx_ssl_capath系统变量类似于ssl_capath，不同之处在于它适用于 X 插件而不是 MySQL 服务器的主连接接口。有关为 X 插件配置加密支持的信息，请参见第 22.5.3 节，“使用 X 插件进行加密连接”。

mysqlx_ssl_cert

mysqlx_ssl_cert系统变量类似于ssl_cert，不同之处在于它适用于 X Plugin 而不是 MySQL 服务器的主连接接口。有关为 X Plugin 配置加密���持的信息，请参见第 22.5.3 节，“使用 X Plugin 进行加密连接”。

mysqlx_ssl_cipher

mysqlx_ssl_cipher系统变量类似于ssl_cipher，不同之处在于它适用于 X Plugin 而不是 MySQL 服务器的主连接接口。有关为 X Plugin 配置加密支持的信息，请参见第 22.5.3 节，“使用 X Plugin 进行加密连接”。

mysqlx_ssl_crl

mysqlx_ssl_crl系统变量类似于ssl_crl，不同之处在于它适用于 X Plugin 而不是 MySQL 服务器的主连接接口。有关为 X Plugin 配置加密支持的信息，请参见第 22.5.3 节，“使用 X Plugin 进行加密连接”。

mysqlx_ssl_crlpath

mysqlx_ssl_crlpath 系统变量类似于 ssl_crlpath，不同之处在于它适用于 X Plugin 而不是 MySQL 服务器的主连接接口。有关为 X Plugin 配置加密支持的信息，请参见 第 22.5.3 节，“使用 X Plugin 进行加密连接”。

mysqlx_ssl_key

mysqlx_ssl_key 系统变量类似于 ssl_key，不同之处在于它适用于 X Plugin 而不是 MySQL 服务器的主连接接口。有关为 X Plugin 配置加密支持的信息，请参见 第 22.5.3 节，“使用 X Plugin 进行加密连接”。

mysqlx_wait_timeout

X Plugin 等待连接上的活动的秒数。超过此时间后，如果读操作不成功，X Plugin 将关闭连接。如果客户端是非交互式的，则会将会话变量的初始值从全局 mysqlx_wait_timeout 变量复制过来。对于交互式客户端，初始值从会话 mysqlx_interactive_timeout 复制过来。

mysqlx_write_timeout

X 插件等待阻塞写操作完成的秒数。超过此时间，如果写操作不成功，X 插件将关闭连接。

mysqlx_zstd_default_compression_level

服务器在 X 协议连接上使用的 zstd 算法的默认压缩级别。对于 zstd 库版本 1.4.0，您可以设置从 1 到 22 的正值（最高压缩力度），或代表逐渐降低力度的负值。值为 0 转换为值为 1。对于较早版本的 zstd 库，您只能指定值为 3。如果客户端在能力协商期间未请求压缩级别，则使用此级别。如果您未指定此系统变量，服务器将使用级别 3 作为默认值。有关更多信息，请参见 第 22.5.5 节，“X 插件连接压缩”。

mysqlx_zstd_max_client_compression_level

服务器允许在 X 协议连接上使用 zstd 算法的最大压缩级别。范围与此算法的默认压缩级别相同。如果客户端请求比此更高的压缩级别，服务器将使用您在此处设置的级别。如果您未指定此系统变量，服务器将设置最大压缩级别为 11。

原文：dev.mysql.com/doc/refman/8.0/en/x-plugin-status-variables.html

22.5.6.3 X Plugin 状态变量

X Plugin 状态变量具有以下含义。

• Mysqlx_aborted_clients 因输入或输出错误而断开连接的客户端数量。
• Mysqlx_address X Plugin 接受 TCP/IP 连接的网络地址或地址。如果使用mysqlx_bind_address系统变量指定了多个地址，则Mysqlx_address仅显示绑定成功的地址。如果对于mysqlx_bind_address指定的每个网络地址绑定失败，或者使用了skip_networking选项，则Mysqlx_address的值为UNDEFINED。如果 X Plugin 启动尚未完成，则Mysqlx_address的值为空。
• Mysqlx_bytes_received 通过网络接收的总字节数。如果连接使用压缩，此数字包括压缩前测量的压缩消息负载（Mysqlx_bytes_received_compressed_payload），未压缩的消息中未压缩的项目（例如 X 协议标头）以及任何未压缩的消息。
• Mysqlx_bytes_received_compressed_payload 作为压缩消息负载接收的字节数，解压缩前测量。
• Mysqlx_bytes_received_uncompressed_frame 作为压缩消息负载接收的字节数，解压缩后测量。
• Mysqlx_bytes_sent 通过网络发送的总字节数。如果连接使用压缩，此数字包括压缩后测量的压缩消息负载（Mysqlx_bytes_sent_compressed_payload），未压缩的消息中未压缩的项目（例如 X 协议标头）以及任何未压缩的消息。
• Mysqlx_bytes_sent_compressed_payload 作为压缩消息负载发送的字节数，压缩后测量。
• Mysqlx_bytes_sent_uncompressed_frame 作为压缩消息负载发送的字节数，压缩前测量。
• Mysqlx_compression_algorithm （会话范围）此会话的 X 协议连接使用的压缩算法。允许的压缩算法由mysqlx_compression_algorithms系统变量列出。
• Mysqlx_compression_level （会话范围）此会话的 X 协议连接使用的压缩级别。
• Mysqlx_connection_accept_errors 导致接受错误的连接数。
• Mysqlx_connection_errors 导致错误的连接数。
• Mysqlx_connections_accepted 已接受的连接数。
• Mysqlx_connections_closed 已关闭的连接数。
• Mysqlx_connections_rejected 已拒绝的连接数。
• Mysqlx_crud_create_view 收到的创建视图请求数。
• Mysqlx_crud_delete 收到的删除请求数。
• Mysqlx_crud_drop_view 收到的删除视图请求数。
• Mysqlx_crud_find 收到的查找请求数。
• Mysqlx_crud_insert 收到的插入请求数。
• Mysqlx_crud_modify_view 收到的修改视图请求数。
• Mysqlx_crud_update 收到的更新请求数。
• Mysqlx_cursor_close 收到的关闭游标消息数
• Mysqlx_cursor_fetch 收到的获取游标消息数
• Mysqlx_cursor_open 收到的打开游标消息数
• Mysqlx_errors_sent 发送给客户端的错误数。
• Mysqlx_errors_unknown_message_type 收到的未知消息类型数量。
• Mysqlx_expect_close 已关闭的期望块数量。
• Mysqlx_expect_open 已打开的期望块数量。
• Mysqlx_init_error 初始化期间的错误数量。
• Mysqlx_messages_sent 发送给客户端的所有类型消息总数。
• Mysqlx_notice_global_sent 发送给客户端的全局通知数量。
• Mysqlx_notice_other_sent 发送回客户端的其他类型通知数量。
• Mysqlx_notice_warning_sent 发送回客户端的警告通知数量。
• Mysqlx_notified_by_group_replication 发送给客户端的 Group Replication 通知数量。
• Mysqlx_port X 插件正在监听的 TCP 端口。如果网络绑定失败，或者启用了 skip_networking 系统变量，则该值显示为 UNDEFINED。
• Mysqlx_prep_deallocate 收到的准备语句释放消息数量
• Mysqlx_prep_execute 收到的准备语句执行消息数量
• Mysqlx_prep_prepare 收到的准备语句消息数量
• Mysqlx_rows_sent 发送回客户端的行数。
• Mysqlx_sessions 已打开的会话数量。
• Mysqlx_sessions_accepted 已接受的会话尝试次数。
• Mysqlx_sessions_closed 已关闭的会话数量。
• Mysqlx_sessions_fatal_error 已关闭且出现致命错误的会话数量。
• Mysqlx_sessions_killed 已终止的会话数量。
• Mysqlx_sessions_rejected 被拒绝的会话尝试次数。
• Mysqlx_socket X 插件正在监听的 Unix 套接字。
• Mysqlx_ssl_accept_renegotiates 建立连接所需的协商次数。
• Mysqlx_ssl_accepts 接受的 SSL 连接数量。
• Mysqlx_ssl_active SSL 是否激活。
• Mysqlx_ssl_cipher 当前的 SSL 密码（非 SSL 连接为空）。
• Mysqlx_ssl_cipher_list 可能的 SSL 密码列表（非 SSL 连接为空）。
• Mysqlx_ssl_ctx_verify_depth 当前在 ctx 中设置的证书验证深度限制。
• Mysqlx_ssl_ctx_verify_mode 当前在 ctx 中设置的证书验证模式。
• Mysqlx_ssl_finished_accepts 成功的 SSL 连接到服务器的数量。
• Mysqlx_ssl_server_not_after SSL 证书有效的最后一个日期。
• Mysqlx_ssl_server_not_before SSL 证书有效的第一个日期。
• Mysqlx_ssl_verify_depth SSL 连接的证书验证深度。
• Mysqlx_ssl_verify_mode SSL 连接的证书验证模式。
• Mysqlx_ssl_version 用于 SSL 连接的协议名称。
• Mysqlx_stmt_create_collection 收到的创建集合语句的数量。
• Mysqlx_stmt_create_collection_index 收到的创建集合索引语句的数量。
• Mysqlx_stmt_disable_notices 收到的禁用通知语句的数量。
• Mysqlx_stmt_drop_collection 收到的删除集合语句的数量。
• Mysqlx_stmt_drop_collection_index 收到的删除集合索引语句的数量。
• Mysqlx_stmt_enable_notices 收到的启用通知语句数量。
• Mysqlx_stmt_ensure_collection 收到的确保集合语句数量。
• Mysqlx_stmt_execute_mysqlx 收到的带有命名空间设置为 mysqlx 的 StmtExecute 消息数量。
• Mysqlx_stmt_execute_sql 收到的针对 SQL 命名空间的 StmtExecute 请求数量。
• Mysqlx_stmt_execute_xplugin 收到的针对 xplugin 命名空间的 StmtExecute 请求数量。从 MySQL 8.0.19 开始，xplugin 命名空间已被移除，因此不再使用此状态变量。
• Mysqlx_stmt_get_collection_options 收到的获取集合对象语句数量。
• Mysqlx_stmt_kill_client 收到的终止客户端语句数量。
• Mysqlx_stmt_list_clients 收到的列出客户端语句数量。
• Mysqlx_stmt_list_notices 收到的列出通知语句数量。
• Mysqlx_stmt_list_objects 收到的列出对象语句数量。
• Mysqlx_stmt_modify_collection_options 收到的修改集合选项语句数量。
• Mysqlx_stmt_ping 收到的 ping 语句数量。
• Mysqlx_worker_threads 可用的工作线程数量。
• Mysqlx_worker_threads_active 当前正在使用的工作线程数量。