外部目录

创建外部目录以从 Oracle AI Data Platform 之外的位置获取数据。

LiveLabs Sprint

外部目录将 AI Data Platform 连接到外部数据源（例如 Oracle Autonomous AI Lakehouse 、Oracle AI Database 和 Oracle Autonomous AI Transaction Processing ）以及第三方存储（例如 Snowflake、Azure SQL 和 MySQL）。AI Data Platform 可搜索这些源的元数据并将其同步到主目录中，使用户能够浏览和查询远程方案和表，而无需复制基础数据。

外部目录使用在外部目录创建期间提供的身份证明来查询外部源。有关数据源的更多信息，请参阅内部源。

例如，如果为 Autonomous AI Lakehouse 实例创建外部目录，其中使用的 Autonomous AI Lakehouse 用户凭证可以访问 schema1 ，但不能访问 schema2 ，则外部目录中仅显示 schema1 。具有外部目录权限的用户只能查询 Autonomous AI Lakehouse 用户有权访问的模式。

注意：

AI Data Platform 不支持从可插入数据库 (Pluggable Databases，PDB) 之间共享的方案和表或从 Oracle 维护的方案和表中收集数据。

Autonomous AI Lakehouse 和 Autonomous AI Transaction Processing 所需的权限

在 AI 数据平台中创建外部目录时，用于连接的用户凭据必须至少具有以下权限：

• 用于连接到数据库的 CREATE SESSION
• 通过最小权限授予或专用读取角色对所需对象（表/视图/外部表）的 SELECT 访问权限
• 阅读，写入 DIRECTORY DATA_PUMP_DIR

如果要在外部目录中插入数据或创建新表，请确保用户是 DWROLE 的一部分。有关详细信息，请参阅 Oracle Autonomous AI Transaction Processing 文档、 Manage User Privileges on Autonomous AI Database - Connecting with a Client Tool 。

限制

外部目录不支持 UPDATE 操作。使用外部目录表进行搜索和查询访问。

不支持 DDL，即使用于创建外部目录的身份证明具有执行 DDL 语句的权限也是如此。

表名大小写会影响在 Oracle Autonomous AI Lakehouse 中创建表的方式：

• 如果以大写形式提供表名，则会使用大写字母创建表，并遵循 Autonomous AI Lakehouse 中的默认不区分大小写行为。
• 如果您以小写形式提供表名，则会在 Autonomous AI Lakehouse 中创建该表时区分大小写。通过 Autonomous AI Lakehouse 创建的表的列名始终区分大小写。
• 在外部目录摄取和刷新期间，源列注释限制为 256 个 UTF-8 字节。限制以字节（而不是字符）为单位进行测量，因此包含多字节字符的注释在包含 256 个字符或更少时可以超过限制。超出限制可能会导致元数据摄取或刷新失败。将源列注释减少到 256 个 UTF-8 字节或更少，然后重试。

创建外部目录

您可以将目录从 Oracle AI Data Platform 实例连接到外部源。

1. 单击左侧导航窗格中的创建，然后选择目录。您还可以导航到主目录，然后单击 在主目录中创建目录。
2. 填写名称和说明字段。
3. 从 Catalog Type（目录类型）下拉列表中，选择 External Catalog（外部目录）。
4. 选择外部来源类型。

   数据源	字段
   Oracle Autonomous AI Lakehouse	提供 wallet 文件或实例配置。
   Oracle Autonomous AI Transaction Processing	提供 wallet 文件或实例配置。
   Oracle AI Database	提供 wallet 文件或实例配置。
   Oracle Exadata Database Service	提供主机、端口、服务名称/SID。
   雪花	提供 Snowflake 帐户名称、数据库名称和仓库。选择验证方法作为密钥对，然后提供私钥文件和私钥密码短语。
   Azure SQL	提供主机、端口和数据库名称（可选）。
   MySQL	提供主机和端口。
   Google 大查询	提供主机、端口、项目 ID、服务账户电子邮件、私钥。
   DB2	提供主机、端口和数据库名称。
   Kafka（即将推出）	提供引导服务器。使用逗号分隔多个服务器。

