# Sharing data in MotherDuck > MotherDuck data sharing model concepts including read-only shares and scope options. MotherDuck's data sharing model has the following key characteristics: - Sharing is at the granularity of a MotherDuck database. - Sharing is read-only. - Sharing is done through **share** objects. - You can make shares discoverable and queryable by every preset role in your [organization](../managing-organizations/managing-organizations.mdx) by granting access to the Explorer role. - You can create restricted shares, where access is granted to specific preset roles or users. - Alternatively, you can use hidden share URLs to limit access to specific people in your organization you share the URL with. - You can also configure the URL of a hidden share to be accessible by anyone with a MotherDuck account in the same cloud region as your Organization. :::note Shares are **region-scoped** based on your Organization's cloud region. Each MotherDuck Organization is scoped to a single cloud region that must be chosen at Org creation when signing up. MotherDuck is available on AWS in six regions: - **US East (N. Virginia):** `us-east-1` - **US West (Oregon):** `us-west-2` - **Europe (Frankfurt):** `eu-central-1` - **Europe (Dublin):** `eu-west-1` - **Asia Pacific (Tokyo):** `ap-northeast-1` - **Asia Pacific (Sydney):** `ap-southeast-2` ::: Sharing in MotherDuck works as follows: 1. The **data provider** shares their database in MotherDuck by creating a share. 2. The **data consumer** attaches said share, which creates a database clone in their workspace. The data consumer can now query this database. 3. The **data provider** periodically updates the share to push updates to the database to **data consumers**. ## Creating a share The first step in sharing databases in MotherDuck is to create a share, which can be done in both UI and SQL. Creating a share does not incur additional costs, and no actual data is copied or transferred - creating a share is a zero-copy, metadata-only operation. ### UI Click on the "trident" next to the database you'd like to share. Select "share". Then: ![trident](./img/ui-share_new.png) 1. Optionally, choose a share name. Default will be the database name. 2. Choose whether the share should be accessible to your organization, specified roles or users, or any MotherDuck user in the same cloud region who has the share link. 3. Choose whether the share should be automatically updated or not. Default is `MANUAL` ### SQL The following example creates a restricted share from database "birds" and grants it to the Explorer role: - Share is also named "birds". - Explorer, Builder, and Admin users can access the Share because preset roles are concentric. - This Share is discoverable to users who have access. ```sql use birds; CREATE SHARE IF NOT EXISTS birds FROM birds (ACCESS RESTRICTED, VISIBILITY DISCOVERABLE, UPDATE MANUAL); GRANT READ ON SHARE birds TO ROLE explorer; ``` Learn more about the [CREATE SHARE](/sql-reference/motherduck-sql-reference/create-share.md) SQL command. ### Organization shares When creating a share, you may choose the scope of access: - **Organization**. This legacy scope is equivalent to granting READ to the Explorer role, so every preset role has access. - **Restricted**. Only the share owner and users or roles specified with `GRANT` commands can access the Share. - **Unrestricted**. Any user signed into any MotherDuck organization in the same cloud region can access this share using the share URL. Use a Restricted Share with a role grant for new organization-wide sharing. For example, grant READ to Explorer for the whole organization, Builder for Builders and Admins, or Admin for Admins only. See [Roles and access control](/concepts/roles-and-access-control/#how-data-access-grants-flow). ### Discoverable shares When creating a share, you may choose to make this share **Discoverable**. All authenticated users in your Organization can find this share in the UI. You can create **Discoverable** shares that are **Unrestricted**, but only members of your Organization can find this share in the UI. Non-members can still access this share using the share URL. ### Share URLs When you create a share, a URL for this share is generated: - If the share is **Discoverable**, members of your Organization can find this share without the share URL. Alternatively, they can use the URL directly. - If the share is **Hidden** (e.g. not Discoverable), other users will not be able to find the share URL. You will need to send this URL directly to the users with whom you want to share this data. ## Consuming shared data The **data consumer** needs to attach the share to their workspace, thereby creating a read-only zero-copy clone of the source database. This is a free, metadata-only operation. When you attach a share, it gets an alias that defaults to the source database name. If you already have a database with that name, the attach fails. Use `AS` to pick a different alias, or [detach](/key-tasks/database-operations/detach-and-reattach-motherduck-database/) the conflicting database first. See [share alias conflicts](/sql-reference/motherduck-sql-reference/attach/#share-alias-conflicts) for details. ### Views and fully-qualified table references If the shared database contains views, those views may reference tables using fully-qualified paths that include the original database name. For example, a view in a database called `org_dwh` might reference `org_dwh.main.sales`. When you attach the share, make sure the database alias matches the original database name. Otherwise, the views fail because they can't resolve the original database name in your namespace. ```sql -- The share was created from a database called "org_dwh". -- Views inside reference the tables as "org_dwh.main.". -- This will cause view errors because the alias doesn't match: ATTACH 'md:_share/org_dwh/id_abc123' AS dwh; -- Use the original database name as the alias: ATTACH 'md:_share/org_dwh/id_abc123' AS org_dwh; ``` This applies to any object in the shared database that uses fully-qualified references, including views, macros, and stored procedures. ### Consuming discoverable shares If the **data provider** created a Discoverable share you have access to, you should be able to find this share in the UI. ### UI 1. Select the share you want under "Shared with me". 2. Optionally roll over the share to see the tooltip that tells you the share owner, when it was last updated, and share access scope. 2. Click "attach". 3. You can query the resulting database. ### Consuming hidden shares If the **data provider** created a Hidden (e.g. non-Discoverable) share, they need to pass the share URL to the **data consumer**. The **data consumer**, in turn, needs to attach the share URL. ```sql ATTACH 'md:_share/ducks/0a9a026ec5a55946a9de39851087ed81' AS birds; # attaches the share as database `birds` ``` ## Updating shared data If during creation of the share, the **data provider** chooses to have the share update automatically, the share will be updated periodically. If the share was created with `MANUAL` updates, the **data provider** needs to manually update the share. ```sql UPDATE SHARE birds; ``` Learn more about [UPDATE SHARE](/sql-reference/motherduck-sql-reference/update-share.md) and [data replication timing and checkpoints](./updating-shares.md). ## Consuming updated data By default, shares automatically update every minute. However, if you need the most up-to-date data sooner, the consumer can manually refresh the share after the producer executes UPDATE SHARE. To manually refresh the data: ```sql REFRESH DATABASES; -- Refreshes all connected databases and shares REFRESH DATABASE my_share; -- Alternatively, refresh a specific database/share ``` Lean more about [REFRESH DATABASES](/sql-reference/motherduck-sql-reference/refresh-database.md). --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fkey-tasks%2Fsharing-data%2Fsharing-overview%2F&page_title=Sharing%20concepts%20and%20overview&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.