/ /

Atlas Data Federation 模式命令

在 Atlas Data Federation 中，您通过 sqlGenerateSchema、sqlGetSchema 和 sqlSetSchema 三个命令管理 SQL 用户界面使用的模式。您从 mongosh 对联合数据库实例运行这些命令，或在 Atlas 用户界面中执行相同的操作。本页面记录了这些命令及其用户界面等效项。

Atlas Data Federation 从集合中抽取示例文档以生成初始模式。有关模式管理和其他支持的部署类型的背景信息，请参阅模式管理。

注意

、和sqlGenerateSchemasqlGetSchema sqlSetSchema命令及其Atlas用户界面等效命令仅应用于Atlas Data Federation部署类型。它们不适应用使用MongoDB SQL Schema Builder CLI的自管理Enterprise Advanced (EA) 部署，也不适用于针对不使用Atlas Data Federation 的标准Atlas 集群的查询。

sqlGenerateSchema

sqlGenerateSchema 命令为指定的集合或视图生成 SQL Interface 模式。Atlas Data Federation 从每个命名空间中抽取文档以获取模式。

语法

当您使用 sampleNamespaces 参数时，必须针对 admin 数据库运行该命令。

use admin
db.runCommand({
   sqlGenerateSchema: 1,
   sampleNamespaces: [<namespace>],
   sampleSize: <int>,
   setSchemas: true|false
})

参数

Parameter	类型	说明	必要性
`sampleNamespaces`	字符串数组	`.`指定以逗号分隔的命名空间列表，为其生成模式。命名空间包括数据库名称、点() 分隔符和集合或视图名称（即`<database>.<collection>\|<view>` ）。要为数据库中的所有集合生成模式，请指定`` 而不是集合或视图名称（即`<database>.` ）。如果省略， Atlas Data Federation将为当前数据库中的所有集合和视图生成模式。	Optional
`sampleSize`	整型	指定创建模式时用作样本的文档数量。如果省略，则默认值为 `1000`。	Optional
`setSchemas`	布尔	指定是否存储为集合或视图生成的模式。值可以是以下之一： `true` 来存储模式。如果该集合或视图的模式已存在，Atlas Data Federation 将覆盖现有模式。 `false` 不存储架构。如果省略，则默认值为 `false`。	Optional

输出

如果成功，该命令将返回以下输出：

{
  "ok" : 1,
  "schemas" : [
    {
      "databaseName" : "<database-name>",
      "namespaces" : [
        {
          "name" : "<collection-name>",
          "schema" : {
            "version" : NumberLong(1),
            "jsonSchema" : { ... }
          }
        }
      ]
    },
    ...
  ]
}

schemas 对象包含以下字段。

Parameter	类型	说明
`databaseName`	字符串	数据库名称。
`namespaces`	对象数组	每个集合或视图的名称和生成模式。
`namespaces.name`	字符串	集合或视图的名称。
`namespaces[n].schema`	文档	集合或视图的模式。
`namespaces[n].schema.version`	整型	模式的格式版本。值始终为 1。
`namespaces[n].schema.jsonSchema`	文档	集合或视图的 JSON 模式。JSON 模式可包含以下字段： `bsonType` `properties` `items` `additionalProperties` `required` 要了解有关这些字段的更多信息，请参阅 JSON schema 关键字。

如果使用 setSchemas 选项为集合或视图设置模式，则可以通过运行 sqlGetSchema 命令来验证命令是否成功。sqlGetSchema 命令 metadata.description 字段包含以下值：

"set using sqlGenerateSchema with setSchemas = true"

Errors

如果该命令失败，该命令将返回以下错误：

"failedNamespaces": [
  {
    "namespace" : "<db.ns>",
    "error" : "no documents found in sample namespace"
  }
]

如果指定的命名空间在存储配置中不存在或为空，Atlas Data Federation 将返回此错误。如果无法为给定命名空间设置模式，Atlas Data Federation 也会返回此错误。

sqlGetSchema

sqlGetSchema 命令可检索为指定集合或视图存储的模式。