5. 填写用户名和密码（如果适用）。
6. SSL 默认情况下处于启用状态。清除该框可禁用 SSL。
7. 单击创建。
   正在从外部源提取数据的外部目录显示旋转圆图标。
   

   

   
   

   您还可以从作业运行监视进度。

为专用网络创建外部目录

您可以创建访问专用网络中数据源的外部目录。

1. 单击左侧导航窗格中的创建，然后选择目录。您还可以导航到主目录，然后单击 在主目录中创建目录。
2. 填写名称和说明字段。
3. 从 Catalog Type（目录类型）下拉列表中，选择 External Catalog（外部目录）。
4. 选择外部源类型：

   数据源	字段
   Oracle Autonomous AI Lakehouse	提供 wallet 文件或实例配置。
   Oracle Autonomous AI Transaction Processing	提供 wallet 文件或实例配置。
   Oracle AI Database	提供 wallet 文件或实例配置。
   Oracle Exadata Database Service	提供主机、端口、服务名称/SID。
   Kafka（即将推出）	提供引导服务器。使用逗号分隔多个服务器。

5. 填写用户名和密码（如果适用）。
6. 默认情况下，SSL 已启用。清除该框可禁用 SSL。
7. 选择启用专用网络。
8. 选择具有所需专用网络配置的工作区。
   有关设置为专用网络配置的工作区的信息，请参见 Create a Workspace with Private Network Access Enabled 。
9. 单击创建。
   正在从外部源提取数据的外部目录显示旋转圆图标。
   

   

   
   

   您还可以从作业运行监视进度。

如何将 Oracle Autonomous AI Database on Exadata Cloud@Customer 连接到 Oracle AI Data Platform

您可以在 Oracle Autonomous AI Database on Exadata Cloud@Customer 上为 Oracle Autonomous AI Transaction Processing 、Oracle Autonomous AI Lakehouse 或 Oracle Autonomous AI Database on Exadata Cloud@Customer 数据库创建外部目录。仅通过专用网络访问数据库时，配置具有专用网络访问权限的 AI 数据平台工作区和数据库 SCAN 详细信息。

连接使用带有客户端身份证明 wallet 的 TLS。

要求

开始之前，确保：

• 数据库已预配且可用。
• 您已下载数据库客户端身份证明 wallet。
• 您知道数据库 SCAN 全限定域名和 TLS 监听程序端口。
• 可以从 AI 数据平台工作区使用的专用网络解析 SCAN 名称。
• 网络路由和安全规则允许从工作区网络到数据库监听程序端口的通信。
• 您有权检查所需的 VCN、子网和网络安全组。
• 数据库用户对要通过外部目录公开的方案和对象具有 CREATE SESSION 和 SELECT 权限。
• 数据库用户具有预期的读取或写入操作所需的任何其他权限。

只有指定数据库用户可访问的方案和对象才会搜索并添加到外部目录中。

创建具有专用连接的工作区

按照 Create a Workspace with Private Network Access Enabled 中的步骤操作，并进行以下更改：

• 提供 VCN 和子网，以提供与 Oracle Exadata Cloud@Customer 环境的连接。
• 在 Advanced network options（高级网络选项）下，选择 My data sources require access through a SCAN proxy（我的数据源需要通过 SCAN 代理访问）。
• 输入数据库 SCAN 全限定域名。
• 输入数据库 TLS 监听程序端口。

创建外部目录

按照 Create an External Catalog for Private Networks 中提供的步骤操作，选择如下：

• 对于外部源类型，选择 Oracle Autonomous AI Transaction Processing 。
• 对于连接方法，选择 Wallet 。
• 上载从数据库下载的客户端身份证明 wallet。
• 从 wallet 选择所需的数据库服务。
• 如果需要，请提供 wallet 密码。
• 选择上面配置了访问数据库网络和 SCAN 地址的工作区。
• 测试连接以确认已正确配置所有内容。

验证连接

目录创建和元数据搜索完成后：

• 确认外部目录中出现预期方案和表。
• 在专用工作区中启动或选择计算集群。
• 使用三部分名称查询搜索到的表：

SELECT *
FROM <catalog_name>.<schema_name>.<table_name>;

刷新外部数据目录

