数据目录（catalog）

自 3.00.0 版本起，DolphinDB 支持 Catalog（数据目录）功能。

基本概念

三级层次

  • Catalog（目录）：
    • Catalog 是数据库中的最高层次，它是一个命名空间，用于组织和管理数据库对象。
    • Catalog 通常用于对不同的应用程序或不同的业务领域进行逻辑上的划分。

  • Schema（模式）：

    • Schema 是数据库中的逻辑容器，用于组织和管理相关的数据库对象。
    • Schema 用于对数据库对象进行逻辑上的分组和隔离，以便于权限管理和对象的组织。
  • Table（表）：
    • 表是数据库中最基本的数据存储结构，用于存储数据。
    • 表由一组有序的列（Column）和行（Row）组成。
    • 每个表都有一个唯一的名称，并且定义了每列的数据类型、约束条件和其他属性。

一个数据库可以包含多个 Catalog；一个 Catalog 可以包含多个 Schema；每个 Schema 可以包含多个表。

映射关系

在 DolphinDB 中，Catalog 的三级概念与原有数据库和表的概念映射关系如下表：

三级层次 映射概念 说明
Catalog superDatabase 用于包含多个 Schema(database)，相当于 superDatabase。
Schema database Schema 对应之前的 database。在 catalog 的相关操作中，使用单独的 Schema Name 而不是之前的 dbUrl 进行相关操作，以此将 Database Name 和 dbUrl 解耦。
Table table Table 对应现在的 DFS Table。

相关操作

catalog 和 schema 的命名限制

catalog 和 schema 的命名当前只支持由大小写字母开头，且只能由大小写字母、数字、下划线(_)组成。如：catalog, catalog1, catalog_example, catalog1_example。

在语句和函数的使用中，对 catalog 和 schema 的名字大小写不敏感。

SQL 写法

提供以下两种访问库表的写法：

select * from catalog.schema.table

该种为标准写法，即遵循 catalog.schema.table 的格式。

select * from schema.table

该写法省略了catalog。即格式为 schema.table 。

  • 假如系统已创建数据库 db1, db2, db3，然后创建 catalog1，并将 db1 设置到到 catalog1 中，那么 db1 属于 catalog1，此时 db1.table 的写法相当于 catalog1.db1.table。
  • 如果系统配置了 catalog，则可以用 use 语句先设置当前的 catalog。如已执行 use catalog1， 此时 schema.table 的写法相当于 catalog1.schema.table。

相关操作语句或函数

操作语句/函数 功能说明
use 切换当前 catalog
create 创建数据库或数据表
alter 向已有的表中添加一列
drop 删除数据库或数据表
select 访问表中数据
update 更新数据表中的记录
delete 删除表中的记录
setDefaultCatalog 为当前 session 设置默认的 catalog
getCurrentCatalog 查看当前 session 位于哪个 catalog 中
existsCatalog 检查指定 catalog 是否存在
createCatalog 创建一个 catalog
dropCatalog 删除指定的 catalog
getAllCatalogs 检索当前所有可用的 catalog
getSchemaByCatalog 检索指定 catalog 中的所有 schema
createSchema 把指定数据库添加到指定的 catalog 中
dropSchema 删掉指定 catalog 中的指定 schema
renameCatalog 重命名 catalog
renameSchema 重命名 schema
dropDatabase 删除数据库；如果该数据库位于某个 catalog 中，其引用关系也会被删掉
getUserAccess 查询指定用户所单独被赋予的权限；或者查询指定用户及其所属组的权限组合后的最终生效权限
getGroupAccess 查询组的权限

Audit 日志

执行 catalog 的相关操作都会在控制节点的日志里打印一条 AuditLog，包含该函数的函数名，参数，用户信息等。格式如下：

ACL Audit: function xxx [arg1,arg2,arg3], called by user [xxx]"

权限

Catalog 相关级别的权限

提供如下权限设置项用于控制当前 catalog 中所有数据库下表的读或写操作。

Catalog 权限 等价的原有权限
CATALOG_READ DB_READ
CATALOG_WRITE DB_WRITE
CATALOG_INSERT DB_INSERT
CATALOG_UPDATE DB_UPDATE
CATALOG_DELETE DB_DELETE

在处理 catalog 级别的权限操作时，与原有处理逻辑保持相同，遵循着范围覆盖原则。如：