语法

db.getSiblingDB("<dbName>").runCommand({
   sqlGetSchema: "<collection-name>|<view-name>"
})

参数

Parameter	类型	说明	必要性
`<collection-name>`	字符串	要检索其模式的集合的名称。提供集合名称或视图名称。	可选的
`<view-name>`	字符串	要检索其模式的视图的名称。提供视图名称或集合名称。	可选的

输出

如果集合或视图没有模式，该命令将返回以下输出：

{ "ok" : 1, "metadata" : { }, "schema" : { } }

如果集合或视图有模式，该命令会返回类似以下内容的输出：

{
  "ok": 1,
  "metadata": {
    "description": "<description>"
  },
  "schema": {
    "version": NumberLong(1),
    "jsonSchema": { ... }
  }
}

metadata.description 字段描述了如何为集合设置模式。值可以是以下任意选项：

generated automatically by Atlas Data Federation: 表示模式是由 Atlas Data Federation 自动生成的。

set using sqlGenerateSchema with setSchemas = true: 表示该模式由 sqlGenerateSchema 命令设立，因为setSchema 选项设立为true 。

set using sqlSetSchema: 表示模式是使用 sqlSetSchema 命令设立的。

schema 文档包含以下字段：

Parameter	类型	说明
`schema.version`	整型	模式的格式版本。值始终为 1。
`schema.jsonSchema`	文档	集合或视图的 JSON 模式。JSON 模式可包含以下字段： `bsonType` `properties` `items` 要了解有关这些字段的更多信息，请参阅 JSON schema 关键字。

sqlSetSchema

sqlSetSchema 命令会设置或删除集合或视图的模式。该命令直接应用您提供的模式。该命令不会根据集合中的数据验证所提供的模式。

语法

db.getSiblingDB("<dbName>").runCommand({
   sqlSetSchema: "<collection-name>|<view-name>",
   schema: {
      "version": 1,
      "jsonSchema": <jsonSchema>
   }
})

db.getSiblingDB("<dbName>").runCommand({
   sqlSetSchema: "<collection-name>|<view-name>",
   schema: {}
})

参数

Parameter	类型	说明	必要性
`<collection-name>`	字符串	要设置模式的集合名称。提供集合名称或视图名称。	可选的
`<view-name>`	字符串	要设置模式的视图名称。提供视图名称或集合名称。	可选的
`schema`	文档	模式的格式版本以及以下任一项：集合或视图的JSON schema 空文档，用于删除集合或视图的模式您可以在`items`字段中提供单个文档或文档数组。检索模式时， `items`会显示您用于设置模式的表单。	必需

输出

如果成功，该命令将返回以下输出：

{ "ok" : 1 }

您可以通过运行sqlGetSchema命令来验证该命令是否成功。响应中的metadata.description字段包含以下值：

"set using sqlSetSchema"

示例

考虑名为 sampleDB 的数据库中名为 egData 的集合，其中包含以下文档：

{"a": {"b": {"c": [1, 2, 3]}}, "s": 1}
{"a": {"b": {"c": [4, 5, 6]}}, "s": 2}
{"a": {"b": [7, 8, 9]}, "s": 3}
{"a": {"b": {"c": []}}, "s": 4}
{"a": {"b": {"c": "hello"}}, "s": 5}
{"a": {"b": {"c": {"d": 1}}}, "s": 6}
{"a": {"b": {"c": null}}}
{"s": 7}

以下示例使用 Atlas Data Federation 模式命令为上述集合生成、检索、设置和删除模式。

生成模式

以下命令可为存储配置中名为 sampleDB.egData 的集合生成模式。该命令使用从集合中随机选择的两个文档来创建模式，因为 sampleSize 为 2。该命令不会为集合设置模式，因为未指定 setSchemas 选项且默认值为 false。

use admin
db.runCommand({
   sqlGenerateSchema: 1,
   sampleNamespaces: ["sampleDB.egData"],
   sampleSize: 2
})

