共享对象
概述
描述如何为租户创建和管理共享，以及如何与其他租户共享共享。租户标识符在您的组织内唯一标识一个账户。
以下数据库对象可以共享：
- 表
- 视图
- UDFs
在租户之间共享的所有数据库对象都是只读的，这意味着共享对象不能被修改或删除。
共享的内容是什么？
共享是封装了共享数据库所需的所有信息的命名对象。每个共享包括：
- 授予访问数据库的权限。
- 授予访问数据库中特定对象的权限。
- 与数据库及其对象共享的消费者租户。
从共享数据库创建数据库后，所有共享对象对消费者账户中的用户都是可访问的。
数据提供者和消费者
提供者
数据提供者是创建共享并使其可供其他租户消费的任何租户。作为数据提供者，租户可以与一个或多个租户共享数据库。对于每个共享数据库，提供者可以使用授权来对数据库中的对象进行访问控制。
消费者
数据消费者是选择从数据提供者提供的共享创建数据库的任何租户。作为数据消费者，一旦提供者将共享数据库添加到您的租户中，消费者就可以像访问账户中的任何其他数据库一样访问和查询数据库中的对象。
数据共享是如何工作的？
通过数据共享，实际数据不会在提供者和消费者之间复制或转移：
- 提供者在他们的账户中创建一个数据库的共享，并授予访问数据库中特定对象的权限。然后，一个或多个租户（即
消费者）被添加到共享中，可以访问共享数据库和其他共享对象。 - 在消费者端，从共享创建一个
只读数据库。这意味着消费者没有权限修改共享数据对象，如更新、插入、删除、删除等。 - 由于提供者和消费者之间没有数据复制，一旦提供者删除共享对象（如
删除数据库、删除表等），消费者将无法再访问共享对象。
共享对象权限
有三种共享对象权限：
- USAGE: 用于数据库。
- SELECT: 用于表或视图。
- REFERENCE_USAGE: 用于数据库。
关于权限的一些注意事项：
- 只能将单个数据库的
USAGE权限授予共享；然而，在该数据库中，可以将对多个对象（如UDFs、表等）的权限授予共享。 - 必须通过单独的GRANT语句将单个对象的权限授予共享。
- 在共享引用多个数据库对象的安全视图时，使用
REFERENCE_USAGE权限，如下所示：- 必须单独将
REFERENCE_USAGE权限授予每个数据库。 - 在将安全视图的
SELECT权限授予共享之前，必须授予数据库的REFERENCE_USAGE权限。
- 必须单独将
共享的DDL
为了支持创建和管理共享，Databend提供以下一组特殊的DDL命令：
- 创建共享
- 删除共享
- 修改共享
- 授予共享对象权限给共享
- 从共享撤销共享对象权限
- 显示共享
- 描述共享
- 显示授权
- 从共享创建数据库、表
- 从共享数据库表中选择数据
- 显示共享数据库表
创建共享
创建一个新的空共享。一旦创建了共享，用户可以使用GRANT <privilege> ... TO SHARE命令将数据库和数据库中的对象（表）包含在共享中。然后，用户可以使用ALTER SHARE将一个或多个租户添加到该共享中。
语法：
CREATE SHARE [IF NOT EXISTS] <share_name> [ COMMENT = '<string_literal>' ]
删除共享
从系统中删除指定的共享，并立即撤销所有租户（即从该共享创建数据库的租户）的访问权限。
语法：
DROP SHARE [IF EXISTS] <share_name>
修改共享
修改现有共享的属性。
- 从租户列表中添加或删除租户。
语法：
ALTER SHARE [IF EXISTS] <share_name> {ADD | REMOVE} TENANTS = <tenant_name> [, <tenant_name>, ...]
授予共享对象权限给共享
授予访问数据库和其他支持的数据库对象（表、视图等）给共享。授予这些对象 的权限实际上将它们添加到共享中，然后可以与一个或多个租户共享。
语法：
GRANT object_privilege ON grant_share_object_name TO SHARE <share_name>
object_privilege ::= [
-- 对于数据库、模式或函数
USAGE |
-- 对于表或视图
SELECT |
-- 对于数据库
REFERENCE_USAGE]
grant_share_object_name := { DATABASE <db_name> | TABLE <db_name>.<table_name> }
从共享撤销共享对象权限
撤销共享中数据库和其他支持的数据库对象（表、视图等）的访问权限。撤销这些对象的权限实际上将它们从共享中移除，使它们对所有已从共享创建数据库的租户不可访问。
语法：
REVOKE object_privilege ON grant_share_object_name FROM SHARE <share_name>
object_privilege := [USAGE|SELECT|REFERENCE_USAGE]
grant_share_object_name := { DATABASE <db_name> | TABLE <db_name>.<table_name> }
显示共享
显示您的租户创建的所有共享或您的租户可消费的所有共享。
语法：
SHOW SHARES;
输出：
SHOW SHARES命令的输出是共享对象信息的列表，包含列Created_on、Kind、Name、Database_name、To、From和Comment。
如果共享是由您的租户创建的，则Kind为OUTBOUND；否则，如果共享可供您的租户消费，则Kind为INBOUND，To为空。
描述共享
描述包含在共享中的共享对象。
语法：
{DESC|DESCRIBE} SHARE <share_name>
输出：
DESCRIBE SHARE命令的输出是共享对象信息的列表，包含列Kind、Name、Shared_on，例如：
+----------+--------------------------------------+-------------------------------+
| Kind | Name | Shared_on |
|----------+--------------------------------------+-------------------------------|
| DATABASE | tenant1.db1 | 2022-08-11 18:04:17.642 -0700 |
| TABLE | tenant1.db1.table1 | 2022-08-11 18:04:17.749 -0700 |
+----------+--------------------------------------+-------------------------------+
注意，每个共享对象的name前缀为<tenant_name>.。
显示授权
列出已明确授予租户和共享的所有访问控制权限。
语法：
SHOW GRANTS ON grant_share_object_name
SHOW GRANTS OF SHARE <share_name>
grant_share_object_name := { DATABASE <db_name> | TABLE <db_name>.<table_name> }
SHOW GRANTS ON grant_share_object_name：列出已授予该对象的所有权限。SHOW GRANTS OF SHARE <share_name>：列出共享的所有租户，并指示正在使用共享的租户。
从共享创建数据库、表
在租户有权访问共享对象后，可以从共享创建数据库。
语法：
CREATE DATABASE <name> FROM SHARE <provider_tenant>.<share_name>
从共享数据库表中选择数据
在租户从共享数据库创建数据库后，租户可以从共享表中选择数据，就像从普通表中选择数据一样，前提是提供者必须已授予对共享数据库和表的访问权限。
语法：
Select * from <share_db_name>.<table_name>
显示共享数据库表
在租户从共享数据库创建数据库后，租户可以显示共享数据库中的表，它只输出已授予访问权限的表。
语法：
use <share_db_name>;
show tables;
使用SQL创建共享的示例
要使用SQL创建共享：
- 使用
CREATE SHARE命令创建一个空共享。 - 使用
GRANT <privilege> … TO SHARE命令将数据库添加到共享中，并选择性地授予对特定数据库对象（表）的访问权限。 - 使用
ALTER SHARE命令将一个或多个账户访问添加到共享中。 - 使用
CREATE DATABASE ... FROM SHARE命令从共享创建数据库。
步骤1：创建一个空共享
以下示例创建一个名为t的空共享：
create share t;
步骤2：为数据库和对象授予权限给共享
要包含共享中的对象，请为每个对象授予权限。在授予权限时，首先授予容器对象的使用权，然后再授予容器中对象的使用权。例如，在授予数据库中任何表的访问权限之前，先授予数据库的访问权限。
以下示例说明了如何将对以下对象的权限授予在前一步骤中创建的t共享：
grant usage on database db1 to share t;
grant select on table db1.table1 to share t;
授予对象权限 操作后，可以向共享添加租户。
步骤3：向共享添加租户
以下示例向t共享添加两个租户：
alter share t add tenants=x, y;
修改共享添加租户后，现在租户x和y有权使用共享对象创建对象（数据库、表）。
步骤4：从共享创建数据库
现在租户x从共享t创建数据库db：
CREATE DATABASE db FROM SHARE t