createSchema("cat1", "dfs://db1", "db")
deny(`user, DB_READ, "dfs://db1")
grant(`user, CATALOG_READ, "catalog") //前面的deny被消除
注： 当 objs=* 时，和 TABLE_READ * 等价。

Schema 相关级别的权限

提供以“SCHEMA_”为前缀的多种权限设置项，与原有处理逻辑相同。其中 obj 的语法需要为 “catalogName.schemaName”。如：

grant(`user, SCHEMA_MANAGE, "catalog1.schema1")
SCHEMA 权限 等价的原有权限
SCHEMA_MANAGE DB_MANAGE
SCHEMAOBJ_CREATE DBOBJ_CREATE
SCHEMAOBJ_DELETE DBOBJ_DELETE
SCHEMA_READ DB_READ
SCHEMA_WRITE DB_WRITE
SCHEMA_INSERT DB_INSERT
SCHEMA_UPDATE DB_UPDATE
SCHEMA_DELETE DB_DELETE

操作需要的权限说明

在进行 catalog 的相关操作时，需要拥有对应权限方能执行。下表针对不同操作进行权限说明。

操作 支持的表类型 需要权限/不同权限下的返回结果
createCatalog 需要全局的 CATALOG_MANAGE 权限
dropCatalog 需要对应的 CATALOG_MANAGE 权限
getAllCatalogs
  • admin 用户会返回所有的 catalog
  • 非 admin 用户仅返回有对应的 CATALOG_MANAGE 权限的 catalog
getSchemaByCatalog 需要该 catalog 的 CATALOG_MANAGE 权限
createSchema
  • 需要该 catalog 的 CATALOG_MANAGE 权限，且用户是该数据库的创建者（Owner）
  • 或拥有要添加数据库的 DB_MANAGE 权限
dropSchema 需要该 catalog 的 CATALOG_MANAGE 权限
renameCatalog 需要该 catalog 的 CATALOG_MANAGE 权限
renameSchema 需要该 catalog 的 CATALOG_MANAGE 权限
addPartitions
  • 需要 CATALOG_MANAGE 权限
  • 或者需要 DB_MANAGE 权限
  • 或者 DB_OWNER 是当前用户
  • 若自动添加 valuePartitions，则不需要权限
dropPartition
  • 当 deleteSchema=false 时（默认只删除数据），需要：
    • CATALOG_MANAGE
    • 或者 DB_MANAGE
    • 或者 DB_OWNER 是当前用户
    • 或者库级 DB_DELETE
    • 或全局 TABLE_DELETE

  • 当 deleteSchema=true，需要：

    • CATALOG_MANAGE 权限
    • 或者 DB_MANAGE 权限
    • 或者 DB_OWNER 是当前用户
addColumn table 可为任何形式的数据表，包括内存表、流数据表、分布式表或维度表
  • 需要 CATALOG_MANAGE 权限
  • 或者 DB_MANAGE 权限
  • 或者 DB_OWNER是当前用户
  • 或者 Table 的 Owner 是当前用户
  • 或者有 DBOBJ_CREATE 和 TABLE_READ 权限
dropColumns! 一个内存表或分布式表（仅支持 OLAP 引擎） 同上
renameColumns 同上
replaceColumns 同上
renameTable 同上
updateColumnComment 同上
createDB（database函数） 需要 DB_OWNER 权限。如果匹配了 dbUrl 前缀，会检查库名是否符合前缀。
createDimensionTable
  • 需要 CATALOG_MANAGE 权限
  • 或者 DB_MANAGE 权限
  • 或者 DB_OWNER 是当前用户
  • 或者 DB_OBJ_CREATE 权限
createPartitionedTable
  • 需要 CATALOG_MANAGE 权限
  • 或者 DB_MANAGE 权限
  • 或者 DB_OWNER 是当前用户
  • 或者有 DB_OBJ_CREATE 权限
truncate
  • 需要 [CATALOG/DB/TABLE]_DELETE 权限
  • 或者 Table 的 Owner 是当前用户
  • 或者是 functionView 操作
loadTable 同上
SQL delete 同上
upsert/SQL update
  • 需要 [CATALOG/DB/TABLE]_UPDATE 权限
  • 或者 Table 的 Owner 是当前用户
  • 或者是 functionView 操作
dropDB
  • 需要 CATALOG_MANAGE 权限
  • 或者 DB_MANAGE 权限
  • 或者 DB_OWNER 是当前用户