本指南使用 Visual Studio Code 中的 Azure DocumentDB 架构迁移程序扩展将 Apache Cassandra 架构转换为 Azure DocumentDB。 该扩展使用 AI 分析 Cassandra 架构文件，包括 SOLR 搜索配置和查询模式，并生成具有集合定义、分片键建议、索引和已翻译查询的 Azure DocumentDB 数据模型。
该扩展支持两个 AI 提供程序：GitHub Copilot（通过现有Copilot订阅）和 Azure OpenAI（使用自己的资源和 API 密钥）。
先决条件
- Visual Studio Code 1.85.0 或更高版本。
- 以下任一人工智能提供方：
- GitHub Copilot：已安装 VS Code Copilot 扩展的有效 Copilot 订阅。
-
Azure OpenAI：具有已部署模型的 Azure OpenAI 资源，例如
gpt-4o。
- 从源集群导出的 Cassandra 架构定义文件。 有关支持的文件类型，请参阅 “导出架构文件 ”。
导出架构文件
在开始之前，请从 Cassandra 群集导出架构定义和查询模式。 该扩展接受以下文件类型：
| 文件类型 | 说明 |
|---|---|
| CQL 架构文件 | 包含 CREATE TABLE、 CREATE TYPE语句和 CREATE INDEX 语句的文件 |
| SOLR 配置文件 |
schema.xml 文件 |
| DML 文件 | 包含 DML 语句的文件 |
可以导入包含这些文件类型组合的单个文件或整个文件夹。 分析文件夹时，该扩展会将所有文件的结果合并到单个项目中。
Tip
导出尽可能多的查询示例。 AI 使用这些模式来建议对 Azure DocumentDB 的等效 MongoDB 查询语言（MQL）表达式和优化索引。
安装扩展
该扩展目前以预览版的形式提供。 若要运行它，请克隆存储库并在Visual Studio Code中启动扩展主机。
克隆 azure-documentdb-schema-migrator 存储库。
在Visual Studio Code中打开克隆的文件夹。
打开终端并运行以下命令以安装依赖项：
npm install按
F5以打开一个已加载该扩展的新 VS Code 扩展开发主机窗口。
创建迁移项目
项目将架构文件、分析工件和转换输出集中在同一个工作区中。
- 在 VS Code 活动栏中打开 Azure DocumentDB 架构迁移程序面板。
- 选择“创建新项目”。
- 输入项目的名称。
- 选择 AI 提供程序并对其进行配置：
- GitHub Copilot（建议）：从可用Copilot模型列表中选择要使用的模型。
- Azure OpenAI：输入终结点 URL、部署名称和 API 密钥。 该扩展安全地将 API 密钥存储在 VS Code 的机密存储中。
- 选择“ 创建项目”。
导入架构文件
- 在 “资源管理器” 面板中展开您的项目。
- 在“架构文件”部分选择“导入架构文件”。
- 从文件系统中选择导出的架构文件夹。
导入的文件显示在项目的 “架构文件 ”部分下，使用与源选择相同的文件夹层次结构进行组织。
分析架构文件
该扩展将分析每个导入的文件或文件夹，并将实体、索引和查询模式提取为项目。
在 “架构文件 ”部分中，右键单击文件或文件夹，然后选择“ 分析文件 ”或 “分析文件夹”。
该扩展会自动检测每种文件类型，并应用相应的分析：
| 源文件类型 | 已生成构件 |
|---|---|
| CQL 架构文件 | 架构、索引和查询 |
SOLR 配置文件 （schema.xml） |
仅限索引 |
| DML 文件 | 仅限查询 |
| 混合文件夹 | 从 CQL 文件中整合出的架构，以及从所有文件中整合出的索引和查询 |
注释
使用 CREATE TYPE 声明的用户定义类型（UDT）可指定嵌套属性的名称和数据类型。 该扩展将 UDT 内联扩展到引用它们的表中，从而保留原始字段名称。 匿名嵌套类型（例如元组的集合）会被转换为使用诸如 field1、field2 之类的通用字段名称。 UDT 定义会出现在工件中供参考，但不会被直接转换为 Azure DocumentDB 集合。
分析结果会显示在项目的 Artifacts 部分下。 每个项目都标有其类型： 架构、 索引或 查询。
转换为 Azure DocumentDB
添加至少一个项目后，运行转换以生成完整Azure DocumentDB 迁移架构。
- 在 “生成的项目 ”部分中，右键单击节标题。
- 选择“转换为 Azure DocumentDB”。
该扩展运行多阶段 AI 分析：
- 架构建模：将 Cassandra 表映射到 Azure DocumentDB 集合，确定分片键，并推荐相关实体（UDT）的嵌入策略。
- 查询转换：将 CQL 和 SOLR 查询模式转换为 MQL 等效项。
- 索引建议：按照 ESR 规则（相等、排序、范围）生成复合索引和部分索引定义。
- 索引优化：合并冗余索引或重复索引并验证最终索引集。
转换输出在项目的 “转换输出 ”部分下保存为 JSON 文件，包括：
- 包含分片键选择的集合定义。
- 针对所有可查询字段的索引建议。
- MQL 中的已翻译查询模式。
该扩展将此文件用作下一步的输入，这将生成 MongoDB shell 脚本以将架构应用到群集。
重要
在将其应用到生产群集之前，请查看所有 AI 生成的建议。 根据实际查询模式和数据分布要求验证分片键选项。
生成 MongoDB shell 脚本
转换完成后，生成可供运行的脚本，以将架构应用到 Azure DocumentDB 群集。
- 在 “转换输出 ”部分中，右键单击生成的输出文件。
- 选择“ 生成 Mongo Shell 脚本”。
该扩展创建 MongoDB shell 脚本，用于：
- 使用建议的分片键创建集合。
- 创建所有建议的索引。
- 包括一个 JSON 文档架构模板，其中显示了每个集合的预期文档结构。
使用 MongoDB shell 或 Visual Studio Code 的 DocumentDB 扩展，将这些脚本应用于 Azure DocumentDB 群集。