数据目录(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 |
|
|
getSchemaByCatalog | 需要该 catalog 的 CATALOG_MANAGE 权限 | |
createSchema |
|
|
dropSchema | 需要该 catalog 的 CATALOG_MANAGE 权限 | |
renameCatalog | 需要该 catalog 的 CATALOG_MANAGE 权限 | |
renameSchema | 需要该 catalog 的 CATALOG_MANAGE 权限 | |
addPartitions |
|
|
dropPartition |
|
|
addColumn | table 可为任何形式的数据表,包括内存表、流数据表、分布式表或维度表 |
|
dropColumns! | 一个内存表或分布式表(仅支持 OLAP 引擎) | 同上 |
renameColumns | 同上 | |
replaceColumns | 同上 | |
renameTable | 同上 | |
updateColumnComment | 同上 | |
createDB(database函数) | 需要 DB_OWNER 权限。如果匹配了 dbUrl 前缀,会检查库名是否符合前缀。 | |
createDimensionTable |
|
|
createPartitionedTable |
|
|
truncate |
|
|
loadTable | 同上 | |
SQL delete | 同上 | |
upsert/SQL update |
|
|
dropDB |
|