上一个命令会返回以下输出。有关输出中字段的更多信息，请参阅输出。

{
  "ok" : 1,
  "schemas" : [
    {
      "databaseName" : "sampleDB",
      "namespaces" : [
        {
          "name" : "egData",
          "schema" : {
            "version" : NumberLong(1),
            "jsonSchema" : {
              "bsonType" : [ "object" ],
              "properties" : {
                "a" : {
                  "bsonType" : [ "object" ],
                  "properties" : {
                    "b" : {
                      "bsonType" : [ "object" ],
                      "properties" : {
                        "c" : {
                          "bsonType" : [ "array" ],
                          "items" : {
                            "bsonType" : [ "int" ]
                          }
                        }
                      }
                    }
                  }
                },
                "s" : {
                  "bsonType" : [ "int" ]
                }
              }
            }
          }
        }
      ]
    }
  ]
}

生成和设置模式

以下命令可为存储配置中名为 sampleDB.egData 的集合生成模式。该命令可使用集合中最多 1000 个文档来创建模式，原因是没有指定 sampleSize 选项而其默认值为 1000。该命令将生成的模式设置为用于集合的模式，原因是 setSchemas 为 true。

use admin
db.runCommand({
   sqlGenerateSchema: 1,
   sampleNamespaces: ["sampleDB.egData"],
   setSchemas: true
})

Retrieve a Schema

以下命令可检索为 egData 集合存储的模式：

db.getSiblingDB("sampleDB").runCommand({
   sqlGetSchema: "egData"
})

上一个命令会返回以下输出。有关输出中字段的更多信息，请参阅输出。

{
  "ok" : 1,
  "metadata" : {
    "description" : "set using sqlGenerateSchema with setSchemas = true"
  },
  "schema" : {
    "version" : NumberLong(1),
    "jsonSchema" : {
      "bsonType" : [ "object" ],
      "properties" : {
        "a" : {
          "bsonType" : [ "object" ],
          "properties" : {
            "b" : {
              "bsonType" : [ "object", "array" ],
              "properties" : {
                "c" : {
                  "bsonType" : [ "array", "string", "object", "null" ],
                  "properties" : {
                    "d" : {
                      "bsonType" : [ "int" ]
                    }
                  },
                  "items" : {
                    "bsonType" : [ "int" ]
                  }
                }
              },
              "items" : {
                "bsonType" : [ "int" ]
              }
            }
          }
        },
        "s" : {
          "bsonType" : [ "int", "object" ]
        }
      }
    }
  }
}

设置模式

以下 sqlSetSchema 命令为 egData 集合设置模式：

db.getSiblingDB("sampleDB").runCommand({
   sqlSetSchema : "egData",
   "schema" : {
      "version" : NumberLong(1),
      "jsonSchema" : {
         "bsonType" : [ "object" ],
         "properties" : {
            "a" : {
               "bsonType" : [ "object" ],
               "properties" : {
                  "b" : {
                     "bsonType" : [ "object", "array" ],
                     "properties" : {
                        "c" : {
                           "bsonType" : [ "array", "string", "object", "null" ],
                           "properties" : {
                              "d" : {
                                 "bsonType" : [ "int" ]
                              }
                           },
                           "items" : {
                              "bsonType" : [ "int" ]
                           }
                        }
                     },
                     "items" : {
                        "bsonType" : [ "int" ]
                     }
                  }
               }
            },
            "s" : {
               "bsonType" : [ "int", "object" ]
            }
         }
      }
   }
})

上一命令会返回以下输出：

{ "ok" : 1 }

删除模式

以下 sqlSetSchema 命令通过传递空 schema 文档来删除 egData 集合的模式：

db.getSiblingDB("sampleDB").runCommand({
   sqlSetSchema: "egData",
   schema: {}
})

上一命令会返回以下输出：

{ "ok" : 1 }

在 Atlas 用户界面中管理模式

您可以在 Atlas 用户界面的 Manage SQL Schemas 页面中执行相同的模式操作。用户界面会对文档进行示例以生成模式，这与 sqlGenerateSchema 命令相同。

