数据目录(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 是当前用户