/ /

Atlas Data Federation 模式命令

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

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

注意

The sqlGenerateSchema, sqlGetSchema, and sqlSetSchema commands and their Atlas UI equivalents apply only to the Atlas Data Federation deployment type. They don't apply to self-managed Enterprise Advanced (EA) deployments, which use the MongoDB SQL Schema Builder CLI, or to queries against a standard Atlas cluster that doesn't use Atlas Data Federation.

sqlGenerateSchema

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

语法

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

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

参数

Parameter	类型	说明	必要性
`sampleNamespaces`	字符串数组	Specifies the comma-separated list of namespaces for which to generate schemas. A namespace includes the database name, a dot (`.`) separator, and the collection or view name (that is, `<database>.<collection>\|<view>`). To generate schemas for all the collections in a database, specify `` instead of the collection or view name (that is, `<database>.`). If omitted, Atlas Data Federation generates schemas for all collections and views in the current database.	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 schema of the collection or view. The JSON schema can contain the following fields: `bsonType` `properties` `items` `additionalProperties` `required` To learn more about these fields, see JSON Schema Keywords.

如果使用 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: Indicates that the schema was set by the sqlGenerateSchema command because the setSchema option was set to true.

set using sqlSetSchema: Indicates that the schema was set using the sqlSetSchema command.

schema 文档包含以下字段：

Parameter	类型	说明
`schema.version`	整型	模式的格式版本。值始终为 1。
`schema.jsonSchema`	文档	JSON schema of the collection or view. The JSON schema can contain the following fields: `bsonType` `properties` `items` To learn more about these fields, see JSON Schema Keywords.

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
})

The previous command returns the following output. To learn more about the fields in the output, see Output.

{
  "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"
})

The previous command returns the following output. To learn more about the fields in the output, see Output.

{
  "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（连接）。

重新生成模式

Regenerate a schema any time the shape of your underlying data changes, such as when you add fields or change field types, so that your SQL queries reflect the current data. To keep schemas current automatically instead, see Schedule Schema Updates.

在 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 教程