创建模式

创建快速启动连接时，Atlas Data Federation 会自动生成模式。要手动创建模式，请使用以下步骤。

在 Atlas 中，转到项目的联合数据库实例。

如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。
如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。
在侧边栏中，单击 Services 标题下的 Data Federation。

显示Data Federation 页面。

导航到“管理 SQL 模式”页面。

在Federated Database Instances部分中，单击模式，然后从下拉列表中选择Manage SQL Schemas 。

创建模式。

在具有空模式的集合上：

单击。
单击Generate new schema from sample ，或提供您自己的JSON。
单击 Save（连接）。

重新生成模式

每当根本的数据的形状发生变化时（例如当您添加字段或更改字段类型时），请重新生成模式，以便您的SQL查询反映当前数据。要自动使模式保持最新状态，请参阅计划模式更新。

在 Atlas 中，转到项目的联合数据库实例。

如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。
如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。
在侧边栏中，单击 Services 标题下的 Data Federation。

显示Data Federation 页面。

导航到“管理 SQL 模式”页面。

在Federated Database Instances部分中，单击模式，然后从下拉列表中选择Manage SQL Schemas 。

重新生成模式。

在已有模式的集合上：

单击。
单击 Generate new schema from sample（连接）。
单击 Save（连接）。

查看模式

在 Atlas 中，转到项目的联合数据库实例。

如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。
如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。
在侧边栏中，单击 Services 标题下的 Data Federation。

显示Data Federation 页面。

导航到“管理 SQL 模式”页面。

在Federated Database Instances部分中，单击模式，然后从下拉列表中选择Manage SQL Schemas 。

在此页面上，您可以查看所有现有的模式。要查看 JSON 格式的特定模式，请单击。

编辑模式

在 Atlas 中，转到项目的联合数据库实例。

如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。
如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。
在侧边栏中，单击 Services 标题下的 Data Federation。

显示Data Federation 页面。

导航到“管理 SQL 模式”页面。

在Federated Database Instances部分中，单击模式，然后从下拉列表中选择Manage SQL Schemas 。

编辑模式。

在模式旁边，单击。
编辑JSON。
单击 Save（连接）。

删除模式

在 Atlas 中，转到项目的联合数据库实例。

如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。
如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。
在侧边栏中，单击 Services 标题下的 Data Federation。

显示Data Federation 页面。

导航到“管理 SQL 模式”页面。

在Federated Database Instances部分中，单击模式，然后从下拉列表中选择Manage SQL Schemas 。

在此页面上，您可以查看所有现有的模式。

删除模式。

对于要删除的模式，单击。
单击 Clear...（连接）。
单击 Clear schema 进行确认。

删除所有模式

在 Atlas 中，转到项目的联合数据库实例。

如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。
如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。
在侧边栏中，单击 Services 标题下的 Data Federation。

显示Data Federation 页面。

导航到“管理 SQL 模式”页面。

在Federated Database Instances部分中，单击模式，然后从下拉列表中选择Manage SQL Schemas 。

在此页面上，您可以查看所有现有的模式。

删除所有模式。

单击右上角的图标。
单击 Clear all schemas（连接）。
再次单击 Clear all schemas 进行确认。

安排模式更新

定时模式更新可帮助您随时保持模式准确性。定时模式更新会对每个命名空间进行采样，并将新模式与现有模式合并。示例：定时模式更新允许 Atlas Data Federation 自动检测添加到集合的新字段。

在 Atlas 中，转到项目的联合数据库实例。

如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。
如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。
在侧边栏中，单击 Services 标题下的 Data Federation。

显示Data Federation 页面。

导航到“管理 SQL 模式”页面。

在Federated Database Instances部分中，单击模式，然后从下拉列表中选择Manage SQL Schemas 。

启用计划模式更新。

单击 Configure schema update schedule（连接）。
选择频率。
单击 Save（连接）。

了解详情

后退

MongoDB SQL 模式构建器 CLI

来年

SQL 教程