您可以在 Oracle AI Data Platform 中刷新外部目录，以将其内容与外部源同步。

1. 在左侧导航窗格中，单击 主目录。
2. 在主目录树中，选择要刷新的外部目录。
3. 单击 刷新。
   外部目录显示在主目录下，其中包含旋转圆形图标，同时从外部源提取数据并更新元数据。
   

   

   
   

   您还可以从作业运行监视进度，请参阅监视作业。

使用 SQL 刷新外部目录

可以使用 SQL 语法刷新外部目录的元数据以及外部目录的方案和表，以将内容与外部源同步。

要刷新外部目录，请在记事本中使用以下 SQL 命令：

REFRESH EXTERNAL CATALOG <<catalog_name>>

要刷新外部目录中的方案，请使用：

REFRESH SCHEMA IN EXTERNAL CATALOG <<catalog_name.schema_name>>

要刷新外部目录中方案中的表，请使用：

REFRESH TABLE IN EXTERNAL CATALOG <<catalog_name.schema_name.table_name>>

有关详细信息，请参阅 SQL 语法。

重命名外部目录

如果外部目录的内容或用途已更改，则可以重命名外部目录。

1. 在左侧导航窗格中，单击 主目录。
2. 在“目录”选项卡中，找到目录，然后单击 操作，然后单击重命名。
   
   

   

   
   
3. 编辑目录名称并按 Enter 键。

编辑外部目录说明

如果外部目录的内容或用途已更改，则可以修改其说明。

1. 在左侧导航窗格中，单击 主目录。
2. 在“目录”选项卡中，找到您的目录，然后单击 操作，然后单击编辑说明。
   
   

   

   
   
3. 编辑目录说明，然后单击保存。

更改外部目录的密码

您可以更新外部目录的必需密码，以便它可以继续访问源。

1. 在左侧导航窗格中，单击 主目录。
2. 在“目录”选项卡中，找到目录，然后单击 操作，然后单击更改口令。
3. 输入外部目录的新密码，然后单击保存。

删除外部目录

可以删除不再需要的外部目录。

删除外部目录只会删除本地存储的元数据。外部数据源中的数据不受影响。

1. 在左侧导航窗格中，单击 主目录。
2. 在“目录”选项卡中，找到目录，然后单击 操作，然后单击删除。
   
   

   

   
   
3. 选择确认删除目录。
4. 单击删除。

从外部目录内的表中删除数据

当将目录和表配置为支持下推 SQL DELETE 时，可以使用 Spark 写入路径从外部目录表中删除行。

使用目录 ID 删除表数据：Python 示例

from pyspark.sql.types import StructType

df = spark.createDataFrame([], StructType([]))


    df.write
      .format("aidataplatform")
      .option("catalog.id", "<catalog>")
      .option("pushdown.sql", "DELETE FROM <schema>.<target_table> WHERE ID = 2")
      .save()

使用目录 ID 删除表数据：Scala 示例

val df = spark.emptyDataFrame

df.write
  .format("aidataplatform")
  .option("catalog.id", "<catalog>")
  .option("pushdown.sql", "DELETE FROM <schema>.<target_table> WHERE ID = 2")
  .save()

用于删除表数据的摄取样式示例：Python 示例

from pyspark.sql.types import StructType
df = spark.createDataFrame([], StructType([]))

df.write
  .format("aidataplatform")
  .option("data.asset.type", "ORACLE_ALH")
  .option("tns.alias", alhTns)
  .option("user.name", userName)
  .option("wallet.content", alhWalletContent)
  .option("password", alhPassword)
  .option("pushdown.sql", "DELETE FROM ADMIN.PUSHDOWN_FEATURE WHERE ID = 2")
  .save()

用于删除表数据的摄取样式示例：Scala 示例

val df = spark.emptyDataFrame

df.write
  .format("aidataplatform")
  .option("data.asset.type", "ORACLE_ALH")
  .option("tns.alias", alhTns)
  .option("user.name", userName)
  .option("wallet.content", alhWalletContent)
  .option("password", alhPassword)
  .option("pushdown.sql", "DELETE FROM ADMIN.PUSHDOWN_FEATURE WHERE ID = 2")
  .save()