motherduck-share-data

与 MotherDuck 共享数据

真实数据源

• 优先查阅最新的 MotherDuck 共享文档和 SQL 参考。
• 如果 MotherDuck MCP 的 ask_docs_question 功能可用，先使用该功能，再查阅公开文档。
• 共享模式应符合文档说明的行为：
  • 零拷贝，且仅共享元数据
  • 数据库是共享源，可通过 INCLUDE_PATTERN 可选地筛选表／视图
  • 可选的安全视图，可针对每位使用者筛选行、移除列或屏蔽值
  • 接收方为只读
  • 更新和包含模式策略由所有者控制

前置条件

需要可用的连接、源数据库和预期受众。复用上下文中的这些信息；若缺少设置或 SQL 细节，可使用相关技能。

默认做法

• 对于受治理的内部分发，优先使用 ACCESS RESTRICTED 和 GRANT READ ON SHARE ... TO ROLE ...。仅当调用方明确需要其旧版的组织范围行为时，才使用 ACCESS ORGANIZATION。
• 如果同一共享的所有接收方都应看到相同的表／视图子集，则使用 INCLUDE_PATTERN。如果受众需要不同的表子集，则创建单独的共享；如果差异仅在于行、列或屏蔽值，则可使用一个共享和安全视图满足所有受众的需求。
• 如果接收方需要稳定的快照或带版本的交付，则使用 UPDATE MANUAL。
• 如果分发需要严格受控，则使用 ACCESS RESTRICTED 或 VISIBILITY HIDDEN。
• 选择访问权限和可见性之前，请确认接收方是内部用户、其他组织还是公众。
• 对于写入频繁的数据发布方，在依赖共享更新工作流中的检查点或并发写入行为之前，请确认 DuckDB 客户端版本受 MotherDuck 支持。
• INCLUDE_PATTERN 用于选择完整的表和视图；切勿将其描述为行级或列级安全机制。它适用于原生 MotherDuck 和完全托管的 DuckLake 数据源。
• 如需筛选行、隐藏列或屏蔽值，请向共享添加安全视图：CREATE SHARE ... WITH SECURE VIEW REPLACES <table> AS (SELECT ...) 或 ALTER SHARE ... ADD [OR REPLACE] SECURE VIEW。针对个人，使用 current_email() 制定策略；针对服务帐户，使用 current_user；针对角色，使用 is_role_in_session('<role>')。一个包含安全视图的共享可以取代一组按受众划分的共享。适用于 Business 和 Enterprise 计划；使用 SQL 管理这些视图需要 DuckDB 1.5.6 或更高版本以及读写令牌。
• 共享公开的表如果没有被替换为安全视图，就仍可被完整读取。结合使用 INCLUDE_PATTERN（用于选择表）和安全视图（用于选择行和列），并将宏架构和映射表排除在匹配模式之外。
• MotherDuck 安全视图是共享策略。DuckDB 自身的 CREATE SECURE VIEW 仅用于阻止优化器优化，不会施加任何限制。

工作流

1. 确定要发布的确切数据库，以及谁会使用它。
2. 编写 SQL 之前，先决定受众、可见的表／视图范围、可发现性和数据新鲜度要求。
3. 针对实时源目录预览并验证任何包含模式，然后创建共享，并明确指定访问权限、可见性、更新模式以及可选的 INCLUDE_PATTERN。
4. 如果访问受限，请明确授予用户或角色权限。如果共享处于隐藏状态或基于链接，请直接分发共享 URL。
5. 使用 LIST SHARES 或 MD_INFORMATION_SCHEMA.OWNED_SHARES 读取共享信息；对于经过筛选的共享，验证已保存的模式和使用者可见的目录。对于安全视图，运行 SHOW SECURE VIEWS ON SHARE <name>，并以使用者身份附加共享以检查结果；身份函数会根据运行测试的用户进行求值。
6. 让接收方 ATTACH 共享数据库，并以只读方式查询。
7. 使用 ALTER SHARE ... SET|RESET INCLUDE_PATTERN 更改表／视图范围，使用 ALTER SHARE ... ADD|DROP SECURE VIEW 更改策略（不能在同一条语句中同时使用）。避免对包含安全视图的共享使用 CREATE OR REPLACE SHARE；该命令会删除所有未在语句中重新声明的视图。如果共享使用 UPDATE MANUAL，所有者应运行 UPDATE SHARE，并在新快照就绪后让使用者运行 REFRESH DATABASE。

对于解答、审查或规划请求，只返回共享设计和 SQL，不执行配置。对于创建、更新、授权或撤销请求，执行请求范围内的操作，并验证最终访问权限；涉及公开披露、破坏性撤销或无关授权时，请先征求确认。

参考资料

只阅读当前任务所需的参考章节。

• 阅读 references/SHARE_PLAYBOOK.md，了解完整的 SQL 操作指南、角色授权、包含模式规则、安全视图、访问／更新决策、使用者工作流和常见故障模式。

相关技能

仅在缺少相应能力时加载相关技能；复用已建立的上下文。

• motherduck-connect：用于 MotherDuck 身份验证和连接设置
• motherduck-explore：用于发现数据库、表、列和现有共享
• motherduck-query：用于验证共享 SQL 和下游查询
• motherduck-duckdb-sql：用于 DuckDB SQL 语法和查询支持
• motherduck-security-governance：用于角色设计和访问边界审查