Python快速入门指南：文档存储的MySQL Shell
该快速入门指南提供了说明，以开始与MySQL Shell交互地对文档存储应用程序进行原型制作。该指南包括以下主题：
- MySQL功能，MySQL Shell和
world_x示例架构简介。 - 用于管理集合和文档的操作。
- 管理关系表的操作。
- 适用于表中文档的操作。
要遵循此快速入门指南，您需要安装了X插件的MySQL服务器，默认8.0版本的MySQL服务器以及用作客户端的MySQL Shell。MySQL Shell包含用JavaScript和Python实现的X DevAPI，使您可以使用X协议连接到MySQL服务器实例，并将该服务器用作文档存储。
MySQL Shell
本快速入门指南假定您对MySQL Shell有所了解。以下部分是高级概述，有关更多信息，请参见MySQL Shell文档。MySQL Shell是MySQL Server的统一脚本接口。它支持JavaScript和Python中的脚本编写。JavaScript是默认处理模式。
启动MySQL Shell
安装并启动MySQL服务器后，将MySQL Shell连接到服务器实例。您需要知道计划连接的MySQL服务器实例的地址。为了能够将该实例用作文档存储，服务器实例必须安装了X插件，并且您应该使用X协议连接到服务器。例如，ds1.example.com使用网络字符串连接到默认X协议端口33060上的实例user@ds1.example.com:33060。
如果使用经典MySQL协议（例如，使用默认值port3306而不是）连接到实例mysqlx_port，则不能使用本教程中显示的文档存储功能。例如，db未填充全局对象。要使用文档存储，请始终使用X协议进行连接。
如果MySQL Shell尚未运行，请打开终端窗口并发出：
mysqlsh user@ds1.example.com:33060/world_x
或者，如果MySQL Shell已经在运行，则\connect通过发出以下命令来使用该命令：
\connect user@ds1.example.com:33060/world_x
您需要指定要将MySQL Shell连接到的MySQL服务器实例的地址。例如，在前面的示例中：
user代表您的MySQL帐户的用户名。ds1.example.com是运行MySQL的服务器实例的主机名。将其替换为用作文档存储的MySQL服务器实例的主机名。- 此会话的默认架构为
world_x。有关设置world_x模式的说明，请参见“JavaScript快速入门指南：文档存储的MySQL Shell”。
有关更多信息，请参见“使用类似URI的字符串或键值对连接到服务器”。
MySQL Shell打开后，mysql-js>提示指示此会话的活动语言是JavaScript。要将MySQL Shell切换到Python模式，请使用\py命令。
mysql-js> \py Switching to Python mode... mysql-py>
MySQL Shell支持输入行编辑，如下所示：
- 左箭头键和右箭头键在当前输入行中水平移动。
- 上箭头键和下箭头键在一组先前输入的行中上下移动。
- Backspace删除光标之前的字符，并键入新字符在光标位置输入它们。
- Enter将当前输入行发送到服务器。
获取有关MySQL Shell的帮助
在命令解释器的提示符下键入mysqlsh --help以获得命令行选项列表。
mysqlsh --help
键入\help在MySQL的壳牌提示可用的命令及其说明的列表。
mysql-py> \help
键入，\help后跟命令名称，以获取有关单个MySQL Shell命令的详细帮助。例如，要参见有关该\connect命令的帮助，请发出：
mysql-py> \help \connect
退出MySQL Shell
要退出MySQL Shell，请发出以下命令：
mysql-py> \quit
下载和导入world_x数据库
作为本快速入门指南的一部分，提供了一个示例架构，称为world_x架构。许多示例都使用此模式演示了文档存储功能。启动MySQL服务器，以便您可以加载world_x架构，然后执行以下步骤：
- 下载 world_x-db.zip。
- 将安装档案解压缩到一个临时位置，例如
/tmp/。解压缩存档会得到一个名为的文件world_x.sql。 将
world_x.sql文件导入到您的服务器。您可以：以SQL模式启动MySQL Shell，并通过发出以下命令导入文件：
mysqlsh -u root --sql --file /tmp/world_x-db/world_x.sql Enter password: ****
在运行时将MySQL Shell设置为SQL模式，并通过发出以下命令来获取模式文件：
\sql Switching to SQL mode... Commands end
with ; \source /tmp/world_x-db/world_x.sql
替换
/tmp/为world_x.sql系统上文件的路径。如果有提示，请输入密码。可以使用非root用户帐户，只要该帐户具有创建新架构的权限即可。
world_x模式
该world_x示例模式包含以下JSON收集和关系表：
采集
countryinfo：有关世界各国的信息。
桌子
country：关于世界各国的最少信息。city：有关这些国家/地区中某些城市的信息。countrylanguage：每个国家/地区使用的语言。
文件和托收
当您将MySQL用作文档存储时，集合是架构中可以创建，列出和删除的容器。集合包含您可以添加，查找，更新和删除的JSON文档。
本节中的示例使用架构中的countryinfo集合world_x。有关设置world_x模式的说明，请参见“JavaScript快速入门指南：文档存储的MySQL Shell”。
文件资料
在MySQL中，文档表示为JSON对象。在内部，它们以有效的二进制格式存储，从而可以快速查找和更新。
Python的简单文档格式：
{“ field1”：“ value”，“ field2”：10，“ field 3”：null}
文档数组由一组用逗号分隔并包含在[和]字符中的文档组成。
简单的Python文档数组：
[{“名称”：“阿鲁巴”，“代码：”：“ ABW”}，{“名称”：“安哥拉”，“代码：”：“ AGO”}]
MySQL在JSON文档中支持以下Python值类型：
- 数字（整数和浮点数）
- 弦
- 布尔值（False和True）
- 没有
- 更多JSON值的数组
- 具有更多JSON值的嵌套（或嵌入式）对象
馆藏
集合是具有共同目的并可能共享一个或多个索引的文档的容器。每个集合都有一个唯一的名称，并且存在于单个架构中。
术语架构等效于数据库，这意味着与关系架构相对的一组数据库对象，用于对数据实施结构和约束。模式不会对集合中的文档强制执行一致性。
在此快速入门指南中：
基本对象包括：
对象形式 描述 db db是分配给当前活动模式的全局变量。当您要对模式运行操作（例如，检索集合）时，请使用可用于db变量的方法。db.get_collections() db.get_collections（）返回模式中的集合列表。使用列表获取对集合对象的引用，对其进行迭代等等。 集合范围内的基本操作包括：
操作形式 描述 db.name.add()该的add（）方法插入一个文档或文档放到指定的集合列表。 db.name.find()该发现（）方法返回指定的集合中的部分或全部文件。 db.name.modify()该修改（）方法更新命名的集合中的文档。 db.name.remove()该删除（）方法删除一个文件或从指定收集的文件清单。
相关信息
- 有关一般概述，请参见使用集合。
- CRUD EBNF定义提供了完整的操作列表。
创建，列出和删除集合
在MySQL Shell中，您可以创建新集合，获取架构中现有集合的列表，并从架构中删除现有集合。集合名称区分大小写，每个集合名称必须唯一。
确认架构
要显示分配给架构变量的值，请发出：
mysql-py> db
如果架构值不是Schema:world_x，则db通过发出以下命令来设置变量：
mysql-py> \use world_x
创建收藏
要在现有架构中创建新集合，请使用db对象的createCollection()方法。以下示例创建一个flags在world_x架构中称为的集合。
mysql-py> db.create_collection("flags")
该方法返回一个收集对象。
<Collection：标志>
列出收藏
要显示world_x架构中的所有集合，请使用db对象的get_collections()方法。当前连接的服务器返回的集合显示在括号之间。
mysql-py> db.get_collections()
[
<Collection:countryinfo>,
<Collection:flags>
]
删除收藏
要从架构中删除现有集合，请使用db对象的drop_collection()方法。例如，flags要从当前模式中删除集合，请发出：
mysql-py> db.drop_collection("flags")
该drop_collection()方法在MySQL Shell中也用于从架构中删除关系表。
使用集合
要在架构中使用集合，请使用db全局对象访问当前架构。在此示例中，我们使用world_x先前导入的架构和countryinfo集合。因此，您发出的操作的格式为，其中是执行操作所依据的集合的名称。在以下示例中，对集合执行操作。db.collection_name.operationcollection_namecountryinfo
新增文件
使用该add()方法可以将一个文档或文档列表插入现有集合中。将以下文档插入countryinfo集合中。由于这是多行内容，因此按Enter键两次以插入文档。
mysql-py> db.countryinfo.add(
{
"GNP": .6,
"IndepYear": 1967,
"Name": "Sealand",
"Code:": "SEA",
"demographics": {
"LifeExpectancy": 79,
"Population": 27
},
"geography": {
"Continent": "Europe",
"Region": "British Islands",
"SurfaceArea": 193
},
"government": {
"GovernmentForm": "Monarchy",
"HeadOfState": "Michael Bates"
}
}
)
该方法返回操作状态。您可以通过搜索文档来验证操作。例如：
mysql-py> db.countryinfo.find("Name = 'Sealand'")
{
"GNP": 0.6,
"_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
}
}
请注意，除了添加文档时指定的字段以外，还有一个字段_id。每个文档都需要一个名为的标识符字段_id。_id在同一集合中的所有文档中，该字段的值必须唯一。在MySQL 8.0.11及更高版本中，文档ID由服务器而非客户端生成，因此MySQL Shell不会自动设置_id值。_id如果文档不包含该_id字段，则8.0.11或更高版本的MySQL服务器会设置一个值。8.0或更早版本的MySQL服务器未设置_id在这种情况下，您必须明确指定它的值。如果不这样做，MySQL Shell将返回错误5115 文档缺少必填字段。有关更多信息，请参阅了解文档ID。
查找文档
您可以使用该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)
该方法产生的结果除集合中的所有文档外还包含操作信息。
空集（没有匹配的文档）将返回以下信息：
空置（0.00秒）
筛选搜寻
您可以在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集合措施国民生产总值中的万台。
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()方法将值与搜索条件分开。例如，不是指定硬编码的国家/地区名称为条件，而是替换由冒号组成的命名占位符，后跟以字母开头的名称，例如country。然后使用如下方法：bind(placeholder,value)
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和名称字段。
使用该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()方法来更改起始文档。例如，要忽略第一个文档并返回与条件匹配的后八个文档，请将skip()方法的值传递给 1。
mysql-py> db.countryinfo.find().sort(["IndepYear desc"]).limit(8).skip(1) ... [output removed] 8 documents in set (0.00 sec)
修改文档
您可以使用该modify()方法来更新集合中的一个或多个文档。X DevAPI提供了其他方法，可以与以下modify()方法一起使用：
- 设置和取消设置文档中的字段。
- 追加，插入和删除数组。
- 绑定，限制和排序要修改的文档。
设置和取消设置文档字段
该modify()方法通过过滤集合以仅包括要修改的文档，然后将您指定的操作应用于这些文档来工作。
在下面的示例中，该modify()方法使用搜索条件来标识要更改的文档，然后该set()方法替换嵌套的人口统计对象内的两个值。
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]")
删除文档
您可以使用该remove()方法从架构中的集合中删除部分或全部文档。X DevAPI提供了其他方法，可与该remove()方法一起使用，以对要删除的文档进行过滤和排序。
使用条件删除文件
下面的示例将搜索条件传递给该remove()方法。符合条件的所有文档将从countryinfo集合中删除。在此示例中，一个文档符合条件。
mysql-py> db.countryinfo.remove("Code = 'SEA'")
删除第一个文档
要删除countryinfo集合中的第一个文档，请使用limit()值为1 的方法。
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集合。
创建和删除索引
索引用于快速查找具有特定字段值的文档。没有索引，MySQL必须从第一个文档开始，然后通读整个集合以查找相关字段。馆藏越大，花费越多。如果集合很大，并且对特定字段的查询很普遍，则可以考虑在文档中的特定字段上创建索引。
例如，以下查询在“人口”字段上使用索引时效果更好：
mysql-py> db.countryinfo.find("demographics.Population < 100")
...[output removed]
8 documents in set (0.00 sec)
该create_index()方法创建一个索引，您可以使用指定使用哪些字段的JSON文档进行定义。本节是索引的高级概述。有关更多信息，请参见索引集合。
添加非唯一索引
要创建非唯一索引，请将索引名称和索引信息传递给create_index()方法。索引名称重复。
以下示例指定了一个名为的索引popul，Population该demographics索引是根据对象的字段定义的，索引为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")